Runtime guardrails for AI agents that detect loops, repeated failures, and runs that stop making progress.
same tool + useful new result -> continue
same tool + same empty result -> stop
503 -> 503 -> success -> continue
401 -> 401 -> 401 -> stop
Agents can keep spending time and tokens without getting closer to an answer. LoopGuard watches LangGraph and LangChain runs and checks repeated actions against results, progress, and failures. Useful polling can continue; repeated empty results can provide evidence to stop.
It complements your agent and tracing tools by turning recorded behavior into runtime decisions. The examples above illustrate patterns; thresholds and evidence determine the actual decision.
Screenshot from a LoopGuard demo run showing repeated intent and an interrupted run. The four visual examples pair detection explanations with Python SDK code so you can inspect the same behavior in your own program.
Watch the demo · Run it locally
Prerequisites: Python 3.11+ and pip. This integration assumes an existing LangGraph/LangChain agent and its framework dependencies.
pip install loopguard-runtimeThe package is loopguard-runtime; the import is loopguard. With your existing
agent and my_input:
from loopguard import LoopGuardCallbackHandler, LoopGuardInterrupt
handler = LoopGuardCallbackHandler()
handler.raise_error = True
try:
result = agent.invoke(my_input, config={"callbacks": [handler]})
except LoopGuardInterrupt as exc:
print("LoopGuard stopped the run:", exc)
print(handler.report())LangChain must propagate callback errors, and the agent's tool-error handling must
let LoopGuardInterrupt escape. Use interrupt_on_fatal=False to collect reports
without raising. REPLAN and PAUSE are recorded recommendations today.
Run a complete example without a model or API key →
| Pattern | Evidence |
|---|---|
| Exact and semantic loops | Repeated calls or repeated intent in different words. |
| Stalls and no progress | Unchanged, empty, or error-like tool results. |
| Repeated failures | Retryable errors versus likely permanent failures. |
| Action and handoff cycles | Repeating sequences or closed multi-agent handoffs. |
| Budget overruns | Configurable limits on recorded steps and tool calls. |
Agent event -> Tracer -> Detectors -> Signals -> Policy -> Decision
Repetition alone can warn; repetition plus no progress can stop. The policy combines
signals into CONTINUE, WARN, REPLAN, PAUSE, or STOP.
Use callbacks during a live run, or inspect an exported trace without rerunning the agent. From a repository checkout:
python -m loopguard.ingest examples/sample_trace.json
python -m loopguard.check examples/sample_trace.jsoningest reports findings; check gives pass/fail behavior for scripts or CI.
The sample includes a loop, so its check exits with code 1.
Integration guide · Saved traces
Compare offline exact loops, paraphrased searches, healthy polling, temporary 503
recovery, permanent 401 failures, empty results, and real calculation/search agents.
Only exact runs without provider credentials; other scenarios need a model,
embeddings, or both.
The core suite uses fake agents and embeddings and runs offline:
python -m unittest discover -vThe repo also includes labeled progress-aware traces and a small detector evaluation harness. Evaluation and its limits →
Hosted documentation: Read the LoopGuard docs.
The Mintlify source covers the full developer journey. The concept guides explain agent loops, tests and traces, and evaluating the path as well as the answer. See preview and deployment instructions, troubleshooting, or the Python API. For changes to the project, read Contributing.
loopguard-runtime v0.2.1 is an alpha release. Python 3.11+ is required; package classifiers list 3.11 and 3.12. Gemini support and controlled demo scenarios currently require the source checkout. JavaScript support and GitHub check annotations remain roadmap ideas.