Quick Fix (TL;DR)

Autonomous agents enter repetitive loops when tool failures return identical errors or when models misinterpret state. To break cyclic tool execution immediately in Python, track action signatures inside a sliding window and abort if the same call repeats three times:

import hashlib
import json

class LoopDetector:
    def __init__(self, max_repeats: int = 3, window_size: int = 6):
        self.max_repeats = max_repeats
        self.window_size = window_size
        self.history: list[str] = []

    def check_action(self, tool_name: str, arguments: dict) -> bool:
        """Returns True if the action is safe, False if trapped in a cycle."""
        # Normalize arguments to create a deterministic hash
        serialized = json.dumps({"tool": tool_name, "args": arguments}, sort_keys=True)
        call_hash = hashlib.sha256(serialized.encode()).hexdigest()[:12]
        
        self.history.append(call_hash)
        if len(self.history) > self.window_size:
            self.history.pop(0)

        # Count occurrences in the active window
        if self.history.count(call_hash) >= self.max_repeats:
            return False
        return True

If check_action returns False, interrupt execution, inject a diagnostic reminder into the conversation context, and prompt the model to adopt an alternative plan.

---

1. Why Autonomous Agents Get Stuck in Loops

Agent loops happen because LLMs are autoregressive token predictors, not state machines. When a tool fails, models often predict the exact same tool call because the preceding prompt context still points toward that initial strategy.

The loop sequence follows a predictable cycle:

+--------------------------------------------------------+
| 1. Model issues tool call: bash("npm test")            |
| 2. Environment returns error: "Module not found"       |
| 3. Model attempts to fix: bash("npm install missing")  |
| 4. Environment returns error: "EACCES: permission"     |
| 5. Model repeats step 1: bash("npm test")              |
| 6. Repeat until context limit or token budget runs out |
+--------------------------------------------------------+

Without deterministic external guardrails, reasoning models like DeepSeek R1, GPT-4o, or Claude Sonnet can consume hundreds of API calls repeating failed terminal commands.

---

2. The 3-Layer Defense Architecture

Production-grade agent frameworks implement three complementary guardrails to guarantee execution bounds:

Defense Layer	Mechanism	Scope	Latency Overhead
Layer 1: Hard Budgets	Max step count & token threshold	Entire execution session	0 ms
Layer 2: Action Signature Hashing	Sliding window deduplication	Immediate repeated tool calls	< 1 ms
Layer 3: Dynamic Reflection Gate	Injected recovery prompt	Stalled or oscillating plans	1 inference pass

---

3. Production Implementation in Python

Below is a complete loop guardrail implementation compatible with OpenAI, Anthropic, or local Ollama tool-calling loops:

import hashlib
import json
from dataclasses import dataclass, field

@dataclass
class AgentLoopGuard:
    max_steps: int = 25
    max_tokens: int = 80000
    cycle_threshold: int = 3
    current_step: int = 0
    total_tokens_used: int = 0
    recent_calls: list[str] = field(default_factory=list)

    def record_step(self, tool_name: str, args: dict, prompt_tokens: int, completion_tokens: int) -> None:
        self.current_step += 1
        self.total_tokens_used += (prompt_tokens + completion_tokens)
        
        # Build deterministic call signature
        payload = json.dumps({"tool": tool_name, "args": args}, sort_keys=True)
        call_hash = hashlib.sha256(payload.encode()).hexdigest()[:10]
        self.recent_calls.append(call_hash)
        if len(self.recent_calls) > 8:
            self.recent_calls.pop(0)

    def validate_next_action(self, tool_name: str, args: dict) -> tuple[bool, str]:
        # Rule 1: Step budget
        if self.current_step >= self.max_steps:
            return False, f"Step budget exceeded ({self.max_steps} steps reached)."

        # Rule 2: Token budget
        if self.total_tokens_used >= self.max_tokens:
            return False, f"Token budget exceeded ({self.total_tokens_used} tokens consumed)."

        # Rule 3: Repetitive cycle detection
        payload = json.dumps({"tool": tool_name, "args": args}, sort_keys=True)
        call_hash = hashlib.sha256(payload.encode()).hexdigest()[:10]
        if self.recent_calls.count(call_hash) >= self.cycle_threshold:
            return False, f"Loop detected: Tool '{tool_name}' invoked with identical arguments {self.cycle_threshold} times."

        return True, "Safe"

---

4. Recovering from Trapped States: The Reflection Prompt

When a loop is detected, simply aborting the program leaves tasks unfinished. A better approach is injecting a high-priority system intervention that forces the model to diagnose its own failure.

Append this message to the message history:

recovery_prompt = {
    "role": "user",
    "content": (
        "[SYSTEM INTERVENTION: REPETITION DETECTED]\n"
        f"You have executed '{tool_name}' with identical parameters multiple times without progress.\n"
        "Do NOT repeat this tool call.\n"
        "1. Explain why the previous attempts failed based on the error output.\n"
        "2. Formulate a different approach or report what missing information blocks completion."
    )
}
messages.append(recovery_prompt)

This breaks autoregressive inertia. The model shifts attention from repeating the mechanical action to evaluating why the environment rejected it.

---

5. Framework Comparison: Built-In Loop Protections

Different agent orchestration frameworks handle runaway loops with varying degrees of automation:

Framework	Max Steps Setting	Cycle Detection	Automated Intervention
LangGraph	recursion_limit=50	Manual via state reducers	User-defined conditional edge
CrewAI	max_iter=25	Hard limit on iterations	Returns task output as failed
AutoGen 0.4	MaxMessageTermination(max_messages=30)	Native stop conditions	Trigger reset hook
Claude Code	Internal tool budget per command	Active bash loop breaker	Direct user confirmation prompt

---

6. Testing Your Guardrail

Test the guardrail with a simulation script that feeds identical failing commands:

guard = AgentLoopGuard(max_steps=10, cycle_threshold=3)

simulated_tool = "bash"
simulated_args = {"command": "cat /nonexistent/config.json"}

for step in range(5):
    is_safe, reason = guard.validate_next_action(simulated_tool, simulated_args)
    if not is_safe:
        print(f"[BLOCKED at step {step + 1}]: {reason}")
        break
    guard.record_step(simulated_tool, simulated_args, prompt_tokens=450, completion_tokens=80)
    print(f"[RUNNING step {step + 1}]: Tool call executed.")

Output:

[RUNNING step 1]: Tool call executed.
[RUNNING step 2]: Tool call executed.
[RUNNING step 3]: Tool call executed.
[BLOCKED at step 4]: Loop detected: Tool 'bash' invoked with identical arguments 3 times.

The system halts execution before burning additional tokens, keeping autonomous workflows reliable and cost-effective.