Claude Platform Docs

Event

Daftar Event
EventListPage beta().sessions().events().list(params = EventListParams.none(), requestOptions = RequestOptions.none())
GET/v1/sessions/{session_id}/events
Kirim Event
BetaManagedAgentsSendSessionEvents beta().sessions().events().send(params, requestOptions = RequestOptions.none())
POST/v1/sessions/{session_id}/events
Stream Event
StreamResponse<BetaManagedAgentsStreamSessionEvents> beta().sessions().events().streamStreaming(params = EventStreamParams.none(), requestOptions = RequestOptions.none())
GET/v1/sessions/{session_id}/events/stream
Models
class BetaManagedAgentsAgentAutoEvaluatedPermission: union

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.

JsonValue type = "allow"
class BetaManagedAgentsAgentAutoEvaluatedPermissionAsk { type = "ask"; reasonCode; }

The server reached no judgement; the invocation is held for client approval.

JsonValue type = "ask"
String reasonCode

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.

maxLength64
class BetaManagedAgentsAgentAutoEvaluatedPermissionDeny { type = "deny"; reasonCode; }

The server judged the invocation high-risk; it does not execute and a synthetic error tool result is appended.

JsonValue type = "deny"
String reasonCode

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.

maxLength64
class BetaManagedAgentsAgentAutoEvaluatedPermissionAllow { type = "allow"; }

The server judged the invocation safe to execute without client approval.

JsonValue type = "allow"
class BetaManagedAgentsAgentAutoEvaluatedPermissionAsk { type = "ask"; reasonCode; }

The server reached no judgement; the invocation is held for client approval.

JsonValue type = "ask"
String reasonCode

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.

maxLength64
class BetaManagedAgentsAgentAutoEvaluatedPermissionDeny { type = "deny"; reasonCode; }

The server judged the invocation high-risk; it does not execute and a synthetic error tool result is appended.

JsonValue type = "deny"
String reasonCode

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.

maxLength64
class BetaManagedAgentsAgentCustomToolUseEvent { type; 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.

Type type
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

Timestamp when this tool use was processed.

formatdate-time
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. Informational only: the server routes the matching user.custom_tool_result by custom_tool_use_id, so clients do not send it back.

enum BetaManagedAgentsAgentEvaluatedPermission
ALLOW("allow")
ASK("ask")
DENY("deny")
class BetaManagedAgentsAgentMcpToolResultEvent { type; id; mcpToolUseId; /* 3 more */ }

Event representing the result of an MCP tool execution.

class BetaManagedAgentsAgentMcpToolUseEvent { type; id; input; /* 6 more */ }

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

class BetaManagedAgentsAgentMessageEvent { type; id; content; processedAt; }

An agent response event in the session conversation.

Type type
String id

Unique identifier for this event.

List<Content> content

Array of text blocks comprising the agent response.

One of the following:
class BetaManagedAgentsTextBlock { type; text; }

Regular text content.

Type type
String text

The text content.

minLength1
class BetaManagedAgentsRedactedBlock { type; }

Placeholder for content withheld by Anthropic model policy.

Type type
LocalDateTime processedAt

Timestamp when this response was generated.

formatdate-time
class BetaManagedAgentsAgentThinkingEvent { type; id; processedAt; }

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

Type type
String id

Unique identifier for this event.

LocalDateTime processedAt

Timestamp when this thinking was produced.

formatdate-time
class BetaManagedAgentsAgentThreadContextCompactedEvent { type; id; processedAt; }

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

Type type
String id

Unique identifier for this event.

LocalDateTime processedAt

Timestamp when compaction was processed.

formatdate-time
class BetaManagedAgentsAgentThreadMessageReceivedEvent { type; id; content; /* 3 more */ }

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

class BetaManagedAgentsAgentThreadMessageSentEvent { type; id; content; /* 3 more */ }

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

class BetaManagedAgentsAgentToolEvaluation: union

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

JsonValue type = "always_allow"
class BetaManagedAgentsAgentToolEvaluationAlwaysAsk { type = "always_ask"; }

The resolved permission_policy was always_ask; accompanies evaluated_permission "ask".

JsonValue type = "always_ask"
class BetaManagedAgentsAgentToolEvaluationAuto { type = "auto"; evaluatedPermission; }

The resolved permission_policy was auto: the server judged this invocation individually.

class BetaManagedAgentsAgentToolEvaluationAlwaysAllow { type = "always_allow"; }

The resolved permission_policy was always_allow; accompanies evaluated_permission "allow".

JsonValue type = "always_allow"
class BetaManagedAgentsAgentToolEvaluationAlwaysAsk { type = "always_ask"; }

The resolved permission_policy was always_ask; accompanies evaluated_permission "ask".

JsonValue type = "always_ask"
class BetaManagedAgentsAgentToolEvaluationAuto { type = "auto"; evaluatedPermission; }

The resolved permission_policy was auto: the server judged this invocation individually.

class BetaManagedAgentsAgentToolResultEvent { type; id; processedAt; /* 3 more */ }

Event representing the result of an agent tool execution.

class BetaManagedAgentsAgentToolUseEvent { type; id; input; /* 5 more */ }

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

class BetaManagedAgentsBase64DocumentSource { type; data; mediaType; }

Base64-encoded document data.

Type type
String data

Base64-encoded document data.

minLength1
String mediaType

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

minLength1
class BetaManagedAgentsBase64ImageSource { type; data; mediaType; }

Base64-encoded image data.

Type type
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
class BetaManagedAgentsBillingError { type; message; retryStatus; }

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.

Type type
String message

Human-readable error description.

RetryStatus retryStatus

What the client should do next.

One of the following:
class BetaManagedAgentsRetryStatusRetrying { type; }

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 { type; }

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

Type type
class BetaManagedAgentsRetryStatusTerminal { type; }

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

Type type
class BetaManagedAgentsCredentialHostUnreachableError { type; credentialId; message; /* 2 more */ }

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

class BetaManagedAgentsDocumentBlock { type; source; context; title; }

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

class BetaManagedAgentsEventParams: union

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

class BetaManagedAgentsFileDocumentSource { type; fileId; }

Document referenced by file ID.

Type type
String fileId

ID of a previously uploaded file.

minLength1
class BetaManagedAgentsFileImageSource { type; fileId; }

Image referenced by file ID.

Type type
String fileId

ID of a previously uploaded file.

minLength1
class BetaManagedAgentsFileRubric { type; fileId; }

Rubric referenced by a file uploaded via the Files API.

Type type
String fileId

ID of the rubric file.

class BetaManagedAgentsFileRubricParams { type; fileId; }

Rubric referenced by a file uploaded via the Files API.

Type type
String fileId

ID of the rubric file.

class BetaManagedAgentsImageBlock { type; source; }

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.

JsonValue type = "max_workflow_runs_error"
String message

Short explanation written by the server. It never contains content from the run or its agents.

class BetaManagedAgentsMcpAuthenticationFailedError { type; mcpServerName; message; retryStatus; }

Authentication to an MCP server failed.

Type type
String mcpServerName

Name of the MCP server that failed authentication.

String message

Human-readable error description.

RetryStatus retryStatus

What the client should do next.

One of the following:
class BetaManagedAgentsRetryStatusRetrying { type; }

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 { type; }

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

Type type
class BetaManagedAgentsRetryStatusTerminal { type; }

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

Type type
class BetaManagedAgentsMcpConnectionFailedError { type; mcpServerName; message; retryStatus; }

Failed to connect to an MCP server.

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

One of the following:
class BetaManagedAgentsRetryStatusRetrying { type; }

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 { type; }

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

Type type
class BetaManagedAgentsRetryStatusTerminal { type; }

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

Type type
class BetaManagedAgentsModelOverloadedError { type; message; retryStatus; }

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

Type type
String message

Human-readable error description.

RetryStatus retryStatus

What the client should do next.

One of the following:
class BetaManagedAgentsRetryStatusRetrying { type; }

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 { type; }

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

Type type
class BetaManagedAgentsRetryStatusTerminal { type; }

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

Type type
class BetaManagedAgentsModelRateLimitedError { type; message; retryStatus; }

The model request was rate-limited.

Type type
String message

Human-readable error description.

RetryStatus retryStatus

What the client should do next.

One of the following:
class BetaManagedAgentsRetryStatusRetrying { type; }

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 { type; }

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

Type type
class BetaManagedAgentsRetryStatusTerminal { type; }

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

Type type
class BetaManagedAgentsModelRequestFailedError { type; message; retryStatus; }

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

Type type
String message

Human-readable error description.

RetryStatus retryStatus

What the client should do next.

One of the following:
class BetaManagedAgentsRetryStatusRetrying { type; }

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 { type; }

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

Type type
class BetaManagedAgentsRetryStatusTerminal { type; }

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

Type type
class BetaManagedAgentsPlainTextDocumentSource { type; data; mediaType; }

Plain text document content.

Type type
String data

The plain text content.

minLength1
MediaType mediaType

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.

JsonValue type = "program_error"
String message

Short explanation written by the server. It never contains content from the run or its agents.

class BetaManagedAgentsRedactedBlock { type; }

Placeholder for content withheld by Anthropic model policy.

Type type
class BetaManagedAgentsRepositoryAuthenticationError { type = "repository_authentication_error"; message; repositoryUrl; retryStatus; }

The repository host rejected the credentials, or required credentials and received none.

class BetaManagedAgentsRepositoryCheckoutError { type = "repository_checkout_error"; message; repositoryUrl; retryStatus; }

The requested branch or commit does not exist in the repository.

class BetaManagedAgentsRepositoryCloneError { type = "repository_clone_error"; message; repositoryUrl; retryStatus; }

The repository could not be cloned.

class BetaManagedAgentsRepositoryForbiddenError { type = "repository_forbidden_error"; message; repositoryUrl; retryStatus; }

The repository host refused access to the repository.

class BetaManagedAgentsRepositoryNotFoundError { type = "repository_not_found_error"; message; repositoryUrl; retryStatus; }

The repository host reported the repository as not found.

class BetaManagedAgentsRetryStatusExhausted { type; }

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

Type type
class BetaManagedAgentsRetryStatusRetrying { type; }

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 { type; }

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

Type type
class BetaManagedAgentsSearchResultBlock { type; citations; content; /* 2 more */ }

A block containing a web search result.

Type type
BetaManagedAgentsSearchResultCitations citations

Citation settings for this search result.

boolean enabled

Whether citations are enabled for this search result.

List<BetaManagedAgentsSearchResultContent> content

Array of text content blocks from the search result.

Type type
String text

The text content.

minLength1
String source

The URL source of the search result.

minLength1
String title

The title of the search result.

minLength1
class BetaManagedAgentsSearchResultCitations { enabled; }

Citation settings for a search result.

boolean enabled

Whether citations are enabled for this search result.

class BetaManagedAgentsSearchResultContent { type; text; }

Text content within a search result.

Type type
String text

The text content.

minLength1
class BetaManagedAgentsSendSessionEvents { data; }

Events that were successfully sent to the session.

class BetaManagedAgentsSessionBudgetReached { type; }

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 { type; id; processedAt; }

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

Type type
String id

Unique identifier for this event.

LocalDateTime processedAt

Timestamp when the session was deleted.

formatdate-time
class BetaManagedAgentsSessionEndTurn { type; }

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

Type type
class BetaManagedAgentsSessionErrorEvent { type; id; error; processedAt; }

An error event indicating a problem occurred during session execution.

class BetaManagedAgentsSessionEvent: union

Union type for all event types in a session.

enum BetaManagedAgentsSessionEventType

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.

JsonValue type = "refusal"
class BetaManagedAgentsSessionRefusalStopDetails { type = "refusal"; category; explanation; }

Structured information about a refusal.

JsonValue type = "refusal"
Optional<Category> category

The policy category that triggered the refusal, or null when there is no named category. New values can be added over time.

One of the following:
CYBER("cyber")
BIO("bio")
FRONTIER_LLM("frontier_llm")
REASONING_EXTRACTION("reasoning_extraction")
GENERAL_HARMS("general_harms")
Optional<String> explanation

Human-readable explanation of the refusal, or null when none is available. The wording can change, so do not parse it.

class BetaManagedAgentsSessionRequiresAction { type; eventIds; }

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.

Type type
List<String> eventIds

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

class BetaManagedAgentsSessionRetriesExhausted { type; }

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

Type type
class BetaManagedAgentsSessionStatusIdleEvent { type; id; processedAt; /* 2 more */ }

Indicates the agent has paused and is awaiting user input.

class BetaManagedAgentsSessionStatusRescheduledEvent { type; id; processedAt; }

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

Type type
String id

Unique identifier for this event.

LocalDateTime processedAt

Timestamp of status change.

formatdate-time
class BetaManagedAgentsSessionStatusRunningEvent { type; id; processedAt; }

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

Type type
String id

Unique identifier for this event.

LocalDateTime processedAt

Timestamp of status change.

formatdate-time
class BetaManagedAgentsSessionStatusTerminatedEvent { type; id; processedAt; }

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

Type type
String id

Unique identifier for this event.

LocalDateTime processedAt

Timestamp of status change.

formatdate-time
class BetaManagedAgentsSessionThreadCreatedEvent { type; id; agentName; /* 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.

Type type
String id

Unique identifier for this event.

String agentName

Name of the callable agent the thread runs.

LocalDateTime processedAt

Timestamp when the thread was created.

formatdate-time
String sessionThreadId

Public sthr_ ID of the newly created thread.

Optional<String> workflowRunId

Identifier of the workflow run that created the thread, or null for any other thread.

class BetaManagedAgentsSessionThreadStatusIdleEvent { type; id; agentName; /* 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.

class BetaManagedAgentsSessionThreadStatusRescheduledEvent { type; id; agentName; /* 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.

Type type
String id

Unique identifier for this event.

String agentName

Name of the agent the thread runs.

LocalDateTime processedAt

Timestamp of the status transition.

formatdate-time
String sessionThreadId

Public sthr_ ID of the thread that is retrying.

class BetaManagedAgentsSessionThreadStatusRunningEvent { type; id; agentName; /* 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.

Type type
String id

Unique identifier for this event.

String agentName

Name of the agent the thread runs.

LocalDateTime processedAt

Timestamp of the status transition.

formatdate-time
String sessionThreadId

Public sthr_ ID of the thread that started running.

class BetaManagedAgentsSessionThreadStatusTerminatedEvent { type; id; agentName; /* 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.

Type type
String id

Unique identifier for this event.

String agentName

Name of the agent the thread runs.

LocalDateTime processedAt

Timestamp of the status transition.

formatdate-time
String sessionThreadId

Public sthr_ ID of the thread that terminated.

class BetaManagedAgentsSessionUsageSnapshot { activeSeconds; cacheCreation; cacheReadInputTokens; /* 4 more */ }

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

class BetaManagedAgentsSpanModelRequestEndEvent { type; id; isError; /* 3 more */ }

Emitted when a model request completes.

class BetaManagedAgentsSpanModelRequestStartEvent { type; id; processedAt; }

Emitted when a model request is initiated by the agent.

Type type
String id

Unique identifier for this event.

LocalDateTime processedAt

Timestamp when the model request started.

formatdate-time
class BetaManagedAgentsSpanModelUsage { cacheCreationInputTokens; cacheReadInputTokens; inputTokens; /* 2 more */ }

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 tier this request actually ran at. Mirrors usage.speed on /v1/messages. Only present when the fast-mode beta is active.

One of the following:
STANDARD("standard")
FAST("fast")
class BetaManagedAgentsSpanOutcomeEvaluationEndEvent { type; 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.

class BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent { type; 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.

Type type
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

Timestamp when this heartbeat was emitted.

formatdate-time
class BetaManagedAgentsSpanOutcomeEvaluationStartEvent { type; id; iteration; /* 2 more */ }

Emitted when an outcome evaluation cycle begins.

Type type
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

Timestamp when outcome evaluation started.

formatdate-time
class BetaManagedAgentsStreamSessionEvents: union

Server-sent event in the session stream.

class BetaManagedAgentsSystemMessageEventParams { type; 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.

Type type
List<BetaManagedAgentsSystemContentBlock> content

System content blocks to append. Text-only.

Type type
String text

The text content.

minLength1
class BetaManagedAgentsTextBlock { type; text; }

Regular text content.

Type type
String text

The text content.

minLength1
class BetaManagedAgentsTextRubric { type; content; }

Rubric content provided inline as text.

Type type
String content

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

class BetaManagedAgentsTextRubricParams { type; content; }

Rubric content provided inline as text.

Type type
String content

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

maxLength262144
class BetaManagedAgentsThreadLimitWorkflowRunError { type = "thread_limit_error"; message; }

The run exceeded the limit on the number of threads that a run can create.

JsonValue type = "thread_limit_error"
String message

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.

JsonValue type = "timeout_error"
String message

Short explanation written by the server. It never contains content from the run or its agents.

class BetaManagedAgentsUnknownError { type; message; retryStatus; }

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.

Type type
String message

Human-readable error description.

RetryStatus retryStatus

What the client should do next.

One of the following:
class BetaManagedAgentsRetryStatusRetrying { type; }

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 { type; }

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

Type type
class BetaManagedAgentsRetryStatusTerminal { type; }

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

Type type
class BetaManagedAgentsUnknownWorkflowRunError { type = "unknown_error"; message; }

A failure that has no type of its own.

JsonValue type = "unknown_error"
String message

Short explanation written by the server. It never contains content from the run or its agents.

class BetaManagedAgentsUrlDocumentSource { type; url; }

Document referenced by URL.

Type type
String url

URL of the document to fetch.

minLength1
class BetaManagedAgentsUrlImageSource { type; url; }

Image referenced by URL.

Type type
String url

URL of the image to fetch.

minLength1
class BetaManagedAgentsUserCustomToolResultEvent { type; id; customToolUseId; /* 4 more */ }

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

class BetaManagedAgentsUserCustomToolResultEventParams { type; customToolUseId; content; isError; }

Parameters for providing the result of a custom tool execution.

class BetaManagedAgentsUserDefineOutcomeEvent { type; 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.

class BetaManagedAgentsUserDefineOutcomeEventParams { type; description; rubric; maxIterations; }

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

Type type
String description

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

Rubric rubric

How to grade the outcome. Text or file reference.

One of the following:
class BetaManagedAgentsFileRubricParams { type; fileId; }

Rubric referenced by a file uploaded via the Files API.

Type type
String fileId

ID of the rubric file.

class BetaManagedAgentsTextRubricParams { type; content; }

Rubric content provided inline as text.

Type type
String content

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

maxLength262144
Optional<Long> maxIterations

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

formatint32
class BetaManagedAgentsUserInterruptEvent { type; id; processedAt; sessionThreadId; }

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

Type type
String id

Unique identifier for this event.

Optional<LocalDateTime> processedAt

Timestamp when the interrupt was processed.

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 { type; sessionThreadId; }

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 { type; id; content; processedAt; }

A user message event in the session conversation.

class BetaManagedAgentsUserMessageEventParams { type; content; }

Parameters for sending a user message to the session.

Type type
List<Content> content

Array of content blocks for the user message.

One of the following:
class BetaManagedAgentsTextBlock { type; text; }

Regular text content.

Type type
String text

The text content.

minLength1
class BetaManagedAgentsImageBlock { type; source; }

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

class BetaManagedAgentsDocumentBlock { type; source; context; title; }

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

class BetaManagedAgentsRedactedBlock { type; }

Placeholder for content withheld by Anthropic model policy.

Type type
class BetaManagedAgentsUserToolConfirmationEvent { type; id; result; /* 4 more */ }

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

Type type
String id

Unique identifier for this event.

Result result

The confirmation result: 'allow' or 'deny'.

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.

Optional<String> denyMessage

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

maxLength10000
Optional<LocalDateTime> processedAt

Timestamp when the confirmation was processed.

formatdate-time
Optional<String> sessionThreadId

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; result; toolUseId; denyMessage; }

Parameters for confirming or denying a tool execution request.

Type type
Result result

The confirmation result: 'allow' or 'deny'.

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
Optional<String> denyMessage

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

maxLength10000
class BetaManagedAgentsUserToolResultEventParams { type; toolUseId; content; isError; }

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.

JsonValue type = "workflow_run.created"
String id

Unique identifier for this event.

Optional<String> description

Description that the agent gave the run, passed on as written, or null if it gave none.

String name

Name that the agent gave the run, passed on as written, or a name that the server assigned.

List<BetaManagedAgentsWorkflowRunPhase> phases

The phases that the run's plan declares, in the plan's order. Can be empty.

String id

Unique identifier for the phase.

Optional<String> description

Description that the agent gave the phase, passed on as written, or null if it gave none.

String name

Name that the agent gave the phase, passed on as written.

LocalDateTime processedAt

Timestamp when this event was processed.

formatdate-time
String workflowRunId

Identifier of the run. The same value is on all of the run's workflow_run.* events.

class BetaManagedAgentsWorkflowRunError: union

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.

JsonValue type = "workflow_run.error"
String id

Unique identifier for this event.

BetaManagedAgentsWorkflowRunError error

Why the run did not finish, or was not created.

One of the following:
LocalDateTime processedAt

Timestamp when this event was processed.

formatdate-time
Optional<String> workflowRunId

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.

String id

Unique identifier for the phase.

Optional<String> description

Description that the agent gave the phase, passed on as written, or null if it gave none.

String name

Name that the agent gave the phase, passed on as written.

class BetaManagedAgentsWorkflowRunPhaseEndedEvent { type = "workflow_run.phase_ended"; id; phaseStartedId; /* 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.

JsonValue type = "workflow_run.phase_ended"
String id

Unique identifier for this event.

String phaseStartedId

Identifier of the workflow_run.phase_started event that opened the phase.

LocalDateTime processedAt

Timestamp when this event was processed.

formatdate-time
String workflowRunId

Identifier of the run. The same value is on all of the run's workflow_run.* events.

String workflowRunPhaseId

Identifier of the phase, as in phases on the run's workflow_run.created event.

class BetaManagedAgentsWorkflowRunPhaseStartedEvent { type = "workflow_run.phase_started"; id; processedAt; /* 2 more */ }

A workflow run's plan entered a phase.

JsonValue type = "workflow_run.phase_started"
String id

Unique identifier for this event.

LocalDateTime processedAt

Timestamp when this event was processed.

formatdate-time
String workflowRunId

Identifier of the run. The same value is on all of the run's workflow_run.* events.

String workflowRunPhaseId

Identifier of the phase, as in phases on the run's workflow_run.created event.

class BetaManagedAgentsWorkflowRunResult: union

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.

JsonValue type = "completed"
class BetaManagedAgentsWorkflowRunResultError { type = "error"; error; }

The run failed or reached its time limit.

JsonValue type = "error"
BetaManagedAgentsWorkflowRunError error

Why the run did not finish.

One of the following:
class BetaManagedAgentsWorkflowRunResultStopped { type = "stopped"; }

The agent stopped the run.

JsonValue type = "stopped"
class BetaManagedAgentsWorkflowRunResultCompleted { type = "completed"; }

The run's plan, a program that the agent wrote, finished. This does not say whether the work succeeded.

JsonValue type = "completed"
class BetaManagedAgentsWorkflowRunResultError { type = "error"; error; }

The run failed or reached its time limit.

JsonValue type = "error"
BetaManagedAgentsWorkflowRunError error

Why the run did not finish.

One of the following:
class BetaManagedAgentsWorkflowRunResultStopped { type = "stopped"; }

The agent stopped the run.

JsonValue type = "stopped"
class BetaManagedAgentsWorkflowRunStatusEndedEvent { type = "workflow_run.status_ended"; id; processedAt; /* 2 more */ }

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; processedAt; workflowRunId; }

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.

JsonValue type = "workflow_run.status_idle"
String id

Unique identifier for this event.

LocalDateTime processedAt

Timestamp when this event was processed.

formatdate-time
String workflowRunId

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; processedAt; workflowRunId; }

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.

JsonValue type = "workflow_run.status_running"
String id

Unique identifier for this event.

LocalDateTime processedAt

Timestamp when this event was processed.

formatdate-time
String workflowRunId

Identifier of the run. The same value is on all of the run's workflow_run.* events.