# TraconRunOptions

> 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.traconrunoptions/
> Summary: TraconRunOptions: Run options that let the caller determine a run's identifier, its place in the tree, and its budget.

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

Run options that let the caller determine a run's identifier, its place
in the tree, and its budget.

```csharp
public sealed class TraconRunOptions : AgentRunOptions
```

<dl class="api-relations"><dt>Inheritance</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object">object</a> ← AgentRunOptions ← <a href="/api/tracon.traconrunoptions/">TraconRunOptions</a></dd><dt>Inherited Members</dt><dd>AgentRunOptions.Clone(), AgentRunOptions.ContinuationToken, AgentRunOptions.AllowBackgroundResponses, AgentRunOptions.AdditionalProperties, AgentRunOptions.ResponseFormat, <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

The wrapper writing the run record normally generates its own identifier
and does not report it outward. A streaming endpoint, however, must know
the identifier **before the first frame**: only then can the
client associate the streamed response with the run record. Having the
caller generate the identifier solves this without an extra notification
channel or ambient state, and follows the same approach as
[RunStartInfo.RunId](/api/tracon.runstartinfo/#Tracon_RunStartInfo_RunId).

The [TraconRunOptions.ParentRunId](/api/tracon.traconrunoptions/#Tracon_TraconRunOptions_ParentRunId), [TraconRunOptions.RootRunId](/api/tracon.traconrunoptions/#Tracon_TraconRunOptions_RootRunId), [TraconRunOptions.Depth](/api/tracon.traconrunoptions/#Tracon_TraconRunOptions_Depth),
and [TraconRunOptions.Budget](/api/tracon.traconrunoptions/#Tracon_TraconRunOptions_Budget) fields are filled in by `ChildAgentInvoker`
when an agent calls another agent. They do not need to be filled in by
hand; if they are, the run is placed at the specified spot in the tree.

This type *carries no* public `ChatOptions`. Tracon's own
endpoints resolve the model options from the agent definition, so a run that
starts at an endpoint cannot change them. Code that runs an agent directly can
pass Microsoft Agent Framework's `ChatClientAgentRunOptions` instead; that
run then has no identifier, tree position, or budget that the caller sets. The
run-recording wrapper refuses such options when they set what the definition
owns (the model, sampling, the response format, a chat client factory, or a
tool that runs); it accepts added instructions and tool declarations.

Only the outermost run-recording wrapper reads this type. It hands the
agents inside it a plain `AI.AgentRunOptions` that carries the base
properties (a `ChatClientAgentRunOptions` when a workflow step was given
model options for the run), and the run's identity reaches them through
`TraconRunContext`. Microsoft Agent Framework's function-invocation
middleware rejects any other options type, so an `IAgentDecorator`
that adds it must have an `Order` above 0.

## Constructors

### <a id="Tracon_TraconRunOptions__ctor"></a> TraconRunOptions\(\)

Creates a new options object.

```csharp
public TraconRunOptions()
```

## Properties

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

The definition version this run measures. If [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null),
the wrapper uses the (current) version from the agent's catalog
summary. For runs resolved by an A/B experiment, this field is
filled in because the compiled agent's *actual* version may
differ from the current one.

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

#### Property Value

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

### <a id="Tracon_TraconRunOptions_BeforePendingApprovalIsPublished"></a> BeforePendingApprovalIsPublished

Gets the work that must be DONE AND VISIBLE before the run is closed with
[RunStatus.AwaitingApproval](/api/tracon.runstatus/).

```csharp
public Func<IEnumerable<ChatMessage>, IReadOnlyDictionary<string, ToolApprovalPresentation?>, CancellationToken, ValueTask>? BeforePendingApprovalIsPublished { get; init; }
```

#### Property Value

 [Func](https://learn.microsoft.com/dotnet/api/system.func\-4)<[IEnumerable](https://learn.microsoft.com/dotnet/api/system.collections.generic.ienumerable\-1)<ChatMessage\>, [IReadOnlyDictionary](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlydictionary\-2)<[string](https://learn.microsoft.com/dotnet/api/system.string), [ToolApprovalPresentation](/api/tracon.toolapprovalpresentation/)?\>, [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken), [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask)\>?

#### Remarks

[RunStatus.AwaitingApproval](/api/tracon.runstatus/) is TERMINAL and is the signal a
consumer polls on. Whoever records the pending approval does so AFTER the
agent call returns — but the run is closed INSIDE that call, so without this
hook the status is published first and `GET /api/approvals/pending`
answers an empty list for a run that already says it is waiting. The window
was not a race: the order was fixed, so it was open on every such run.

The callback receives the messages the run produced and runs on BOTH the
buffered and the streaming path, immediately before the terminal status is
written. It runs only when the run actually ends by requesting approval;
anything it throws fails the run, which is correct — a published
[RunStatus.AwaitingApproval](/api/tracon.runstatus/) whose approval was never recorded
is unanswerable.

The second parameter carries the [ToolApprovalPresentation](/api/tracon.toolapprovalpresentation/) already
resolved for each pending request, keyed by `ToolApprovalRequestContent.RequestId`
— the same resolution the closing run event's payload was built from. A caller that
also persists a [PendingApproval](/api/tracon.pendingapproval/) row (as `AgentRunJobHandler` does)
reads the presentation from here instead of resolving it a second time.

### <a id="Tracon_TraconRunOptions_Budget"></a> Budget

The budget **shared** across the tree. If
[null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null), the wrapper opening the root run produces a
budget from its settings.

```csharp
public AgentRunBudget? Budget { get; init; }
```

#### Property Value

 [AgentRunBudget](/api/tracon.agentrunbudget/)?

#### Remarks

The object is the *same instance* at every run in the tree. If
it were copied, each branch would get its own budget and the limit
would lose its meaning.

### <a id="Tracon_TraconRunOptions_ContinuedFromRunId"></a> ContinuedFromRunId

If this run continues an interrupted run, the interrupted run's
identifier. The value is written to the `runs.continued_from_run_id` column.

```csharp
public Guid? ContinuedFromRunId { get; init; }
```

#### Property Value

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

#### Remarks

This field is meaningful only for the **root** run; a
continuation's child calls do not carry their own lineage.

### <a id="Tracon_TraconRunOptions_Depth"></a> Depth

The depth in the tree. The root run is 0.

```csharp
public int Depth { get; init; }
```

#### Property Value

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

### <a id="Tracon_TraconRunOptions_ExperimentId"></a> ExperimentId

The identifier of the experiment this run belongs to. [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) for a non-experiment run.

```csharp
public Guid? ExperimentId { get; init; }
```

#### Property Value

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

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

This run's kind. If [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null), the wrapper assumes
[RunKind.Agent](/api/tracon.runkind/).

```csharp
public RunKind? Kind { get; init; }
```

#### Property Value

 [RunKind](/api/tracon.runkind/)?

#### Remarks

The eval job processor gives [RunKind.Eval](/api/tracon.runkind/) for
every case run; this lets [IRunStore.GetStatisticsAsync](/api/tracon.irunstore/#Tracon_IRunStore_GetStatisticsAsync_Tracon_RunStatisticsQuery_System_Threading_CancellationToken_)
exclude these synthetic calls from the summary.

### <a id="Tracon_TraconRunOptions_ParentRunId"></a> ParentRunId

The identifier of the run that started this run. [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null)
for the root run.

```csharp
public Guid? ParentRunId { get; init; }
```

#### Property Value

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

### <a id="Tracon_TraconRunOptions_ReplayOfRunId"></a> ReplayOfRunId

If this run is a replay, the source run's identifier. The
value is written to the `runs.replay_of_run_id` column.

```csharp
public Guid? ReplayOfRunId { get; init; }
```

#### Property Value

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

#### Remarks

This field is meaningful only for the **root** run; a
replay's child calls do not carry their own lineage.

### <a id="Tracon_TraconRunOptions_RootRunId"></a> RootRunId

The identifier of the run at the root of the tree. [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) if the
run itself is the root.

```csharp
public Guid? RootRunId { get; init; }
```

#### Property Value

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

#### Remarks

The value is denormalized: fetching a whole tree through [TraconRunOptions.ParentRunId](/api/tracon.traconrunoptions/#Tracon_TraconRunOptions_ParentRunId) would require a recursive query; a single indexed query on
the root identifier is enough.

### <a id="Tracon_TraconRunOptions_RunId"></a> RunId

The run identifier to use. If [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null), the identifier
is generated by the wrapper that writes the run record.

```csharp
public Guid? RunId { get; init; }
```

#### Property Value

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

#### Remarks

The value must be time-ordered; `TraconId.NewId` ensures
this. A random identifier produced by `Guid.NewGuid` fragments
the storage index.

### <a id="Tracon_TraconRunOptions_SessionId"></a> SessionId

The identifier of the session at the root of the tree. Filled in for child runs;
the root run reads its identifier from its own `AgentSession`.

```csharp
public string? SessionId { get; init; }
```

#### Property Value

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

#### Remarks

This field only feeds `AgentRunScope.SessionId`; it **does not
change** a run record's `session_id` column. The two concepts are
separate: the column says "the run was started with this session," while the
scope says "content produced here belongs to this session." On a child agent
call, MAF passes no session, but the produced attachment still belongs to the
root session.

This matters for retention: an attachment written without a session counts as
orphaned, and the retention policy deletes it.

### <a id="Tracon_TraconRunOptions_Variant"></a> Variant

The name of the experiment variant this run is assigned to. [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) for a non-experiment run.

```csharp
public string? Variant { get; init; }
```

#### Property Value

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

## Methods

### <a id="Tracon_TraconRunOptions_Clone"></a> Clone\(\)

Produces a clone of the current `AI.AgentRunOptions` instance.

```csharp
public override AgentRunOptions Clone()
```

#### Returns

 AgentRunOptions

A clone of the current `AI.AgentRunOptions` instance.

#### Remarks

The clone will have the same values for all properties as the original instance. Any collections, like `AgentRunOptions.AdditionalProperties`,
are shallow-cloned, meaning a new collection instance is created, but any references contained by the collections are shared with the original.

Derived types should override `AgentRunOptions.Clone` to return an instance of the derived type.