# LoopGuard

> Detect stuck AI agents without treating every retry as a loop.

> ## Agent Instructions
> LoopGuard is a Python runtime guardrail SDK. Install loopguard-runtime and import loopguard. Use /getting-started and /guides/integration for application code.
> Use the Concepts section for agent loops, tests versus traces versus evals, and trajectory/convergence. The convergence helper compares counts without checking success; LoopGuard events are not OpenTelemetry spans. Distinguish these general concepts from implemented SDK features.
> The exact, semantic, calc, and trap UI examples illustrate Python SDK detection behavior. Read /demo/scenarios for runnable SDK examples and /guides/integration to attach callbacks or inspect streamed updates.
> These docs follow the checkout. PyPI 0.2.1 lacks Gemini support, controlled demo scenarios, and additional decision display fields; check /development/status before describing release capabilities.
> Repetition alone does not force STOP. REPLAN and PAUSE are recorded recommendations. Observe-only mode records decisions without raising. Follow /guides/integration for interrupt propagation.
> Use the Python API, CLI, and configuration references for supported names and flags. Screenshots illustrate observed runs, not guaranteed stop counts or benchmark results.

- [LoopGuard](https://loopguard.mintlify.app/index.md): Catch agents that keep spending steps without getting closer to an answer.
- [Getting started](https://loopguard.mintlify.app/getting-started.md): See LoopGuard catch repeated empty results, then attach it to your own agent.
- [How LoopGuard works](https://loopguard.mintlify.app/how-it-works.md): Understand events, detector evidence, and the policy that decides what happens next.
- [AI agents and loops](https://loopguard.mintlify.app/concepts/agents-and-loops.md): Understand the agent decision cycle and distinguish useful repetition from a run that is stuck.
- [Tests, traces, and evals](https://loopguard.mintlify.app/concepts/tests-traces-and-evals.md): Check the answer and the path, and choose the right evaluator for each kind of failure.
- [Agent trajectories and convergence](https://loopguard.mintlify.app/concepts/trajectory-and-convergence.md): Compare run paths, understand the step-count score, and turn failures into regression cases.
- [Detecting stuck agents](https://loopguard.mintlify.app/detection.md): Recognize repeated actions, stagnant results, failures, cycles, and exceeded budgets.
- [LangGraph and LangChain](https://loopguard.mintlify.app/guides/integration.md): Add tool callbacks to an existing agent and control how stop decisions reach your application.
- [Configure LoopGuard](https://loopguard.mintlify.app/guides/configuration.md): Tune run limits and detection sensitivity for the way your agent works.
- [Analyze saved traces](https://loopguard.mintlify.app/guides/saved-traces.md): Replay an exported run locally and use check mode for script or CI pass/fail behavior.
- [Add a trace regression check](https://loopguard.mintlify.app/guides/regression-checks.md): Turn a healthy or stuck run into a repeatable test without rerunning the original agent.
- [Demo scenarios](https://loopguard.mintlify.app/demo/scenarios.md): Run the Python SDK behind the UI examples and compare healthy and stuck behavior.
- [Run the demo UI](https://loopguard.mintlify.app/demo/running-locally.md): Start the local backend and frontend, then compare healthy and stuck runs.
- [Evaluation and tests](https://loopguard.mintlify.app/development/evaluation.md): Check offline behavior and understand what the small detector evaluation measures.
- [Troubleshooting](https://loopguard.mintlify.app/troubleshooting.md): Diagnose missing imports, provider failures, unexpected decisions, and demo connection problems.
- [Project status](https://loopguard.mintlify.app/development/status.md): Current scope, repository layout, and directions that remain roadmap ideas.
- [Contributing and docs maintenance](https://loopguard.mintlify.app/development/contributing.md): Run the checks, review developer-facing changes, and keep documentation accurate as the SDK evolves.
- [Python API](https://loopguard.mintlify.app/reference/python.md): Public integration entry points, report shapes, and lower-level extension APIs.
- [CLI reference](https://loopguard.mintlify.app/reference/cli.md): Supported trace commands, flags, and exit behavior.
- [Configuration reference](https://loopguard.mintlify.app/reference/configuration.md): Supported file settings, defaults, and provider environment variables.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.