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

# Getting started

> See LoopGuard catch repeated empty results, then attach it to your own agent.

You need Python 3.11+ and pip in your existing Python project.

## Install the package

```bash theme={null}
pip install loopguard-runtime
```

The **PyPI package** is `loopguard-runtime`. The **Python import** is `loopguard`.
The core package has no required third-party dependencies or API key requirement.

For the working tool example below, install the framework extra if your project
doesn't already include LangChain/LangGraph:

```bash theme={null}
pip install "loopguard-runtime[langgraph]"
```

## Catch a stuck tool loop

Save this as `first_run.py`. It uses a real LangChain tool with scripted output,
so you can exercise the callback path without calling a model or external service.

```python theme={null}
from langchain_core.tools import tool
from loopguard import LoopGuardCallbackHandler, LoopGuardInterrupt

@tool
def search(query: str) -> str:
    """Search for a source; this example always returns no results."""
    return "no results"

handler = LoopGuardCallbackHandler()
handler.raise_error = True

try:
    for _ in range(3):
        search.invoke({"query": "pricing page"}, config={"callbacks": [handler]})
except LoopGuardInterrupt as exc:
    print("LoopGuard stopped the run:", exc)

report = handler.report()
print("Decision:", report["decisions"][-1]["action"])
print("Tool calls:", report["metrics"]["tool_calls"])
```

Run it:

```bash theme={null}
python first_run.py
```

The final summary shows:

```text theme={null}
Decision: stop
Tool calls: 3
```

Three identical calls returned no useful new information, so LoopGuard requests
a stop. The callback raises `LoopGuardInterrupt`, which the example catches.
LangChain may also log the callback exception; that is expected for this run.

> [!NOTE]
>
> `handler.raise_error = True` lets LangChain propagate the interrupt. Your agent's
> tool-error handlers must also let it escape. Follow the
> [integration guide](https://loopguard.mintlify.site/guides/integration.md#let-the-interrupt-reach-your-application)
> when attaching LoopGuard to your own agent.

To record decisions without stopping execution, replace the handler construction:

```python theme={null}
handler = LoopGuardCallbackHandler(interrupt_on_fatal=False)
```

All three calls finish, while the report still records a `stop` recommendation.
Its `interrupted` flag records that recommendation, not proof that execution stopped.
See [observe-only mode](https://loopguard.mintlify.site/guides/integration.md#observe-first) and the
[report reference](https://loopguard.mintlify.site/reference/python.md#read-the-result) for details.

## Next steps

* [Add LoopGuard to a LangGraph/LangChain run](https://loopguard.mintlify.site/guides/integration.md).
* [Understand healthy repetition and stuck runs](https://loopguard.mintlify.site/detection.md).


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