GuardReport & Telemetry

Every agent execution produces a structured GuardReport snapshot.

---

Accessing the Report

# In LangGraph:
guard = workflow.__longguard__
report = guard.get_report()

# Or directly on CircuitBreaker:
report = breaker.report

---

Output Formats

1. Human-Readable Summary

print(report.summary())

Output:

=== LongGuard Run Report ===
Total Steps: 5
Total Tokens: 1,842
Final State: open
Detections: 2
Reflections Injected: 1
Estimated Cost: $0.0184 USD (gpt-4o)
Kill Reason: reflection_failed: tool_repeat (confidence: 100%)

Detection Details:
  Step 4: tool_repeat (confidence: 100%)
  Step 5: tool_repeat (confidence: 100%)

2. JSON Serialization (Logging & Metrics)

json_str = report.to_json()

3. Python Dictionary

data = report.to_dict()
# {
#   "total_steps": 5,
#   "total_tokens": 1842,
#   "estimated_cost_usd": 0.0184,
#   "model": "gpt-4o",
#   "final_state": "open",
#   "kill_reason": "reflection_failed: tool_repeat...",
#   "detections": [...],
#   "step_timeline": [...]
# }

---

Saving & Loading Reports (v0.1.3)

Persist run telemetry to disk for CI artifacts, post-mortem debugging, or dashboards:

# Save to JSON (zero extra dependencies)
report.save("run_report.json")

# Save to YAML (requires: pip install pyyaml)
report.save("run_report.yaml")

# Load a saved report back for analysis
from longguard import GuardReport
loaded = GuardReport.load("run_report.json")
print(loaded.summary())

---

Event Callbacks

Stream events to LangSmith, Datadog, or custom webhooks:

def on_guard_event(event_name: str, payload: dict):
    print(f"LongGuard Event [{event_name}]: {payload}")

breaker = CircuitBreaker(
    config=GuardConfig(emit_events=True),
    event_callback=on_guard_event,
)

# Emits:
# - "detection": loop pattern detected
# - "reflect": pivot prompt injected
# - "kill": agent killed
# - "recovered": circuit recovered to CLOSED