Sessions and Turns

A Session is one stored conversation belonging to a Tenant and Agent. Use it when later chat Turns need earlier messages; stateless generation is still a Turn but has no Session, while each executing Task run receives a fresh Session.

Session and Turn ownership

A Turn is one metered execution of an Agent request. The Tenant owns the Agent, Session, transcript, and usage; a Session belongs to exactly one Agent and cannot be resumed through another Agent.

Session list results are summaries. Each item contains its id, nullable agentVersion Pin, timestamps, messageCount, lastMessagePreview, userId, and metadata; fetch messages separately for the full transcript.

Start and resume a Session

Starting chat without sessionId calls POST /v1/agents/:agentId/sessions. Blazing Agents mints an ss_… ID, returns 201 Created with its canonical resource path in Location, and exposes the ID as result.sessionId in the TypeScript SDK. The ID is available from the response headers before the Turn finishes.

The Session row materializes lazily with the first successful Turn. Resume it by passing the returned ID; the SDK then calls the Session URL and the platform loads its stored history. A failed or aborted first Turn leaves no Session to resume.

const first = await client.chat({
  agentId,
  message: {
    id: "message-1",
    role: "user",
    parts: [{ type: "text", text: "Plan a weekend in Lisbon." }],
  },
});

for await (const _chunk of first.toUIMessageStream()) {
  // Drain the stream so the Turn settles.
}
const sessionId = await first.sessionId;

const second = await client.chat({
  agentId,
  sessionId,
  message: {
    id: "message-2",
    role: "user",
    parts: [{ type: "text", text: "Make it suitable for children." }],
  },
});

for await (const _chunk of second.toUIMessageStream()) {
}
const transcript = await client.sessions.messages(agentId, sessionId);
console.log(transcript.data);

The final read contains the committed messages from both successful Turns.

Successful and failed Turns

A successful interactive Turn atomically commits the accepted user message, the assistant message and its Tool activity, pending Tool-approval records, and any regeneration truncation. Its assistant-message metadata includes the Turn's usage summary.

Failed and cancelled interactive Turns are metered but do not change the transcript. A mid-stream failure therefore cannot leave a partial exchange in the Session, and a failed first Turn cannot create an empty Session. Task-run Sessions differ: their messages are committed incrementally so asynchronous progress can be inspected while the run is active.

Read and poll the transcript

client.sessions.messages returns AI SDK UIMessage values in chronological order within each page. The default limit is 50 and the maximum is 200.

With neither cursor, the response contains the newest page. Pass opaque nextCursor back as cursor to walk backward to older pages.
Pass latestCursor back as after to poll forward for messages added after that tail. When a forward page has more data, continue with nextCursor as the next after value.
latestCursor is present whenever a returned page is non-empty, even when nextCursor is null. An empty poll returns both cursors as null.
cursor and after are mutually exclusive. Treat both as opaque values.

Version and end-user Attribution

Without a Pin, every Turn resolves the Agent's latest Version at that time and records the resolved number in usage; the Session's agentVersion remains null. A version supplied when starting the Session Pins that Session for its lifetime and is recorded as agentVersion; resume calls cannot override it. See Versions and lifecycle.

The first successful Turn also stamps the Session's immutable userId and initial metadata. userId is a trusted, Tenant-chosen shadow identity used for filtering and grouping; an empty string means Tenant-level. Attribution is not authorization: an API key can access the whole Tenant, so application access rules belong in the Tenant backend. See tenancy and end-user Attribution and the multi-tenant application guide.

Busy, deleted, and concurrent Sessions

A missing, foreign, or deleted Session returns 404; resume never silently creates a replacement. A new Turn or regeneration returns SESSION_BUSY with status 409 while any approval has decision: "pending" or a continuation has state: "waiting", "queued", or "running". Deletion checks only active continuation state: it returns SESSION_BUSY for those three continuation states, but a Session with pending decisions and no continuation can still be deleted.

Ordinary concurrent Turns can resolve the same Session version, but commits use optimistic version checks. After one commits, a competing stale commit fails with a Session version mismatch instead of merging histories. Serialize Turns per Session in the application when their ordering matters.