Eventi
Elenca gli eventi
beta.sessions.events.list(session_id, **kwargs) -> PageCursor<BetaManagedAgentsSessionEvent>Invia eventi
beta.sessions.events.send_(session_id, **kwargs) -> BetaManagedAgentsSendSessionEventsTrasmetti eventi in streaming
beta.sessions.events.stream_events(session_id, **kwargs) -> Stream<BetaManagedAgentsStreamSessionEvents>Models
type BetaManagedAgentsAgentAutoEvaluatedPermission = BetaManagedAgentsAgentAutoEvaluatedPermissionAllow | BetaManagedAgentsAgentAutoEvaluatedPermissionAsk | BetaManagedAgentsAgentAutoEvaluatedPermissionDenyThe server's per-invocation judgement under the auto permission policy. Its type always equals the event's top-level evaluated_permission. Open union: clients must tolerate unknown variants.
The server's per-invocation judgement under the auto permission policy. Its type always equals the event's top-level evaluated_permission. Open union: clients must tolerate unknown variants.
class BetaManagedAgentsAgentAutoEvaluatedPermissionAllow { type: :allow }The server judged the invocation safe to execute without client approval.
The server judged the invocation safe to execute without client approval.
class BetaManagedAgentsAgentAutoEvaluatedPermissionAsk { type: :ask, reason_code }The server reached no judgement; the invocation is held for client approval.
The server reached no judgement; the invocation is held for client approval.
reason_code: StringThe judgement's grounds in registry-bound terms, for client branching and audit rather than end-user display. Open registry; currently "indeterminate" (no judgement was reached). Clients must tolerate values outside this set.
The judgement's grounds in registry-bound terms, for client branching and audit rather than end-user display. Open registry; currently "indeterminate" (no judgement was reached). Clients must tolerate values outside this set.
class BetaManagedAgentsAgentAutoEvaluatedPermissionDeny { type: :deny, reason_code }The server judged the invocation high-risk; it does not execute and a synthetic error tool result is appended.
The server judged the invocation high-risk; it does not execute and a synthetic error tool result is appended.
reason_code: StringThe judgement's grounds in registry-bound terms. Open registry; currently "high_risk" (judged high-risk; the call does not run). Clients must tolerate values outside this set.
The judgement's grounds in registry-bound terms. Open registry; currently "high_risk" (judged high-risk; the call does not run). Clients must tolerate values outside this set.
class BetaManagedAgentsAgentCustomToolUseEvent { type: :"agent.custom_tool_use", id, input, 3 more }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.
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.
Unique identifier for this event.
Input parameters for the tool call.
Name of the custom tool being called.
processed_at: TimeTimestamp when this tool use was processed.
Timestamp when this tool use was processed.
When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Informational only: the server routes the matching user.custom_tool_result by custom_tool_use_id, so clients do not send it back.
type BetaManagedAgentsAgentEvaluatedPermission = :allow | :ask | :deny
class BetaManagedAgentsAgentMCPToolResultEvent { type: :"agent.mcp_tool_result", id, mcp_tool_use_id, 3 more }Event representing the result of an MCP tool execution.
Event representing the result of an MCP tool execution.
class BetaManagedAgentsAgentMCPToolUseEvent { type: :"agent.mcp_tool_use", id, input, 6 more }Event emitted when the agent invokes a tool provided by an MCP server.
Event emitted when the agent invokes a tool provided by an MCP server.
class BetaManagedAgentsAgentMessageEvent { type: :"agent.message", id, content, processed_at }An agent response event in the session conversation.
An agent response event in the session conversation.
class BetaManagedAgentsAgentThinkingEvent { type: :"agent.thinking", id, processed_at }Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.
Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.
Unique identifier for this event.
processed_at: TimeTimestamp when this thinking was produced.
Timestamp when this thinking was produced.
class BetaManagedAgentsAgentThreadContextCompactedEvent { type: :"agent.thread_context_compacted", id, processed_at }Indicates that context compaction (summarization) occurred during the session.
Indicates that context compaction (summarization) occurred during the session.
Unique identifier for this event.
processed_at: TimeTimestamp when compaction was processed.
Timestamp when compaction was processed.
class BetaManagedAgentsAgentThreadMessageReceivedEvent { type: :"agent.thread_message_received", id, content, 3 more }Delivery event written to the target thread's input stream when an agent-to-agent message arrives.
Delivery event written to the target thread's input stream when an agent-to-agent message arrives.
class BetaManagedAgentsAgentThreadMessageSentEvent { type: :"agent.thread_message_sent", id, content, 3 more }Observability event emitted to the sender's output stream when an agent-to-agent message is sent.
Observability event emitted to the sender's output stream when an agent-to-agent message is sent.
type BetaManagedAgentsAgentToolEvaluation = BetaManagedAgentsAgentToolEvaluationAlwaysAllow | BetaManagedAgentsAgentToolEvaluationAlwaysAsk | BetaManagedAgentsAgentToolEvaluationAutoNames the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants.
Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants.
class BetaManagedAgentsAgentToolEvaluationAlwaysAllow { type: :always_allow }The resolved permission_policy was always_allow; accompanies evaluated_permission "allow".
The resolved permission_policy was always_allow; accompanies evaluated_permission "allow".
class BetaManagedAgentsAgentToolEvaluationAlwaysAsk { type: :always_ask }The resolved permission_policy was always_ask; accompanies evaluated_permission "ask".
The resolved permission_policy was always_ask; accompanies evaluated_permission "ask".
class BetaManagedAgentsAgentToolEvaluationAuto { type: :auto, evaluated_permission }The resolved permission_policy was auto: the server judged this invocation individually.
The resolved permission_policy was auto: the server judged this invocation individually.
evaluated_permission: BetaManagedAgentsAgentAutoEvaluatedPermissionThe server's judgement for this invocation.
The server's judgement for this invocation.
class BetaManagedAgentsAgentToolResultEvent { type: :"agent.tool_result", id, processed_at, 3 more }Event representing the result of an agent tool execution.
Event representing the result of an agent tool execution.
class BetaManagedAgentsAgentToolUseEvent { type: :"agent.tool_use", id, input, 5 more }Event emitted when the agent invokes a built-in agent tool.
Event emitted when the agent invokes a built-in agent tool.
class BetaManagedAgentsBase64DocumentSource { type: :base64, data, media_type }Base64-encoded document data.
Base64-encoded document data.
data: StringBase64-encoded document data.
Base64-encoded document data.
media_type: StringMIME type of the document (e.g., "application/pdf").
MIME type of the document (e.g., "application/pdf").
class BetaManagedAgentsBase64ImageSource { type: :base64, data, media_type }Base64-encoded image data.
Base64-encoded image data.
data: StringBase64-encoded image data.
Base64-encoded image data.
media_type: StringMIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
class BetaManagedAgentsBillingError { type: :billing_error, message, retry_status }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.
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.
class BetaManagedAgentsCredentialHostUnreachableError { type: :credential_host_unreachable_error, credential_id, message, 2 more }An environment_variable credential's auth.networking.allowed_hosts includes a host the environment's network policy does not permit.
An environment_variable credential's auth.networking.allowed_hosts includes a host the environment's network policy does not permit.
class BetaManagedAgentsDocumentBlock { type: :document, source, context, title }Document content, either specified directly as base64 data, as text, or as a reference via a URL.
Document content, either specified directly as base64 data, as text, or as a reference via a URL.
type BetaManagedAgentsEventParams = BetaManagedAgentsUserMessageEventParams | BetaManagedAgentsUserInterruptEventParams | BetaManagedAgentsUserToolConfirmationEventParams | 4 moreUnion type for event parameters that can be sent to a session.
Union type for event parameters that can be sent to a session.
class BetaManagedAgentsFileDocumentSource { type: :file, file_id }Document referenced by file ID.
Document referenced by file ID.
file_id: StringID of a previously uploaded file.
ID of a previously uploaded file.
class BetaManagedAgentsFileImageSource { type: :file, file_id }Image referenced by file ID.
Image referenced by file ID.
file_id: StringID of a previously uploaded file.
ID of a previously uploaded file.
class BetaManagedAgentsFileRubric { type: :file, file_id }Rubric referenced by a file uploaded via the Files API.
Rubric referenced by a file uploaded via the Files API.
ID of the rubric file.
class BetaManagedAgentsFileRubricParams { type: :file, file_id }Rubric referenced by a file uploaded via the Files API.
Rubric referenced by a file uploaded via the Files API.
ID of the rubric file.
class BetaManagedAgentsImageBlock { type: :image, source }Image content specified directly as base64 data or as a reference via a URL.
Image content specified directly as base64 data or as a reference via a URL.
class BetaManagedAgentsMaxWorkflowRunsWorkflowRunError { type: :max_workflow_runs_error, message }No run was created, because the session was at its limit of open workflow runs, which are runs that have not ended. Only workflow_run.error carries this type.
No run was created, because the session was at its limit of open workflow runs, which are runs that have not ended. Only workflow_run.error carries this type.
Short explanation written by the server. It never contains content from the run or its agents.
class BetaManagedAgentsMCPAuthenticationFailedError { type: :mcp_authentication_failed_error, mcp_server_name, message, retry_status }Authentication to an MCP server failed.
Authentication to an MCP server failed.
class BetaManagedAgentsMCPConnectionFailedError { type: :mcp_connection_failed_error, mcp_server_name, message, retry_status }Failed to connect to an MCP server.
Failed to connect to an MCP server.
class BetaManagedAgentsModelOverloadedError { type: :model_overloaded_error, message, retry_status }The model is currently overloaded. Emitted after automatic retries are exhausted.
The model is currently overloaded. Emitted after automatic retries are exhausted.
class BetaManagedAgentsModelRateLimitedError { type: :model_rate_limited_error, message, retry_status }The model request was rate-limited.
The model request was rate-limited.
class BetaManagedAgentsModelRequestFailedError { type: :model_request_failed_error, message, retry_status }A model request failed for a reason other than overload or rate-limiting.
A model request failed for a reason other than overload or rate-limiting.
class BetaManagedAgentsPlainTextDocumentSource { type: :text, data, media_type }Plain text document content.
Plain text document content.
data: StringThe plain text content.
The plain text content.
MIME type of the text content. Must be "text/plain".
class BetaManagedAgentsProgramWorkflowRunError { type: :program_error, message }The plan, a program that the agent wrote, failed, or the server refused it.
The plan, a program that the agent wrote, failed, or the server refused it.
Short explanation written by the server. It never contains content from the run or its agents.
class BetaManagedAgentsRedactedBlock { type: :redacted }Placeholder for content withheld by Anthropic model policy.
Placeholder for content withheld by Anthropic model policy.
class BetaManagedAgentsRepositoryAuthenticationError { type: :repository_authentication_error, message, repository_url, retry_status }The repository host rejected the credentials, or required credentials and received none.
The repository host rejected the credentials, or required credentials and received none.
class BetaManagedAgentsRepositoryCheckoutError { type: :repository_checkout_error, message, repository_url, retry_status }The requested branch or commit does not exist in the repository.
The requested branch or commit does not exist in the repository.
class BetaManagedAgentsRepositoryCloneError { type: :repository_clone_error, message, repository_url, retry_status }The repository could not be cloned.
The repository could not be cloned.
class BetaManagedAgentsRepositoryForbiddenError { type: :repository_forbidden_error, message, repository_url, retry_status }The repository host refused access to the repository.
The repository host refused access to the repository.
class BetaManagedAgentsRepositoryNotFoundError { type: :repository_not_found_error, message, repository_url, retry_status }The repository host reported the repository as not found.
The repository host reported the repository as not found.
class BetaManagedAgentsRetryStatusExhausted { type: :exhausted }This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
class BetaManagedAgentsRetryStatusRetrying { type: :retrying }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 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.
class BetaManagedAgentsRetryStatusTerminal { type: :terminal }The session encountered a terminal error and will transition to terminated state.
The session encountered a terminal error and will transition to terminated state.
class BetaManagedAgentsSearchResultBlock { type: :search_result, citations, content, 2 more }A block containing a web search result.
A block containing a web search result.
citations: BetaManagedAgentsSearchResultCitations { enabled }Citation settings for this search result.
Citation settings for this search result.
Whether citations are enabled for this search result.
content: Array[BetaManagedAgentsSearchResultContent { type: :text, text }]Array of text content blocks from the search result.
Array of text content blocks from the search result.
text: StringThe text content.
The text content.
source: StringThe URL source of the search result.
The URL source of the search result.
title: StringThe title of the search result.
The title of the search result.
class BetaManagedAgentsSearchResultCitations { enabled }Citation settings for a search result.
Citation settings for a search result.
Whether citations are enabled for this search result.
class BetaManagedAgentsSearchResultContent { type: :text, text }Text content within a search result.
Text content within a search result.
text: StringThe text content.
The text content.
class BetaManagedAgentsSendSessionEvents { data }Events that were successfully sent to the session.
Events that were successfully sent to the session.
class BetaManagedAgentsSessionBudgetReached { type: :budget_reached }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.
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.
class BetaManagedAgentsSessionDeletedEvent { type: :"session.deleted", id, processed_at }Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.
Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.
Unique identifier for this event.
processed_at: TimeTimestamp when the session was deleted.
Timestamp when the session was deleted.
class BetaManagedAgentsSessionEndTurn { type: :end_turn }The agent completed its turn naturally and is ready for the next user message.
The agent completed its turn naturally and is ready for the next user message.
class BetaManagedAgentsSessionErrorEvent { type: :"session.error", id, error, processed_at }An error event indicating a problem occurred during session execution.
An error event indicating a problem occurred during session execution.
type BetaManagedAgentsSessionEvent = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 39 moreUnion type for all event types in a session.
Union type for all event types in a session.
type BetaManagedAgentsSessionEventType = :"user.message" | :"user.interrupt" | :"user.tool_confirmation" | 38 moreThe type of a session event.
The type of a session event.
class BetaManagedAgentsSessionRefusal { type: :refusal }The turn ended because the model's response was refused, for example by a safety classifier.
The turn ended because the model's response was refused, for example by a safety classifier.
class BetaManagedAgentsSessionRefusalStopDetails { type: :refusal, category, explanation }Structured information about a refusal.
Structured information about a refusal.
category: :cyber | :bio | :frontier_llm | 2 moreThe policy category that triggered the refusal, or null when there is no named category. New values can be added over time.
The policy category that triggered the refusal, or null when there is no named category. New values can be added over time.
Human-readable explanation of the refusal, or null when none is available. The wording can change, so do not parse it.
class BetaManagedAgentsSessionRequiresAction { type: :requires_action, event_ids }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 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 ids of events the agent is blocked on. Resolving fewer than all re-emits session.status_idle with the remainder.
class BetaManagedAgentsSessionRetriesExhausted { type: :retries_exhausted }The turn ended because repeated errors exhausted the retry budget or an error escalated to retry_status: 'exhausted'.
The turn ended because repeated errors exhausted the retry budget or an error escalated to retry_status: 'exhausted'.
class BetaManagedAgentsSessionStatusIdleEvent { type: :"session.status_idle", id, processed_at, 2 more }Indicates the agent has paused and is awaiting user input.
Indicates the agent has paused and is awaiting user input.
class BetaManagedAgentsSessionStatusRescheduledEvent { type: :"session.status_rescheduled", id, processed_at }Indicates the session is recovering from an error state and is rescheduled for execution.
Indicates the session is recovering from an error state and is rescheduled for execution.
Unique identifier for this event.
processed_at: TimeTimestamp of status change.
Timestamp of status change.
class BetaManagedAgentsSessionStatusRunningEvent { type: :"session.status_running", id, processed_at }Indicates the session is actively running and the agent is working.
Indicates the session is actively running and the agent is working.
Unique identifier for this event.
processed_at: TimeTimestamp of status change.
Timestamp of status change.
class BetaManagedAgentsSessionStatusTerminatedEvent { type: :"session.status_terminated", id, processed_at }Indicates the session has terminated, either due to an error or completion.
Indicates the session has terminated, either due to an error or completion.
Unique identifier for this event.
processed_at: TimeTimestamp of status change.
Timestamp of status change.
class BetaManagedAgentsSessionThreadCreatedEvent { type: :"session.thread_created", id, agent_name, 3 more }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 a child thread is created. Written to the parent thread's output stream so clients observing the session see child creation.
Unique identifier for this event.
Name of the callable agent the thread runs.
processed_at: TimeTimestamp when the thread was created.
Timestamp when the thread was created.
Public sthr_ ID of the newly created thread.
Identifier of the workflow run that created the thread, or null for any other thread.
class BetaManagedAgentsSessionThreadStatusIdleEvent { type: :"session.thread_status_idle", id, agent_name, 4 more }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 yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
class BetaManagedAgentsSessionThreadStatusRescheduledEvent { type: :"session.thread_status_rescheduled", id, agent_name, 2 more }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 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.
Unique identifier for this event.
Name of the agent the thread runs.
processed_at: TimeTimestamp of the status transition.
Timestamp of the status transition.
Public sthr_ ID of the thread that is retrying.
class BetaManagedAgentsSessionThreadStatusRunningEvent { type: :"session.thread_status_running", id, agent_name, 2 more }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 begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
Unique identifier for this event.
Name of the agent the thread runs.
processed_at: TimeTimestamp of the status transition.
Timestamp of the status transition.
Public sthr_ ID of the thread that started running.
class BetaManagedAgentsSessionThreadStatusTerminatedEvent { type: :"session.thread_status_terminated", id, agent_name, 2 more }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.
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.
Unique identifier for this event.
Name of the agent the thread runs.
processed_at: TimeTimestamp of the status transition.
Timestamp of the status transition.
Public sthr_ ID of the thread that terminated.
class BetaManagedAgentsSessionUsageSnapshot { active_seconds, cache_creation, cache_read_input_tokens, 4 more }Point-in-time snapshot of a session's cumulative usage.
Point-in-time snapshot of a session's cumulative usage.
class BetaManagedAgentsSpanModelRequestEndEvent { type: :"span.model_request_end", id, is_error, 3 more }Emitted when a model request completes.
Emitted when a model request completes.
class BetaManagedAgentsSpanModelRequestStartEvent { type: :"span.model_request_start", id, processed_at }Emitted when a model request is initiated by the agent.
Emitted when a model request is initiated by the agent.
Unique identifier for this event.
processed_at: TimeTimestamp when the model request started.
Timestamp when the model request started.
class BetaManagedAgentsSpanModelUsage { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }Token usage for a single model request.
Token usage for a single model request.
cache_creation_input_tokens: IntegerTokens used to create prompt cache in this request.
Tokens used to create prompt cache in this request.
cache_read_input_tokens: IntegerTokens read from prompt cache in this request.
Tokens read from prompt cache in this request.
input_tokens: IntegerInput tokens consumed by this request.
Input tokens consumed by this request.
output_tokens: IntegerOutput tokens generated by this request.
Output tokens generated by this request.
speed: :standard | :fastInference speed tier this request actually ran at. Mirrors usage.speed on /v1/messages. Only present when the fast-mode beta is active.
Inference speed tier this request actually ran at. Mirrors usage.speed on /v1/messages. Only present when the fast-mode beta is active.
class BetaManagedAgentsSpanOutcomeEvaluationEndEvent { type: :"span.outcome_evaluation_end", id, explanation, 6 more }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 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.
class BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent { type: :"span.outcome_evaluation_ongoing", id, iteration, 2 more }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.
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.
Unique identifier for this event.
iteration: Integer0-indexed revision cycle, matching the corresponding span.outcome_evaluation_start.
0-indexed revision cycle, matching the corresponding span.outcome_evaluation_start.
The outc_ ID of the outcome being evaluated.
processed_at: TimeTimestamp when this heartbeat was emitted.
Timestamp when this heartbeat was emitted.
class BetaManagedAgentsSpanOutcomeEvaluationStartEvent { type: :"span.outcome_evaluation_start", id, iteration, 2 more }Emitted when an outcome evaluation cycle begins.
Emitted when an outcome evaluation cycle begins.
Unique identifier for this event.
iteration: Integer0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.
0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.
The outc_ ID of the outcome being evaluated.
processed_at: TimeTimestamp when outcome evaluation started.
Timestamp when outcome evaluation started.
type BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 41 moreServer-sent event in the session stream.
Server-sent event in the session stream.
class BetaManagedAgentsSystemMessageEventParams { type: :"system.message", content }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.
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.
content: Array[BetaManagedAgentsSystemContentBlock { type: :text, text }]System content blocks to append. Text-only.
System content blocks to append. Text-only.
text: StringThe text content.
The text content.
class BetaManagedAgentsTextBlock { type: :text, text }Regular text content.
Regular text content.
text: StringThe text content.
The text content.
class BetaManagedAgentsTextRubric { type: :text, content }Rubric content provided inline as text.
Rubric content provided inline as text.
Rubric content. Plain text or markdown — the grader treats it as freeform text.
class BetaManagedAgentsTextRubricParams { type: :text, content }Rubric content provided inline as text.
Rubric content provided inline as text.
content: StringRubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.
Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.
class BetaManagedAgentsThreadLimitWorkflowRunError { type: :thread_limit_error, message }The run exceeded the limit on the number of threads that a run can create.
The run exceeded the limit on the number of threads that a run can create.
Short explanation written by the server. It never contains content from the run or its agents.
class BetaManagedAgentsTimeoutWorkflowRunError { type: :timeout_error, message }The run reached its time limit.
The run reached its time limit.
Short explanation written by the server. It never contains content from the run or its agents.
class BetaManagedAgentsUnknownError { type: :unknown_error, message, retry_status }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.
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.
class BetaManagedAgentsUnknownWorkflowRunError { type: :unknown_error, message }A failure that has no type of its own.
A failure that has no type of its own.
Short explanation written by the server. It never contains content from the run or its agents.
class BetaManagedAgentsURLDocumentSource { type: :url, url }Document referenced by URL.
Document referenced by URL.
url: StringURL of the document to fetch.
URL of the document to fetch.
class BetaManagedAgentsURLImageSource { type: :url, url }Image referenced by URL.
Image referenced by URL.
url: StringURL of the image to fetch.
URL of the image to fetch.
class BetaManagedAgentsUserCustomToolResultEvent { type: :"user.custom_tool_result", id, custom_tool_use_id, 4 more }Event sent by the client providing the result of a custom tool execution.
Event sent by the client providing the result of a custom tool execution.
class BetaManagedAgentsUserCustomToolResultEventParams { type: :"user.custom_tool_result", custom_tool_use_id, content, is_error }Parameters for providing the result of a custom tool execution.
Parameters for providing the result of a custom tool execution.
class BetaManagedAgentsUserDefineOutcomeEvent { type: :"user.define_outcome", id, description, 4 more }Echo of a user.define_outcome input event. Carries the server-generated outcome_id that subsequent span.outcome_evaluation_* events reference.
Echo of a user.define_outcome input event. Carries the server-generated outcome_id that subsequent span.outcome_evaluation_* events reference.
class BetaManagedAgentsUserDefineOutcomeEventParams { type: :"user.define_outcome", description, rubric, max_iterations }Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.
Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.
class BetaManagedAgentsUserInterruptEvent { type: :"user.interrupt", id, processed_at, session_thread_id }An interrupt event that pauses agent execution and returns control to the user.
An interrupt event that pauses agent execution and returns control to the user.
Unique identifier for this event.
processed_at: TimeTimestamp when the interrupt was processed.
Timestamp when the interrupt was processed.
If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.
class BetaManagedAgentsUserInterruptEventParams { type: :"user.interrupt", session_thread_id }Parameters for sending an interrupt to pause the agent.
Parameters for sending an interrupt to pause the agent.
If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.
class BetaManagedAgentsUserMessageEvent { type: :"user.message", id, content, processed_at }A user message event in the session conversation.
A user message event in the session conversation.
class BetaManagedAgentsUserMessageEventParams { type: :"user.message", content }Parameters for sending a user message to the session.
Parameters for sending a user message to the session.
class BetaManagedAgentsUserToolConfirmationEvent { type: :"user.tool_confirmation", id, result, 4 more }A tool confirmation event that approves or denies a pending tool execution.
A tool confirmation event that approves or denies a pending tool execution.
Unique identifier for this event.
result: :allow | :denyThe confirmation result: 'allow' or 'deny'.
The confirmation result: 'allow' or 'deny'.
The id of the agent.tool_use or agent.mcp_tool_use event this result corresponds to, which can be found in the last session.status_idle event's stop_reason.event_ids field.
deny_message: StringOptional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
processed_at: TimeTimestamp when the confirmation was processed.
Timestamp when the confirmation was processed.
Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread.
class BetaManagedAgentsUserToolConfirmationEventParams { type: :"user.tool_confirmation", result, tool_use_id, deny_message }Parameters for confirming or denying a tool execution request.
Parameters for confirming or denying a tool execution request.
result: :allow | :denyThe confirmation result: 'allow' or 'deny'.
The confirmation result: 'allow' or 'deny'.
tool_use_id: StringThe id of the agent.tool_use or agent.mcp_tool_use event this result corresponds to, which can be found in the last session.status_idle event's stop_reason.event_ids field.
The id of the agent.tool_use or agent.mcp_tool_use event this result corresponds to, which can be found in the last session.status_idle event's stop_reason.event_ids field.
deny_message: StringOptional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
class BetaManagedAgentsUserToolResultEventParams { type: :"user.tool_result", tool_use_id, content, is_error }Parameters for 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.
Parameters for 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.
class BetaManagedAgentsWorkflowRunCreatedEvent { type: :"workflow_run.created", id, description, 4 more }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 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.
type BetaManagedAgentsWorkflowRunError = BetaManagedAgentsTimeoutWorkflowRunError | BetaManagedAgentsProgramWorkflowRunError | BetaManagedAgentsUnknownWorkflowRunError | 2 moreWhy a workflow run did not finish, or was not created. More types may be added. On workflow_run.status_ended, for a type you do not recognize, rely on the event's result.type.
Why a workflow run did not finish, or was not created. More types may be added. On workflow_run.status_ended, for a type you do not recognize, rely on the event's result.type.
class BetaManagedAgentsWorkflowRunErrorEvent { type: :"workflow_run.error", id, error, 2 more }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.
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.
Unique identifier for this event.
Why the run did not finish, or was not created.
Why the run did not finish, or was not created.
processed_at: TimeTimestamp when this event was processed.
Timestamp when this event was processed.
Identifier of the run that met the error, or null when the error kept a run from being created.
class BetaManagedAgentsWorkflowRunPhase { id, description, name }A phase that a workflow run's plan declares.
A phase that a workflow run's plan declares.
Unique identifier for the phase.
Description that the agent gave the phase, passed on as written, or null if it gave none.
Name that the agent gave the phase, passed on as written.
class BetaManagedAgentsWorkflowRunPhaseEndedEvent { type: :"workflow_run.phase_ended", id, phase_started_id, 3 more }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'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.
Unique identifier for this event.
Identifier of the workflow_run.phase_started event that opened the phase.
processed_at: TimeTimestamp when this event was processed.
Timestamp when this event was processed.
Identifier of the run. The same value is on all of the run's workflow_run.* events.
Identifier of the phase, as in phases on the run's workflow_run.created event.
class BetaManagedAgentsWorkflowRunPhaseStartedEvent { type: :"workflow_run.phase_started", id, processed_at, 2 more }A workflow run's plan entered a phase.
A workflow run's plan entered a phase.
Unique identifier for this event.
processed_at: TimeTimestamp when this event was processed.
Timestamp when this event was processed.
Identifier of the run. The same value is on all of the run's workflow_run.* events.
Identifier of the phase, as in phases on the run's workflow_run.created event.
type BetaManagedAgentsWorkflowRunResult = BetaManagedAgentsWorkflowRunResultCompleted | BetaManagedAgentsWorkflowRunResultError | BetaManagedAgentsWorkflowRunResultStoppedHow a workflow run ended.
How a workflow run ended.
class BetaManagedAgentsWorkflowRunResultCompleted { type: :completed }The run's plan, a program that the agent wrote, finished. This does not say whether the work succeeded.
The run's plan, a program that the agent wrote, finished. This does not say whether the work succeeded.
class BetaManagedAgentsWorkflowRunResultError { type: :error, error }The run failed or reached its time limit.
The run failed or reached its time limit.
Why the run did not finish.
Why the run did not finish.
class BetaManagedAgentsWorkflowRunResultStopped { type: :stopped }The agent stopped the run.
The agent stopped the run.
class BetaManagedAgentsWorkflowRunResultCompleted { type: :completed }The run's plan, a program that the agent wrote, finished. This does not say whether the work succeeded.
The run's plan, a program that the agent wrote, finished. This does not say whether the work succeeded.
class BetaManagedAgentsWorkflowRunResultError { type: :error, error }The run failed or reached its time limit.
The run failed or reached its time limit.
Why the run did not finish.
Why the run did not finish.
class BetaManagedAgentsWorkflowRunResultStopped { type: :stopped }The agent stopped the run.
The agent stopped the run.
class BetaManagedAgentsWorkflowRunStatusEndedEvent { type: :"workflow_run.status_ended", id, processed_at, 2 more }A workflow run ended. Emitted once per run, as the last of the run's workflow_run.* events.
A workflow run ended. Emitted once per run, as the last of the run's workflow_run.* events.
class BetaManagedAgentsWorkflowRunStatusIdleEvent { type: :"workflow_run.status_idle", id, processed_at, workflow_run_id }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 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.
Unique identifier for this event.
processed_at: TimeTimestamp when this event was processed.
Timestamp when this event was processed.
Identifier of the run. The same value is on all of the run's workflow_run.* events.
class BetaManagedAgentsWorkflowRunStatusRunningEvent { type: :"workflow_run.status_running", id, processed_at, workflow_run_id }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 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.
Unique identifier for this event.
processed_at: TimeTimestamp when this event was processed.
Timestamp when this event was processed.
Identifier of the run. The same value is on all of the run's workflow_run.* events.