Iteration budget

How it works

An agent loop keeps going as long as the model decides there is more to do. That decision is unreliable: a model can loop on a failing tool, re-plan forever, or chase a goal it will never reach. An iteration budget is the external stop condition the loop does not supply for itself.

You pick a resource to meter and a ceiling on it:

• Turns — the number of model calls or tool cycles in the loop.
• Wall-clock — elapsed time from the task's start.
• Tokens — cumulative input and output tokens spent.

The harness increments a counter each iteration and checks it before the next step. When the budget is exhausted, the loop stops and hands back a defined terminal state — not a crash. That state matters: the agent should return partial results, the last checkpoint, and the reason it stopped, so the caller can decide whether to extend, escalate, or abandon.

Budgets are usually layered. A per-task ceiling bounds one unit of work; a per-subagent ceiling bounds a delegated branch; a global ceiling bounds a whole run. The tightest applicable budget wins. The point is not to guess the perfect number — it is to guarantee that some finite number exists, so no path through the system runs forever.

Why it matters in an agent harness

An unbounded loop is three problems at once, and the budget addresses all of them.

First, resource containment. A stuck agent burns tokens, API quota, and wall-clock with no upper bound. The budget converts an open-ended liability into a known, capped cost per task.

Second, blast radius. An agent that keeps acting keeps taking actions — more tool calls, more writes, more external effects. Every extra iteration is another chance to do damage. A tight budget shrinks how far a misbehaving run can get before something stops it, which is why budgets pair naturally with reversibility and checkpoints.

Third, observability and control. A loop that halts on a budget produces a signal: this task did not converge in N turns. That is a first-class event you can alert on, route to review, or feed back into evals. A loop that silently spins produces nothing but a rising bill. Termination on budget turns an invisible failure into a legible one.

A budget is also the backstop that makes autonomy safe to grant. You can let an agent run without a human watching each step precisely because the budget guarantees it cannot run indefinitely without a watcher.

Iteration budget vs tool budget

Both cap consumption, but they meter different things and fail differently.

Use an iteration budget to guarantee the loop ends. Use a tool budget to constrain a particular capability — say, at most three deploys, or a spend ceiling on a paid API. They compose: a task can be inside its iteration budget while still being cut off by a tool budget, and vice versa. Treating them as one number is the mistake; a loop can terminate cleanly and still have made too many irreversible calls.

The Rifty take

We treat the iteration budget as a controllability guarantee, not a cost optimization. Its real job is to make "the agent cannot run forever" a property you can prove, not hope for. So we set budgets tight enough that hitting one is a signal worth investigating, and we make the terminal state carry the partial work and the stop reason — a budget that halts silently just trades a runaway loop for a lost one. We accept that some legitimate tasks will hit the ceiling and need a deliberate extension; that friction is the price of a system that always stops.

Common failure modes

• Budget set so high it never fires. If the ceiling is never reached in practice, it is documentation, not a control. Set it near real task cost so exhaustion is meaningful.
• Halting without returning state. A loop that stops but discards partial results and the stop reason forces a full restart and hides why it failed. Always emit a checkpoint and a cause.
• Metering the wrong resource. A turn cap does not bound a single agent that spends huge tokens per turn; a token cap does not bound wall-clock. Meter the resource you actually need to protect.
• No per-branch budgets in multi-agent runs. A global budget alone lets one delegated subagent starve the rest. Give delegated branches their own ceilings.
• Treating exhaustion as success. A task that stops on budget did not necessarily finish. Route budget-exhausted terminations to review or retry logic, never straight to "done."
• Retrying without decrementing. If a retry resets the counter, the budget stops bounding anything. Carry the spend across retries within a task.

Frequently asked questions

What should I meter an iteration budget in — turns, time, or tokens?

Meter the resource you most need to bound, and often more than one. Turns bound loop count but ignore per-turn cost; tokens bound spend but not elapsed time; wall-clock bounds latency but not compute. Production harnesses usually set all three, and the first ceiling reached stops the loop.

How is an iteration budget different from a tool budget?

An iteration budget caps the whole loop's progress so it cannot run forever; a tool budget caps a specific capability so one action cannot over-fire. They compose. A task can stay within its iteration budget yet still be stopped by a tool budget after too many irreversible calls, so treat them as separate controls.

What should happen when the budget runs out?

The loop should halt into a defined terminal state, not crash. Return partial results, the last checkpoint, and an explicit stop reason so the caller can extend, escalate to a human, or abandon. A budget that stops silently and discards work trades a runaway loop for a lost one, which is often worse.

Won't a tight budget kill legitimate long tasks?

Sometimes, and that is acceptable. A tight budget makes exhaustion a signal worth investigating rather than a rare edge case. Legitimate long tasks should hit the ceiling and request a deliberate extension or checkpoint-and-resume. That friction is the price of a system that provably always stops, instead of one you hope will.

Does an iteration budget make an agent safe to run unattended?

It is a necessary backstop, not the whole answer. The budget guarantees an agent cannot run indefinitely without a watcher, which is what makes unattended autonomy tolerable. But you still need reversibility, permission boundaries, and tool budgets to contain what the agent does within those iterations before it stops.