TraconAgentGraphOptions

Namespace Tracon · Assembly Tracon.Core.dll

Defines limits that apply when an agent calls another agent.

public sealed class TraconAgentGraphOptions

Inheritance

object ← TraconAgentGraphOptions

Inherited Members

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

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, 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. A chain that cannot be read does not start with a budget of zero: the run ends Failed before its first node.

Constructors

TraconAgentGraphOptions()

public TraconAgentGraphOptions()

Properties

ChildDeadline

Gets or sets the deadline applied to a single sub-agent call (the cooperative layer). Overridable per agent with SubAgentSettings.ChildDeadline.

public TimeSpan ChildDeadline { get; set; }

Property Value

TimeSpan

Remarks

Unlike TraconAgentGraphOptions.MaxDuration, this default intentionally exists and is non-zero, the same reasoning as TraconAgentGraphOptions.MaxDepth and 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.

MaxDepth

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

public int MaxDepth { get; set; }

Property Value

int

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.

public TimeSpan MaxDuration { get; set; }

Property Value

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.

MaxTotalCost

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

public decimal MaxTotalCost { get; set; }

Property Value

decimal

Remarks

Unlike TraconAgentGraphOptions.MaxTotalTokens, this has no default: pricing is not always known (PricingSource.Unknown), 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 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) all start before any of them reports; an installation that needs the ceiling to hold turns concurrent calls off.

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.

public int MaxTotalRuns { get; set; }

Property Value

int

MaxTotalTokens

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

public long MaxTotalTokens { get; set; }

Property Value

long

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.

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; overridable per agent with SubAgentSettings.WaitTimeout.

public TimeSpan WaitTimeout { get; set; }

Property Value

TimeSpan

Remarks

When never set explicitly, this tracks TraconAgentGraphOptions.ChildDeadline plus a fixed 30-second pad — raising TraconAgentGraphOptions.ChildDeadline alone keeps the hard cutoff strictly after the cooperative one by construction, exactly the guarantee Tracon.TraconOptionsValidator checks. Setting this property pins it to that value instead. A TraconAgentGraphOptions.ChildDeadline within TraconAgentGraphOptions.WaitTimeoutPad of TimeSpan.MaxValue clamps the derived value to TimeSpan.MaxValue rather than overflowing — the same “an absurd duration behaves as practically unlimited, not a crash” convention AgentRunBudget uses for its own deadline.

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

Methods

CreateBudget(TimeProvider)

Creates a tree budget from these options.

public AgentRunBudget CreateBudget(TimeProvider timeProvider)

Parameters

timeProvider TimeProvider

The time source AgentRunBudget.Deadline is computed from.

Returns

AgentRunBudget

The budget that the root run shares through its tree.