Documentation
Issues & Diagnosis
Guardy automatically detects issues in your agent sessions and provides AI-powered diagnosis to help you fix them fast.
How Issue Detection Works
Guardy analyzes every session automatically to identify problems. No manual tagging required.
Every session is analyzed in real-time as events stream in.
LLM evaluates sessions for failures, confusion, errors, and inefficiencies.
Similar issues are grouped together so you see patterns, not noise.
What We Detect
Guardy identifies a wide range of issues across your agent sessions:
| Issue | Description | Severity |
|---|---|---|
| Task Failures | Agent failed to complete the user's request | High |
| Tool Errors | A tool call failed, returned unexpected results, or timed out | High |
| Hallucinations | Agent made claims not supported by context or tools | High |
| User Frustration | Signs of user dissatisfaction, repeated questions, or negative sentiment | Medium |
| Confusion Loops | Agent appears stuck, repeating actions or asking the same questions | Medium |
| Slow Responses | Session took significantly longer than expected | Low |
| High Cost | Session used more tokens/cost than typical | Low |
AI-Powered Diagnosis
When you click on an issue, Guardy provides:
- Root Cause Analysis — Why did this happen? What triggered it?
- Affected Sessions — All sessions impacted by this issue
- Recommended Fix — Specific suggestions to resolve the issue
- Code Context — Links to relevant code if GitHub is connected
The Signals Page
The Signals page in your dashboard is your command center for issues:
All detected issues sorted by severity and frequency.
See how issue counts change over time.
Filter by agent, time range, severity, or issue type.
Jump to diagnosis, affected sessions, or code fixes.
Fixing Issues in Code
Best Practices
Track session outcomes
Always call complete_session() with success=True/False so we can identify failures.
Include failure reasons
When success=False, include failure_reason for better diagnosis.
Use consistent agent names
Group sessions by agent_name to see issues per agent type.
Track user IDs
Include user_id to identify user-specific issues and patterns.
# Good: Complete session with full context
client.complete_session(
session_id=session_id,
success=False,
failure_reason="Tool 'search_kb' returned empty results for query",
estimated_cost=0.023
)
# This gives Guardy the context to:
# - Identify this as a tool failure issue
# - Group similar empty-result failures
# - Suggest fixes (e.g., improve search, add fallback)