Agent spend cap (task budget)

What is an agent spend cap?

An agent spend cap is a limit on what one piece of agent work may cost before it stops. Not per request, but across the whole job: the session, the run, the loop, everything between handing the agent work and getting a report back.

The unit is what makes it different. Nearly every cost control you already know counts requests: so many calls a minute, so many tokens in one call. An agent turns one instruction into an unknown number of requests, and the model decides that number at runtime, not you.

Anthropic ships it as an optional dollar ceiling you attach when you create an agent session: a budget object with a max_list_cost in whole US cents. The platform prices model tokens, web searches and running time at list rates, holds a running total, and stops issuing new model requests once that total reaches the cap. The session pauses with a stop reason of budget_reached, history and sandbox intact, and raising the budget lets it carry on. A running total, a threshold and a recorded stop reason: that is the shape of a spend cap anywhere.

A per-call limit does not protect you

The disaster people prepare for is one expensive request. The one that happens is a loop that will not stop, made of hundreds of requests that are each individually trivial. Nothing errors, every call is a fraction of a cent, and the total is the problem.

• The context grows on every step. Each turn resends everything before it, so the bill of a loop grows with the square of its length rather than in a straight line.

• Retries are billed at full price. A plain retry loop around a dependency that is down pays for every attempt.

• Subagents fan out. Anthropic measured its own workloads and reported that agents use about four times as many tokens as a chat interaction, and multi-agent systems about fifteen times.

• An expensive model does a cheap step. The gap between a vendor's top model and its small one is roughly a factor of ten, on every step.

• A scheduled agent runs whether there is work or not. On the night the folder is empty it still starts a session, loads its instructions and reasons about what it found.

The levels a cap can sit at

1. Per task or session. The only level that acts inside the accident rather than after it, because it stops a runaway loop while the loop is running. Set this one first.

2. Per user. Catches the colleague who found the agent useful and now runs it forty times a day. Nothing is broken, the volume is just not what the pilot assumed.

3. Per agent or per deployment. Anthropic's scheduled deployments copy the cap onto each session they start, so it bounds every run separately rather than the month's total.

4. Per environment. A small ceiling on test keeps a developer's overnight experiment off the production invoice.

5. A monthly ceiling on the account. The backstop for what the other levels missed, including the agent nobody told you about. OpenAI sets these per organisation and per project, and requests past the limit return a 429 with project_spend_limit_exceeded.

How enforcement works, and how an alert is different

A cap that stops the work checks the running total between steps, not in the middle of one. Anthropic states the consequence plainly: the request that carried the total past the cap was admitted while the session was still under it and runs to completion, so a session capped at 50 cents can pause with a recorded cost of 53. Treat the cap as a bound on new work rather than as an exact stopping point.

A hard cap is enforced outside the model. An Anthropic session sitting at its cap accepts only events that settle work already in progress, such as a tool result, and a new instruction comes back as a 400. Their task budgets are the other kind: counted in tokens, injected as a countdown the model can see, and described in the documentation as a soft hint, not a hard cap. The model paces itself against it, which is useful and is a different thing from a spending control.

An alert is a third thing again. Microsoft's wording for Azure budgets leaves no room: notifications are triggered when the thresholds are exceeded, resources are not affected, and your consumption is not stopped. Cost data is typically available within 8 to 24 hours and budgets are evaluated every 24 hours, so an agent looping overnight can be a full day of spend into the accident before the first mail goes out. Alerts read a trend across a month. They do not catch a loop.

A reconciliation loop that runs to 41 dollars

A wholesaler runs an agent every night to match supplier invoices to purchase orders. It sits on Claude Sonnet 5, listed in September 2026 at 2 dollars per million input tokens, 10 per million output and 0.20 per million read from the prompt cache. Its standing instructions and tool definitions come to 4,000 cached tokens, and every step adds around 1,000 tokens of tool call and result to a history that gets resent in full on the step after. One step costs the cache read, plus the whole history so far at the input rate, plus 300 output tokens.

Step 1 costs about 0.6 of a cent, invisible under any per-call limit you would think to set. Step 50 costs about 10 cents, because it is resending 50,000 tokens of history. Step 200 costs about 40 cents for the same amount of work.

One invoice will not reconcile: a credit note the agent cannot find. It searches, reads, tries a different query, reads again. Nothing fails, so nothing stops it. Add the 200 steps up and the run comes to about 41 dollars, some 20 million input tokens, for one unmatched credit note. The schedule is nightly, so if nobody looks the month lands around 1,230 dollars. Somebody tested this agent in a chat window at fractions of a cent per question, and that test is what the budget was based on.

Now put a 5 dollar cap on the session. Cumulative spend crosses 5 dollars during step 69, that step finishes, and the session pauses at about 5.09 with a stop reason of budget_reached. The invoice is still unmatched, but you find out at 5 dollars instead of 41, on the first night instead of at month end, and the stop reason tells you which agent did it.

A spend cap versus a rate limit

Both stop an agent that is going too hard, so they get treated as the same tool. The dimension that separates them is who each one protects.

A rate limit protects the provider and the other callers. It caps requests inside a time window so one client cannot starve everyone else. The provider sets it, it is about capacity, and it says nothing about money. An agent that hits one backs off and retries, and the work still finishes. The same bill arrives, only later.

A spend cap protects your invoice. It caps accumulated cost with no time window at all, and the run ends rather than slows. You set it yourself. Every one of those 200 steps above was a polite, well-spaced request that no rate limiter had any reason to refuse.

What to watch out for with an agent spend cap

Decide what happens when the budget runs out. Three honest answers, one per agent: stop and report, hand it to a person with the state so far, or finish on a cheaper model. Most platforms default to the first, and a paused session with no route to a human is how a cap turns into a silent outage.

The cap needs cost per task and per user beside it. One line on an invoice tells you the month was expensive, not which agent, which task or which colleague. Without that, you cannot set the next cap any better than you set this one. Record per run: the identifier, the user, the model, the token totals and the final cost.

A cap set too low reads as failure. Anthropic warns that a model given a budget clearly too small for the work may decline the task, scope it down hard, or stop early with a partial result. If an agent starts refusing after you introduce a budget, raise the budget before you hunt for a bug in the prompt.