TraconWorkflowsBuilderExtensions

Namespace Tracon · Assembly Tracon.Workflows.dll

Extensions that register workflow execution.

public static class TraconWorkflowsBuilderExtensions

Inheritance

object ← TraconWorkflowsBuilderExtensions

Inherited Members

object.GetType(), object.MemberwiseClone(), object.ToString(), object.Equals(object?), object.Equals(object?, object?), object.ReferenceEquals(object?, object?), object.GetHashCode()

Methods

AddWorkflow(ITraconBuilder, string, Func<IServiceProvider, Workflow>)

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

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

Parameters

builder ITraconBuilder

The Tracon configuration chain.

name string

The workflow name.

factory Func<IServiceProvider, Workflow>

The factory that builds the graph.

Returns

ITraconBuilder

The chain, for continued configuration.

Remarks

The same registration as TraconWorkflowsBuilderExtensions.AddWorkflow with no description; its remarks apply.

Exceptions

ArgumentNullException

One of the parameters is null.

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.

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.

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

Parameters

builder ITraconBuilder

The Tracon configuration chain.

name string

The workflow name.

factory Func<IServiceProvider, Workflow>

The factory that builds the graph.

description string?

A short description; null for none.

Returns

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 receives both and runs twice; give it a List<ChatMessage> handler instead.

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

Exceptions

ArgumentNullException

One of the parameters is null.

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.

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.

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

Parameters

builder ITraconBuilder

The Tracon configuration chain.

name string

The workflow name.

factory Func<IServiceProvider, Workflow>

The factory that builds the graph.

configure Action<WorkflowRegistrationOptions>

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

Returns

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 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 closes a run whose request nobody answers in time, which is also what lets retention delete the rows such a run keeps. WorkflowRegistrationOptions.RunTimeout and 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.

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

One of the parameters is null.

ArgumentException

name is empty or reserved (see the other overload), or configure set a WorkflowRegistrationOptions.ResponseMode that is not a member of WorkflowResponseMode, a WorkflowRegistrationOptions.RequestTimeout outside one minute to 365 days, a WorkflowRegistrationOptions.RunTimeout outside one millisecond to about 49.7 days, or WorkflowRegistrationOptions.Parameters with a name that is not an identifier or is repeated.

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.

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

Parameters

builder ITraconBuilder

The Tracon configuration chain.

configure Action<TraconWorkflowOptions>?

The option customizer.

Returns

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. 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 (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.

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

Exceptions

ArgumentNullException

builder is null.