Skip to main content
You can inspect a saved trace without access to the original agent, model, or tools. The analyzer reads JSON, maps each exported step into observations, and runs the offline detectors. It does not rerun the agent.

​
Inspect the included traces

From a repository checkout with LoopGuard installed:
The sample has three runs: one looping, one stalled/warned, and one clean. Its summary ends with:
Use JSON when another program needs the results:
ingest exits successfully after analysis even when it finds a loop. Use check when detection should affect the process exit code.

​
Fail a script or CI check

The default failure rule is looping. This sample exits with code 1 because it contains a run where the policy reaches STOP. To fail on warnings as well as stops:
--fail-on stalled by itself checks only stalled status; it replaces the default looping rule. --fail-on alerts fails when a run has any recorded alert.

​
Add per-run budgets

Budgets fail independently of the selected statuses and trigger only when a count is greater than the maximum. For saved traces, max_steps counts exported steps. One step containing both a call and a result becomes two internal events.

​
Keep check settings in a file

Save this as loopguard.yml:
Command-line values override the file. These check settings control failure rules and budgets; they do not configure live detectors or turn on semantic detection.

​
Analyze more than one file

The JSON report includes aggregate counts, matched failure rules, budget violations, and per-source reports. Redirect it to a file if your CI needs an artifact:
The exit code is still 1 for this sample; JSON output does not disable failure.

​
Trace shape

A file can contain one run object or a list of run objects. Each run has a steps list; run_id is optional and defaults to unknown.
This one-step example is too short to establish a loop. Add the rest of the run when exporting a real trace. The adapter accepts several common names for each field. It uses the first present, non-null value in the order shown: Non-object arguments become a value entry. Result text is flattened and truncated to 160 characters before comparison. Supply caller together with the acting agent name to preserve handoff information. No step index is required; list order determines replay order.

​
Interpret the status

  • looping: a policy decision reached STOP anywhere in the replay, including permanent failures or handoff loops.
  • stalled: no STOP, but the final decision is something other than continue.
  • clean: neither condition matched.
Earlier alerts can remain even when the final status is clean. The analyzer replays the full export after a stop decision, so final_decision can differ from the earlier stop. Check status and alert history together. Both CLIs use offline detectors by default. For custom or semantic detectors, use the Python analysis functions. CLI reference · Configuration reference To preserve expected healthy and stuck behavior across changes, add a trace regression check.