Sessions
Group multi-turn agent conversations and visualize cross-agent execution graphs.
Sessions
Sessions group related traces into multi-turn conversations. Each trace can carry a session_id that links it to a logical session — useful for chatbots, multi-step agents, and multi-agent systems.
Recording a Session
@retrace.record(name="chat-agent", session_id="sess-abc-123")
def handle_message(user_input: str):
return agent.run(user_input)const run = trace(handler, { name: "chat-agent", sessionId: "sess-abc-123" });Listing Sessions
curl https://api.retraceai.tech/api/v1/sessions \
-H "x-retrace-key: rt_live_..."Returns sessions with trace counts, total cost, and time range.
Session Graph
curl https://api.retraceai.tech/api/v1/sessions/sess-abc-123/graph \
-H "x-retrace-key: rt_live_..."Returns a DAG of traces within the session, ordered by vector clocks for causal consistency.
Multi-Agent Tracing
Each span can carry an agent_id to identify which agent produced it:
with trace.span("tool-call", agent_id="planner-agent"):
result = planner.run(task)The session graph endpoint shows cross-agent interactions with causal ordering.
CLI
retrace sessions list --limit 20 --json
retrace sessions get sess-abc-123Graph Queries
Query the execution graph to find specific patterns:
curl -X POST https://api.retraceai.tech/api/v1/sessions/:id/query \
-H "x-retrace-key: rt_live_..." \
-H "Content-Type: application/json" \
-d '{"query_type": "compare_branches", "branch_a": "trace-1", "branch_b": "trace-2"}'Supported query types:
| Type | Description |
|---|---|
find_path | BFS path between two spans |
compare_branches | Find divergence point between two traces |
find_divergence | All points where execution paths branch |
filter_by_agent | Filter spans by agent_id, type, error status |
find_loops | Detect repeated span names (loop detection) |