Stream Events

A user message event in the session conversation.

An interrupt event that pauses agent execution and returns control to the user.

A tool confirmation event that approves or denies a pending tool execution.

Event sent by the client providing the result of a custom tool execution.

Event emitted when the agent calls a custom tool. The session goes idle until the client sends a user.custom_tool_result event with the result. The client can send it as soon as this event arrives, without waiting for session.status_idle.

An agent response event in the session conversation.

Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.

Event emitted when the agent invokes a tool provided by an MCP server.

Event representing the result of an MCP tool execution.

Event emitted when the agent invokes a built-in agent tool.

Event representing the result of an agent tool execution.

Delivery event written to the target thread's input stream when an agent-to-agent message arrives.

Observability event emitted to the sender's output stream when an agent-to-agent message is sent.

Indicates that context compaction (summarization) occurred during the session.

An error event indicating a problem occurred during session execution.

Indicates the session is recovering from an error state and is rescheduled for execution.

Indicates the session is actively running and the agent is working.

Indicates the agent has paused and is awaiting user input.

Indicates the session has terminated, either due to an error or completion.

Emitted when a child thread is created. Written to the parent thread's output stream so clients observing the session see child creation.

Emitted when an outcome evaluation cycle begins.

Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of needs_revision means another evaluation cycle follows; satisfied, max_iterations_reached, failed, or interrupted are terminal — no further evaluation cycles follow.

Emitted when a model request is initiated by the agent.

Emitted when a model request completes.

Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding span.outcome_evaluation_start and span.outcome_evaluation_end events.

Echo of a user.define_outcome input event. Carries the server-generated outcome_id that subsequent span.outcome_evaluation_* events reference.

Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.

A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

Event sent by the client providing the result of an agent-toolset tool execution. Only valid on self_hosted environments, where sandbox-routed tools are executed by the client rather than the server.

A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn.

Opens a preview of a buffered event. Carries the previewed event's type and id only. Followed by zero or more event_delta events with the same event id, normally concluded by the buffered event carrying that id. If the producing model request ends without that event (an error or interrupt mid-stream), its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history.

An incremental update to an event that is still being streamed. Deltas are best-effort and may stop early; when the buffered event with id == event_id is produced it carries the complete content. A model request that ends early (an error or interrupt) produces no buffered event — its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history.

A mid-conversation system message event. Carries system-role content that is appended to the session as a role: "system" turn.

Periodic snapshot of the session's cumulative usage and tracked list cost.

A workflow run was created. A workflow run is background work that the session's agent starts. Emitted once per run, before the run's other workflow_run.* events.

A workflow run ended. Emitted once per run, as the last of the run's workflow_run.* events.

A workflow run's plan entered a phase.

A workflow run's plan left a phase, or the run's end closed it. Emitted once for every workflow_run.phase_started event, before the run's workflow_run.status_ended event. The event does not say whether the plan finished the phase's work, or why it left.

A workflow run is running. Emitted when the run starts to execute, and each time it resumes after being idle. A run that starts idle emits workflow_run.status_idle first.

A workflow run is idle. Emitted each time the run goes idle, whatever the cause. If the run ends while idle, no workflow_run.status_running comes between this event and its workflow_run.status_ended.

A workflow run met an error, or an error kept a run from being created. A run that ends with a result.type of error emits this event before its workflow_run.status_ended, with the same error.