Max Iterations vs Goal Completion: Setting Loop Limits

Picture this: you're an ML engineer, it's Friday, and your coding agent that "usually finishes in six steps" just started failing on a whole class of tasks. Nothing changed in the model or the prompt. What changed is that the tasks got slightly harder, they now need nine steps, and your agent loop iteration limit is set to eight. Every failure looks like the model got dumber. It didn't. Your cap got in the way. This is the quiet tax of a limit picked by hunch instead of data.

An iteration limit is the maximum number of loop turns an agent may take before you force it to stop. Set it too low and you truncate your best work; set it too high and a stuck agent burns your budget before the cap saves you. The right number isn't a default — it's a measurement, and the tension between a fixed limit and genuine goal completion is worth understanding before you pick one.

What Is an Agent Loop Iteration Limit?

An agent loop iteration limit is a hard ceiling on turns, independent of whether the goal is met. It exists as a backstop: even a perfectly designed agent can encounter a task it can't finish, and without a ceiling, "can't finish" becomes "never stops."

[object Object], step ,[object Object], ,[object Object],(max_iterations):
    reply = model.call(messages)
    ,[object Object], reply.finished:
        ,[object Object], reply.answer          ,[object Object],
    run_tools(reply, messages)
,[object Object], best_partial(messages)         ,[object Object],

What this does: shows the two ways a loop ends — goal completion returns the real answer, the iteration limit returns the best partial — making clear the cap is a fallback, not the primary control.

The key insight most people miss: these two exits should rarely compete. In a healthy agent, goal completion fires first, comfortably inside the limit. If the iteration limit is doing the stopping on most runs, your cap isn't a backstop — it's your primary stop condition, and that's a sign something is miscalibrated.

Worth separating two things people conflate: the iteration limit and the goal. The goal is what success looks like; the limit is how patient you're willing to be while waiting for it. If your two exits collide often, that collision is diagnostic — it means goals you thought were reachable frequently aren't, and no amount of raising the cap fixes an unreachable goal. Sometimes the honest fix is a better tool or a smaller goal, not a bigger ceiling.

⚡ Pro tip: Track your goal-completion rate and your cap-hit rate as two separate numbers over time. If cap-hits climb while completions fall, your tasks got harder or your tools got weaker — the cap is the messenger, not the cause. Raising it blindly just pays more for the same failures.

Why It Matters

The iteration limit silently shapes your success rate. Because a truncated run returns a partial answer, not an error, a too-tight cap doesn't announce itself. It just lowers quality across the board, and you blame the model. I've watched teams swap models chasing a few points of accuracy when the real fix was raising a cap from eight to twelve.

There's a cost dimension too. Every allowed iteration is a potential full-price model call. A generous limit protects hard tasks but exposes you to expensive spins on stuck ones. The limit is a dial between "give up too early on hard work" and "pay too long for stuck work," and where you set it is a real business decision, not a default to accept.

⚡ Pro tip: Log the actual iteration count of every successful run for a week. The distribution tells you everything — set your cap a few steps above the 95th percentile of successful runs, and you'll fit almost all genuine work while still catching true runaways.

Setting the Limit From Data

Don't guess the number. Measure it.

Run your agent across a representative task set with a deliberately high cap — say, thirty — and record how many iterations each successful run actually used. Plot that. You'll usually see a clear body of runs finishing in a tight band and a thin tail of hard cases. Your limit belongs just past the tail of legitimate successes, not at the median.

[object Object],
success_steps = [r.iterations ,[object Object], r ,[object Object], runs ,[object Object], r.succeeded]
p95 = percentile(success_steps, ,[object Object],)
recommended_cap = p95 + ,[object Object],         ,[object Object],

What this does: derives an iteration limit from the observed step counts of successful runs, so the cap is set by how many turns real work needs — not by a round number someone typed once.

The

+2

One caution about the measurement itself: measure with a cap high enough that it isn't the thing stopping most runs, or you'll measure your own ceiling instead of the task's true need. If you record step counts under a cap of eight, your data can never tell you that some tasks want twelve — they were all clipped at eight and look identical in the histogram. Measure loose, then set tight. Measure tight and you'll only ever confirm the limit you already had.

⚠️ Common mistake: Setting one global iteration limit for every task type. A quick classification task and a multi-file refactor have completely different step distributions — a cap that's generous for one strangles the other. If your agent handles varied work, set the limit per task category, or derive it from the task's estimated complexity, rather than forcing one number to serve jobs that need three steps and jobs that need fifteen.

When to Let the Goal Decide Instead

Sometimes a fixed iteration limit is the wrong tool entirely. For open-ended tasks where legitimate step counts vary enormously — deep research, complex debugging — a hard cap either strangles the hard cases or wastes budget on the easy ones.

For those, lean on goal completion plus a token budget rather than an iteration count. Let the agent take as many small steps as it needs, and stop it based on total spend, which tracks actual cost regardless of how the steps are distributed. A run that finishes in three big steps and one that finishes in fifteen small ones can cost the same; a token budget treats them fairly where an iteration limit wouldn't.

There's a hybrid worth knowing for variable workloads: a dynamic limit that scales with the task. Estimate task complexity up front — a quick heuristic or a cheap classifier — and set the iteration cap proportionally, so a trivial job gets five turns and a gnarly one gets twenty. It's more work than a constant, but for agents that see wildly different tasks, one adaptive limit beats endlessly re-tuning a global number that fits nothing well.

⚡ Pro tip: Combine both. Keep a loose iteration limit as a pure sanity backstop (say, 50) and a tight token budget as your real economic control. The iteration cap catches genuine runaways; the token budget governs cost. They protect against different failures and cost nothing to run together.

⚡ Pro tip: When you raise a cap to fix truncated runs, re-measure afterward. Raising the limit changes the step distribution — some runs that used to fail now succeed at higher counts — so last week's percentile is already stale. Caps drift as your agent improves; treat the number as a living setting, not a constant.

Common Mistakes

Two more traps recur. Teams never revisit the limit after the agent or its tasks evolve — a cap that fit last quarter's workload quietly throttles this quarter's. And teams treat hitting the cap as normal — if your agent regularly finishes exactly at the limit, it's almost certainly being cut off mid-task, not succeeding. A healthy agent finishes with room to spare; one living at the ceiling is telling you the ceiling is the floor.

Conclusion

An agent loop iteration limit is a backstop, not a strategy. Set it from the observed step counts of successful runs plus a little headroom, split it by task type when your work varies, and lean on token budgets and goal completion for genuinely open-ended jobs. Above all, watch how often the cap does the stopping — that single metric tells you whether your limit is protecting you or quietly capping your best work. It's the cheapest piece of instrumentation you can add and the one that most often reframes a "the model got worse" panic into a two-line config change.

The measurement script and the combined iteration-plus-token guard become reusable across every agent you tune. I keep both saved in PromptABCD alongside the loop code, so a new agent inherits a data-driven limit instead of a copied round number that may or may not fit what it actually does.