Sessions

A session is an append-only record of everything an agent does during a single run: decisions, tool calls, results, and intermediate state. One run, one session.

Why this matters

Agents make multi-step decisions over long horizons. The session lets you reconstruct any run after the fact: which input caused which action, which tool returned what, and which step failed.

What a session contains

Each session has a unique ID and a sequence of timestamped events. Events are idempotent, so a retried step produces the same event rather than a duplicate. That's what makes orchestration safe to retry.

The event stream includes:

• Plans and decisions. What the agent is about to do, and why.
• Tool calls and results. Name, input, output, latency, cost.
• Checkpoints. Intermediate state the run can resume from.
• Status transitions. pending → running → succeeded | failed | cancelled.

Where to find them

Every run has a session attached. You can:

• Stream events live with GET /api/v1/runs/{run_id}/logs.
• Read run-level metadata — status, cost, token counts, error — with GET /api/v1/runs/{run_id}.

Sessions are also the data you compare when you optimize an agent — two versions of an agent, compared head-to-head, is two sets of sessions compared head-to-head.