Documentation
Sessions & Tracking
Sessions are the foundation of Guardy. Every agent interaction is a session — a complete record of what happened, when, and why.
What is a Session?
A session represents a single agent interaction from start to finish. It captures:
When the interaction started and ended, plus duration.
Which user triggered the interaction.
Every LLM call, tool usage, and decision in sequence.
Whether the session succeeded or failed, plus metrics.
Creating Sessions
Simple API (Recommended)
The simplest way to track sessions using the begin/finish pattern:
import guardy
guardy.configure(api_key="guardy_live_xxx")
# Begin tracking
interaction = guardy.begin(
user_id="user_123", # Required: group by user
event="chat_message", # Event type (becomes agent name)
input="User's question", # Optional: input data
convo_id="conv_456" # Optional: conversation grouping
)
# Your agent logic...
response = agent.run(user_input)
# Finish with outcome
interaction.finish(
output=response,
success=True,
estimated_cost=0.023
)Full Control API
For more control over session data:
from guardy import GuardyClient
client = GuardyClient(api_key="guardy_live_xxx")
# Create session with full control
session_id = client.create_session(
name="Customer Support Request", # Descriptive name
agent_name="support-agent", # Groups sessions
user_id="user_123", # External user ID
metadata={ # Any custom data
"ticket_id": "TKT-789",
"channel": "web_chat",
"priority": "high"
}
)
# Track events manually...
# Complete session
client.complete_session(
session_id=session_id,
success=True,
estimated_cost=0.045,
prompt_tokens=1500,
completion_tokens=500,
custom_metrics={
"satisfaction": 4.5,
"resolution_time": 120
}
)Event Types
Sessions contain events that capture everything your agent does:
Tool Calls
When your agent uses a tool (search, API call, database query, etc.)
client.track_tool_call(
session_id=session_id,
tool_name="search_knowledge_base",
tool_input={"query": "password reset"},
tool_output={"results": ["KB-001", "KB-002"]},
reasoning="User asked about password reset",
estimated_cost=0.001
)Decisions
When your agent makes a choice between alternatives:
client.track_decision(
session_id=session_id,
reasoning="User needs password help, will search KB first",
alternatives=["escalate_to_human", "ask_clarifying_question"],
confidence=0.92
)Automatic Tracking
from guardy.langchain import GuardyCallbackHandler
# Create handler
handler = GuardyCallbackHandler(client, session_id)
# Use with your agent - everything tracked automatically!
result = agent_executor.invoke(
{"input": user_query},
{"callbacks": [handler]}
)
# Get real usage stats
print(f"Cost: ${handler.total_cost:.4f}")
print(f"Tokens: {handler.total_tokens}")
print(f"LLM calls: {handler.llm_calls}")Session Lifecycle
Session starts when agent begins processing.
Tool calls, decisions, and LLM calls are tracked.
Session ends with success/failure status and metrics.
Viewing Sessions
In the Guardy dashboard, you can:
- Browse all sessions with filters for time range, agent, user, and status
- Replay sessions to see exactly what happened step-by-step
- View event details including inputs, outputs, and reasoning
- See detected issues and jump to AI diagnosis