> ## Documentation Index
> Fetch the complete documentation index at: https://loopguard.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## 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

> Catch agents that keep spending steps without getting closer to an answer.

LoopGuard watches an AI agent while it runs and checks whether it is still making
progress. It detects loops, repeated failures, and stalled runs while allowing
useful polling and retries to continue.

```text theme={null}
same tool + useful new result   -> continue
same tool + same empty result   -> stop
503 -> 503 -> success           -> continue
401 -> 401 -> 401               -> stop
```

These are patterns to look for, not guarantees about a fixed number of calls.
Decisions depend on the active detectors, thresholds, and recorded evidence.

> **[Get Started](https://loopguard.mintlify.site/getting-started.md)**
>
> Install the SDK and catch a stuck tool loop without an API key.

> **[View GitHub](https://github.com/mahimathacker/loopguard)**
>
> Explore the Python SDK, examples, and tests.

## See the problem

![LoopGuard demo with a red agent-tool loop, semantic repetition evidence, and an interrupted-run verdict](https://mintcdn.com/loopguard/XpzeUOn7Yfd_-2Y1/images/stuck-agent.png?fit=max\&auto=format\&n=XpzeUOn7Yfd_-2Y1\&q=85\&s=c5a9d3bad71eb79f9550415fcb0e551e)

Screenshot from a LoopGuard demo run showing repeated intent and an interrupted run.

The [visual examples and SDK code](https://loopguard.mintlify.site/demo/scenarios.md#run-the-visual-examples-through-the-sdk)
show how to inspect the same detection behavior from Python.

## Where LoopGuard fits

LoopGuard focuses on whether an agent is still making progress. It is not an agent
framework, a general observability platform, a tracing replacement, or an LLM
evaluation platform. Keep your existing agent and tracing tools; add LoopGuard
where you need evidence about repetition and stuck runs.

The Python package includes LangGraph/LangChain tool callbacks, a live-stream
wrapper, and saved-trace analysis. The local demo helps you compare healthy repeats
with runs that should stop.

> [!NOTE]
>
> The published `0.2.1` package supports the core callback and trace workflows.
> Gemini support, controlled demo scenarios, and additional decision display fields
> currently require the source checkout. See [release scope](https://loopguard.mintlify.site/development/status.md).

> **[Integrate with your agent](https://loopguard.mintlify.site/guides/integration.md)**
>
> Attach callbacks and handle runtime stop decisions.

> **[Understand the pipeline](https://loopguard.mintlify.site/how-it-works.md)**
>
> Follow an event from the agent to a runtime decision.

> **[Recognize stuck behavior](https://loopguard.mintlify.site/detection.md)**
>
> Compare repetition, failure, no progress, and cycles.

> **[Compare demo scenarios](https://loopguard.mintlify.site/demo/scenarios.md)**
>
> See healthy recovery beside runs that should stop.

Already running into a problem? Start with [troubleshooting](https://loopguard.mintlify.site/troubleshooting.md).

For background, read [AI agents and loops](https://loopguard.mintlify.site/concepts/agents-and-loops.md),
[tests, traces, and evals](https://loopguard.mintlify.site/concepts/tests-traces-and-evals.md), and
[agent trajectories and convergence](https://loopguard.mintlify.site/concepts/trajectory-and-convergence.md).

## Ask about LoopGuard

Use the menu beside the page title to open the current documentation page in
**ChatGPT**, **Claude**, **Google AI Studio (Gemini)**, **Perplexity**, or **Grok**.
These links open an external AI tool using your own account and include the page
as context for questions.

Try asking how to attach the callback, why a repeated tool call didn't stop, or
which features are available in the published package. Start from the relevant
guide or reference page and ask for links to the supporting documentation.

For a project-wide question, include the published site's `llms.txt` index or
`llms-full.txt` export. If the tool cannot fetch a page, use **Copy page** from
the same menu and paste the Markdown into your conversation. Public page fetching
needs the deployed docs URL; an external tool cannot read your localhost preview.


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