Skip to main content
Sessions are the primary way to debug multi-turn behavior in Maitai. A Session groups related requests together under a shared session_id and provides a timeline view in the Portal. For single-request debugging (including reruns for prompt/model changes), use the Request Overview page.

​
What is a Session?

A Session represents a single, continuous interaction (for example, one end-user conversation in your product).
  • A standard chat completion is one request/response.
  • A session is many requests/turns tied together by session_id.
For the best Portal experience, pass a stable session_id for each end-user session. (If you omit it, the SDK can generate one automatically, but you’ll lose the ability to thread requests the way your product does.)
For observed agents (maitai.observe()), session grouping uses maitai.set_session() / maitai.session(). When no session attribute is present on the trace, ingest falls back to session_id = trace_id (one invocation = one session). See Observe (BYOA).

​
Using Session Details

The Session Details page is your command center for understanding what happened and why.

​
The Timeline

The Timeline is a chronological flow of events in the session, including:
  • user messages and assistant responses
  • evaluation outcomes (when enabled)
  • (for agents) internal steps and tool executions

​
Context Sidebar

The right-hand sidebar provides the metadata and environment state for the session:
  • Session ID & metadata: quickly copy identifiers for debugging
  • Active context: what was available at runtime (when applicable)
  • Usage and timing: token counts, cost, and latency (when available)

​
Stepping into Tasks

For Agents, sessions can include nested tasks (API actions, sub-agent calls, etc.). These tasks form a tree. To step into a task:
  1. Locate the task block in the Timeline.
  2. Click View Task Details.
  3. Inspect inputs, outputs, and intermediate steps.

​
Utilizing Agent Task Details

Agent Task Details provides the most granular view of a single unit of work in an agent run.

​
Granular Trace

Every task has its own mini-lifecycle:
  • Input parameters: arguments passed to a tool or subagent
  • Execution logs: for API actions, the raw request/response (when available)
  • Outputs: what the tool returned and how it affected the next steps

​
Efficient Debugging with Task Details

  • Identify parameter mismatches: did the agent call a tool with the wrong args?
  • Tune capabilities: do you need to tighten schemas, descriptions, or instructions?
  • Verify context usage: what context was available for this step?

​
Using Sessions for Optimization

Sessions are your primary tool for understanding why a system behaved a certain way.
  • Spot failures: correlate faults with specific requests and context
  • Optimize tool usage: reduce unnecessary calls and tighten schemas
  • Refine prompts/config: iterate based on real examples