Skip to content

Build an agent

Budgets and limits

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
compaction.keepRecentTokens 20,000 Recent context preserved during compaction
compaction.mode "prune-then-summarize" Compaction strategy
const
const researcher: Agent.Definition<Schema.String, Schema.Struct<{
readonly answer: Schema.String;
}>, "Answer from the available evidence.", Toolkit.Toolkit<{}>, undefined, undefined, undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "researcher";
}
researcher
=
import Agent
Agent
.
function make<"researcher", Schema.String, Schema.Struct<{
readonly answer: Schema.String;
}>, "Answer from the available evidence.", Toolkit.Toolkit<{}>, undefined>(id: "researcher", options: Agent.DefinitionOptions<Schema.String, Schema.Struct<{
readonly answer: Schema.String;
}>, "Answer from the available evidence.", Toolkit.Toolkit<{}>, undefined, undefined, undefined> & {
readonly inputPrompt?: undefined;
readonly runDisposition?: undefined;
}): Agent.Definition<Schema.String, ... 5 more ..., undefined> & {
...;
} (+3 overloads)

Validate an agent ID and return a shallowly frozen, model-agnostic definition.

make
("researcher", {
DefinitionOptions<String, Struct<{ readonly answer: String; }>, "Answer from the available evidence.", Toolkit<{}>, undefined, undefined, undefined>.input: Schema.String
input
:
import Schema
Schema
.
const String: 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<{ readonly answer: String; }>, "Answer from the available evidence.", Toolkit<{}>, undefined, undefined, undefined>.output: Schema.Struct<{
readonly answer: Schema.String;
}>
output
:
import Schema
Schema
.
function Struct<{
readonly answer: Schema.String;
}>(fields: {
readonly answer: Schema.String;
}): Schema.Struct<{
readonly answer: 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.

Example (Defining a basic struct)

import { Schema } from "effect"
const Person = Schema.Struct({
name: Schema.String,
age: Schema.Number,
email: Schema.optionalKey(Schema.String)
})
// { readonly name: string; readonly age: number; readonly email?: string }
type Person = typeof Person.Type
Schema.decodeUnknownSync(Person)({ name: "Alice", age: 30 }) // => { name: "Alice", age: 30 }

@stability ― stable

@category ― constructors

@since ― 3.10.0

Struct
({
answer: Schema.String
answer
:
import Schema
Schema
.
const String: 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<{ readonly answer: 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<{ readonly answer: String; }>, "Answer from the available evidence.", Toolkit<{}>, undefined, undefined, undefined>.toolkit: Toolkit.Toolkit<{}>
toolkit
:
import Toolkit
Toolkit
.
const empty: 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<{ readonly answer: String; }>, "Answer from the available evidence.", Toolkit<{}>, undefined, undefined, undefined>.policy?: Partial<Readonly<Omit<{
readonly runStatus: "appended" | "off";
readonly maxTurns: number;
readonly maxToolCalls: number;
readonly maxDuration: Duration;
readonly toolConcurrency: number;
readonly repeatedFailureLimit: number;
readonly onExhaustion: "final-answer" | "fail";
readonly completionReserveTokens: number;
readonly toolResultBounds: ToolResultBounds;
readonly compaction: CompactionPolicy;
readonly tokenBudget?: number | undefined;
readonly costBudgetMicrousd?: number | undefined;
readonly contextTokenLimit?: number | undefined;
readonly restartOnJoinedInput?: boolean | undefined;
readonly modelRetries?: number | undefined;
}, "runStatus" | ... 7 more ... | "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.

completionReserveTokens
: 4_000,
},
});

Context management explains compaction and oversized tool results. The travel planner shows policies in a complete application.

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.

Boundary Limit
Individual persisted JSON payload 1 MiB
Whole canonical record wire 4 MiB
Logical committed record JSON per Turn 4 MiB
Run execution dispatch 16,384 facts and 32 MiB
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.