Budgets and limits for agents

⚠️

Preview — this feature is being built; the design below is the spec.

An agent that loops, searches too widely or receives a huge input can spend far more than intended. Hosted agents have limits at three levels (the agent, the session and the organization) so a single run cannot get out of hand. This page explains each limit, what happens when one is reached, and how to pick values.

Limits on the agent definition

Set in limits on the agent definition. They are the defaults and the maximums for every session of that agent.

Field	What it bounds	When reached
`max_turns`	Model calls in one session turn (each tool round is one call).	The turn ends with outcome `max_turns`.
`max_output_tokens_per_turn`	Output tokens of a single model call.	That reply stops with `finish_reason: "length"`.
`session_token_budget`	Input plus output tokens across the whole session.	The turn ends with outcome `budget_exhausted`.
`session_cost_budget_usd`	Cost of the session in US dollars, at retail rates.	The turn ends with outcome `budget_exhausted`.

Limits per session

When starting a session, limits can lower any of these for that session only, never raise them; a higher value returns 400 limit_above_agent. Use it for cheaper tiers of your own product, or for untrusted inputs:

{
  "agent_id": "agt_01JC4R8W6Q2N9X3T5V7Y",
  "limits": { "max_turns": 10, "session_cost_budget_usd": 0.25 }
}

Organization and workspace controls

Sessions are billed like any other model use, so the usual controls apply on top:

Plan windows and usage credits: a model call that cannot be paid for returns 402 quota_exhausted, and the session moves to idle with outcome budget_exhausted. See Limits.
Monthly spend limits for the organization, a workspace or a member. See Spend limits.
Concurrency: at most 50 running sessions per workspace at once, more on higher rate-limit tiers.

What happens at a limit

The agent does not get to squeeze in a final answer after a limit is reached: the turn stops, the session becomes idle, and outcome says why. The transcript and traces up to that point are kept. Your application decides what to do next:

Outcome	Typical response
`max_turns`	Look at the traces: a loop usually means a tool returns unhelpful results. Retry once with clearer input, or hand over to a person.
`budget_exhausted`	Tell the user the request was too large, offer a narrower version, or route to a person.

Listen for status.changed events on the stream or the session.idle webhook to react without polling.

Choosing values

Run your test scenarios with generous limits and record, per scenario, the number of model calls, tokens and cost from the session’s usage (or executions).
Set max_turns to roughly twice the highest count you saw in a successful run.
Set session_cost_budget_usd to a few times the typical successful run’s cost; this catches runaways without cutting off legitimate long tasks.
Watch real traffic for a week and adjust. Alert on sessions ending with max_turns; they point to prompts or tools that need work.

Limits protect against accidents, not abuse. For agents exposed to the public, also limit how many sessions each of your users can start, in your own application.

Tool permissions & approvals Agent skills

Was this page helpful?