agent-tool-call-loop-diagnosis-and-circuit-breaking

Agent Tool Call Loop Diagnosis and Circuit Breaking

Purpose

A runaway tool-call loop — an agent calling the same tool repeatedly, or oscillating between two or three calls, without making progress — is one of the most common and most expensive agent failure modes in production: it burns tokens and API quota, can hammer a downstream system, and often goes unnoticed until a bill or a rate-limit alert fires. Preventing loops at design time (a hard iteration cap, stall detection in the dispatcher) is covered in agent-architecture-design and agent-tool-use-patterns; this skill is the operational companion — what to do when a loop is actually happening or has already happened: how to confirm it's really a loop and not a legitimate long-running task, how to stop an in-flight session safely, how to root-cause the trigger, and how to design a bounded retry with a hard ceiling rather than the reflexive, unsafe fix of just raising the existing limit. Raising a limit without addressing the cause doesn't stop the loop — it makes the loop more expensive before it stops.

When to use

• A cost or latency alert traces back to one agent session or one workflow making an unusually high number of tool calls (see agent-cost-and-latency-spike-investigation for the broader spike-triage process this often feeds into).
• An agent session is actively stuck and needs to be stopped safely without corrupting in-flight state.
• The transcript shows the same (or near-identical) tool call repeated many times with no new information between calls.
• Someone proposes "just raise MAX_ITERATIONS" or "just increase the retry count" as the fix, and you need to evaluate whether that's masking the real problem.
• Designing or auditing a circuit-breaker/retry policy for a tool-calling agent before it's given broader autonomy or higher-volume traffic.