Hard Caps and Soft Hints: Two Ways to Budget an AI Agent

There are 2 ways to give an AI agent a budget, and they behave nothing alike. One asks the model to pace itself and hopes it listens. The other refuses to start the next request. Both are called budgets, both are set with a single field, and confusing them is how teams end up with a spend ceiling that never actually stops anything.

Why does an agent need a spend ceiling at all?#

Because an agentic loop has no natural stopping point. A chat turn ends when the model stops talking; a loop ends when the model decides it is finished, which can be many tool calls and several dollars later. Without a ceiling, a stuck agent retries until something else stops it.

The failure that motivates this is not a model being expensive. It is a model being wrong in a loop: a search that returns nothing useful, a test that keeps failing, a tool whose error message reads like something worth retrying. Each cycle is individually reasonable and the aggregate is not. Estimating cost per task, as covered in the token math behind an API bill, tells you what a healthy run costs. It says nothing about the unhealthy one.

The word is the same in both columns. The guarantee is not.

That is the gap a ceiling fills. It is not an optimisation, and it should not be confused with one. Spending less is a design problem. Not spending without bound is a safety problem, and safety problems want enforcement rather than encouragement. The levers in 7 ways to cut AI API costs make the healthy path cheaper; none of them put a floor under the unhealthy one.

The distinction shows up most clearly in who the control is for. A pacing hint exists to make the model's own decisions better, which presumes the model is making decisions worth improving. A ceiling exists for the case where that presumption is already false, which is why it cannot be implemented as advice. Anything that can be reasoned past is not a bound.

What does a hard session budget actually enforce?#

A dollar ceiling on one session, checked between model requests and priced at public list rates. You set it once at session creation as a whole number of US cents written as a string, and the platform prices model tokens, web searches and running time against it continuously.

The shape is small enough to read in one go:

{
  "budget": {
    "type": "limit",
    "max_list_cost": { "amount": "125", "currency": "USD" }
  }
}

That "125" is $1.25, not $125. The amount is a whole number of cents, and it is a string rather than a number so no float rounding is ever applied to it. Decimal forms such as "25.00" are rejected outright, and USD is the only currency accepted.

What gets priced into that total is worth knowing, because 2 of the 3 components are easy to forget:

The phrase carrying the most weight is list rates. The budget compares against public list pricing, not whatever your organisation actually pays. If you have negotiated discounts, the session stops when the list-price total hits the cap while your billed spend sits lower. The cap is a bound on list cost that happens to bound your real spend too, rather than a bound on your invoice.

The first 3 feed the hard cap's running total. The last is a floor on the advisory one.

Two constraints deserve a note before you design around them. A budget can only be attached when the session is created, so adding one to a running session returns a 400. And removing a budget is one-way: a session whose cap has been removed cannot be given a new one. If you might want a ceiling again later, change the budget rather than removing it.

What happens the moment the cap is hit?#

The session pauses rather than dying. Threads stop before their next model request, the session goes idle with a budget_reached stop reason, and its history and sandbox survive intact. Raising or removing the budget resumes the paused work automatically, with no client-side replay needed.

The enforcement point is between requests, not inside one. The request that carried the total past the cap was admitted while the session was still under it, and it runs to completion. So a session capped at 50 cents can pause having consumed 53, which is expected rather than a billing error. The overshoot is bounded by 1 model request per thread, and the honest way to size a cap is to leave room for that margin.

The usage snapshot always lands immediately before the idle event, so it is a reliable hook.

While paused, the session accepts only events that settle work already in progress: tool confirmations, tool results, custom tool results, and interrupts. Anything that would start new work, user.message included, is rejected with a 400 that names the accepted list. This is the part that makes the pause meaningful rather than cosmetic, and it is the behaviour to build your operator tooling around, since a paused agent needs a human decision rather than a retry.

There is a second-order consequence here that matters for scheduled work. Because a paused session keeps its sandbox and history, resuming it is genuinely cheap: you are not re-running the first 90% of a task to get back to where it stopped. That makes a deliberately tight cap a reasonable default for unfamiliar workloads, since the cost of guessing low is a pause and a decision rather than lost work. It also means a paused session holds resources, so a queue of them waiting on a human is a thing worth monitoring.

Raising a cap has one non-obvious rule attached. The new value must be strictly greater than what the session has already consumed, and the consumed figure usually sits slightly past the old cap because of that final in-flight request. Basing the new number on the old cap therefore fails; base it on the session's reported usage instead, and add a margin, since the reported figure is rounded to the cent while the check uses the exact amount.

Multiagent sessions share a single budget across all their threads, with no per-thread caps, and advisor consultations are billed into the same pot at the advisor model's rates. Threads pause independently as the shared cap is reached, so 1 can be paused while another finishes an in-flight request. There is a small precedence rule worth remembering: a thread waiting on a human answer outranks the cap at session level, because answering a pending question is a settle event rather than new work.

How is an advisory task budget different?#

It asks rather than refuses. A task budget gives the model a token allowance for a whole agentic loop and injects a countdown it can see, so it paces itself and wraps up gracefully. Nothing enforces it: the model may overshoot, and only max_tokens actually stops generation.

The documentation is unusually direct about this, calling it a soft hint rather than a hard cap. The countdown marker is injected server-side and is visible only to the model. There is no remaining-budget field anywhere in the API response and no SDK accessor for one, so client-side tracking means summing usage yourself.

Each of these has a documented behaviour that differs from the obvious assumption.

What the budget counts is the detail that trips people up. It decrements by what the model sees in a turn, meaning thinking, tool calls, tool results and output, not by the size of the payload you send. In a normal loop your client resends the whole conversation every turn, so the payload grows while the budget only charges for genuinely new content. Resent history is not counted twice.

That distinction has a sharp edge. If you decrement remaining client-side while also resending full history, the model sees an under-reported budget, the countdown falls faster than it should, and the agent wraps up early for no reason. The guidance is to set the budget once and let the server track it, reaching for remaining only when you compact context and genuinely break the server's view.

There is also a caching interaction worth planning around. The countdown marker is injected per turn on the server side, so it never matches across requests, and if you mutate the budget value yourself you invalidate any cache prefix containing it. On a long loop that is a real cost, and it argues for the same conclusion from a different direction: set the budget once, then leave it alone.

An undersized budget fails in a way that looks like a different bug entirely. Given an allowance clearly insufficient for the work, a model may decline the task, scope it down hard, or stop early with a partial result rather than start something it cannot finish. If an agent starts refusing work after you introduce a budget, raise the budget before investigating anything else. The minimum accepted total is 20,000 tokens, and the sensible starting point is the p99 of what your tasks already spend without a budget set.

Which one should you reach for?#

Both, for different jobs. The hard cap is your protection against a runaway loop and a bad night's sleep; the advisory budget is how you get a graceful finish instead of an abrupt halt. They operate at different layers, so using one does not remove the reason for the other.

The first check is whether an overrun costs money or just time. They want different tools.

A useful way to hold it: the advisory budget shapes behaviour inside a run, and the hard cap bounds the damage when that shaping does not work. An agent that paces itself well still needs a ceiling, because the case the ceiling exists for is precisely the case where the model's judgement has already failed. Pairing them gives you an agent that usually finishes tidily and never runs away, which is a better outcome than either alone.

Two practical notes on where each one lives. Task budgets are a per-request setting on the Messages API and are supported on a specific subset of models, so a stack standardised on Sonnet 5 does not have them available today. Hard session budgets live on managed sessions and extend to scheduled deployments, where the cap is copied onto each run rather than summed across them, which bounds a nightly job per night rather than per month.

Whichever you use, the operational half matters as much as the configuration. A cap that pauses an agent at 2am is only useful if somebody can see that it happened and decide what to do, which is an argument for wiring budget events into the same place your agent traces already go. A silent pause and a silent failure look identical from the outside, and only one of them is fine.