Skip to main content
Keep your existing agent construction and input. LoopGuard attaches through the callbacks entry in the run config and records tool starts, results, and errors.

​
Attach the callback

In this example, agent is your already-built LangGraph/LangChain agent and my_input is the input it normally accepts.
Create one handler per run. If you reuse a handler, call handler.reset() before the next run to clear its recorded state.

​
Let the interrupt reach your application

At STOP, the handler raises LoopGuardInterrupt unless observe-only mode is enabled. LangChain callbacks normally suppress callback errors, so set handler.raise_error = True when you want to catch the interrupt around invoke. An agent can have another error boundary around tool execution. If that boundary catches the interrupt and returns an error message to the model, the agent may continue. Configure it to propagate LoopGuardInterrupt and verify this using a repeated-empty-result run before relying on automatic interruption. For LangGraph’s ToolNode, handle_tool_errors=False propagates tool errors; this also changes handling of ordinary tool failures. A custom error handler can instead re-raise LoopGuardInterrupt while handling other exceptions. Check the behavior of your installed framework version. REPLAN and PAUSE remain recorded recommendations. This integration does not automatically replace a plan, suspend a graph, or roll back a completed tool call.

​
Observe first

Use observe-only mode when tuning thresholds or comparing LoopGuard decisions with your own run labels:
The callback’s interrupted report field records whether STOP was reached, including in observe-only mode. Track actual execution separately in your application.

​
Load application settings

Save a small loopguard.yml in your working directory:
Then change the handler construction:
These limits count recorded tool events and calls, not model tokens. See configuration before choosing values for your workload.

​
Keep a report with the result

The repository’s run_with_loopguard helper returns the agent result alongside interruption state, signals, decisions, and metrics. For example, from a repository checkout with your compiled agent:
The helper uses default settings when you omit config_path.

​
Use the stream wrapper for supported graph updates

Use LoopGuard.stream() to inspect supported streamed graph updates and the decisions LoopGuard records:
The wrapper interprets the scripted demo state fields and LangGraph message updates. It reads the newest message and the first tool call in that message; it is not a general adapter for every possible graph state. Use callbacks to observe individual tool invocations or saved traces for exported runs. The four visual examples pair UI captures with runnable Python SDK streams. For framework background, see the official LangGraph overview.