跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

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

Guides diagnosing an active or recurring runaway agent tool-call loop and stopping it safely with a bounded retry policy and a hard ceiling — distinct from raising the iteration limit. Use when a user asks to "figure out why the agent is stuck calling the same tool," "safely kill a runaway agent session," "the agent keeps retrying the same failing action," "someone just raised the retry limit and it's still looping," or needs to design a circuit breaker so a stalled agent fails closed instead of burning cost/quota indefinitely.

selvarajmurugesan90 · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add selvarajmurugesan90/ops-engineering-skills --skill agent-tool-call-loop-diagnosis-and-circuit-breaking

技能说明


name: agent-tool-call-loop-diagnosis-and-circuit-breaking description: > Guides diagnosing an active or recurring runaway agent tool-call loop and stopping it safely with a bounded retry policy and a hard ceiling — distinct from raising the iteration limit. Use when a user asks to "figure out why the agent is stuck calling the same tool," "safely kill a runaway agent session," "the agent keeps retrying the same failing action," "someone just raised the retry limit and it's still looping," or needs to design a circuit breaker so a stalled agent fails closed instead of burning cost/quota indefinitely. license: Apache-2.0 compatibility: "Claude Code, GitHub Copilot, OpenAI Codex, Cursor, Gemini CLI" metadata: domain: ai-agent maturity: stable

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.

Prerequisites & environment

  • Per-session logs of every tool call (name, arguments, result, timestamp) so a loop can be identified from history, not just suspected from a vague "this looks slow" report.
  • A way to cancel or interrupt an in-flight agent session (a kill switch at the orchestration layer, not just "stop sending it new input") — see step 3 for why cancellation timing matters.
  • The tool risk classification already established in agent-tool-use-patterns (read-only / reversible / irreversible), since safe cancellation and circuit-breaker design depend on knowing which in-flight call, if any, has a side effect that can't simply be abandoned mid-call.
  • Access to the dispatcher/loop code so a circuit breaker can actually be implemented, not just recommended.

Step-by-step guidance

  1. Confirm it's actually a loop before treating it as one. Pull the session's tool-call history and check for genuine repetition, not just "many calls" — a legitimately long task (paginating through a large result set, retrying a transient network blip a bounded number of times) can also produce a high call count. The distinguishing signal is whether each call carries new information toward the goal:

    def is_loop(call_history, window=5):
        recent = call_history[-window:]
        signatures = [(c.tool_name, json.dumps(c.arguments, sort_keys=True)) for c in recent]
        return len(recent) == window and len(set(signatures)) <= 2  # near-total repetition
    
  2. Classify the loop type — the fix differs by type:

    • Exact-repeat stall: identical (tool, arguments) called repeatedly with no change — almost never intentional progress.
    • Oscillation: alternating between two or three calls (e.g. search(x) → search(y) → search(x) → ...) — usually the model re-trying variations without converging, often because neither result satisfies an implicit precondition the prompt never stated.
    • Error-retry storm: the same call fails (error/timeout) and the agent retries it verbatim rather than adapting — this is a dispatcher problem (the error wasn't surfaced usefully) as much as a model one.
    • Cost-without-progress: calls are all distinct but the session's state (as tracked by the agent's own plan/goal) never advances — harder to detect mechanically; usually surfaces via a session duration/cost outlier rather than a repeated-signature check.
  3. Stop the in-flight session at a safe boundary, not mid-call. Before force-killing a session, check whether any tool currently executing (or just completed but not yet acknowledged) is a reversible-write or irreversible-write action per its risk classification — killing a process mid-write can leave a partial state (a half-applied update, a sent-but-unlogged message) that's harder to clean up than the loop itself. Prefer a cooperative cancellation (set a flag the loop checks between tool calls) over a hard process kill wherever the runtime supports it; reserve a hard kill for cases where the loop is read-only or already c

阅读完整来源 ↗