The Agent Definition bounds work; the application chooses limits appropriate to its model
and tools. A durable Run keeps cumulative accounting across replacement Attempts.
Model-context capacity and Thread history are separate from those execution budgets.
Pass a partial policy to Agent.make. Omitted fields use standalone defaults; delegated
children can inherit the parent’s policy within their delegation ceilings.
Option
Default
Meaning
maxTurns
12
Model turns per Run; null disables the count ceiling
maxToolCalls
24
Tool calls, including programmatic calls; null disables the count ceiling
maxDuration
"5 minutes"
Ordinary Run deadline; active Attempt deadline for durable execution
toolConcurrency
4
Parallel application handlers per batch
repeatedFailureLimit
3
Consecutive terminal tool failures
onExhaustion
"final-answer"
Turn, tool-call, and token exhaustion behavior
tokenBudget
Unset
Cumulative input and output tokens
costBudgetMicrousd
Unset
Estimated cost in millionths of a US dollar
completionReserveTokens
20% of tokenBudget, capped at 4,096; 4,096 without a token budget
Capacity reserved for final delivery
contextTokenLimit
Unset
Estimated live context that triggers compaction
toolResultBounds.maxBytes
51,200
Encoded bytes per application tool result
runStatus
"off"
Set "appended" for a derived status message in model requests
restartOnJoinedInput
Off
Replace a disposable model call on joined input, at most twice per Run
modelRetries
0
Retry a qualifying model failure before content arrives
Validate an agent ID and return a shallowly frozen, model-agnostic definition.
make("researcher",{
DefinitionOptions<String,Struct<{ readonlyanswer:String; }>,"Answer from the available evidence.",Toolkit<{}>,undefined,undefined,undefined>.input: Schema.String
input:
importSchema
Schema.
constString:Schema.String
Type-level representation of
String
.
Schema for string values. Validates that the input is typeof"string".
@stability ― stable
@category ― models
@since ― 4.0.0
@stability ― stable
@category ― schemas
@since ― 4.0.0
String,
DefinitionOptions<String,Struct<{ readonlyanswer:String; }>,"Answer from the available evidence.",Toolkit<{}>,undefined,undefined,undefined>.output: Schema.Struct<{
readonlyanswer:Schema.String;
}>
output:
importSchema
Schema.
functionStruct<{
readonlyanswer:Schema.String;
}>(fields:{
readonlyanswer:Schema.String;
}):Schema.Struct<{
readonlyanswer:Schema.String;
}>
Defines a struct schema from a map of field schemas.
Details
Each field value is a schema. Use
optionalKey
or
optional
to
mark fields as optional, and
mutableKey
to mark them as mutable.
The resulting schema's Type is a readonly object type with the fields'
decoded types. The Encoded form mirrors the field schemas' encoded types.
Declared fields may be inherited and are copied to own properties in the
output. The __proto__ field is accepted only when it is an own property.
Parsing does not guarantee that output keys retain their input order.
Schema for string values. Validates that the input is typeof"string".
@stability ― stable
@category ― models
@since ― 4.0.0
@stability ― stable
@category ― schemas
@since ― 4.0.0
String}),
DefinitionOptions<String,Struct<{ readonlyanswer:String; }>,"Answer from the available evidence.",Toolkit<{}>,undefined,undefined,undefined>.instructions: "Answer from the available evidence."
instructions:"Answer from the available evidence.",
DefinitionOptions<String,Struct<{ readonlyanswer:String; }>,"Answer from the available evidence.",Toolkit<{}>,undefined,undefined,undefined>.toolkit: Toolkit.Toolkit<{}>
toolkit:
importToolkit
Toolkit.
constempty:Toolkit.Toolkit<{}>
An empty toolkit with no tools.
When to use
Use when you need an empty starting point for building toolkits or a default
toolkit value that can be extended with merge.
@stability ― unstable
@category ― constructors
@since ― 4.0.0
empty,
DefinitionOptions<String,Struct<{ readonlyanswer:String; }>,"Answer from the available evidence.",Toolkit<{}>,undefined,undefined,undefined>.policy?:Partial<Readonly<Omit<{
readonlyrunStatus:"appended"|"off";
readonlymaxTurns:number;
readonlymaxToolCalls:number;
readonlymaxDuration:Duration;
readonlytoolConcurrency:number;
readonlyrepeatedFailureLimit:number;
readonlyonExhaustion:"final-answer"|"fail";
readonlycompletionReserveTokens:number;
readonlytoolResultBounds:ToolResultBounds;
readonlycompaction:CompactionPolicy;
readonlytokenBudget?:number|undefined;
readonlycostBudgetMicrousd?:number|undefined;
readonlycontextTokenLimit?:number|undefined;
readonlyrestartOnJoinedInput?:boolean|undefined;
readonlymodelRetries?:number|undefined;
},"runStatus"| ... 7more... |"compaction">&{
...;
}>>|undefined
policy:{
maxTurns?:number|null|undefined
Maximum model turns, or null to leave turn count unbounded.
maxTurns:8,
maxToolCalls?:number|null|undefined
Maximum declared and programmatic Tool Calls, or null to leave count unbounded.
maxToolCalls:16,
maxDuration?:Input|undefined
Finite, positive wall-clock duration accepted in any Effect Duration input form.
maxDuration:"2 minutes",
tokenBudget?:number|undefined
Observed cumulative usage can cross this threshold before exhaustion is handled.
tokenBudget:80_000,
contextTokenLimit?:number|undefined
Per-model-call live-context bound; crossing it triggers compaction rather than failure.
contextTokenLimit:32_000,
completionReserveTokens?:number|undefined
Tokens reserved for final delivery; defaults to 20% of tokenBudget, capped at 4,096.
Use maxTurns: null and maxToolCalls: null when the host owns the Run lifetime through
its finite duration and cancellation. Omitted counts retain the defaults above. JSON preserves
null; a resolved AgentPolicy exposes disabled counts as Infinity. Per-Run allowances can
still tighten them. An unbounded parent must supply an explicit finite delegation policy for
subagent reservations.
onExhaustion: "final-answer" allows at most one constrained finalization opportunity for
turn, tool-call, or token exhaustion. A designated completion tool remains required.
A completed result carries
finishReason: "budget-exhausted" and the exhausted dimension. Use "fail" when a partial
answer is not acceptable. Duration, estimated cost, and repeated failure limits always fail.
When a failed completion cannot be corrected because the next turn is exhausted, the policy
error retains its original cause for private diagnostic capture. toolFailureObserverLayer
also observes parameter rejections and returned tool failures with their original causes,
including failures that the model later recovers from.
Usage is measured at response boundaries and can cross a threshold. These budgets are not
prepaid provider spending caps. A strict monetary ceiling requires host admission that reserves
possible charges before calling the provider. Cost budgets require the host’s
estimateCostMicrousd; a missing estimator or unknown pricing fails with a typed cost-policy error.
The estimator receives one request with usage, provider, and model, plus optional
response, finishMetadata, purpose, and webSearchCalls. It returns an Effect containing
{ costMicrousd, pricingStatus?, serviceTier?, pricingVersion? }.
Durable maxDuration uses the original allowance for each active Attempt; eviction,
suspension, and missing-binding waits do not consume it. An actual duration exhaustion remains
terminal across recovery. Other cumulative counters do not reset.
modelRetries applies only before content, for retryable failures. Hosted tools must all be
marked readonly. Backoff counts toward the active deadline; streamed content prevents retry.
turnAllowance and toolCallAllowance can tighten one Run’s policy, never raise it.
Set scheduling: { runOverride: 1 } on a Run to execute its application tools sequentially.
runOverride accepts a positive integer and only tightens policy.toolConcurrency.
Tools that require sequential execution still run alone within their batch.
Subagents reserve from a shared pool with their own count, concurrency, duration, and result
bounds. Unknown usage stays charged conservatively. See the subagent reference.
Optional usage-budget hooks share accounting across application scopes such as tenant and
Thread; the application owns their accounting period. Code Mode separately bounds inner host
calls; its default concurrency is four.
See Code Mode for its caller-visible limits.
Distinct application tool-call IDs per durable Run
4,096
Thread history has no lifetime quota; these bounds apply per payload, Turn or Run.
Reservations can refuse a dispatch before its byte ceiling to retain room for outcomes and
failure settlement. These limits do not replace model context sizing or the application’s
physical storage capacity.
Persisted sequence numbers and counters use safe integers with a representational ceiling of 2⁵³−1.