# TraconAgentGraphOptions

> 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.traconagentgraphoptions/
> Summary: TraconAgentGraphOptions: Defines limits that apply when an agent calls another agent.

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

Defines limits that apply when an agent calls another agent.

```csharp
public sealed class TraconAgentGraphOptions
```

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

Child-agent calls **multiply** cost because every layer makes its
own model calls. Without limits, one incorrectly written definition can start
dozens of runs for one request. Depth, token, and count limits therefore have defaults.

Limits apply *per tree*: the root run creates an
[AgentRunBudget](/api/tracon.agentrunbudget/), and every run in the tree shares it.

For a workflow, the tree is the *logical run*: a run that continues an earlier
one (a person's answer to a request, an operator's resume, a recovery after an
interruption) starts from what the earlier runs of the chain spent, and from the time
they were executing. A workflow with a human approval loop does not get the whole
limit again with every answer. The time a workflow waited for a person does not count
against [TraconAgentGraphOptions.MaxDuration](/api/tracon.traconagentgraphoptions/#Tracon_TraconAgentGraphOptions_MaxDuration). A chain that cannot be read does not start with a
budget of zero: the run ends `Failed` before its first node.

## Constructors

### <a id="Tracon_TraconAgentGraphOptions__ctor"></a> TraconAgentGraphOptions\(\)

```csharp
public TraconAgentGraphOptions()
```

## Properties

### <a id="Tracon_TraconAgentGraphOptions_ChildDeadline"></a> ChildDeadline

Gets or sets the deadline applied to a single sub-agent call (the
cooperative layer). Overridable per agent with [SubAgentSettings.ChildDeadline](/api/tracon.subagentsettings/#Tracon_SubAgentSettings_ChildDeadline).

```csharp
public TimeSpan ChildDeadline { get; set; }
```

#### Property Value

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

#### Remarks

Unlike [TraconAgentGraphOptions.MaxDuration](/api/tracon.traconagentgraphoptions/#Tracon_TraconAgentGraphOptions_MaxDuration), this default intentionally
*exists* and is non-zero, the same reasoning as [TraconAgentGraphOptions.MaxDepth](/api/tracon.traconagentgraphoptions/#Tracon_TraconAgentGraphOptions_MaxDepth)
and [TraconAgentGraphOptions.MaxTotalTokens](/api/tracon.traconagentgraphoptions/#Tracon_TraconAgentGraphOptions_MaxTotalTokens): an unlimited installation learns about
its first hanging sub-agent call from a stuck tree, not from a setting.

Must be from one millisecond to about 49.7 days; any other value fails at startup.

### <a id="Tracon_TraconAgentGraphOptions_MaxDepth"></a> MaxDepth

Gets or sets the largest allowed call depth. The root run has depth zero,
so the default allows a three-layer tree.

```csharp
public int MaxDepth { get; set; }
```

#### Property Value

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

### <a id="Tracon_TraconAgentGraphOptions_MaxDuration"></a> MaxDuration

Gets or sets the wall-clock time the whole tree may take, counted from
the root run's start. Zero or a negative value removes the limit.

```csharp
public TimeSpan MaxDuration { get; set; }
```

#### Property Value

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

#### Remarks

Unlike the other three dimensions, this has no non-zero default: an
eval run and a chat turn do not run on the same time scale, so there is
no one duration every installation should be silently held to.

The cutoff always lands between two model turns; a tool call already in
progress when the deadline passes is **not** interrupted
and runs to completion. The same holds for a workflow function node: once the
deadline has passed, the next node does not start, and one that is already
running is not stopped. A tool call that has not started when the deadline has
passed does not start either. See [AgentRunBudget](/api/tracon.agentrunbudget/).

### <a id="Tracon_TraconAgentGraphOptions_MaxTotalCost"></a> MaxTotalCost

Gets or sets the largest amount a tree can spend. Zero or a negative
value removes the limit.

```csharp
public decimal MaxTotalCost { get; set; }
```

#### Property Value

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

#### Remarks

Unlike [TraconAgentGraphOptions.MaxTotalTokens](/api/tracon.traconagentgraphoptions/#Tracon_TraconAgentGraphOptions_MaxTotalTokens), this has no default: pricing is not
always known ([PricingSource.Unknown](/api/tracon.pricingsource/)), so a cost cap must
be an explicit opt-in, not a value every installation is silently held to.

Once the tree has spent this amount, the next model call is refused and so is the
next workflow function node: it does not start, and the run ends `Failed` with
`run_budget_exceeded`. A node that is already running is not stopped, so the
tree can pass the ceiling by as much as its last node spends. What a node reported
beyond tokens counts. A node that must still run after the ceiling is passed sets
`WorkflowFunctionOptions.StartsWhenBudgetIsSpent`.

A tool call does not start either. When one model turn asks for two paid tools and
the first passes the ceiling, the second is not run: its result would be read only by
a model call that is refused. The result of a refused call is a sentence that says the
call did not start, and a streaming run records the call as failed. A tool that has
started is never stopped, and what it
reported through [TraconToolUsage](/api/tracon.tracontoolusage/) counts the moment it is reported, so
the call that crosses the ceiling is the last one that starts. Tool calls that start
together ([ToolLoopSettings.AllowConcurrentToolCalls](/api/tracon.toolloopsettings/#Tracon_ToolLoopSettings_AllowConcurrentToolCalls)) all start before
any of them reports; an installation that needs the ceiling to hold turns concurrent
calls off.

### <a id="Tracon_TraconAgentGraphOptions_MaxTotalRuns"></a> MaxTotalRuns

Gets or sets the largest number of *child* runs a tree can start.
The root run does not count. Zero or a negative value removes the limit.

```csharp
public int MaxTotalRuns { get; set; }
```

#### Property Value

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

### <a id="Tracon_TraconAgentGraphOptions_MaxTotalTokens"></a> MaxTotalTokens

Gets or sets the largest token count that a tree can spend. Zero or a
negative value removes the limit.

```csharp
public long MaxTotalTokens { get; set; }
```

#### Property Value

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

#### Remarks

The default intentionally *exists*. An unlimited installation learns
about its first invalid definition from the bill.

Once the tree has spent this many tokens, the next model call is refused, and so is
every tool call that has not started: the tool's result would be read only by a model
call that is refused. The result of a refused call is a sentence that says the call
did not start, and the run ends `Failed` with `run_budget_exceeded` at its
next model call. A workflow
function node is not stopped by this limit, since it spends no tokens.

### <a id="Tracon_TraconAgentGraphOptions_WaitTimeout"></a> WaitTimeout

Gets or sets the hard wait cutoff for a sub-agent call that ignores
cancellation (the hard-cutoff layer). Must be greater than
[TraconAgentGraphOptions.ChildDeadline](/api/tracon.traconagentgraphoptions/#Tracon_TraconAgentGraphOptions_ChildDeadline); overridable per agent with
[SubAgentSettings.WaitTimeout](/api/tracon.subagentsettings/#Tracon_SubAgentSettings_WaitTimeout).

```csharp
public TimeSpan WaitTimeout { get; set; }
```

#### Property Value

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

#### Remarks

When never set explicitly, this tracks [TraconAgentGraphOptions.ChildDeadline](/api/tracon.traconagentgraphoptions/#Tracon_TraconAgentGraphOptions_ChildDeadline) plus
a fixed 30-second pad — raising [TraconAgentGraphOptions.ChildDeadline](/api/tracon.traconagentgraphoptions/#Tracon_TraconAgentGraphOptions_ChildDeadline) alone keeps
the hard cutoff strictly after the cooperative one by construction,
exactly the guarantee [Tracon.TraconOptionsValidator](/api/tracon/) checks.
Setting this property pins it to that value instead. A
[TraconAgentGraphOptions.ChildDeadline](/api/tracon.traconagentgraphoptions/#Tracon_TraconAgentGraphOptions_ChildDeadline) within [TraconAgentGraphOptions.WaitTimeoutPad](/api/tracon.traconagentgraphoptions/) of
[TimeSpan.MaxValue](https://learn.microsoft.com/dotnet/api/system.timespan) clamps the derived value to
[TimeSpan.MaxValue](https://learn.microsoft.com/dotnet/api/system.timespan) rather than overflowing — the same
"an absurd duration behaves as practically unlimited, not a crash"
convention [AgentRunBudget](/api/tracon.agentrunbudget/) uses for its own deadline.

Must be from one millisecond to about 49.7 days; any other value fails at startup.

## Methods

### <a id="Tracon_TraconAgentGraphOptions_CreateBudget_System_TimeProvider_"></a> CreateBudget\(TimeProvider\)

Creates a tree budget from these options.

```csharp
public AgentRunBudget CreateBudget(TimeProvider timeProvider)
```

#### Parameters

`timeProvider` [TimeProvider](https://learn.microsoft.com/dotnet/api/system.timeprovider)

The time source [AgentRunBudget.Deadline](/api/tracon.agentrunbudget/#Tracon_AgentRunBudget_Deadline) is computed from.

#### Returns

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

The budget that the root run shares through its tree.