Beyond max_steps: How to Detect and Stop Stagnant Agent Loops

In a four‑step experiment the author demonstrates that an Agent can return ok on every tool call yet make no real progress: after the first two steps the evidence count rises from 0 to 1, but steps 3 and 4 only repeat the same result without reducing the remaining gap.

The controller stops at step 4 with no_progress before reaching the configured max_steps=8, illustrating that a simple step budget cannot distinguish a normal termination from a silent loop that wastes tokens, time, and API quota.

To avoid this, the author argues that each action must be evaluated against a "progress contract" that defines target states, open gaps, authoritative fields, and the evidence required to close a gap. Pure natural‑language summaries are insufficient; structured fields like evidence_count, open_gaps, and versioned task state are needed.

Loop detection should rely on three signal classes: (1) action fingerprints – normalized tool name and key parameters; (2) observation fingerprints – stable summaries of results, ignoring noisy fields such as timestamps or request IDs; (3) state differences – changes in evidence count, gaps, task state, or business status. The author warns against naïve duplicate detection that only compares raw strings, as semantically identical calls may differ in case or whitespace.

A concrete script computes a fingerprint (e.g., 47abf3e4) for each step; steps 1, 3, and 4 share the same fingerprint, and because evidence and gaps do not change, a consecutive‑no‑progress counter increments, triggering the stop at step 4.

Hard limits like max_steps remain useful as budget caps, but soft stop conditions must evaluate business progress: completed, no_progress, needs_input, risk_gate, etc. Each condition should produce a distinct status rather than a generic failed.

The author proposes a comprehensive trace record for every step, including trace_id, step number, normalized action, tool status, result fingerprint, key state version, state delta, remaining budget, controller decision, and stop_reason. This enables post‑mortem analysis, policy version comparison, and accurate replay of decisions.

Finally, offline evaluation should capture four trajectory categories – semantically duplicate actions, allowed retries, result changes without business progress, and completed tasks with extra actions – to balance false‑positive loop stops against missed stagnation.