> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trymaitai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

> Debug multi-turn behavior (including agent runs) via session timelines and task details.

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](/observe/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`.

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

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)](/sdk/observe).

## 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