WorkflowNodeReference

Namespace Tracon · Assembly Tracon.Abstractions.dll

Points to a single node entering a workflow’s graph: an agent from the catalog, or a function registered in code.

public sealed record WorkflowNodeReference : IEquatable<WorkflowNodeReference>

Inheritance

object ← WorkflowNodeReference

Implements

IEquatable<WorkflowNodeReference>

Inherited Members

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

Remarks

Used only by WorkflowKind.Sequential definitions that mix agent and function nodes. A definition that uses only agents may keep using WorkflowDefinition.AgentNames; the two fields are mutually exclusive (the validator in Tracon.Core enforces this). Both forms are valid and both are accepted on save; the console writes WorkflowDefinition.Nodes only when the chain holds at least one function node.

WorkflowNodeReference.Kind reuses WorkflowNodeKind, the same enum the compiled graph reports. Only WorkflowNodeKind.Agent and WorkflowNodeKind.Function are valid here — the other members (Orchestration, RequestPort, Output) describe nodes the compiler adds on its own; a definition never names one directly.

Constructors

WorkflowNodeReference()

public WorkflowNodeReference()

Properties

AgentVersion

Gets the version of the agent this step runs. null (the default) runs the agent’s current version, resolved each time the step runs.

public int? AgentVersion { get; init; }

Property Value

int?

Remarks

Only for WorkflowNodeKind.Agent. A function node that carries a version, and a version below 1, are refused when the definition is saved (400). So is a version the agent does not have, and an agent defined in code, which keeps no version history. The check is repeated when the workflow is compiled: the agent can be deleted after the workflow was saved.

A pinned step runs that version’s instructions, model and tools, and its child run row records that version. The step still resolves late, so the pin holds across edits of the agent; it is the way to keep a production chain on text that was tested while the agent is being edited.

The pin is not part of the node’s identity: changing it does not stop a run that waits for input from being resumed. Only a definition that lists WorkflowDefinition.Nodes can pin a version; an agent-only chain written as WorkflowDefinition.AgentNames cannot, and the console writes the nodes form as soon as one step is pinned.

A pin does not reach into the agent’s own sub-agents or skills: they resolve the current version, as they do for a direct run.

Kind

Gets which registry Name is looked up in.

public required WorkflowNodeKind Kind { get; init; }

Property Value

WorkflowNodeKind

Name

Gets the referenced name: an agent name from the catalog when WorkflowNodeReference.Kind is WorkflowNodeKind.Agent, or a function name from the code registry when it is WorkflowNodeKind.Function.

public required string Name { get; init; }

Property Value

string

Settings

Gets the function node’s settings: a JSON object checked against the settings type the function declares. null means the node carries no settings. Only for WorkflowNodeKind.Function; an agent node that carries settings is refused when the definition is saved.

public JsonElement? Settings { get; init; }

Property Value

JsonElement?

Remarks

Settings are values, not expressions. The function’s code declares the shape (the TSettings type of AddWorkflowFunction<TInput, TOutput, TSettings>); an operator only writes values for it. A value is not substituted from a run parameter - a function that needs a run’s value reads it itself.

Never write a secret here. The settings are stored in the definition, in the audit trail, and are returned to every caller who can read the workflow. Where a function needs a credential, the settings carry the name of the configuration key and the function reads the value from IConfiguration itself.

A value of JsonValueKind.Undefined or JsonValueKind.Null is read as null. An unset JsonElement cannot be written as JSON, and one such node would fail the whole workflow list.

Timeout

Gets the longest time one call of this node may take. null (the default) uses the node’s default: the timeout its function was registered with, or the installation’s Tracon:AgentGraph:ChildDeadline for an agent node.

public TimeSpan? Timeout { get; init; }

Property Value

TimeSpan?

Remarks

A function node that does not return in time is cancelled: the token its handler was given is cancelled, the run stops waiting for it, and the run ends RunStatus.Failed with the error type workflow_function_timeout (TraconWorkflowFunctionTimeoutException). No later node runs. A handler that ignores its token keeps running in the background until it returns; what it returns then is discarded and logged. With a retry policy, the timeout applies to each attempt, and a timed-out attempt is retried like any other transient failure.

An agent node replaces Tracon:AgentGraph:ChildDeadline for this step only, and the hard cutoff for an agent that ignores its token is this value plus 30 seconds. A step that does not answer in time fails the run with child_run_timeout (TraconChildRunTimeoutException).

Must be from one millisecond to about 49.7 days; an agent node allows 30 seconds less, for its hard cutoff. A value outside that range is refused when the definition is saved (400). It is not checked against the run’s own timeout (WorkflowDefinition.RunTimeout): whichever ends first stops the node, and a run that reaches its own deadline ends RunStatus.Canceled, not with this node’s timeout.

The timeout is not part of the node’s identity: changing it does not stop a run that waits for input from being resumed. The resumed run uses the value of the definition version it recorded; a resume that names a newer version (WorkflowResumeRequest.DefinitionVersion) uses that version’s.

Methods

Equals(object?)

public override bool Equals(object? obj)

Parameters

obj object?

Returns

bool

Equals(WorkflowNodeReference?)

public bool Equals(WorkflowNodeReference? other)

Parameters

other WorkflowNodeReference?

Returns

bool

GetHashCode()

public override int GetHashCode()

Returns

int

ToString()

public override string ToString()

Returns

string

Operators

operator ==(WorkflowNodeReference?, WorkflowNodeReference?)

public static bool operator ==(WorkflowNodeReference? left, WorkflowNodeReference? right)

Parameters

left WorkflowNodeReference?

right WorkflowNodeReference?

Returns

bool

operator !=(WorkflowNodeReference?, WorkflowNodeReference?)

public static bool operator !=(WorkflowNodeReference? left, WorkflowNodeReference? right)

Parameters

left WorkflowNodeReference?

right WorkflowNodeReference?

Returns

bool