# WorkflowNodeReference

> 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.workflownodereference/
> Summary: WorkflowNodeReference: Points to a single node entering a workflow's graph: an agent from the catalog, or a function registered in code.

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

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

```csharp
public sealed record WorkflowNodeReference : IEquatable<WorkflowNodeReference>
```

<dl class="api-relations"><dt>Inheritance</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object">object</a> ← <a href="/api/tracon.workflownodereference/">WorkflowNodeReference</a></dd><dt>Implements</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.iequatable-1">IEquatable&lt;WorkflowNodeReference&gt;</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

Used only by [WorkflowKind.Sequential](/api/tracon.workflowkind/) definitions that mix
agent and function nodes. A definition that uses only agents may keep using
[WorkflowDefinition.AgentNames](/api/tracon.workflowdefinition/#Tracon_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](/api/tracon.workflowdefinition/#Tracon_WorkflowDefinition_Nodes) only when the chain holds at least one
function node.

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

## Constructors

### <a id="Tracon_WorkflowNodeReference__ctor"></a> WorkflowNodeReference\(\)

```csharp
public WorkflowNodeReference()
```

## Properties

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

Gets the version of the agent this step runs. [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) (the default)
runs the agent's current version, resolved each time the step runs.

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

#### Property Value

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

#### Remarks

Only for [WorkflowNodeKind.Agent](/api/tracon.workflownodekind/). 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](/api/tracon.workflowdefinition/#Tracon_WorkflowDefinition_Nodes)
can pin a version; an agent-only chain written as
[WorkflowDefinition.AgentNames](/api/tracon.workflowdefinition/#Tracon_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.

### <a id="Tracon_WorkflowNodeReference_Kind"></a> Kind

Gets which registry `Name` is looked up in.

```csharp
public required WorkflowNodeKind Kind { get; init; }
```

#### Property Value

 [WorkflowNodeKind](/api/tracon.workflownodekind/)

### <a id="Tracon_WorkflowNodeReference_Name"></a> Name

Gets the referenced name: an agent name from the catalog when
[WorkflowNodeReference.Kind](/api/tracon.workflownodereference/#Tracon_WorkflowNodeReference_Kind) is [WorkflowNodeKind.Agent](/api/tracon.workflownodekind/), or a
function name from the code registry when it is
[WorkflowNodeKind.Function](/api/tracon.workflownodekind/).

```csharp
public required string Name { get; init; }
```

#### Property Value

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

### <a id="Tracon_WorkflowNodeReference_Settings"></a> Settings

Gets the function node's settings: a JSON object checked against the
settings type the function declares. [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) means the node
carries no settings. Only for [WorkflowNodeKind.Function](/api/tracon.workflownodekind/); an
agent node that carries settings is refused when the definition is saved.

```csharp
public JsonElement? Settings { get; init; }
```

#### Property Value

 [JsonElement](https://learn.microsoft.com/dotnet/api/system.text.json.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](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null). An
unset [JsonElement](https://learn.microsoft.com/dotnet/api/system.text.json.jsonelement) cannot be written as JSON, and one such
node would fail the whole workflow list.

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

Gets the longest time one call of this node may take. [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/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.

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

#### Property Value

 [TimeSpan](https://learn.microsoft.com/dotnet/api/system.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](/api/tracon.runstatus/) with the error type
`workflow_function_timeout` ([TraconWorkflowFunctionTimeoutException](/api/tracon.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](/api/tracon.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](/api/tracon.workflowdefinition/#Tracon_WorkflowDefinition_RunTimeout)): whichever ends first
stops the node, and a run that reaches its own deadline ends
[RunStatus.Canceled](/api/tracon.runstatus/), 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](/api/tracon.workflowresumerequest/#Tracon_WorkflowResumeRequest_DefinitionVersion)) uses that version's.

## Methods

### <a id="Tracon_WorkflowNodeReference_Equals_System_Object_"></a> Equals\(object?\)

```csharp
public override bool Equals(object? obj)
```

#### Parameters

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

#### Returns

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

### <a id="Tracon_WorkflowNodeReference_Equals_Tracon_WorkflowNodeReference_"></a> Equals\(WorkflowNodeReference?\)

```csharp
public bool Equals(WorkflowNodeReference? other)
```

#### Parameters

`other` [WorkflowNodeReference](/api/tracon.workflownodereference/)?

#### Returns

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

### <a id="Tracon_WorkflowNodeReference_GetHashCode"></a> GetHashCode\(\)

```csharp
public override int GetHashCode()
```

#### Returns

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

### <a id="Tracon_WorkflowNodeReference_ToString"></a> ToString\(\)

```csharp
public override string ToString()
```

#### Returns

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

## Operators

### <a id="Tracon_WorkflowNodeReference_op_Equality_Tracon_WorkflowNodeReference_Tracon_WorkflowNodeReference_"></a> operator ==\(WorkflowNodeReference?, WorkflowNodeReference?\)

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

#### Parameters

`left` [WorkflowNodeReference](/api/tracon.workflownodereference/)?

`right` [WorkflowNodeReference](/api/tracon.workflownodereference/)?

#### Returns

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

### <a id="Tracon_WorkflowNodeReference_op_Inequality_Tracon_WorkflowNodeReference_Tracon_WorkflowNodeReference_"></a> operator \!=\(WorkflowNodeReference?, WorkflowNodeReference?\)

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

#### Parameters

`left` [WorkflowNodeReference](/api/tracon.workflownodereference/)?

`right` [WorkflowNodeReference](/api/tracon.workflownodereference/)?

#### Returns

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)