Claude Platform Docs

Events

List Events
EventListPage beta().sessions().events().list(EventListParamsparams = EventListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())
GET/v1/sessions/{session_id}/events
Send Events
BetaManagedAgentsSendSessionEvents beta().sessions().events().send(EventSendParamsparams, RequestOptionsrequestOptions = RequestOptions.none())
POST/v1/sessions/{session_id}/events
Stream Events
BetaManagedAgentsStreamSessionEvents beta().sessions().events().streamStreaming(EventStreamParamsparams = EventStreamParams.none(), RequestOptionsrequestOptions = RequestOptions.none())
GET/v1/sessions/{session_id}/events/stream
Models
class BetaManagedAgentsAgentCustomToolUseEvent:

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.

String id

Unique identifier for this event.

Input input

Input parameters for the tool call.

String name

Name of the custom tool being called.

LocalDateTime processedAt

A timestamp in RFC 3339 format

formatdate-time
Type type
Optional<String> sessionThreadId

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. Echo this on a user.custom_tool_result event to route the result back.

class BetaManagedAgentsAgentMcpToolResultEvent:

Event representing the result of an MCP tool execution.

class BetaManagedAgentsAgentMcpToolUseEvent:

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

String id

Unique identifier for this event.

Input input

Input parameters for the tool call.

String mcpServerName

Name of the MCP server providing the tool.

String name

Name of the MCP tool being used.

LocalDateTime processedAt

A timestamp in RFC 3339 format

formatdate-time
Type type
Optional<EvaluatedPermission> evaluatedPermission

AgentEvaluatedPermission enum

One of the following:
ALLOW("allow")
ASK("ask")
DENY("deny")
Optional<String> sessionThreadId

When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a user.tool_confirmation event to route the approval back.

class BetaManagedAgentsAgentMessageEvent:

An agent response event in the session conversation.

String id

Unique identifier for this event.

List<Content> content

Array of text blocks comprising the agent response.

One of the following:
class BetaManagedAgentsTextBlock:

Regular text content.

String text

The text content.

minLength1
Type type
class BetaManagedAgentsRedactedBlock:

Placeholder for content withheld by Anthropic model policy.

Type type
LocalDateTime processedAt

A timestamp in RFC 3339 format

formatdate-time
Type type
class BetaManagedAgentsAgentThinkingEvent:

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

String id

Unique identifier for this event.

LocalDateTime processedAt

A timestamp in RFC 3339 format

formatdate-time
Type type
class BetaManagedAgentsAgentThreadContextCompactedEvent:

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

String id

Unique identifier for this event.

LocalDateTime processedAt

A timestamp in RFC 3339 format

formatdate-time
Type type
class BetaManagedAgentsAgentThreadMessageReceivedEvent:

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

class BetaManagedAgentsAgentThreadMessageSentEvent:

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

class BetaManagedAgentsAgentToolResultEvent:

Event representing the result of an agent tool execution.

class BetaManagedAgentsAgentToolUseEvent:

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

String id

Unique identifier for this event.

Input input

Input parameters for the tool call.

String name

Name of the agent tool being used.

LocalDateTime processedAt

A timestamp in RFC 3339 format

formatdate-time
Type type
Optional<EvaluatedPermission> evaluatedPermission

AgentEvaluatedPermission enum

One of the following:
ALLOW("allow")
ASK("ask")
DENY("deny")
Optional<String> sessionThreadId

When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a user.tool_confirmation event to route the approval back.

class BetaManagedAgentsBase64DocumentSource:

Base64-encoded document data.

String data

Base64-encoded document data.

minLength1
String mediaType

MIME type of the document (e.g., "application/pdf").

minLength1
Type type
class BetaManagedAgentsBase64ImageSource:

Base64-encoded image data.

String data

Base64-encoded image data.

minLength1
String mediaType

MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

minLength1
Type type
class BetaManagedAgentsBillingError:

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.

String message

Human-readable error description.

RetryStatus retryStatus

What the client should do next in response to this error.

One of the following:
class BetaManagedAgentsRetryStatusRetrying:

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.

Type type
class BetaManagedAgentsRetryStatusExhausted:

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

Type type
class BetaManagedAgentsRetryStatusTerminal:

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

Type type
Type type
class BetaManagedAgentsCredentialHostUnreachableError:

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

String credentialId

ID of the affected credential.

String message

Human-readable error description.

RetryStatus retryStatus

What the client should do next in response to this error.

One of the following:
class BetaManagedAgentsRetryStatusRetrying:

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.

Type type
class BetaManagedAgentsRetryStatusExhausted:

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

Type type
class BetaManagedAgentsRetryStatusTerminal:

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

Type type
Type type
String vaultId

ID of the vault containing the affected credential.

class BetaManagedAgentsDocumentBlock:

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

class BetaManagedAgentsEventParams: A class that can be one of several variants.union

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

class BetaManagedAgentsFileDocumentSource:

Document referenced by file ID.

String fileId

ID of a previously uploaded file.

minLength1
Type type
class BetaManagedAgentsFileImageSource:

Image referenced by file ID.

String fileId

ID of a previously uploaded file.

minLength1
Type type
class BetaManagedAgentsFileRubric:

Rubric referenced by a file uploaded via the Files API.

String fileId

ID of the rubric file.

Type type
class BetaManagedAgentsFileRubricParams:

Rubric referenced by a file uploaded via the Files API.

String fileId

ID of the rubric file.

Type type
class BetaManagedAgentsImageBlock:

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

Source source

Union type for image source variants.

One of the following:
class BetaManagedAgentsBase64ImageSource:

Base64-encoded image data.

String data

Base64-encoded image data.

minLength1
String mediaType

MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

minLength1
Type type
class BetaManagedAgentsUrlImageSource:

Image referenced by URL.

Type type
String url

URL of the image to fetch.

minLength1
class BetaManagedAgentsFileImageSource:

Image referenced by file ID.

String fileId

ID of a previously uploaded file.

minLength1
Type type
Type type
class BetaManagedAgentsMcpAuthenticationFailedError:

Authentication to an MCP server failed.

String mcpServerName

Name of the MCP server that failed authentication.

String message

Human-readable error description.

RetryStatus retryStatus

What the client should do next in response to this error.

One of the following:
class BetaManagedAgentsRetryStatusRetrying:

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.

Type type
class BetaManagedAgentsRetryStatusExhausted:

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

Type type
class BetaManagedAgentsRetryStatusTerminal:

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

Type type
Type type
class BetaManagedAgentsMcpConnectionFailedError:

Failed to connect to an MCP server.

String mcpServerName

Name of the MCP server that failed to connect.

String message

Human-readable error description.

RetryStatus retryStatus

What the client should do next in response to this error.

One of the following:
class BetaManagedAgentsRetryStatusRetrying:

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.

Type type
class BetaManagedAgentsRetryStatusExhausted:

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

Type type
class BetaManagedAgentsRetryStatusTerminal:

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

Type type
Type type
class BetaManagedAgentsModelOverloadedError:

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

String message

Human-readable error description.

RetryStatus retryStatus

What the client should do next in response to this error.

One of the following:
class BetaManagedAgentsRetryStatusRetrying:

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.

Type type
class BetaManagedAgentsRetryStatusExhausted:

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

Type type
class BetaManagedAgentsRetryStatusTerminal:

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

Type type
Type type
class BetaManagedAgentsModelRateLimitedError:

The model request was rate-limited.

String message

Human-readable error description.

RetryStatus retryStatus

What the client should do next in response to this error.

One of the following:
class BetaManagedAgentsRetryStatusRetrying:

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.

Type type
class BetaManagedAgentsRetryStatusExhausted:

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

Type type
class BetaManagedAgentsRetryStatusTerminal:

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

Type type
Type type
class BetaManagedAgentsModelRequestFailedError:

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

String message

Human-readable error description.

RetryStatus retryStatus

What the client should do next in response to this error.

One of the following:
class BetaManagedAgentsRetryStatusRetrying:

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.

Type type
class BetaManagedAgentsRetryStatusExhausted:

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

Type type
class BetaManagedAgentsRetryStatusTerminal:

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

Type type
Type type
class BetaManagedAgentsPlainTextDocumentSource:

Plain text document content.

String data

The plain text content.

minLength1
MediaType mediaType

MIME type of the text content. Must be "text/plain".

Type type
class BetaManagedAgentsRedactedBlock:

Placeholder for content withheld by Anthropic model policy.

Type type
class BetaManagedAgentsRetryStatusExhausted:

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

Type type
class BetaManagedAgentsRetryStatusRetrying:

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.

Type type
class BetaManagedAgentsRetryStatusTerminal:

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

Type type
class BetaManagedAgentsSearchResultBlock:

A block containing a web search result.

BetaManagedAgentsSearchResultCitations citations

Citation settings for a search result.

boolean enabled

Whether citations are enabled for this search result.

List<BetaManagedAgentsSearchResultContent> content

Array of text content blocks from the search result.

String text

The text content.

minLength1
Type type
String source

The URL source of the search result.

minLength1
String title

The title of the search result.

minLength1
Type type
class BetaManagedAgentsSearchResultCitations:

Citation settings for a search result.

boolean enabled

Whether citations are enabled for this search result.

class BetaManagedAgentsSearchResultContent:

Text content within a search result.

String text

The text content.

minLength1
Type type
class BetaManagedAgentsSendSessionEvents:

Events that were successfully sent to the session.

class BetaManagedAgentsSessionBudgetReached:

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.

Type type
class BetaManagedAgentsSessionDeletedEvent:

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

String id

Unique identifier for this event.

LocalDateTime processedAt

A timestamp in RFC 3339 format

formatdate-time
Type type
class BetaManagedAgentsSessionEndTurn:

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

Type type
class BetaManagedAgentsSessionErrorEvent:

An error event indicating a problem occurred during session execution.

class BetaManagedAgentsSessionEvent: A class that can be one of several variants.union

Union type for all event types in a session.

class BetaManagedAgentsSessionRequiresAction:

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.

List<String> eventIds

The ids of events the agent is blocked on. Resolving fewer than all re-emits session.status_idle with the remainder.

Type type
class BetaManagedAgentsSessionRetriesExhausted:

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

Type type
class BetaManagedAgentsSessionStatusIdleEvent:

Indicates the agent has paused and is awaiting user input.

String id

Unique identifier for this event.

LocalDateTime processedAt

A timestamp in RFC 3339 format

formatdate-time
StopReason stopReason

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

One of the following:
class BetaManagedAgentsSessionEndTurn:

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

Type type
class BetaManagedAgentsSessionRequiresAction:

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.

List<String> eventIds

The ids of events the agent is blocked on. Resolving fewer than all re-emits session.status_idle with the remainder.

Type type
class BetaManagedAgentsSessionRetriesExhausted:

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

Type type
class BetaManagedAgentsSessionBudgetReached:

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.

Type type
Type type
class BetaManagedAgentsSessionStatusRescheduledEvent:

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

String id

Unique identifier for this event.

LocalDateTime processedAt

A timestamp in RFC 3339 format

formatdate-time
Type type
class BetaManagedAgentsSessionStatusRunningEvent:

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

String id

Unique identifier for this event.

LocalDateTime processedAt

A timestamp in RFC 3339 format

formatdate-time
Type type
class BetaManagedAgentsSessionStatusTerminatedEvent:

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

String id

Unique identifier for this event.

LocalDateTime processedAt

A timestamp in RFC 3339 format

formatdate-time
Type type
class BetaManagedAgentsSessionThreadCreatedEvent:

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.

String id

Unique identifier for this event.

String agentName

Name of the callable agent the thread runs.

LocalDateTime processedAt

A timestamp in RFC 3339 format

formatdate-time
String sessionThreadId

Public sthr_ ID of the newly created thread.

Type type
class BetaManagedAgentsSessionThreadStatusIdleEvent:

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:

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.

String id

Unique identifier for this event.

String agentName

Name of the agent the thread runs.

LocalDateTime processedAt

A timestamp in RFC 3339 format

formatdate-time
String sessionThreadId

Public sthr_ ID of the thread that is retrying.

Type type
class BetaManagedAgentsSessionThreadStatusRunningEvent:

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

String id

Unique identifier for this event.

String agentName

Name of the agent the thread runs.

LocalDateTime processedAt

A timestamp in RFC 3339 format

formatdate-time
String sessionThreadId

Public sthr_ ID of the thread that started running.

Type type
class BetaManagedAgentsSessionThreadStatusTerminatedEvent:

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.

String id

Unique identifier for this event.

String agentName

Name of the agent the thread runs.

LocalDateTime processedAt

A timestamp in RFC 3339 format

formatdate-time
String sessionThreadId

Public sthr_ ID of the thread that terminated.

Type type
class BetaManagedAgentsSessionUsageSnapshot:

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

class BetaManagedAgentsSpanModelRequestEndEvent:

Emitted when a model request completes.

String id

Unique identifier for this event.

Optional<Boolean> isError

Whether the model request resulted in an error.

String modelRequestStartId

The id of the corresponding span.model_request_start event.

BetaManagedAgentsSpanModelUsage modelUsage

Token usage for a single model request.

long cacheCreationInputTokens

Tokens used to create prompt cache in this request.

formatint32
long cacheReadInputTokens

Tokens read from prompt cache in this request.

formatint32
long inputTokens

Input tokens consumed by this request.

formatint32
long outputTokens

Output tokens generated by this request.

formatint32
Optional<Speed> speed

Inference speed mode. fast provides significantly faster output token generation at premium pricing. Not all models support fast; invalid combinations are rejected at create time.

One of the following:
STANDARD("standard")
FAST("fast")
LocalDateTime processedAt

A timestamp in RFC 3339 format

formatdate-time
Type type
class BetaManagedAgentsSpanModelRequestStartEvent:

Emitted when a model request is initiated by the agent.

String id

Unique identifier for this event.

LocalDateTime processedAt

A timestamp in RFC 3339 format

formatdate-time
Type type
class BetaManagedAgentsSpanModelUsage:

Token usage for a single model request.

long cacheCreationInputTokens

Tokens used to create prompt cache in this request.

formatint32
long cacheReadInputTokens

Tokens read from prompt cache in this request.

formatint32
long inputTokens

Input tokens consumed by this request.

formatint32
long outputTokens

Output tokens generated by this request.

formatint32
Optional<Speed> speed

Inference speed mode. fast provides significantly faster output token generation at premium pricing. Not all models support fast; invalid combinations are rejected at create time.

One of the following:
STANDARD("standard")
FAST("fast")
class BetaManagedAgentsSpanOutcomeEvaluationEndEvent:

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:

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.

String id

Unique identifier for this event.

long iteration

0-indexed revision cycle, matching the corresponding span.outcome_evaluation_start.

formatint32
String outcomeId

The outc_ ID of the outcome being evaluated.

LocalDateTime processedAt

A timestamp in RFC 3339 format

formatdate-time
Type type
class BetaManagedAgentsSpanOutcomeEvaluationStartEvent:

Emitted when an outcome evaluation cycle begins.

String id

Unique identifier for this event.

long iteration

0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.

formatint32
String outcomeId

The outc_ ID of the outcome being evaluated.

LocalDateTime processedAt

A timestamp in RFC 3339 format

formatdate-time
Type type
class BetaManagedAgentsStreamSessionEvents: A class that can be one of several variants.union

Server-sent event in the session stream.

class BetaManagedAgentsSystemMessageEventParams:

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.

List<BetaManagedAgentsSystemContentBlock> content

System content blocks to append. Text-only.

String text

The text content.

minLength1
Type type
Type type
class BetaManagedAgentsTextBlock:

Regular text content.

String text

The text content.

minLength1
Type type
class BetaManagedAgentsTextRubric:

Rubric content provided inline as text.

String content

Rubric content. Plain text or markdown — the grader treats it as freeform text.

Type type
class BetaManagedAgentsTextRubricParams:

Rubric content provided inline as text.

String content

Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.

maxLength262144
Type type
class BetaManagedAgentsUnknownError:

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.

String message

Human-readable error description.

RetryStatus retryStatus

What the client should do next in response to this error.

One of the following:
class BetaManagedAgentsRetryStatusRetrying:

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.

Type type
class BetaManagedAgentsRetryStatusExhausted:

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

Type type
class BetaManagedAgentsRetryStatusTerminal:

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

Type type
Type type
class BetaManagedAgentsUrlDocumentSource:

Document referenced by URL.

Type type
String url

URL of the document to fetch.

minLength1
class BetaManagedAgentsUrlImageSource:

Image referenced by URL.

Type type
String url

URL of the image to fetch.

minLength1
class BetaManagedAgentsUserCustomToolResultEvent:

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

class BetaManagedAgentsUserCustomToolResultEventParams:

Parameters for providing the result of a custom tool execution.

class BetaManagedAgentsUserDefineOutcomeEvent:

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

String id

Unique identifier for this event.

String description

What the agent should produce. Copied from the input event.

Optional<Long> maxIterations

Evaluate-then-revise cycles before giving up. Default 3, max 20.

formatint32
String outcomeId

Server-generated outc_ ID for this outcome. Referenced by span.outcome_evaluation_* events and the session's outcome_evaluations list.

LocalDateTime processedAt

A timestamp in RFC 3339 format

formatdate-time
Rubric rubric

Rubric for grading the quality of an outcome.

One of the following:
class BetaManagedAgentsFileRubric:

Rubric referenced by a file uploaded via the Files API.

String fileId

ID of the rubric file.

Type type
class BetaManagedAgentsTextRubric:

Rubric content provided inline as text.

String content

Rubric content. Plain text or markdown — the grader treats it as freeform text.

Type type
Type type
class BetaManagedAgentsUserDefineOutcomeEventParams:

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

String description

What the agent should produce. This is the task specification.

Rubric rubric

Rubric for grading the quality of an outcome.

One of the following:
class BetaManagedAgentsFileRubricParams:

Rubric referenced by a file uploaded via the Files API.

String fileId

ID of the rubric file.

Type type
class BetaManagedAgentsTextRubricParams:

Rubric content provided inline as text.

String content

Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.

maxLength262144
Type type
Type type
Optional<Long> maxIterations

Eval→revision cycles before giving up. Default 3, max 20.

formatint32
class BetaManagedAgentsUserInterruptEvent:

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

String id

Unique identifier for this event.

Type type
Optional<LocalDateTime> processedAt

A timestamp in RFC 3339 format

formatdate-time
Optional<String> sessionThreadId

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:

Parameters for sending an interrupt to pause the agent.

Type type
Optional<String> sessionThreadId

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:

A user message event in the session conversation.

class BetaManagedAgentsUserMessageEventParams:

Parameters for sending a user message to the session.

class BetaManagedAgentsUserToolConfirmationEvent:

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

String id

Unique identifier for this event.

Result result

UserToolConfirmationResult enum

One of the following:
ALLOW("allow")
DENY("deny")
String toolUseId

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.

Type type
Optional<String> denyMessage

Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

maxLength10000
Optional<LocalDateTime> processedAt

A timestamp in RFC 3339 format

formatdate-time
Optional<String> sessionThreadId

When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the session_thread_id on the agent.tool_use or agent.mcp_tool_use event that prompted the approval.

class BetaManagedAgentsUserToolConfirmationEventParams:

Parameters for confirming or denying a tool execution request.

Result result

UserToolConfirmationResult enum

One of the following:
ALLOW("allow")
DENY("deny")
String toolUseId

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.

minLength1
maxLength128
Type type
Optional<String> denyMessage

Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

maxLength10000
class BetaManagedAgentsUserToolResultEventParams:

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.