Max Iterations — AI Glossary

Reference details

Related terms

• Stopping Condition
• Retry Logic
• AI Agent

How it works

1. The loop counts model turns or tool calls and halts when the count reaches a configured ceiling, which is the simplest stopping condition to implement and the one every framework exposes.
2. Its purpose is to terminate a loop that is not converging — repeating the same call, oscillating between two states, or reasoning without acting.
3. What happens at the ceiling is a design decision rather than a default: returning the best partial answer, raising an error, or escalating to a human are different contracts and the caller needs to know which it gets.
4. The ceiling must be derived from the measured step distribution of successful runs, because any value below the upper tail of that distribution truncates work that would have completed.
5. It bounds turns and not cost, since the expense of a turn varies with how much the tools return — which is why it belongs alongside a token or spend budget rather than instead of one.
6. Hitting it is a signal worth monitoring in its own right: a rising rate of ceiling-hits usually means the task distribution has shifted, not that the ceiling is wrong.

Example: Why the ceiling must come from the successful runs

Suppose successful runs average 8 steps, and the ceiling is set to 10 on the reasoning that 8 plus a margin is generous. The mean is the wrong statistic: what matters is the upper tail. If 25% of successful runs need more than 10 steps — entirely plausible when the mean is 8 and the distribution has any spread — then a ceiling of 10 truncates one run in four. Across 10,000 tasks that is 10,000 x 0.25 = 2,500 failures caused by the control rather than by the agent, and they present as the agent being unable to complete the task. Setting the ceiling from the 99th percentile of successful runs instead — say 24 steps — truncates 1% rather than 25%, which is 100 tasks instead of 2,500. The cost of the looser ceiling is bounded by what the runaway runs spend before hitting it, and that is exactly the thing a token budget bounds properly: a ceiling of 24 with a 100,000-token budget stops a cheap spinning loop at 24 turns and an expensive one at the budget, whichever comes first. The ceiling set from the mean is the common misconfiguration, and it is diagnosed as a capability problem.

Commonly confused with

An iteration ceiling is not a cost control, which is the most expensive misunderstanding available here. It bounds the number of turns, and turn cost varies by orders of magnitude depending on what a tool returns — so a loop capped at 20 iterations can consume anything from a few thousand tokens to a million. A token or spend budget is what bounds cost. The two are complementary: the ceiling catches a loop spinning cheaply that would otherwise run a long time, and the budget catches one spending fast. A loop with only the ceiling has no ceiling on spend.

When to use it

Reach for it when:

• Every production agent loop, as the floor-level guard against non-termination.
• Set from a high percentile of the observed step distribution of successful runs, not from the mean.
• Alongside a token or spend budget, which is what actually bounds cost.
• With the ceiling-hit rate monitored, since a rise in it is a signal about the task distribution.

Reach for something else when:

• As a cost control, which it is not — turn cost varies far too widely for a turn count to bound spend.
• Set from the mean step count, which truncates a large share of legitimate runs and looks like a capability failure.
• Without defining what the caller receives at the ceiling, where a silent partial answer is indistinguishable from a complete one.
• As the only stopping condition, since it says nothing about progress — a loop making no headway still consumes every permitted turn.

Continue your research

Use these connected ModelRefs sections to compare alternatives, inspect implementation paths, and review the evidence and governance boundaries relevant to Max Iterations — AI Glossary.

• Browse models
• Review providers
• Inspect benchmarks
• Explore workflows
• Learn AI concepts
• Read decision guides
• Review trust and methodology
• Start a decision path