Sessions and turns

A session is a durable conversation pinned to one version of an agent. A turn is the work Cereal does in response to an input: call the model, run requested tools, and repeat until the model finishes or a stopping condition is reached. Your application can send more inputs to the same session.

The durable event log records messages, tool calls, decisions, and status changes. The browser stream is a client-safe projection of this log, plus live previews. It does not expose the raw log or internal model request data.

A turn

A typical turn moves through:

User message → running → model response → tools → model response → idle
                                             ↘ approval → resume

Session status is running, idle, or terminated. idle does not mean success. Its stopReason distinguishes completion from an interrupt, a limit, an error, or required action. An approval parks work until a decision arrives; the session and its pending call survive a browser disconnect.

Read failure handling for examples of each outcome.

The events worth knowing

Use durable agent.message events to build a transcript. agent.text_delta is a live preview and is not a resume point. Tool and status events explain progress. The event catalogue owns event names and field references.

Who a message is from

Messages have a user, assistant, or system role. User input normally starts a turn; system and assistant messages can seed context. System messages are not included in the browser stream. Role and delivery mode are different: delivery modes determine when input affects work.

See seeding a conversation for the request fields and examples.

Reading it

Server-side event reads expose the authorized log. Browser subscriptions use a short-lived token for a single session and a projection suitable for that viewer. Keep a transcript as well as a cursor if you persist browser state; a cursor alone cannot reconstruct earlier messages. See the chat tutorial and streaming protocol.

Interrupting

An interrupt ends the current turn while preserving the conversation. Steering instead adds input for the running turn. See interrupting a session.

Durability

Completed work remains in the durable log. On recovery, an unfinished model request may be retried. An unfinished tool call marked read-only or idempotent may be run again; other tool calls receive an interrupted result. A pending human decision remains pending. Design side-effecting tools to tolerate retries where promised; an annotation does not make a non-idempotent service safe to repeat.

Ephemeral deltas are not retained. Reconnection replays durable messages, so the UI can recover even if a typing preview was interrupted.

Listing

Sessions can be filtered by agent, status, identity, and metadata. Child sessions are sessions too; the roots filter selects top-level work. See list conversations for request examples.

Starting one exactly once

Use a stable idempotency key when retrying one logical create. Reusing the key returns the original session, even if the later payload differs. Generate a new key for a new conversation. See creation retries and send retries.