🛡️ AgentLoopGuard

Detect and kill infinite AI agent loops before they burn your API budget.

The Problem

AI agents get stuck in loops. Your agent calls the same tool 50 times. Or it generates nearly identical outputs over and over. Or it oscillates between two states forever.

Meanwhile, your API bill climbs: $0.12... $1.50... $15.00... $47.00... $412.00.

You wake up to a surprise bill because your agent ran all night doing nothing useful.

The Solution

from agentloopguard import LoopGuard

guard = LoopGuard(
    max_iterations=50,
    max_cost_usd=10.00,
    max_duration_seconds=300,
)

with guard.session() as session:
    for step in my_agent.run():
        session.record({
            "tool_name": step.tool,
            "tool_args": step.args,
            "output": step.result,
            "model": "gpt-4o",
            "input_tokens": step.input_tokens,
            "output_tokens": step.output_tokens,
        })
        # LoopGuard watches every call.
        # Loops die. Your budget lives.

Installation

pip install agentloopguard

Four Detection Engines

All four run automatically on every session.record() call. Zero configuration needed.

Usage

As a Context Manager

from agentloopguard import LoopGuard

guard = LoopGuard(max_iterations=100, max_cost_usd=5.00)

with guard.session() as session:
    for i in range(200):  # Will be killed at iteration 100
        session.record({
            "tool_name": "search",
            "tool_args": {"query": "same thing"},
            "output": "same result",
            "model": "gpt-4o",
            "input_tokens": 100,
            "output_tokens": 50,
        })

As a Decorator

from agentloopguard import LoopGuard

guard = LoopGuard(max_cost_usd=10.00)

@guard.watch
def run_agent(prompt: str) -> str:
    # Your agent logic here
    ...

Custom Alert Handling

def my_alert_handler(detection_result):
    send_slack_notification(f"Loop detected: {detection_result.description}")

guard = LoopGuard(
    max_iterations=50,
    on_alert="callback",
    alert_callback=my_alert_handler,
)

Budget Tracking Only

from agentloopguard import BudgetTracker

tracker = BudgetTracker(max_cost_usd=20.00, max_tokens=1_000_000)

tracker.record(model="gpt-4o", input_tokens=500, output_tokens=200)
print(tracker.summary())
# {'total_cost_usd': 0.0055, 'total_tokens': 700, 'iterations': 1, ...}

Supported Models

Built-in pricing for:

• OpenAI: gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo
• Anthropic: claude-3.5-sonnet, claude-3-haiku, claude-3-opus
• Google: gemini-1.5-pro, gemini-1.5-flash, gemini-2.0-flash

Configuration

Performance

• <1ms overhead per record() call
• Zero external dependencies — stdlib only
• Thread-safe — works in async and multi-threaded agents
• No network calls — everything runs locally

License

MIT — free forever. Use it in production. Use it in your startup. Use it everywhere.

Links

• GitHub
• PyPI
• Changelog

Built by developers who got a $400 surprise API bill.