# TraconWorkflowsBuilderExtensions

> Tracon documentation. Tracon is a .NET package family that adds a control
> plane on Microsoft Agent Framework, published as NuGet packages that run
> inside your own ASP.NET Core application.
>
> Page: https://tracon.dev/api/tracon.traconworkflowsbuilderextensions/
> Summary: TraconWorkflowsBuilderExtensions: Extensions that register workflow execution.

<div class="api-provenance">Namespace Tracon · Assembly <code>Tracon.Workflows.dll</code></div>

Extensions that register workflow execution.

```csharp
public static class TraconWorkflowsBuilderExtensions
```

<dl class="api-relations"><dt>Inheritance</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object">object</a> ← <a href="/api/tracon.traconworkflowsbuilderextensions/">TraconWorkflowsBuilderExtensions</a></dd><dt>Inherited Members</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object.gettype">object.GetType()</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.memberwiseclone">object.MemberwiseClone()</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.tostring">object.ToString()</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object)">object.Equals(object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object-system-object)">object.Equals(object?, object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.referenceequals">object.ReferenceEquals(object?, object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.gethashcode">object.GetHashCode()</a></dd></dl>

## Methods

### <a id="Tracon_TraconWorkflowsBuilderExtensions_AddWorkflow_Tracon_ITraconBuilder_System_String_System_Func_System_IServiceProvider_Microsoft_Agents_AI_Workflows_Workflow__"></a> AddWorkflow\(ITraconBuilder, string, Func<IServiceProvider, Workflow\>\)

Defines a factory-based workflow in code. How the graph is built is
entirely up to the caller.

```csharp
public static ITraconBuilder AddWorkflow(this ITraconBuilder builder, string name, Func<IServiceProvider, Workflow> factory)
```

#### Parameters

`builder` [ITraconBuilder](/api/tracon.itraconbuilder/)

The Tracon configuration chain.

`name` [string](https://learn.microsoft.com/dotnet/api/system.string)

The workflow name.

`factory` [Func](https://learn.microsoft.com/dotnet/api/system.func\-2)<[IServiceProvider](https://learn.microsoft.com/dotnet/api/system.iserviceprovider), Workflow\>

The factory that builds the graph.

#### Returns

 [ITraconBuilder](/api/tracon.itraconbuilder/)

The chain, for continued configuration.

#### Remarks

The same registration as [TraconWorkflowsBuilderExtensions.AddWorkflow](/api/tracon.traconworkflowsbuilderextensions/)
with no description; its remarks apply.

#### Exceptions

 [ArgumentNullException](https://learn.microsoft.com/dotnet/api/system.argumentnullexception)

One of the parameters is [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null).

 [ArgumentException](https://learn.microsoft.com/dotnet/api/system.argumentexception)

`name` is empty, or is `functions`: `GET /api/workflows/functions`
lists the registered function nodes, so a workflow under that name could not be read back.

### <a id="Tracon_TraconWorkflowsBuilderExtensions_AddWorkflow_Tracon_ITraconBuilder_System_String_System_Func_System_IServiceProvider_Microsoft_Agents_AI_Workflows_Workflow__System_String_"></a> AddWorkflow\(ITraconBuilder, string, Func<IServiceProvider, Workflow\>, string?\)

Defines a factory-based workflow in code, with a description. How the graph is built is
entirely up to the caller.

```csharp
public static ITraconBuilder AddWorkflow(this ITraconBuilder builder, string name, Func<IServiceProvider, Workflow> factory, string? description)
```

#### Parameters

`builder` [ITraconBuilder](/api/tracon.itraconbuilder/)

The Tracon configuration chain.

`name` [string](https://learn.microsoft.com/dotnet/api/system.string)

The workflow name.

`factory` [Func](https://learn.microsoft.com/dotnet/api/system.func\-2)<[IServiceProvider](https://learn.microsoft.com/dotnet/api/system.iserviceprovider), Workflow\>

The factory that builds the graph.

`description` [string](https://learn.microsoft.com/dotnet/api/system.string)?

A short description; [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) for none.

#### Returns

 [ITraconBuilder](/api/tracon.itraconbuilder/)

The chain, for continued configuration.

#### Remarks

A workflow defined in code **takes precedence over** a
database definition with the same name. The same rule applies to the
agent catalog: someone with write access to the database cannot
take over a behavior registered in code.

**The start executor receives two messages.** A run sends it the
user's message as a `List<ChatMessage>` and then a
`Workflows.TurnToken`, on every start and every resume that does not answer a
request: an agent host needs the token to speak, and a resume without it waits
for its deadline when nothing is left to run. A start executor whose handler
takes [Object](https://learn.microsoft.com/dotnet/api/system.object) receives both and runs twice; give it a
`List<ChatMessage>` handler instead.

```csharp
builder.AddTracon()
       .UseWorkflows()
       .AddWorkflow("triage", provider => BuildTriageGraph(provider), "Routes an incoming ticket.");
```

#### Exceptions

 [ArgumentNullException](https://learn.microsoft.com/dotnet/api/system.argumentnullexception)

One of the parameters is [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null).

 [ArgumentException](https://learn.microsoft.com/dotnet/api/system.argumentexception)

`name` is empty, or is `functions`: `GET /api/workflows/functions`
lists the registered function nodes, so a workflow under that name could not be read back.

### <a id="Tracon_TraconWorkflowsBuilderExtensions_AddWorkflow_Tracon_ITraconBuilder_System_String_System_Func_System_IServiceProvider_Microsoft_Agents_AI_Workflows_Workflow__System_Action_Tracon_WorkflowRegistrationOptions__"></a> AddWorkflow\(ITraconBuilder, string, Func<IServiceProvider, Workflow\>, Action<WorkflowRegistrationOptions\>\)

Defines a factory-based workflow in code, with the settings a stored definition would
carry: its description and how it treats more than one answer to the same request.

```csharp
public static ITraconBuilder AddWorkflow(this ITraconBuilder builder, string name, Func<IServiceProvider, Workflow> factory, Action<WorkflowRegistrationOptions> configure)
```

#### Parameters

`builder` [ITraconBuilder](/api/tracon.itraconbuilder/)

The Tracon configuration chain.

`name` [string](https://learn.microsoft.com/dotnet/api/system.string)

The workflow name.

`factory` [Func](https://learn.microsoft.com/dotnet/api/system.func\-2)<[IServiceProvider](https://learn.microsoft.com/dotnet/api/system.iserviceprovider), Workflow\>

The factory that builds the graph.

`configure` [Action](https://learn.microsoft.com/dotnet/api/system.action\-1)<[WorkflowRegistrationOptions](/api/tracon.workflowregistrationoptions/)\>

Sets the workflow's settings; called once, here.

#### Returns

 [ITraconBuilder](/api/tracon.itraconbuilder/)

The chain, for continued configuration.

#### Remarks

Everything the other overload says applies here too: a workflow defined in code takes
precedence over a stored one with the same name, and its start executor receives the
message and a `Workflows.TurnToken`.

[WorkflowResponseMode.SingleAnswer](/api/tracon.workflowresponsemode/) makes each pending request of this graph
take one answer: the same answer given twice (a double click, a retried HTTP call) follows
the run the first one started, and a different answer is refused with `409`. Every
answer that starts a run is written to the audit trail before the run starts.

[WorkflowRegistrationOptions.RequestTimeout](/api/tracon.workflowregistrationoptions/#Tracon_WorkflowRegistrationOptions_RequestTimeout) closes a run whose request nobody
answers in time, which is also what lets retention delete the rows such a run keeps.
[WorkflowRegistrationOptions.RunTimeout](/api/tracon.workflowregistrationoptions/#Tracon_WorkflowRegistrationOptions_RunTimeout) and [WorkflowRegistrationOptions.Parameters](/api/tracon.workflowregistrationoptions/#Tracon_WorkflowRegistrationOptions_Parameters)
give the graph the run time limit and the run parameters a stored workflow carries; a run timeout
above `Tracon:Workflows:MaxRunTimeout` stops the host at startup.

```csharp
builder.AddTracon()
       .UseWorkflows()
       .AddWorkflow("triage", provider => BuildTriageGraph(provider), options =>
       {
           options.Description = "Routes a ticket after one approval.";
           options.ResponseMode = WorkflowResponseMode.SingleAnswer;
           options.RequestTimeout = TimeSpan.FromDays(7);
       });
```

#### Exceptions

 [ArgumentNullException](https://learn.microsoft.com/dotnet/api/system.argumentnullexception)

One of the parameters is [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null).

 [ArgumentException](https://learn.microsoft.com/dotnet/api/system.argumentexception)

`name` is empty or reserved (see the other overload), or
`configure` set a [WorkflowRegistrationOptions.ResponseMode](/api/tracon.workflowregistrationoptions/#Tracon_WorkflowRegistrationOptions_ResponseMode)
that is not a member of [WorkflowResponseMode](/api/tracon.workflowresponsemode/), a
[WorkflowRegistrationOptions.RequestTimeout](/api/tracon.workflowregistrationoptions/#Tracon_WorkflowRegistrationOptions_RequestTimeout) outside one minute to 365 days, a
[WorkflowRegistrationOptions.RunTimeout](/api/tracon.workflowregistrationoptions/#Tracon_WorkflowRegistrationOptions_RunTimeout) outside one millisecond to about 49.7 days, or
[WorkflowRegistrationOptions.Parameters](/api/tracon.workflowregistrationoptions/#Tracon_WorkflowRegistrationOptions_Parameters) with a name that is not an identifier or is repeated.

### <a id="Tracon_TraconWorkflowsBuilderExtensions_UseWorkflows_Tracon_ITraconBuilder_System_Action_Tracon_TraconWorkflowOptions__"></a> UseWorkflows\(ITraconBuilder, Action<TraconWorkflowOptions\>?\)

Registers the workflow execution engine. Agents from the catalog can be
chained together with ready-made patterns, and every execution produces
a `runs` row.

```csharp
public static ITraconBuilder UseWorkflows(this ITraconBuilder builder, Action<TraconWorkflowOptions>? configure = null)
```

#### Parameters

`builder` [ITraconBuilder](/api/tracon.itraconbuilder/)

The Tracon configuration chain.

`configure` [Action](https://learn.microsoft.com/dotnet/api/system.action\-1)<[TraconWorkflowOptions](/api/tracon.traconworkflowoptions/)\>?

The option customizer.

#### Returns

 [ITraconBuilder](/api/tracon.itraconbuilder/)

The chain, for continued configuration.

#### Remarks

**Security boundary.** A workflow defined from the UI does
not produce new behavior: it only sequences catalog agents with
ready-made patterns whose order is fixed. A free-form graph - custom
`Executor` types, conditional edges, sub-workflows - is only
defined in code, with [TraconWorkflowsBuilderExtensions.AddWorkflow](/api/tracon.traconworkflowsbuilderextensions/). The code-only tools rule is
preserved this way.

The definition and checkpoint stores are already registered by
`AddTracon`; this call only turns *execution* on.
While the engine is not registered, the HTTP layer can still list and
manage definitions - only the execution endpoint returns `501`.

[TraconWorkflowOptions.SectionName](/api/tracon.traconworkflowoptions/#Tracon_TraconWorkflowOptions_SectionName) (`Tracon:Workflows`)
is BOUND from `IConfiguration` - the same contract as
every other `Use*` extension (`UseOpenAI`,
`UsePostgreSql`, `UseSkillScripts`, and so on).
`configure` runs AFTER this binding, so code can still
override the config.

```csharp
builder.AddTracon()
       .UseOpenAI(apiKey)
       .UsePostgreSql(connectionString)
       .UseWorkflows()
       .UseUI();
```

#### Exceptions

 [ArgumentNullException](https://learn.microsoft.com/dotnet/api/system.argumentnullexception)

`builder` is [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null).