Session Events: Stream Real-Time Agent Output via SSE

The session event stream is a Server-Sent Events (SSE) endpoint that delivers real-time agent output as it is produced. Unlike the REST snapshot endpoint, the stream does not replay history — it starts from the moment you connect and delivers every event that occurs while your connection is open. On reconnect, fetch the session snapshot (GET /v1/sessions/{id}) to reconcile state, then re-open the stream.

The Python SDK’s SessionsNamespace.stream() handles the low-level SSE framing automatically. It does not auto-reconnect — reconnect logic lives at the application layer so you can control the snapshot-and-reconcile step.

Subscribing with curl

curl -N -H "Authorization: Bearer <token>" \
  "http://localhost:6767/v1/sessions/conv_abc123/stream"

The -N flag disables curl’s output buffering so you see events as they arrive. Each SSE frame has the shape:

event: session.status
data: {"type":"session.status","conversation_id":"conv_abc123","status":"running","sequence_number":1}

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"Hello","sequence_number":2}

event: response.completed
data: {"type":"response.completed","response":{...},"sequence_number":5}

Query parameter: idle (boolean, default false) — set to true to signal that your tab is backgrounded. Other viewers see you as idle in presence events.

Event Types

Every SSE frame carries a type discriminator field. The full union is the ServerStreamEvent discriminated type in the OpenAPI schema.

Session Lifecycle Events

session.status

object

Session lifecycle status transition. Emitted at every transition between "idle", "running", "waiting" (parent turn parked on async sub-agents), and "failed".Key fields: conversation_id, status, response_id (for terminal-backed sessions), error (when status == "failed").

session.heartbeat

object

Idle-stream keepalive emitted on a fixed cadence when no turn is in flight. Keeps intermediate proxies from treating the stream as stale.Key fields: server_time (ISO 8601 UTC timestamp).

session.interrupted

object

User-triggered cancel reached the loop. Co-emitted with response.incomplete when the session is interrupted via POST /v1/sessions/{id}/events with type: "interrupt".Key fields: data.requested_at, data.response_id.

session.created

object

A child (sub-agent) session was spawned from this session. Emitted on the parent session’s stream when a sub-agent is launched.Key fields: conversation_id (parent), child_session_id, agent_id, parent_session_id.

session.child_session.updated

object

A child session’s status changed. Carries a partial ChildSessionSummary that should be merged over the cached child row.Key fields: conversation_id (parent), child_session_id, child (partial summary dict).

session.agent_changed

object

The session’s bound agent was changed in place via POST .../switch-agent. Clients should re-fetch the session snapshot to update their cached state.Key fields: conversation_id, agent_id, agent_name.

session.model

object

The active LLM model changed (e.g. via a /model command in a terminal-backed session).Key fields: conversation_id, model.

session.usage

object

Token-usage update. Carries context-window metrics and optional per-model breakdown.Key fields: conversation_id, context_tokens, context_window, total_cost_usd, usage_by_model.

session.presence

object

The session’s viewer list changed. Full replacement — not a delta. Clients should replace their presence state wholesale.Key fields: conversation_id, viewers (array of {user_id, joined_at, idle}).

session.skills

object

Runner-owned skills have resolved. Clients should re-fetch the session snapshot to populate their skill/slash-command menu.Key field: conversation_id.

session.todos

object

Todo-list update from a Claude Code terminal-backed session.Key fields: conversation_id, todos (array of {content, status, activeForm}).

session.sandbox_status

object

Managed-sandbox provisioning progress for host_type="managed" sessions.Key fields: conversation_id, stage ("provisioning", "cloning", "starting", "connecting", "ready", "failed"), error.

session.terminal_pending

object

Terminal spin-up status. pending: true while the terminal is being created; pending: false once it lands.Key fields: conversation_id, pending.

session.terminal.activity

object

A terminal pane produced output (transient activity pulse).Key fields: session_id, terminal_id.

session.resource.created

object

A session resource (terminal, file, environment) was created.Key fields: resource (a SessionResourceObject dict).

session.resource.deleted

object

A session resource was deleted.Key fields: resource_id, resource_type, session_id.

session.changed_files.invalidated

object

The session’s changed-files list may have changed. Clients should refetch GET .../resources/environments/{env_id}/changes.Key fields: session_id, environment_id.

Response (Turn) Events

response.created

object

Always the first event of a new turn. Carries the freshly allocated ResponseObject with status: "queued" or "in_progress".

response.queued

object

Emitted between response.created and response.in_progress for background tasks.

response.in_progress

object

The turn transitioned to "in_progress".

response.output_text.delta

object

Incremental assistant text token. Concatenate delta fields in arrival order to reconstruct the full message.Key fields: delta (text fragment), message_id (for terminal-observed streaming), index, final.

response.reasoning.started

object

A reasoning block began (providers that surface chain-of-thought). Clients can render a “thinking…” indicator.

response.reasoning_text.delta

object

Incremental full chain-of-thought token.Key fields: delta.

response.reasoning_summary_text.delta

object

Incremental reasoning-summary token (when reasoning.summary is configured).Key fields: delta.

response.output_item.done

object

A conversation output item completed during the turn. Item type varies: message, function_call, function_call_output, reasoning, compaction.Key fields: item (heterogeneous dict — shape depends on item.type).

response.output_file.done

object

A streamed file output completed materializing.Key fields: file_id, filename, content_type.

response.completed

object

Terminal event — turn finished successfully. Carries the final ResponseObject with status: "completed".

response.failed

object

Terminal event — turn ended with an error. response.error field describes the failure.

response.incomplete

object

Terminal event — turn stopped early (e.g. hit the iteration cap). response.incomplete_details.reason gives the reason.

response.cancelled

object

Terminal event — turn was cancelled.

response.error

object

Non-recoverable error during the turn (LLM error, execution timeout, tool failure).Key fields: source ("llm", "execution", "tool"), tool_name, error.code, error.message.

response.retry

object

A retryable failure was caught and a retry is scheduled.Key fields: source, tool_name, attempt, max_attempts, delay_seconds, error.

response.heartbeat

object

Per-turn keepalive emitted every ~15 seconds while a response is producing output.Key fields: server_time, last_event_seq.

Turn Events

turn.started

object

The runner started a new turn. Key fields: session_id.

turn.completed

object

The turn finished successfully with no pending work. Key fields: session_id.

turn.failed

object

The turn failed. Key fields: session_id, error.

turn.cancelled

object

The turn was interrupted. Key fields: session_id.

Compaction Events

response.compaction.in_progress

object

Conversation history compaction is running. Clients can show a “summarizing history…” spinner.

response.compaction.completed

object

Compaction finished. Key fields: total_tokens (post-compaction context size estimate).

response.compaction.failed

object

Compaction failed; history was not modified. Dismiss any spinner.

Elicitation Events

response.elicitation_request

object

The agent paused and is requesting a decision from the user (e.g. approve a tool call). The consumer must reply via POST /v1/sessions/{id}/elicitations/{elicitation_id}/resolve.Key fields: elicitation_id, params.message, params.mode ("form" or "url"), params.phase, params.policy_name, params.content_preview, params.requestedSchema.

response.elicitation_resolved

object

A previously outstanding elicitation was cleared (timed out, turn cancelled, or resolved elsewhere).Key field: elicitation_id.

response.client_task.cancel

object

Server-to-client notification that an async client-tool task was cancelled mid-flight (via direct cancel or parent-cancel propagation). The SDK should cancel the matching local task.Key fields: task_id (the server-issued client-tool task id), call_id (the synthesized function-call id, or null on legacy emissions).

Python SDK Streaming

Subscribe to a session’s event stream using SessionsNamespace.stream():

from omnigent_client import OmnigentClient

async with OmnigentClient(base_url="http://localhost:6767") as client:
    async for event in client.sessions.stream("conv_abc123"):
        print(event.type, event)

Each yielded event is a typed Pydantic model from the ServerStreamEvent discriminated union — e.g. SessionStatusEvent, OutputTextDeltaEvent, CompletedEvent. For a higher-level text-streaming API, use a Session object (the /v1/responses path):

session = client.session(model="my-agent")
async for chunk in await session.query("Write a hello world", stream=True):
    print(chunk, end="", flush=True)

Elicitations

When a policy triggers an approval request, the agent pauses and emits a response.elicitation_request event. The consumer must resolve the elicitation before the agent proceeds:

# Approve the request
curl -X POST \
  "http://localhost:6767/v1/sessions/conv_abc123/elicitations/elicit_xyz/resolve" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"action": "accept"}'

# Decline the request
curl -X POST \
  "http://localhost:6767/v1/sessions/conv_abc123/elicitations/elicit_xyz/resolve" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"action": "decline"}'

Via the Python SDK:

await client.sessions.resolve_elicitation(
    "conv_abc123",
    "elicit_xyz",
    {"action": "accept"},
)

The action field follows the MCP ElicitResult semantics:

`action`	Meaning
`"accept"`	Approved — the agent proceeds
`"decline"`	Explicit refusal
`"cancel"`	Dismissed without an explicit choice (also the server-synthesized verdict on timeout)

You can also inspect a pending elicitation without streaming:

GET /v1/sessions/{session_id}/elicitations/{elicitation_id}

Overview

Sessions

Hosts & Runners

Resources

Session Events: Stream Real-Time Agent Output via SSE

Subscribing with curl

Event Types

Session Lifecycle Events

Response (Turn) Events

Turn Events

Compaction Events

Elicitation Events

Python SDK Streaming

Elicitations

Build docs developers (and LLMs) love

Overview

Sessions

Hosts & Runners

Resources

Documentation Index

​Subscribing with curl

​Event Types

​Session Lifecycle Events

​Response (Turn) Events

​Turn Events

​Compaction Events

​Elicitation Events

​Python SDK Streaming

​Elicitations

Build docs developers (and LLMs) love

Subscribing with curl

Event Types

Session Lifecycle Events

Response (Turn) Events

Turn Events

Compaction Events

Elicitation Events

Python SDK Streaming

Elicitations