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

# How LoopGuard works

> Understand events, detector evidence, and the policy that decides what happens next.

LoopGuard separates what happened from what the application should do about it.
A repeated call is evidence. Stopping the run is a policy decision.

For the broader agent cycle, start with [AI agents and loops](https://loopguard.mintlify.site/concepts/agents-and-loops.md).
For the difference between a runtime decision and an evaluation, see
[tests, traces, and evals](https://loopguard.mintlify.site/concepts/tests-traces-and-evals.md).

```mermaid theme={null}
flowchart TD
    A[Agent event] --> B[Tracer]
    B --> C[Detectors]
    C --> D[Signals]
    D --> E[Policy]
    E --> F[Continue / Warn / Replan / Pause / Stop]
```

## Record what happened

The tracer stores ordered events. A tool call and its returned result are separate
events, so three tool calls can produce six recorded events.

An **event** describes one observation: which node acted, what it did, its normalized
signature, and any attached details. For example, a search call might produce a
`tool:search(query=pricing)` signature, followed by `result:no results`.

Live callbacks record tool starts, tool results, and tool errors. They do not record
every token, thought, or arbitrary graph node.

## Collect evidence

Detectors inspect the new event and the trace so far. A **signal** describes a
finding, such as a repeated tool call, unchanged output, or a permanent failure.
It includes a score and the evidence behind the finding.

Consider these two runs:

```text theme={null}
poll job -> pending
poll job -> processing
poll job -> completed
```

```text theme={null}
search -> no results
search -> no results
search -> no results
```

Both repeat an action. The first returns new information; the second doesn't.
LoopGuard compares recorded output signatures and uses simple text heuristics.
It does not prove whether the agent has achieved a business goal.

## Make a decision

A **decision** combines signals into an action, a risk score, and reasons.
The default policy can produce:

| Action | Current behavior |
| - | - |
| `continue` | Keep running. |
| `warn` | Record evidence worth inspecting. |
| `replan` | Record a recommendation to change approach. |
| `pause` | Record a recommendation to pause for review. |
| `stop` | Request interruption through the active integration. |

> [!NOTE]
>
> `REPLAN` and `PAUSE` do not rewrite the plan or suspend execution. Your application
> must act on those recommendations. Observe-only mode also records `STOP` without
> raising an interrupt.

With the default policy, exact repetition alone produces a warning. Repetition or
an action cycle combined with no-progress evidence can reach `STOP`. Repeated
permanent failures, repeated closed handoff cycles, and exceeded budgets can also
reach `STOP`.

The monitor retains recent signals. When new evidence fires, the policy considers
up to the last 12 signals. An event with no new signal gets a `continue` decision;
an earlier `STOP` still makes the run's interruption flag true.

## Enforce the decision

The callback handler raises `LoopGuardInterrupt` on `STOP` when interruption is
enabled. The surrounding framework must let that exception propagate.

The stream wrapper checks the monitor after a streamed update and stops consuming
the stream at `STOP`. This does not undo completed tool calls or cancel external
work that a tool has already started.

Saved-trace analysis replays the entire export. It reports where `STOP` would have
occurred without rerunning or interrupting the original agent.


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