# WorkflowAgentStepOptions

> 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.workflowagentstepoptions/
> Summary: WorkflowAgentStepOptions: The settings of one agent step in a workflow graph built in code, passed to WorkflowAgentBinding.GetWorkflowAgentStep.

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

The settings of one agent step in a workflow graph built in code, passed to
[WorkflowAgentBinding.GetWorkflowAgentStep](/api/tracon.workflowagentbinding/).

```csharp
public sealed class WorkflowAgentStepOptions
```

<dl class="api-relations"><dt>Inheritance</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object">object</a> ← <a href="/api/tracon.workflowagentstepoptions/">WorkflowAgentStepOptions</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.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>

## Remarks

A stored workflow carries [WorkflowAgentStepOptions.Timeout](/api/tracon.workflowagentstepoptions/#Tracon_WorkflowAgentStepOptions_Timeout) and [WorkflowAgentStepOptions.AgentVersion](/api/tracon.workflowagentstepoptions/#Tracon_WorkflowAgentStepOptions_AgentVersion) in a
[WorkflowNodeReference](/api/tracon.workflownodereference/); a graph built in code has no node reference, so it chooses them here.
[WorkflowAgentStepOptions.AgentVersionParameter](/api/tracon.workflowagentstepoptions/#Tracon_WorkflowAgentStepOptions_AgentVersionParameter) has no node-reference twin: a stored workflow is pinned as a whole by
the definition version a run starts with. A callback with properties rather than optional parameters, for
the reason [WorkflowFunctionOptions](/api/tracon.workflowfunctionoptions/) gives.

## Constructors

### <a id="Tracon_WorkflowAgentStepOptions__ctor"></a> WorkflowAgentStepOptions\(\)

```csharp
public WorkflowAgentStepOptions()
```

## Properties

### <a id="Tracon_WorkflowAgentStepOptions_AgentVersion"></a> AgentVersion

Gets or sets the version of the stored agent the step runs. [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) (the default) runs
the agent's current version on every call.

```csharp
public int? AgentVersion { get; set; }
```

#### Property Value

 [int](https://learn.microsoft.com/dotnet/api/system.int32)?

#### Remarks

The same setting as [WorkflowNodeReference.AgentVersion](/api/tracon.workflownodereference/#Tracon_WorkflowNodeReference_AgentVersion). Versions are numbered from 1, and
only an agent stored in the database keeps versions: an agent defined in code has none. Cannot be set
together with [WorkflowAgentStepOptions.AgentVersionParameter](/api/tracon.workflowagentstepoptions/#Tracon_WorkflowAgentStepOptions_AgentVersionParameter).

**A version that cannot be held fails the step, not the build.** A stored workflow checks
the pin before its first node runs; the factory of a graph built in code is synchronous and cannot read
the catalog, so a missing version or an agent that keeps no history ends the run `Failed` at the
step, by name, before its model call. Earlier steps have already run.

### <a id="Tracon_WorkflowAgentStepOptions_AgentVersionParameter"></a> AgentVersionParameter

Gets or sets the name of a run parameter that picks the version of the stored agent the step runs.
[null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) (the default) leaves the choice to [WorkflowAgentStepOptions.AgentVersion](/api/tracon.workflowagentstepoptions/#Tracon_WorkflowAgentStepOptions_AgentVersion).

```csharp
public string? AgentVersionParameter { get; set; }
```

#### Property Value

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

#### Remarks

**The value is read every time the step runs**, from the run's parameter values, so one graph
serves every version: the factory of a graph built in code runs before a run's parameters are bound and
cannot read them. Declare the parameter in [WorkflowRegistrationOptions.Parameters](/api/tracon.workflowregistrationoptions/#Tracon_WorkflowRegistrationOptions_Parameters). A run
that leaves it empty or out runs the agent's current version; a whole number from 1 runs that version,
and the step's run row records it. Declare the parameter optional, with no default, when a run may
leave it out: a required one is refused at the start of a run that omits it.

A run that continues after a human answer reads the value its first part started with. A number keeps
that version through the wait; an empty value still means the current version, resolved when the step
runs, so an edit made while the run waited is the version a later step runs.

**A value that cannot be held fails the step, not the build.** A value that is not a whole
number from 1, a name the workflow does not declare, a version the agent does not have and an agent that
keeps no history all end the run `Failed` at the step, by name, before its model call. The error
for a value that is not a number, and for a name the workflow does not declare, names the parameter and
never repeats the value; a version the agent does not have is named by its number, and an agent that
keeps no history says so. Earlier steps have already run. Cannot be set together with
[WorkflowAgentStepOptions.AgentVersion](/api/tracon.workflowagentstepoptions/#Tracon_WorkflowAgentStepOptions_AgentVersion): the graph is refused when it is built.

Whoever may start the run chooses the version, and any stored version of the agent can be chosen. Pass
the value from your own code, not from an end user's input, unless every version is meant to be reachable.

```csharp
tracon.AddWorkflow(
    "episode",
    services =>
    {
        var writer = services.GetWorkflowAgentStep("episode", "writer", step => step.AgentVersionParameter = "writerVersion");

        return new WorkflowBuilder(writer).WithOutputFrom(writer).WithName("episode").Build();
    },
    options => options.Parameters =
    [
        new AgentParameter { Name = "writerVersion", Kind = AgentParameterKind.Number },
    ]);
```

### <a id="Tracon_WorkflowAgentStepOptions_Timeout"></a> Timeout

Gets or sets the longest time the step may wait for the agent. [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) (the default)
uses `Tracon:AgentGraph:ChildDeadline`.

```csharp
public TimeSpan? Timeout { get; set; }
```

#### Property Value

 [TimeSpan](https://learn.microsoft.com/dotnet/api/system.timespan)?

#### Remarks

The same setting as [WorkflowNodeReference.Timeout](/api/tracon.workflownodereference/#Tracon_WorkflowNodeReference_Timeout) on an agent node: it replaces
`ChildDeadline` for this step, and the hard cutoff is the timeout plus 30 seconds. When the time
is up the run ends `Failed` with [TraconChildRunTimeoutException](/api/tracon.traconchildruntimeoutexception/). Must be from one
millisecond to about 49.7 days less 30 seconds.