WorkflowAgentStepOptions

Namespace Tracon · Assembly Tracon.Workflows.dll

The settings of one agent step in a workflow graph built in code, passed to WorkflowAgentBinding.GetWorkflowAgentStep.

public sealed class WorkflowAgentStepOptions

Inheritance

object ← WorkflowAgentStepOptions

Inherited Members

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

Remarks

A stored workflow carries WorkflowAgentStepOptions.Timeout and WorkflowAgentStepOptions.AgentVersion in a WorkflowNodeReference; a graph built in code has no node reference, so it chooses them here. 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 gives.

Constructors

WorkflowAgentStepOptions()

public WorkflowAgentStepOptions()

Properties

AgentVersion

Gets or sets the version of the stored agent the step runs. null (the default) runs the agent’s current version on every call.

public int? AgentVersion { get; set; }

Property Value

int?

Remarks

The same setting as 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.

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.

AgentVersionParameter

Gets or sets the name of a run parameter that picks the version of the stored agent the step runs. null (the default) leaves the choice to WorkflowAgentStepOptions.AgentVersion.

public string? AgentVersionParameter { get; set; }

Property Value

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

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 },
    ]);

Timeout

Gets or sets the longest time the step may wait for the agent. null (the default) uses Tracon:AgentGraph:ChildDeadline.

public TimeSpan? Timeout { get; set; }

Property Value

TimeSpan?

Remarks

The same setting as 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. Must be from one millisecond to about 49.7 days less 30 seconds.