Sessions & events

A session pins its configuration when it is created (agent definition, model, environment, memory) and keeps an append-only event log. You drive it by sending events and observe it by reading events.

Session status

`status`	Meaning
`idle`	No work in flight. Also used while a permission or question waits for you (`stop_reason.type = "requires_action"`).
`running`	A turn is running, or queued work has a machine that can run it
`rescheduling`	Work is queued, but the session’s machine is still being provisioned, resumed or restored. BMA continues automatically.
`terminated`	The session is archived; its history stays readable

Status is computed per session; sibling sessions of the same agent never leak into it.

Sending events

Event	Effect
`user.message`	Starts a turn, or queues behind the running one. Text content.
`user.interrupt`	Stops the running turn of this session only (tool calls, open interactions). The session stays usable.
`user.tool_confirmation`	Answers a permission request: `{"tool_use_id": "...", "result": "allow" \| "deny", "deny_message": "..."}`
`user.tool_result`	Returns the result of a custom tool call (BMA naming)

POST /v1/sessions with Idempotency-Key is replay-safe: the same key returns the same session.

Events you receive

Event	Source
`session.status_running`, `session.status_idle`	Turn boundaries. `session.status_idle.stop_reason` is `end_turn` or `requires_action` (with the pending `event_ids`).
`agent.message`	Model text
`agent.thinking`	Model reasoning
`agent.tool_use`, `agent.tool_result`	Tool calls and their results. The `agent.tool_use` id is the id you confirm.
`user.message`, `user.interrupt`, `user.tool_confirmation`	Your inputs, as recorded
`session.updated`	Title or metadata changed (for example the automatic title after the first turn)
`session.error`	A turn failed; `error.code` gives the BMA reason (for example `context_too_large`)
`session.machine_resumed`, `session.machine_rebuilt`, `session.machine_restored`, `session.machine_restore_failed`	BMA extension: the session’s machine changed underneath the conversation. See Machines.
`session.mcp_server_unavailable`	BMA extension: a configured MCP server failed to initialize and was dropped
`event_start`, `event_delta`	Streaming previews when you pass `event_deltas` (for example `event_deltas[]=agent.message`). Best-effort; the final event carries the full content.

Streaming and resuming

GET /v1/sessions/{id}/events/stream is a server-sent event stream.

Without Last-Event-ID, the stream delivers events emitted after it opens. Open it before you send, or rely on BMA’s rule that a stream opened during a running turn starts at that turn’s input.
Every durable event carries bma_sequence. Store the last value you processed and reconnect with Last-Event-ID: <bma_sequence>. A browser EventSource sends back the opaque SSE id automatically; BMA accepts both. Last-Event-ID: 0 replays the whole session. A malformed or unknown value is 400.
History: GET /v1/sessions/{id}/events pages with limit/page and filters by types[]. If the last page ends with an open permission request, BMA appends the same requires_action idle event the stream announced, so a restarted worker knows it must answer.

# Resume after a disconnect
with client.beta.sessions.events.stream(
    session_id,
    extra_headers={"Last-Event-ID": str(last_sequence)},
) as stream:
    for event in stream:
        ...

Get started

Concepts

Executor & brains

Session status

Sending events

Events you receive

Streaming and resuming

​Session status

​Sending events

​Events you receive

​Streaming and resuming

Session status

Sending events

Events you receive

Streaming and resuming