Claude Platform Docs

Events

List Events
client.Beta.Sessions.Events.List(ctx, sessionID, params) (*PageCursor[BetaManagedAgentsSessionEventUnion], error)
GET/v1/sessions/{session_id}/events
Send Events
client.Beta.Sessions.Events.Send(ctx, sessionID, params) (*BetaManagedAgentsSendSessionEvents, error)
POST/v1/sessions/{session_id}/events
Stream Events
client.Beta.Sessions.Events.Stream(ctx, sessionID, params) (*BetaManagedAgentsStreamSessionEventsUnion, error)
GET/v1/sessions/{session_id}/events/stream
Models
type BetaManagedAgentsAgentCustomToolUseEvent struct{…}

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.

ID string

Unique identifier for this event.

Input map[string, any]

Input parameters for the tool call.

Name string

Name of the custom tool being called.

ProcessedAt Time

A timestamp in RFC 3339 format

formatdate-time
Type BetaManagedAgentsAgentCustomToolUseEventType
SessionThreadID string Optional

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.

type BetaManagedAgentsAgentMCPToolResultEvent struct{…}

Event representing the result of an MCP tool execution.

type BetaManagedAgentsAgentMCPToolUseEvent struct{…}

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

ID string

Unique identifier for this event.

Input map[string, any]

Input parameters for the tool call.

MCPServerName string

Name of the MCP server providing the tool.

Name string

Name of the MCP tool being used.

ProcessedAt Time

A timestamp in RFC 3339 format

formatdate-time
Type BetaManagedAgentsAgentMCPToolUseEventType
EvaluatedPermission BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission Optional

AgentEvaluatedPermission enum

One of the following:
const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "allow"
const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "ask"
const BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentMCPToolUseEventEvaluatedPermission = "deny"
SessionThreadID string Optional

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.

type BetaManagedAgentsAgentMessageEvent struct{…}

An agent response event in the session conversation.

ID string

Unique identifier for this event.

Content []BetaManagedAgentsAgentMessageEventContentUnion

Array of text blocks comprising the agent response.

One of the following:
type BetaManagedAgentsTextBlock struct{…}

Regular text content.

Text string

The text content.

minLength1
Type BetaManagedAgentsTextBlockType
type BetaManagedAgentsRedactedBlockParam struct{…}

Placeholder for content withheld by Anthropic model policy.

Type BetaManagedAgentsRedactedBlockType
ProcessedAt Time

A timestamp in RFC 3339 format

formatdate-time
Type BetaManagedAgentsAgentMessageEventType
type BetaManagedAgentsAgentThinkingEvent struct{…}

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

ID string

Unique identifier for this event.

ProcessedAt Time

A timestamp in RFC 3339 format

formatdate-time
Type BetaManagedAgentsAgentThinkingEventType
type BetaManagedAgentsAgentThreadContextCompactedEvent struct{…}

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

ID string

Unique identifier for this event.

ProcessedAt Time

A timestamp in RFC 3339 format

formatdate-time
Type BetaManagedAgentsAgentThreadContextCompactedEventType
type BetaManagedAgentsAgentThreadMessageReceivedEvent struct{…}

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

type BetaManagedAgentsAgentThreadMessageSentEvent struct{…}

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

type BetaManagedAgentsAgentToolResultEvent struct{…}

Event representing the result of an agent tool execution.

type BetaManagedAgentsAgentToolUseEvent struct{…}

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

ID string

Unique identifier for this event.

Input map[string, any]

Input parameters for the tool call.

Name string

Name of the agent tool being used.

ProcessedAt Time

A timestamp in RFC 3339 format

formatdate-time
Type BetaManagedAgentsAgentToolUseEventType
EvaluatedPermission BetaManagedAgentsAgentToolUseEventEvaluatedPermission Optional

AgentEvaluatedPermission enum

One of the following:
const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAllow BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "allow"
const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionAsk BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "ask"
const BetaManagedAgentsAgentToolUseEventEvaluatedPermissionDeny BetaManagedAgentsAgentToolUseEventEvaluatedPermission = "deny"
SessionThreadID string Optional

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.

type BetaManagedAgentsBase64DocumentSource struct{…}

Base64-encoded document data.

Data string

Base64-encoded document data.

minLength1
MediaType string

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

minLength1
Type BetaManagedAgentsBase64DocumentSourceType
type BetaManagedAgentsBase64ImageSource struct{…}

Base64-encoded image data.

Data string

Base64-encoded image data.

minLength1
MediaType string

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

minLength1
Type BetaManagedAgentsBase64ImageSourceType
type BetaManagedAgentsBillingError struct{…}

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.

Message string

Human-readable error description.

RetryStatus BetaManagedAgentsBillingErrorRetryStatusUnion

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

One of the following:
type BetaManagedAgentsRetryStatusRetrying struct{…}

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 BetaManagedAgentsRetryStatusRetryingType
type BetaManagedAgentsRetryStatusExhausted struct{…}

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

Type BetaManagedAgentsRetryStatusExhaustedType
type BetaManagedAgentsRetryStatusTerminal struct{…}

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

Type BetaManagedAgentsRetryStatusTerminalType
Type BetaManagedAgentsBillingErrorType
type BetaManagedAgentsCredentialHostUnreachableError struct{…}

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

CredentialID string

ID of the affected credential.

Message string

Human-readable error description.

RetryStatus BetaManagedAgentsCredentialHostUnreachableErrorRetryStatusUnion

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

One of the following:
type BetaManagedAgentsRetryStatusRetrying struct{…}

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 BetaManagedAgentsRetryStatusRetryingType
type BetaManagedAgentsRetryStatusExhausted struct{…}

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

Type BetaManagedAgentsRetryStatusExhaustedType
type BetaManagedAgentsRetryStatusTerminal struct{…}

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

Type BetaManagedAgentsRetryStatusTerminalType
Type BetaManagedAgentsCredentialHostUnreachableErrorType
VaultID string

ID of the vault containing the affected credential.

type BetaManagedAgentsDocumentBlock struct{…}

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

type BetaManagedAgentsEventParamsUnionResp interface{…}

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

One of the following:
type BetaManagedAgentsFileDocumentSource struct{…}

Document referenced by file ID.

FileID string

ID of a previously uploaded file.

minLength1
Type BetaManagedAgentsFileDocumentSourceType
type BetaManagedAgentsFileImageSource struct{…}

Image referenced by file ID.

FileID string

ID of a previously uploaded file.

minLength1
Type BetaManagedAgentsFileImageSourceType
type BetaManagedAgentsFileRubric struct{…}

Rubric referenced by a file uploaded via the Files API.

FileID string

ID of the rubric file.

Type BetaManagedAgentsFileRubricType
type BetaManagedAgentsFileRubricParams struct{…}

Rubric referenced by a file uploaded via the Files API.

FileID string

ID of the rubric file.

Type BetaManagedAgentsFileRubricParamsType
type BetaManagedAgentsImageBlock struct{…}

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

Source BetaManagedAgentsImageBlockSourceUnion

Union type for image source variants.

One of the following:
type BetaManagedAgentsBase64ImageSource struct{…}

Base64-encoded image data.

Data string

Base64-encoded image data.

minLength1
MediaType string

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

minLength1
Type BetaManagedAgentsBase64ImageSourceType
type BetaManagedAgentsURLImageSource struct{…}

Image referenced by URL.

Type BetaManagedAgentsURLImageSourceType
URL string

URL of the image to fetch.

minLength1
type BetaManagedAgentsFileImageSource struct{…}

Image referenced by file ID.

FileID string

ID of a previously uploaded file.

minLength1
Type BetaManagedAgentsFileImageSourceType
Type BetaManagedAgentsImageBlockType
type BetaManagedAgentsMCPAuthenticationFailedError struct{…}

Authentication to an MCP server failed.

MCPServerName string

Name of the MCP server that failed authentication.

Message string

Human-readable error description.

RetryStatus BetaManagedAgentsMCPAuthenticationFailedErrorRetryStatusUnion

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

One of the following:
type BetaManagedAgentsRetryStatusRetrying struct{…}

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 BetaManagedAgentsRetryStatusRetryingType
type BetaManagedAgentsRetryStatusExhausted struct{…}

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

Type BetaManagedAgentsRetryStatusExhaustedType
type BetaManagedAgentsRetryStatusTerminal struct{…}

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

Type BetaManagedAgentsRetryStatusTerminalType
Type BetaManagedAgentsMCPAuthenticationFailedErrorType
type BetaManagedAgentsMCPConnectionFailedError struct{…}

Failed to connect to an MCP server.

MCPServerName string

Name of the MCP server that failed to connect.

Message string

Human-readable error description.

RetryStatus BetaManagedAgentsMCPConnectionFailedErrorRetryStatusUnion

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

One of the following:
type BetaManagedAgentsRetryStatusRetrying struct{…}

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 BetaManagedAgentsRetryStatusRetryingType
type BetaManagedAgentsRetryStatusExhausted struct{…}

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

Type BetaManagedAgentsRetryStatusExhaustedType
type BetaManagedAgentsRetryStatusTerminal struct{…}

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

Type BetaManagedAgentsRetryStatusTerminalType
Type BetaManagedAgentsMCPConnectionFailedErrorType
type BetaManagedAgentsModelOverloadedError struct{…}

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

Message string

Human-readable error description.

RetryStatus BetaManagedAgentsModelOverloadedErrorRetryStatusUnion

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

One of the following:
type BetaManagedAgentsRetryStatusRetrying struct{…}

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 BetaManagedAgentsRetryStatusRetryingType
type BetaManagedAgentsRetryStatusExhausted struct{…}

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

Type BetaManagedAgentsRetryStatusExhaustedType
type BetaManagedAgentsRetryStatusTerminal struct{…}

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

Type BetaManagedAgentsRetryStatusTerminalType
Type BetaManagedAgentsModelOverloadedErrorType
type BetaManagedAgentsModelRateLimitedError struct{…}

The model request was rate-limited.

Message string

Human-readable error description.

RetryStatus BetaManagedAgentsModelRateLimitedErrorRetryStatusUnion

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

One of the following:
type BetaManagedAgentsRetryStatusRetrying struct{…}

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 BetaManagedAgentsRetryStatusRetryingType
type BetaManagedAgentsRetryStatusExhausted struct{…}

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

Type BetaManagedAgentsRetryStatusExhaustedType
type BetaManagedAgentsRetryStatusTerminal struct{…}

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

Type BetaManagedAgentsRetryStatusTerminalType
Type BetaManagedAgentsModelRateLimitedErrorType
type BetaManagedAgentsModelRequestFailedError struct{…}

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

Message string

Human-readable error description.

RetryStatus BetaManagedAgentsModelRequestFailedErrorRetryStatusUnion

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

One of the following:
type BetaManagedAgentsRetryStatusRetrying struct{…}

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 BetaManagedAgentsRetryStatusRetryingType
type BetaManagedAgentsRetryStatusExhausted struct{…}

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

Type BetaManagedAgentsRetryStatusExhaustedType
type BetaManagedAgentsRetryStatusTerminal struct{…}

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

Type BetaManagedAgentsRetryStatusTerminalType
Type BetaManagedAgentsModelRequestFailedErrorType
type BetaManagedAgentsPlainTextDocumentSource struct{…}

Plain text document content.

Data string

The plain text content.

minLength1
MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType

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

Type BetaManagedAgentsPlainTextDocumentSourceType
type BetaManagedAgentsRedactedBlockParam struct{…}

Placeholder for content withheld by Anthropic model policy.

Type BetaManagedAgentsRedactedBlockType
type BetaManagedAgentsRetryStatusExhausted struct{…}

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

Type BetaManagedAgentsRetryStatusExhaustedType
type BetaManagedAgentsRetryStatusRetrying struct{…}

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 BetaManagedAgentsRetryStatusRetryingType
type BetaManagedAgentsRetryStatusTerminal struct{…}

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

Type BetaManagedAgentsRetryStatusTerminalType
type BetaManagedAgentsSearchResultBlock struct{…}

A block containing a web search result.

Citations BetaManagedAgentsSearchResultCitations

Citation settings for a search result.

Enabled bool

Whether citations are enabled for this search result.

Content []BetaManagedAgentsSearchResultContent

Array of text content blocks from the search result.

Text string

The text content.

minLength1
Type BetaManagedAgentsSearchResultContentType
Source string

The URL source of the search result.

minLength1
Title string

The title of the search result.

minLength1
Type BetaManagedAgentsSearchResultBlockType
type BetaManagedAgentsSearchResultCitations struct{…}

Citation settings for a search result.

Enabled bool

Whether citations are enabled for this search result.

type BetaManagedAgentsSearchResultContent struct{…}

Text content within a search result.

Text string

The text content.

minLength1
Type BetaManagedAgentsSearchResultContentType
type BetaManagedAgentsSendSessionEvents struct{…}

Events that were successfully sent to the session.

type BetaManagedAgentsSessionBudgetReached struct{…}

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 BetaManagedAgentsSessionBudgetReachedType
type BetaManagedAgentsSessionDeletedEvent struct{…}

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

ID string

Unique identifier for this event.

ProcessedAt Time

A timestamp in RFC 3339 format

formatdate-time
Type BetaManagedAgentsSessionDeletedEventType
type BetaManagedAgentsSessionEndTurn struct{…}

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

Type BetaManagedAgentsSessionEndTurnType
type BetaManagedAgentsSessionErrorEvent struct{…}

An error event indicating a problem occurred during session execution.

type BetaManagedAgentsSessionEventUnion interface{…}

Union type for all event types in a session.

One of the following:
type BetaManagedAgentsSessionRequiresAction struct{…}

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.

EventIDs []string

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

Type BetaManagedAgentsSessionRequiresActionType
type BetaManagedAgentsSessionRetriesExhausted struct{…}

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

Type BetaManagedAgentsSessionRetriesExhaustedType
type BetaManagedAgentsSessionStatusIdleEvent struct{…}

Indicates the agent has paused and is awaiting user input.

ID string

Unique identifier for this event.

ProcessedAt Time

A timestamp in RFC 3339 format

formatdate-time
StopReason BetaManagedAgentsSessionStatusIdleEventStopReasonUnion

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

One of the following:
type BetaManagedAgentsSessionEndTurn struct{…}

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

Type BetaManagedAgentsSessionEndTurnType
type BetaManagedAgentsSessionRequiresAction struct{…}

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.

EventIDs []string

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

Type BetaManagedAgentsSessionRequiresActionType
type BetaManagedAgentsSessionRetriesExhausted struct{…}

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

Type BetaManagedAgentsSessionRetriesExhaustedType
type BetaManagedAgentsSessionBudgetReached struct{…}

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 BetaManagedAgentsSessionBudgetReachedType
Type BetaManagedAgentsSessionStatusIdleEventType
type BetaManagedAgentsSessionStatusRescheduledEvent struct{…}

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

ID string

Unique identifier for this event.

ProcessedAt Time

A timestamp in RFC 3339 format

formatdate-time
Type BetaManagedAgentsSessionStatusRescheduledEventType
type BetaManagedAgentsSessionStatusRunningEvent struct{…}

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

ID string

Unique identifier for this event.

ProcessedAt Time

A timestamp in RFC 3339 format

formatdate-time
Type BetaManagedAgentsSessionStatusRunningEventType
type BetaManagedAgentsSessionStatusTerminatedEvent struct{…}

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

ID string

Unique identifier for this event.

ProcessedAt Time

A timestamp in RFC 3339 format

formatdate-time
Type BetaManagedAgentsSessionStatusTerminatedEventType
type BetaManagedAgentsSessionThreadCreatedEvent struct{…}

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.

ID string

Unique identifier for this event.

AgentName string

Name of the callable agent the thread runs.

ProcessedAt Time

A timestamp in RFC 3339 format

formatdate-time
SessionThreadID string

Public sthr_ ID of the newly created thread.

Type BetaManagedAgentsSessionThreadCreatedEventType
type BetaManagedAgentsSessionThreadStatusIdleEvent struct{…}

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.

type BetaManagedAgentsSessionThreadStatusRescheduledEvent struct{…}

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.

ID string

Unique identifier for this event.

AgentName string

Name of the agent the thread runs.

ProcessedAt Time

A timestamp in RFC 3339 format

formatdate-time
SessionThreadID string

Public sthr_ ID of the thread that is retrying.

Type BetaManagedAgentsSessionThreadStatusRescheduledEventType
type BetaManagedAgentsSessionThreadStatusRunningEvent struct{…}

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

ID string

Unique identifier for this event.

AgentName string

Name of the agent the thread runs.

ProcessedAt Time

A timestamp in RFC 3339 format

formatdate-time
SessionThreadID string

Public sthr_ ID of the thread that started running.

Type BetaManagedAgentsSessionThreadStatusRunningEventType
type BetaManagedAgentsSessionThreadStatusTerminatedEvent struct{…}

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.

ID string

Unique identifier for this event.

AgentName string

Name of the agent the thread runs.

ProcessedAt Time

A timestamp in RFC 3339 format

formatdate-time
SessionThreadID string

Public sthr_ ID of the thread that terminated.

Type BetaManagedAgentsSessionThreadStatusTerminatedEventType
type BetaManagedAgentsSessionUsageSnapshot struct{…}

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

type BetaManagedAgentsSpanModelRequestEndEvent struct{…}

Emitted when a model request completes.

ID string

Unique identifier for this event.

IsError bool

Whether the model request resulted in an error.

ModelRequestStartID string

The id of the corresponding span.model_request_start event.

ModelUsage BetaManagedAgentsSpanModelUsage

Token usage for a single model request.

CacheCreationInputTokens int64

Tokens used to create prompt cache in this request.

formatint32
CacheReadInputTokens int64

Tokens read from prompt cache in this request.

formatint32
InputTokens int64

Input tokens consumed by this request.

formatint32
OutputTokens int64

Output tokens generated by this request.

formatint32
Speed BetaManagedAgentsSpanModelUsageSpeed Optional

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:
const BetaManagedAgentsSpanModelUsageSpeedStandard BetaManagedAgentsSpanModelUsageSpeed = "standard"
const BetaManagedAgentsSpanModelUsageSpeedFast BetaManagedAgentsSpanModelUsageSpeed = "fast"
ProcessedAt Time

A timestamp in RFC 3339 format

formatdate-time
Type BetaManagedAgentsSpanModelRequestEndEventType
type BetaManagedAgentsSpanModelRequestStartEvent struct{…}

Emitted when a model request is initiated by the agent.

ID string

Unique identifier for this event.

ProcessedAt Time

A timestamp in RFC 3339 format

formatdate-time
Type BetaManagedAgentsSpanModelRequestStartEventType
type BetaManagedAgentsSpanModelUsage struct{…}

Token usage for a single model request.

CacheCreationInputTokens int64

Tokens used to create prompt cache in this request.

formatint32
CacheReadInputTokens int64

Tokens read from prompt cache in this request.

formatint32
InputTokens int64

Input tokens consumed by this request.

formatint32
OutputTokens int64

Output tokens generated by this request.

formatint32
Speed BetaManagedAgentsSpanModelUsageSpeed Optional

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:
const BetaManagedAgentsSpanModelUsageSpeedStandard BetaManagedAgentsSpanModelUsageSpeed = "standard"
const BetaManagedAgentsSpanModelUsageSpeedFast BetaManagedAgentsSpanModelUsageSpeed = "fast"
type BetaManagedAgentsSpanOutcomeEvaluationEndEvent struct{…}

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.

type BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent struct{…}

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.

ID string

Unique identifier for this event.

Iteration int64

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

formatint32
OutcomeID string

The outc_ ID of the outcome being evaluated.

ProcessedAt Time

A timestamp in RFC 3339 format

formatdate-time
Type BetaManagedAgentsSpanOutcomeEvaluationOngoingEventType
type BetaManagedAgentsSpanOutcomeEvaluationStartEvent struct{…}

Emitted when an outcome evaluation cycle begins.

ID string

Unique identifier for this event.

Iteration int64

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

formatint32
OutcomeID string

The outc_ ID of the outcome being evaluated.

ProcessedAt Time

A timestamp in RFC 3339 format

formatdate-time
Type BetaManagedAgentsSpanOutcomeEvaluationStartEventType
type BetaManagedAgentsStreamSessionEventsUnion interface{…}

Server-sent event in the session stream.

One of the following:
type BetaManagedAgentsSystemMessageEventParamsResp struct{…}

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 []BetaManagedAgentsSystemContentBlock

System content blocks to append. Text-only.

Text string

The text content.

minLength1
Type BetaManagedAgentsSystemContentBlockType
Type BetaManagedAgentsSystemMessageEventParamsType
type BetaManagedAgentsTextBlock struct{…}

Regular text content.

Text string

The text content.

minLength1
Type BetaManagedAgentsTextBlockType
type BetaManagedAgentsTextRubric struct{…}

Rubric content provided inline as text.

Content string

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

Type BetaManagedAgentsTextRubricType
type BetaManagedAgentsTextRubricParams struct{…}

Rubric content provided inline as text.

Content string

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

maxLength262144
Type BetaManagedAgentsTextRubricParamsType
type BetaManagedAgentsUnknownError struct{…}

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.

Message string

Human-readable error description.

RetryStatus BetaManagedAgentsUnknownErrorRetryStatusUnion

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

One of the following:
type BetaManagedAgentsRetryStatusRetrying struct{…}

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 BetaManagedAgentsRetryStatusRetryingType
type BetaManagedAgentsRetryStatusExhausted struct{…}

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

Type BetaManagedAgentsRetryStatusExhaustedType
type BetaManagedAgentsRetryStatusTerminal struct{…}

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

Type BetaManagedAgentsRetryStatusTerminalType
Type BetaManagedAgentsUnknownErrorType
type BetaManagedAgentsURLDocumentSource struct{…}

Document referenced by URL.

Type BetaManagedAgentsURLDocumentSourceType
URL string

URL of the document to fetch.

minLength1
type BetaManagedAgentsURLImageSource struct{…}

Image referenced by URL.

Type BetaManagedAgentsURLImageSourceType
URL string

URL of the image to fetch.

minLength1
type BetaManagedAgentsUserCustomToolResultEvent struct{…}

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

type BetaManagedAgentsUserCustomToolResultEventParamsResp struct{…}

Parameters for providing the result of a custom tool execution.

type BetaManagedAgentsUserDefineOutcomeEvent struct{…}

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

ID string

Unique identifier for this event.

Description string

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

MaxIterations int64

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

formatint32
OutcomeID string

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

ProcessedAt Time

A timestamp in RFC 3339 format

formatdate-time
Rubric BetaManagedAgentsUserDefineOutcomeEventRubricUnion

Rubric for grading the quality of an outcome.

One of the following:
type BetaManagedAgentsFileRubric struct{…}

Rubric referenced by a file uploaded via the Files API.

FileID string

ID of the rubric file.

Type BetaManagedAgentsFileRubricType
type BetaManagedAgentsTextRubric struct{…}

Rubric content provided inline as text.

Content string

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

Type BetaManagedAgentsTextRubricType
Type BetaManagedAgentsUserDefineOutcomeEventType
type BetaManagedAgentsUserDefineOutcomeEventParams struct{…}

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

Description string

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

Rubric BetaManagedAgentsUserDefineOutcomeEventParamsRubricUnionResp

Rubric for grading the quality of an outcome.

One of the following:
type BetaManagedAgentsFileRubricParams struct{…}

Rubric referenced by a file uploaded via the Files API.

FileID string

ID of the rubric file.

Type BetaManagedAgentsFileRubricParamsType
type BetaManagedAgentsTextRubricParams struct{…}

Rubric content provided inline as text.

Content string

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

maxLength262144
Type BetaManagedAgentsTextRubricParamsType
Type BetaManagedAgentsUserDefineOutcomeEventParamsType
MaxIterations int64 Optional

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

formatint32
type BetaManagedAgentsUserInterruptEvent struct{…}

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

ID string

Unique identifier for this event.

Type BetaManagedAgentsUserInterruptEventType
ProcessedAt Time Optional

A timestamp in RFC 3339 format

formatdate-time
SessionThreadID string Optional

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.

type BetaManagedAgentsUserInterruptEventParamsResp struct{…}

Parameters for sending an interrupt to pause the agent.

Type BetaManagedAgentsUserInterruptEventParamsType
SessionThreadID string Optional

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.

type BetaManagedAgentsUserMessageEvent struct{…}

A user message event in the session conversation.

type BetaManagedAgentsUserMessageEventParams struct{…}

Parameters for sending a user message to the session.

type BetaManagedAgentsUserToolConfirmationEvent struct{…}

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

ID string

Unique identifier for this event.

Result BetaManagedAgentsUserToolConfirmationEventResult

UserToolConfirmationResult enum

One of the following:
const BetaManagedAgentsUserToolConfirmationEventResultAllow BetaManagedAgentsUserToolConfirmationEventResult = "allow"
const BetaManagedAgentsUserToolConfirmationEventResultDeny BetaManagedAgentsUserToolConfirmationEventResult = "deny"
ToolUseID string

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 BetaManagedAgentsUserToolConfirmationEventType
DenyMessage string Optional

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

maxLength10000
ProcessedAt Time Optional

A timestamp in RFC 3339 format

formatdate-time
SessionThreadID string Optional

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.

type BetaManagedAgentsUserToolConfirmationEventParamsResp struct{…}

Parameters for confirming or denying a tool execution request.

Result BetaManagedAgentsUserToolConfirmationEventParamsResult

UserToolConfirmationResult enum

One of the following:
const BetaManagedAgentsUserToolConfirmationEventParamsResultAllow BetaManagedAgentsUserToolConfirmationEventParamsResult = "allow"
const BetaManagedAgentsUserToolConfirmationEventParamsResultDeny BetaManagedAgentsUserToolConfirmationEventParamsResult = "deny"
ToolUseID string

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 BetaManagedAgentsUserToolConfirmationEventParamsType
DenyMessage string Optional

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

maxLength10000
type BetaManagedAgentsUserToolResultEventParamsResp struct{…}

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.