Sessions

A causal state container for an agent workflow - not a cache entry. How a session anchors bundles, branches, and the events that accumulate over a task.

A session is the home for a single agent workflow over time. It holds a stable prefix of bundles, one or more branches of history, and the events those branches accumulate as the agent works.

The most important thing to understand about a session is what it is not.

A session is not a cache entry. It is a causal state container. A cache entry is a physical optimization that can be discarded at any time; a session is durable customer state with lineage, ordering, and deletion semantics. The two live in different identity layers.

Shape

{
  "id": "ses_01jy...",
  "object": "session",
  "project_id": "prj_01jy...",
  "default_branch_id": "br_01jy...",
  "status": "active",
  "base_bundle_ids": ["bnd_agent_prefix"],
  "created_at": "2026-06-09T20:15:00Z"
}

base_bundle_ids are the stable prefix bundles every branch inherits.
default_branch_id is where events land unless you target another branch.
status is one of active, archived, or tombstoned.

Mutable metadata, immutable content

A session's metadata is mutable: status changes, labels, the set of base bundles can evolve. But the content it points at is immutable. The bundles are immutable, the events on its branches are immutable, and history only ever grows by appending. You change what a session is doing, never what it already did.

This split is deliberate. It means a session can be a long-lived, evolving object while every individual fact inside it stays fixed and auditable. When you later purge a session, there is a precise, ordered set of immutable records to remove.

How the pieces fit

Create a session over your stable prefix

Attach the bundles that hold your system policy, tools, and schema as base_bundle_ids. These form the cacheable front of every request in the session.

Work on a branch

A session always has at least a default branch. Each turn appends an immutable event - a user message, a tool result, an assistant message - to a branch.

Compile a snapshot per request

When you generate, the platform compiles a snapshot of the branch head: the ordered logical state the model will see. A response pins exactly one snapshot.

Why sessions raise your reuse

Because a session keeps stable bundles separate from changing events, the platform can recognize the recurring prefix family across every turn. That recurrence is exactly what reuse metrics measure and what drives the session_continuity component of the Workload Reuse Score. Traffic that belongs to multi-turn sessions is, almost by definition, traffic with reuse to capture.

Branches

How history grows safely under concurrency.

Sessions and branching

Build a multi-turn agent on /v2.