agent-patrol

Runtime pathology detection for AI agents. Diagnoses loops, stalls, oscillation, drift, and silent abandonment.

The Problem

Your AI agents get stuck. They loop, oscillate, stall, drift from their task, and silently abandon their mission -- and you don't know until the token bill arrives.

Current solutions are blunt instruments:

• max_steps / timeout -- kills productive and unproductive agents equally
• Observability platforms -- trace what happened but not why it went wrong
• Framework-specific guards -- locked to one framework, not portable

agent-patrol diagnoses what kind of failure your agent is experiencing, in real time, across any framework.

Five Agent Pathologies

Installation

pip install agent-patrol

Zero hard dependencies. Works with Python stdlib alone. Optional enhancements:

# For embedding-based detection (recommended for production)
pip install agent-patrol[embeddings]

# For LLM-based semantic analysis
pip install agent-patrol[llm]

Quick Start

Option 1: Decorator

from agent_patrol import patrol

@patrol(on_pathology="log", sensitivity="medium")
def agent_step(state: dict) -> dict:
    # Your agent logic here
    return new_state

Option 2: Monitor

from agent_patrol import PatrolMonitor

monitor = PatrolMonitor(
    task_description="Research and summarize recent economic data",
    milestones=["Find GDP data", "Find inflation data", "Write summary"],
)

for step in agent_loop():
    report = monitor.observe(step.action, step.result)
    if report.pathology:
        print(f"DETECTED: {report.pathology} at step {report.step_detected}")
        print(f"Evidence: {report.evidence}")
        print(f"Action: {report.recommended_action}")

Option 3: CI Gate

# Run agent-patrol on a recorded trace file
agent-patrol check trace.jsonl --fail-on FUTILE_CYCLE,STALL

Output

PatrolReport(
    pathology="FUTILE_CYCLE",
    confidence=0.87,
    step_detected=14,
    evidence=["Steps 12-14: repeated 'search for X' with <0.05 semantic variance"],
    recommended_action="HALT",
    total_steps_observed=14,
    token_estimate_wasted=3400,
)

Framework Integration

Works with any agent framework. No lock-in.

• LangGraph -- wrap your node functions
• CrewAI -- wrap agent step callbacks
• OpenAI Agents SDK -- wrap tool execution
• Anthropic Claude Agent SDK -- wrap tool use blocks
• Raw loops -- wrap your iteration function

See examples/ for integration guides.

Configuration

from agent_patrol import PatrolConfig

config = PatrolConfig(
    # Detection sensitivity (low = fewer false positives, high = catches more)
    sensitivity="medium",  # "low" | "medium" | "high"

    # Which pathologies to detect
    detect=["FUTILE_CYCLE", "OSCILLATION", "STALL", "DRIFT", "ABANDONMENT"],

    # What to do when pathology is detected
    on_pathology="log",  # "log" | "raise" | "halt" | "callback"

    # Similarity backend
    similarity_backend="tfidf",  # "tfidf" | "embeddings" | "llm"

    # Custom thresholds
    cycle_similarity_threshold=0.92,
    stall_window=5,
    drift_threshold=0.60,
    oscillation_min_switches=3,
)

How It Works

agent-patrol maintains a rolling window of agent actions (text descriptions + optional state). For each new action, it runs five lightweight detectors:

1. Futile Cycle Detector -- Computes pairwise similarity in a sliding window. If the last N actions are all >0.92 similar, the agent is cycling.

2. Oscillation Detector -- Clusters actions by semantic similarity. If the agent alternates between 2+ clusters more than 3 times, it is oscillating.

3. Stall Detector -- If milestones are declared, computes distance to each milestone at every step. If the minimum distance is non-decreasing for 5+ steps, the agent is stalled.

4. Drift Detector -- Maintains the original task embedding. Computes cosine similarity between current action context and original task. If below 0.60, intent has drifted.

5. Abandonment Detector -- Combines drift detection with novel-cluster detection. If the agent is far from its original task AND close to a new coherent objective, it has silently abandoned its task.

Why This Exists

Every team running AI agents in production has experienced stuck agents. The token cost of a stuck agent looping for 200 steps before a timeout kills it can be $5-50 per incident. Multiply by hundreds of daily agent runs and the cost is material.

More importantly: stuck agents produce bad output. A stalled research agent returns incomplete results. A drifted coding agent implements the wrong feature. An oscillating planning agent produces an incoherent plan. These failures are silent -- the agent returns output that looks complete but isn't.

agent-patrol makes these failures visible and actionable.

License

MIT