If you have deployed autonomous AI agents using tool calling, you have probably experienced—or feared—the midnight API bill spike.

An agent calls a tool, hits a minor validation error, apologizes to its own context window, and retries the exact same failing call in a tight loop until your token budget explodes.

Most frameworks (like LangChain, LangGraph, or Vercel AI SDK) patch this with static hard caps like max_iterations=15. That approach has three major flaws in production:

  1. It kills legitimate long tasks: If a complex enterprise workflow genuinely requires 20 steps, a rigid cap breaks it prematurely.
  2. It is blind to early loops: If an agent gets stuck repeating the exact same 2-step cycle at turn 2, it still burns 13 unnecessary LLM calls before hitting the limit.
  3. It crashes the user experience: Hard caps terminate the runtime abruptly, leaving the end-user stranded with an error instead of a completed answer.

To solve this without rewriting your agent logic, I built LoopShield—an open-source Python SDK and OpenAI/Anthropic-compatible gateway proxy that detects loops in flight and guides agents to self-heal.

How LoopShield Works (Twin-Engine Detection)

LoopShield sits directly in front of your LLM provider (POST /v1/chat/completions), screening every turn before forwarding traffic upstream:

Agent / App ──▶ LoopShield Proxy ──▶ Graph & Semantic Check │ ┌───────────────────────┴───────────────────────┐ ▼ (Loop Detected) ▼ (Clean Traffic) Lock Tool + Inject System Nudge Symmetrical Context Pruning (Returns valid completion to Agent) (Forwards to OpenAI / Anthropic)

Instead of relying on static iteration counters, LoopShield runs two detectors on every step:

  1. Structural Graph Analysis (networkx): Maps sequential tool calls (including normalized arguments) as a directed graph. If the agent walks the same multi-step cycle again, it flags a graph loop immediately.
  2. Semantic Thought Proximity (numpy): Evaluates cosine similarity on internal thought metadata locally. If an agent gets stuck rephrasing the same failing plan without calling tools, it catches the loop once similarity exceeds your threshold (default > 0.92).

Self-Healing Over Termination

Instead of crashing your application when a loop is caught, LoopShield intercepts the request before it hits your upstream API bill, locks the repeating tool, and returns a valid assistant message containing a System Nudge:

"You are repeating a tool cycle. Tool X is locked. Switch strategies or finalize your response."

The agent adapts, picks a different tool or path, and finishes the job. When long conversations approach your token limit (SHIELD_MAX_TOKENS), LoopShield also applies Symmetrical Context Pruning, stripping historical failed tool calls alongside their matching error outputs so upstream schemas stay valid.

Quick Start (1-Line Proxy or In-Process Python SDK)

Option 1: Run as a Containerized Gateway Proxy

Start the Docker container and point your OpenAI or Anthropic SDK base_url to port 8000:

docker run --rm -p 8000:8000 \ -e UPSTREAM_API_BASE=https://openai.com \ -e SHIELD_SIMILARITY_THRESHOLD=0.92 \ loopshield:1.0.0 
from openai import OpenAI client = OpenAI( base_url="http://127.0.0", api_key="sk-..." )

Option 2: Use the Python SDK Directly

Install via pip and wrap your agent steps in-process:

pip install loopshield 
from loopshield import AgentStep, LoopShield shield = LoopShield(similarity_threshold=0.92, max_cycles=1) verdict = shield.step( AgentStep( thought="Checking config file again.", tool_name="read_file", tool_args={"path": "config.txt"}, tokens_used=12, ) ) if verdict.is_loop: print(verdict.intervention_prompt)

Native middleware wrappers are also included for LangChain, LangGraph, and CrewAI (pip install "loopshield[langchain]").

Check Out the Code

How are you currently handling runaway agent loops and token budgets in production? I would love to hear your thoughts in the comments!