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.)

​
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