Events

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.

Event representing the result of an MCP tool execution.

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

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.

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

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.

Event representing the result of an agent tool execution.

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

Base64-encoded document data.

Base64-encoded image data.

The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state.

An environment_variable credential's auth.networking.allowed_hosts includes a host the environment's network policy does not permit.

Document content, either specified directly as base64 data, as text, or as a reference via a URL.

Union type for event parameters that can be sent to a session.

Document referenced by file ID.

Image referenced by file ID.

Rubric referenced by a file uploaded via the Files API.

Rubric referenced by a file uploaded via the Files API.

Image content specified directly as base64 data or as a reference via a URL.

Authentication to an MCP server failed.

Failed to connect to an MCP server.

The model is currently overloaded. Emitted after automatic retries are exhausted.

The model request was rate-limited.

A model request failed for a reason other than overload or rate-limiting.

Plain text document content.

Placeholder for content withheld by Anthropic model policy.

This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

The session encountered a terminal error and will transition to terminated state.

A block containing a web search result.

Citation settings for a search result.

Text content within a search result.

Events that were successfully sent to the session.

The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget.

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

The agent completed its turn naturally and is ready for the next user message.

An error event indicating a problem occurred during session execution.

Union type for all event types in a session.

The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.

The turn ended because repeated errors exhausted the retry budget or an error escalated to retry_status: 'exhausted'.

Indicates the agent has paused and is awaiting user input.

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 session has terminated, either due to an error or completion.

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

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 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.

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 terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

Point-in-time snapshot of a session's cumulative usage.

Emitted when a model request completes.

Emitted when a model request is initiated by the agent.

Token usage for a single model request.

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.

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.

Emitted when an outcome evaluation cycle begins.

Server-sent event in the session stream.

Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a role: "system" turn rather than replacing the top-level system prompt. At most one per request: it must be the final event and immediately follow the user.message, user.tool_result, or user.custom_tool_result it accompanies. Only supported on models that accept mid-conversation system messages.

Regular text content.

Rubric content provided inline as text.

Rubric content provided inline as text.

An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on retry_status and message alone.

Document referenced by URL.

Image referenced by URL.

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

Parameters for providing the result of a custom tool execution.

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

Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.

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

Parameters for sending an interrupt to pause the agent.

A user message event in the session conversation.

Parameters for sending a user message to the session.