How to Stop an AI Agent from Looping or Repeating Tool Calls
Detect non-progress, cap retries, preserve idempotency, and stop repeated calls before they burn budget or duplicate work.
Short answer
Stop agent loops with explicit budgets, progress checks, idempotent mutations, and terminal conditions the runtime enforces outside the model. Prompt instructions help, but they are not a reliable substitute for hard step, time, retry, and cost limits.
Key takeaways
- Define progress as a measurable state change, not more reasoning text.
- Enforce ceilings in runtime code and emit a clear stop reason.
- Use idempotency keys and read-before-retry checks for side effects.
Signs this is the problem
Start by confirming the symptom before changing prompts, models, or infrastructure.
- The same tool and materially equivalent arguments appear several times.
- Token or cost growth continues while the task state does not change.
- A timeout causes the agent to repeat a mutation without checking whether it already succeeded.
Step-by-step approach
- 1
Instrument progress
Record state transitions, unique evidence acquired, completed subtasks, and repeated call signatures. A loop detector needs more than a raw turn count.
- 2
Set hard budgets
Cap steps, wall time, retries per operation, tool calls, and spend. Return a structured stop reason so operators can distinguish budget exhaustion from success.
- 3
Guard mutations
Attach stable idempotency keys, check current state before retrying, and separate a read-only verification call from the original write.
- 4
Test stalled paths
Simulate timeouts, empty results, contradictory results, permission denial, and an impossible objective. Assert that the agent stops safely with useful evidence.
What to measure
| Metric | What it measures | How to use it |
|---|---|---|
| Non-progress turns | Consecutive steps that add no new evidence or state change. | Use a small bounded threshold before forcing recovery or stopping. |
| Duplicate-call rate | Repeated normalized tool calls per run. | Investigate increases even when the final answer passes. |
| Cost per verified outcome | Total run cost divided by independently verified completions. | Prefer this to cost per call because cheap loops still waste the workflow. |
Common mistakes
- Telling the model 'do not loop' without runtime enforcement.
- Treating any different wording as progress.
- Retrying a timed-out write before checking the destination state.
Practical checklist
- Define observable progress for the workflow.
- Enforce step, retry, time, and cost budgets.
- Normalize call signatures for duplicate detection.
- Use idempotency keys for mutations.
- Test impossible and permission-denied tasks.
Frequently asked questions
What is a reasonable maximum step count?
There is no universal number. Measure successful representative runs, add limited recovery headroom, and keep a separate ceiling for each workflow class.
Should the agent decide when to stop?
It can propose completion or explain a block, but the runtime should enforce budgets and verify completion independently.
Are retries always bad?
No. Bounded retries can recover transient failures. They become dangerous when the operation is not idempotent or the agent cannot observe whether it already succeeded.