How to Detect Tool Call Loops in AI Agents (Python)

[bmdhodl]

AI agents that call tools can get stuck in loops — calling the same tool with the same arguments repeatedly, burning through tokens while doing nothing useful.

This happens with every LLM provider (OpenAI, Anthropic, Google) and every framework. The root cause is the model not knowing how to proceed, so it retries the same action.

Three types of loops

1. Exact repeats: Same tool, same arguments, over and over.

search("weather NYC") → search("weather NYC") → search("weather NYC")

2. Fuzzy repeats: Same tool, slightly different arguments.

search("weather NYC") → search("NYC weather") → search("weather in New York")

3. Alternation (A-B-A-B): Two tools calling each other in a cycle.

search("docs") → write("summary") → search("docs") → write("summary")

Detecting exact loops

from agentguard import LoopGuard, LoopDetected

guard = LoopGuard(max_repeats=3, window=6)

# In your agent loop, after each tool call:
try:
    guard.check(tool_name="search", tool_args={"query": "weather NYC"})
except LoopDetected as e:
    print(f"Loop detected: {e}")
    # Handle: retry with different prompt, fall back, or exit

LoopGuard uses a sliding window. It tracks the last N tool calls and triggers when the same (tool, args_hash) pair appears more than max_repeats times.

Detecting fuzzy loops and alternation

from agentguard import FuzzyLoopGuard

guard = FuzzyLoopGuard(
    max_tool_repeats=5,    # Same tool called 5+ times (any args)
    max_alternations=3,    # A-B-A-B pattern 3+ times
    window=10,
)

FuzzyLoopGuard ignores arguments — it only looks at tool names. This catches the case where the model paraphrases its input on each retry.

Automatic detection with LangChain

If you're using LangChain, the callback handler does the checking for you:

from agentguard import LoopGuard
from agentguard.integrations.langchain import AgentGuardCallbackHandler

guard = LoopGuard(max_repeats=3, window=6)
handler = AgentGuardCallbackHandler(loop_guard=guard)

agent.invoke(
    {"input": "Research AI trends"},
    config={"callbacks": [handler]},
)

Install

pip install agentguard47

Zero dependencies, MIT licensed, Python 3.9+.

GitHub: https://github.com/bmdhodl/agent47

---

What loop patterns have you seen in your agents? I'm collecting failure modes to improve detection — drop a comment with your experience.