> ## Documentation Index > Fetch the complete documentation index at: https://oma-codex-339-workspace-permissions.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # List Events > List Events through the OMA API. Every request requires `?beta=true`. ## OpenAPI ````yaml /openapi/oma.en.json get /v1/sessions/{session_id}/events openapi: 3.1.0 info: title: OMA API Reference version: 1.0.0 description: Open Managed Agents application API reference. servers: - url: http://localhost:38080 description: Local OMA server security: - omaApiKey: [] - omaBearer: [] paths: /v1/sessions/{session_id}/events: get: summary: List Events operationId: BetaListEvents parameters: - name: beta in: query required: true description: Selects the beta API contract for this endpoint. Must be `true`. schema: type: boolean enum: - true - name: anthropic-version in: header required: false schema: type: string - name: anthropic-beta in: header required: false schema: type: string items: type: string x-stainless-override-schema: x-stainless-param: betas x-stainless-extend-default: true type: array description: Optional header to specify the beta version(s) you want to use. items: $ref: '#/components/schemas/AnthropicBeta' x-default: managed-agents-2026-04-01 - name: session_id in: path required: true schema: type: string description: Path parameter session_id example: sesn_011CZkZAtmR3yMPDzynEDxu7 - name: limit in: query required: false schema: type: integer format: int32 description: Query parameter for limit - name: page in: query required: false schema: type: string description: Opaque pagination cursor from a previous response's next_page. - name: order in: query required: false schema: $ref: '#/components/schemas/BetaManagedAgentsListOrder' description: >- Sort direction for results, ordered by the event's `processed_at`. Defaults to asc (chronological). - name: types[] in: query required: false style: form explode: true schema: items: type: string type: array description: >- Filter by event type. Values match the `type` field on returned events (for example, `user.message` or `agent.tool_use`). Omit to return all event types. - name: created_at[gte] in: query required: false schema: $ref: '#/components/schemas/BetaTimestamp' description: >- Return events created at or after this time (inclusive). Compared against the event's `processed_at` value. - name: created_at[gt] in: query required: false schema: $ref: '#/components/schemas/BetaTimestamp' description: >- Return events created after this time (exclusive). Compared against the event's `processed_at` value. - name: created_at[lte] in: query required: false schema: $ref: '#/components/schemas/BetaTimestamp' description: >- Return events created at or before this time (inclusive). Compared against the event's `processed_at` value. - name: created_at[lt] in: query required: false schema: $ref: '#/components/schemas/BetaTimestamp' description: >- Return events created before this time (exclusive). Compared against the event's `processed_at` value. responses: '200': description: Successful response (OK) content: application/json: schema: $ref: '#/components/schemas/BetaManagedAgentsListSessionEvents' '400': description: Invalid argument - The client specified an invalid argument content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '401': description: >- Unauthenticated - The request does not have valid authentication credentials content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '403': description: >- Permission denied - The caller does not have permission to execute the specified operation content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '404': description: Not found - Some requested entity was not found content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '408': description: >- Deadline exceeded - The deadline expired before the operation could complete content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '409': description: Aborted - The operation was aborted due to concurrency issue content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '412': description: >- Failed precondition - Operation was rejected because the system is not in required state content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '413': description: Out of range - Operation was attempted past the valid range content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '429': description: >- Resource exhausted - Some resource has been exhausted (rate limiting) content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '431': description: Request header fields too large - Request metadata was too large content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '499': description: Cancelled - The operation was cancelled by the client content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '500': description: Internal - Internal server error content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '501': description: Unimplemented - The operation is not implemented or supported content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '503': description: Unavailable - The service is currently unavailable content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' '504': description: Deadline exceeded - Upstream service did not respond in time content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' components: schemas: BetaManagedAgentsListOrder: type: string description: ListOrder enum enum: - asc - desc BetaTimestamp: description: A timestamp in RFC 3339 format type: string format: date-time BetaManagedAgentsListSessionEvents: description: Paginated list of events for a `session`. type: object additionalProperties: false properties: data: description: Events for the session, ordered by `processed_at`. x-stainless-pagination-property: purpose: items type: array items: $ref: '#/components/schemas/BetaManagedAgentsSessionEvent' examples: - - type: user.message id: sevt_011CZkZGOp0iBcp4kaQSihUmy content: - type: text text: 'Where is my order #1234?' processed_at: '2026-03-15T10:00:00Z' - type: agent.message id: sevt_011CZkZHPq1jCdq5lbRTjiVnz content: - type: text text: 'Let me look up order #1234 for you.' processed_at: '2026-03-15T10:00:00Z' next_page: description: Opaque cursor for the next page. Null when no more results. x-stainless-pagination-property: purpose: next_cursor_field type: string nullable: true examples: - page_MjAyNS0wNS0xNFQwMDowMDowMFo= example: data: - type: user.message id: sevt_011CZkZGOp0iBcp4kaQSihUmy content: - type: text text: 'Where is my order #1234?' processed_at: '2026-03-15T10:00:00Z' - type: agent.message id: sevt_011CZkZHPq1jCdq5lbRTjiVnz content: - type: text text: 'Let me look up order #1234 for you.' processed_at: '2026-03-15T10:00:00Z' next_page: page_MjAyNS0wNS0xNFQwMDowMDowMFo= BetaErrorResponse: properties: error: discriminator: mapping: api_error: $ref: '#/components/schemas/BetaAPIError' authentication_error: $ref: '#/components/schemas/BetaAuthenticationError' billing_error: $ref: '#/components/schemas/BetaBillingError' invalid_request_error: $ref: '#/components/schemas/BetaInvalidRequestError' not_found_error: $ref: '#/components/schemas/BetaNotFoundError' overloaded_error: $ref: '#/components/schemas/BetaOverloadedError' permission_error: $ref: '#/components/schemas/BetaPermissionError' rate_limit_error: $ref: '#/components/schemas/BetaRateLimitError' timeout_error: $ref: '#/components/schemas/BetaGatewayTimeoutError' propertyName: type oneOf: - $ref: '#/components/schemas/BetaInvalidRequestError' - $ref: '#/components/schemas/BetaAuthenticationError' - $ref: '#/components/schemas/BetaBillingError' - $ref: '#/components/schemas/BetaPermissionError' - $ref: '#/components/schemas/BetaNotFoundError' - $ref: '#/components/schemas/BetaRateLimitError' - $ref: '#/components/schemas/BetaGatewayTimeoutError' - $ref: '#/components/schemas/BetaAPIError' - $ref: '#/components/schemas/BetaOverloadedError' title: Error request_id: anyOf: - type: string - type: 'null' default: null title: Request Id type: const: error default: error title: Type type: string required: - error - request_id - type title: ErrorResponse type: object BetaManagedAgentsSessionEvent: description: Union type for all event types in a session. type: object discriminator: propertyName: type mapping: user.message: $ref: '#/components/schemas/BetaManagedAgentsUserMessageEvent' user.interrupt: $ref: '#/components/schemas/BetaManagedAgentsUserInterruptEvent' user.tool_confirmation: $ref: '#/components/schemas/BetaManagedAgentsUserToolConfirmationEvent' user.custom_tool_result: $ref: '#/components/schemas/BetaManagedAgentsUserCustomToolResultEvent' agent.custom_tool_use: $ref: '#/components/schemas/BetaManagedAgentsAgentCustomToolUseEvent' agent.message: $ref: '#/components/schemas/BetaManagedAgentsAgentMessageEvent' agent.thinking: $ref: '#/components/schemas/BetaManagedAgentsAgentThinkingEvent' agent.mcp_tool_use: $ref: '#/components/schemas/BetaManagedAgentsAgentMcpToolUseEvent' agent.mcp_tool_result: $ref: '#/components/schemas/BetaManagedAgentsAgentMcpToolResultEvent' agent.tool_use: $ref: '#/components/schemas/BetaManagedAgentsAgentToolUseEvent' agent.tool_result: $ref: '#/components/schemas/BetaManagedAgentsAgentToolResultEvent' agent.thread_message_received: $ref: >- #/components/schemas/BetaManagedAgentsAgentThreadMessageReceivedEvent agent.thread_message_sent: $ref: '#/components/schemas/BetaManagedAgentsAgentThreadMessageSentEvent' agent.thread_context_compacted: $ref: >- #/components/schemas/BetaManagedAgentsAgentThreadContextCompactedEvent session.error: $ref: '#/components/schemas/BetaManagedAgentsSessionErrorEvent' session.status_rescheduled: $ref: >- #/components/schemas/BetaManagedAgentsSessionStatusRescheduledEvent session.status_running: $ref: '#/components/schemas/BetaManagedAgentsSessionStatusRunningEvent' session.status_idle: $ref: '#/components/schemas/BetaManagedAgentsSessionStatusIdleEvent' session.status_terminated: $ref: '#/components/schemas/BetaManagedAgentsSessionStatusTerminatedEvent' session.thread_created: $ref: '#/components/schemas/BetaManagedAgentsSessionThreadCreatedEvent' span.outcome_evaluation_start: $ref: >- #/components/schemas/BetaManagedAgentsSpanOutcomeEvaluationStartEvent span.outcome_evaluation_end: $ref: >- #/components/schemas/BetaManagedAgentsSpanOutcomeEvaluationEndEvent span.model_request_start: $ref: '#/components/schemas/BetaManagedAgentsSpanModelRequestStartEvent' span.model_request_end: $ref: '#/components/schemas/BetaManagedAgentsSpanModelRequestEndEvent' span.outcome_evaluation_ongoing: $ref: >- #/components/schemas/BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent user.define_outcome: $ref: '#/components/schemas/BetaManagedAgentsUserDefineOutcomeEvent' session.deleted: $ref: '#/components/schemas/BetaManagedAgentsSessionDeletedEvent' session.thread_status_running: $ref: >- #/components/schemas/BetaManagedAgentsSessionThreadStatusRunningEvent session.thread_status_idle: $ref: '#/components/schemas/BetaManagedAgentsSessionThreadStatusIdleEvent' session.thread_status_terminated: $ref: >- #/components/schemas/BetaManagedAgentsSessionThreadStatusTerminatedEvent user.tool_result: $ref: '#/components/schemas/BetaManagedAgentsUserToolResultEvent' session.thread_status_rescheduled: $ref: >- #/components/schemas/BetaManagedAgentsSessionThreadStatusRescheduledEvent session.updated: $ref: '#/components/schemas/BetaManagedAgentsSessionUpdatedEvent' system.message: $ref: '#/components/schemas/BetaManagedAgentsSystemMessageEvent' session.usage: $ref: '#/components/schemas/BetaManagedAgentsSessionUsageEvent' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsUserMessageEvent' - $ref: '#/components/schemas/BetaManagedAgentsUserInterruptEvent' - $ref: '#/components/schemas/BetaManagedAgentsUserToolConfirmationEvent' - $ref: '#/components/schemas/BetaManagedAgentsUserCustomToolResultEvent' - $ref: '#/components/schemas/BetaManagedAgentsAgentCustomToolUseEvent' - $ref: '#/components/schemas/BetaManagedAgentsAgentMessageEvent' - $ref: '#/components/schemas/BetaManagedAgentsAgentThinkingEvent' - $ref: '#/components/schemas/BetaManagedAgentsAgentMcpToolUseEvent' - $ref: '#/components/schemas/BetaManagedAgentsAgentMcpToolResultEvent' - $ref: '#/components/schemas/BetaManagedAgentsAgentToolUseEvent' - $ref: '#/components/schemas/BetaManagedAgentsAgentToolResultEvent' - $ref: >- #/components/schemas/BetaManagedAgentsAgentThreadMessageReceivedEvent - $ref: '#/components/schemas/BetaManagedAgentsAgentThreadMessageSentEvent' - $ref: >- #/components/schemas/BetaManagedAgentsAgentThreadContextCompactedEvent - $ref: '#/components/schemas/BetaManagedAgentsSessionErrorEvent' - $ref: '#/components/schemas/BetaManagedAgentsSessionStatusRescheduledEvent' - $ref: '#/components/schemas/BetaManagedAgentsSessionStatusRunningEvent' - $ref: '#/components/schemas/BetaManagedAgentsSessionStatusIdleEvent' - $ref: '#/components/schemas/BetaManagedAgentsSessionStatusTerminatedEvent' - $ref: '#/components/schemas/BetaManagedAgentsSessionThreadCreatedEvent' - $ref: >- #/components/schemas/BetaManagedAgentsSpanOutcomeEvaluationStartEvent - $ref: '#/components/schemas/BetaManagedAgentsSpanOutcomeEvaluationEndEvent' - $ref: '#/components/schemas/BetaManagedAgentsSpanModelRequestStartEvent' - $ref: '#/components/schemas/BetaManagedAgentsSpanModelRequestEndEvent' - $ref: >- #/components/schemas/BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent - $ref: '#/components/schemas/BetaManagedAgentsUserDefineOutcomeEvent' - $ref: '#/components/schemas/BetaManagedAgentsSessionDeletedEvent' - $ref: >- #/components/schemas/BetaManagedAgentsSessionThreadStatusRunningEvent - $ref: '#/components/schemas/BetaManagedAgentsSessionThreadStatusIdleEvent' - $ref: >- #/components/schemas/BetaManagedAgentsSessionThreadStatusTerminatedEvent - $ref: '#/components/schemas/BetaManagedAgentsUserToolResultEvent' - $ref: >- #/components/schemas/BetaManagedAgentsSessionThreadStatusRescheduledEvent - $ref: '#/components/schemas/BetaManagedAgentsSessionUpdatedEvent' - $ref: '#/components/schemas/BetaManagedAgentsSystemMessageEvent' - $ref: '#/components/schemas/BetaManagedAgentsSessionUsageEvent' BetaAPIError: properties: message: default: Internal server error title: Message type: string type: const: api_error default: api_error title: Type type: string required: - message - type title: APIError type: object BetaAuthenticationError: properties: message: default: Authentication error title: Message type: string type: const: authentication_error default: authentication_error title: Type type: string required: - message - type title: AuthenticationError type: object BetaBillingError: properties: message: default: Billing error title: Message type: string type: const: billing_error default: billing_error title: Type type: string required: - message - type title: BillingError type: object BetaInvalidRequestError: properties: message: default: Invalid request title: Message type: string type: const: invalid_request_error default: invalid_request_error title: Type type: string required: - message - type title: InvalidRequestError type: object BetaNotFoundError: properties: message: default: Not found title: Message type: string type: const: not_found_error default: not_found_error title: Type type: string required: - message - type title: NotFoundError type: object BetaOverloadedError: properties: message: default: Overloaded title: Message type: string type: const: overloaded_error default: overloaded_error title: Type type: string required: - message - type title: OverloadedError type: object BetaPermissionError: properties: message: default: Permission denied title: Message type: string type: const: permission_error default: permission_error title: Type type: string required: - message - type title: PermissionError type: object BetaRateLimitError: properties: message: default: Rate limited title: Message type: string type: const: rate_limit_error default: rate_limit_error title: Type type: string required: - message - type title: RateLimitError type: object BetaGatewayTimeoutError: properties: message: default: Request timeout title: Message type: string type: const: timeout_error default: timeout_error title: Type type: string required: - message - type title: GatewayTimeoutError type: object BetaManagedAgentsUserMessageEvent: description: A user message event in the session conversation. type: object additionalProperties: false required: - type - id - content properties: type: type: string enum: - user.message examples: - user.message id: description: Unique identifier for this event. type: string examples: - sevt_011CZkZGOp0iBcp4kaQSihUmy content: description: Array of content blocks comprising the user message. type: array items: $ref: '#/components/schemas/BetaManagedAgentsUserContentBlock' examples: - - type: text text: 'Where is my order #1234?' processed_at: description: Timestamp when the agent finished processing this message. allOf: - $ref: '#/components/schemas/BetaTimestamp' nullable: true examples: - '2026-03-15T10:00:00Z' example: type: user.message id: sevt_011CZkZGOp0iBcp4kaQSihUmy content: - type: text text: 'Where is my order #1234?' processed_at: '2026-03-15T10:00:00Z' BetaManagedAgentsUserInterruptEvent: description: >- An interrupt event that pauses agent execution and returns control to the user. type: object additionalProperties: false required: - type - id properties: type: type: string enum: - user.interrupt id: description: Unique identifier for this event. type: string processed_at: description: Timestamp when the interrupt was processed. allOf: - $ref: '#/components/schemas/BetaTimestamp' nullable: true session_thread_id: description: >- 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: string nullable: true BetaManagedAgentsUserToolConfirmationEvent: description: >- A tool confirmation event that approves or denies a pending tool execution. type: object additionalProperties: false required: - type - id - tool_use_id - result properties: type: type: string enum: - user.tool_confirmation id: description: Unique identifier for this event. type: string tool_use_id: description: >- 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: string result: description: 'The confirmation result: ''allow'' or ''deny''.' allOf: - $ref: '#/components/schemas/BetaManagedAgentsUserToolConfirmationResult' deny_message: description: >- Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. type: string maxLength: 10000 nullable: true processed_at: description: Timestamp when the confirmation was processed. allOf: - $ref: '#/components/schemas/BetaTimestamp' nullable: true session_thread_id: description: >- 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: string nullable: true BetaManagedAgentsUserCustomToolResultEvent: description: >- Event sent by the client providing the result of a custom tool execution. type: object additionalProperties: false required: - type - id - custom_tool_use_id properties: type: type: string enum: - user.custom_tool_result id: description: Unique identifier for this event. type: string custom_tool_use_id: description: >- The id of the `agent.custom_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: string content: description: The result content returned by the tool. type: array items: $ref: '#/components/schemas/BetaManagedAgentsToolResultContentBlock' is_error: description: Whether the tool execution resulted in an error. type: boolean nullable: true processed_at: description: Timestamp when this result was processed. allOf: - $ref: '#/components/schemas/BetaTimestamp' nullable: true session_thread_id: description: >- Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`. type: string nullable: true BetaManagedAgentsAgentCustomToolUseEvent: description: >- 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. type: object additionalProperties: false required: - type - id - name - input - processed_at properties: type: type: string enum: - agent.custom_tool_use id: description: Unique identifier for this event. type: string name: description: Name of the custom tool being called. type: string input: description: Input parameters for the tool call. allOf: - $ref: '#/components/schemas/BetaManagedAgentsStruct' processed_at: description: Timestamp when this tool use was processed. allOf: - $ref: '#/components/schemas/BetaTimestamp' session_thread_id: description: >- 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: string nullable: true BetaManagedAgentsAgentMessageEvent: description: An agent response event in the session conversation. type: object additionalProperties: false required: - type - id - content - processed_at properties: type: type: string enum: - agent.message examples: - agent.message id: description: Unique identifier for this event. type: string examples: - sevt_011CZkZHPq1jCdq5lbRTjiVnz content: description: Array of text blocks comprising the agent response. type: array items: $ref: '#/components/schemas/BetaManagedAgentsAgentMessageContentBlock' examples: - - type: text text: 'Let me look up order #1234 for you.' processed_at: description: Timestamp when this response was generated. allOf: - $ref: '#/components/schemas/BetaTimestamp' examples: - '2026-03-15T10:00:00Z' example: type: agent.message id: sevt_011CZkZHPq1jCdq5lbRTjiVnz content: - type: text text: 'Let me look up order #1234 for you.' processed_at: '2026-03-15T10:00:00Z' BetaManagedAgentsAgentThinkingEvent: description: >- Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. type: object additionalProperties: false required: - type - id - processed_at properties: type: type: string enum: - agent.thinking id: description: Unique identifier for this event. type: string processed_at: description: Timestamp when this thinking was produced. allOf: - $ref: '#/components/schemas/BetaTimestamp' BetaManagedAgentsAgentMcpToolUseEvent: description: Event emitted when the agent invokes a tool provided by an MCP server. type: object additionalProperties: false required: - type - id - name - mcp_server_name - input - processed_at properties: type: type: string enum: - agent.mcp_tool_use id: description: Unique identifier for this event. type: string name: description: Name of the MCP tool being used. type: string mcp_server_name: description: Name of the MCP server providing the tool. type: string input: description: Input parameters for the tool call. allOf: - $ref: '#/components/schemas/BetaManagedAgentsStruct' processed_at: description: Timestamp when this event was processed. allOf: - $ref: '#/components/schemas/BetaTimestamp' evaluated_permission: description: The evaluated permission policy for this tool invocation. allOf: - $ref: '#/components/schemas/BetaManagedAgentsAgentEvaluatedPermission' session_thread_id: description: >- 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: string nullable: true BetaManagedAgentsAgentMcpToolResultEvent: description: Event representing the result of an MCP tool execution. type: object additionalProperties: false required: - type - id - mcp_tool_use_id - processed_at properties: type: type: string enum: - agent.mcp_tool_result id: description: Unique identifier for this event. type: string mcp_tool_use_id: description: The id of the `agent.mcp_tool_use` event this result corresponds to. type: string content: description: The result content returned by the tool. type: array items: $ref: '#/components/schemas/BetaManagedAgentsToolResultContentBlock' is_error: description: Whether the tool execution resulted in an error. type: boolean nullable: true processed_at: description: Timestamp when this event was processed. allOf: - $ref: '#/components/schemas/BetaTimestamp' BetaManagedAgentsAgentToolUseEvent: description: Event emitted when the agent invokes a built-in agent tool. type: object additionalProperties: false required: - type - id - name - input - processed_at properties: type: type: string enum: - agent.tool_use id: description: Unique identifier for this event. type: string name: description: Name of the agent tool being used. type: string input: description: Input parameters for the tool call. allOf: - $ref: '#/components/schemas/BetaManagedAgentsStruct' processed_at: description: Timestamp when this event was processed. allOf: - $ref: '#/components/schemas/BetaTimestamp' evaluated_permission: description: The evaluated permission policy for this tool invocation. allOf: - $ref: '#/components/schemas/BetaManagedAgentsAgentEvaluatedPermission' session_thread_id: description: >- 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: string nullable: true BetaManagedAgentsAgentToolResultEvent: description: Event representing the result of an agent tool execution. type: object additionalProperties: false required: - type - id - tool_use_id - processed_at properties: type: type: string enum: - agent.tool_result id: description: Unique identifier for this event. type: string tool_use_id: description: The id of the `agent.tool_use` event this result corresponds to. type: string content: description: The result content returned by the tool. type: array items: $ref: '#/components/schemas/BetaManagedAgentsToolResultContentBlock' is_error: description: Whether the tool execution resulted in an error. type: boolean nullable: true processed_at: description: Timestamp when this event was processed. allOf: - $ref: '#/components/schemas/BetaTimestamp' BetaManagedAgentsAgentThreadMessageReceivedEvent: description: >- Delivery event written to the target thread's input stream when an agent-to-agent message arrives. type: object additionalProperties: false required: - type - id - processed_at - content - from_session_thread_id properties: type: type: string enum: - agent.thread_message_received id: description: Unique identifier for this event. type: string processed_at: description: Timestamp when the message was received. allOf: - $ref: '#/components/schemas/BetaTimestamp' from_agent_name: description: >- Name of the callable agent this message came from. Absent when received from the primary agent. type: string nullable: true content: description: Message content blocks. type: array items: $ref: '#/components/schemas/BetaManagedAgentsUserContentBlock' from_session_thread_id: description: Public `sthr_` ID of the thread that sent the message. type: string BetaManagedAgentsAgentThreadMessageSentEvent: description: >- Observability event emitted to the sender's output stream when an agent-to-agent message is sent. type: object additionalProperties: false required: - type - id - processed_at - content - to_session_thread_id properties: type: type: string enum: - agent.thread_message_sent id: description: Unique identifier for this event. type: string processed_at: description: Timestamp when the message was sent. allOf: - $ref: '#/components/schemas/BetaTimestamp' to_agent_name: description: >- Name of the callable agent this message was sent to. Absent when sent to the primary agent. type: string nullable: true content: description: Message content blocks. type: array items: $ref: '#/components/schemas/BetaManagedAgentsUserContentBlock' to_session_thread_id: description: Public `sthr_` ID of the thread the message was sent to. type: string BetaManagedAgentsAgentThreadContextCompactedEvent: description: >- Indicates that context compaction (summarization) occurred during the session. type: object additionalProperties: false required: - type - id - processed_at properties: type: type: string enum: - agent.thread_context_compacted id: description: Unique identifier for this event. type: string processed_at: description: Timestamp when compaction was processed. allOf: - $ref: '#/components/schemas/BetaTimestamp' BetaManagedAgentsSessionErrorEvent: description: An error event indicating a problem occurred during session execution. type: object additionalProperties: false required: - type - id - processed_at - error properties: type: type: string enum: - session.error id: description: Unique identifier for this event. type: string processed_at: description: Timestamp when the error occurred. allOf: - $ref: '#/components/schemas/BetaTimestamp' error: type: object discriminator: propertyName: type mapping: unknown_error: $ref: '#/components/schemas/BetaManagedAgentsUnknownError' model_overloaded_error: $ref: '#/components/schemas/BetaManagedAgentsModelOverloadedError' model_rate_limited_error: $ref: '#/components/schemas/BetaManagedAgentsModelRateLimitedError' model_request_failed_error: $ref: '#/components/schemas/BetaManagedAgentsModelRequestFailedError' mcp_connection_failed_error: $ref: '#/components/schemas/BetaManagedAgentsMcpConnectionFailedError' mcp_authentication_failed_error: $ref: >- #/components/schemas/BetaManagedAgentsMcpAuthenticationFailedError billing_error: $ref: '#/components/schemas/BetaManagedAgentsBillingError' credential_host_unreachable_error: $ref: >- #/components/schemas/BetaManagedAgentsCredentialHostUnreachableError oneOf: - $ref: '#/components/schemas/BetaManagedAgentsUnknownError' - $ref: '#/components/schemas/BetaManagedAgentsModelOverloadedError' - $ref: '#/components/schemas/BetaManagedAgentsModelRateLimitedError' - $ref: '#/components/schemas/BetaManagedAgentsModelRequestFailedError' - $ref: '#/components/schemas/BetaManagedAgentsMcpConnectionFailedError' - $ref: >- #/components/schemas/BetaManagedAgentsMcpAuthenticationFailedError - $ref: '#/components/schemas/BetaManagedAgentsBillingError' - $ref: >- #/components/schemas/BetaManagedAgentsCredentialHostUnreachableError BetaManagedAgentsSessionStatusRescheduledEvent: description: >- Indicates the session is recovering from an error state and is rescheduled for execution. type: object additionalProperties: false required: - type - id - processed_at properties: type: type: string enum: - session.status_rescheduled id: description: Unique identifier for this event. type: string processed_at: description: Timestamp of status change. allOf: - $ref: '#/components/schemas/BetaTimestamp' BetaManagedAgentsSessionStatusRunningEvent: description: Indicates the session is actively running and the agent is working. type: object additionalProperties: false required: - type - id - processed_at properties: type: type: string enum: - session.status_running id: description: Unique identifier for this event. type: string processed_at: description: Timestamp of status change. allOf: - $ref: '#/components/schemas/BetaTimestamp' BetaManagedAgentsSessionStatusIdleEvent: description: Indicates the agent has paused and is awaiting user input. type: object additionalProperties: false required: - type - id - processed_at - stop_reason properties: type: type: string enum: - session.status_idle id: description: Unique identifier for this event. type: string processed_at: description: Timestamp of status change. allOf: - $ref: '#/components/schemas/BetaTimestamp' stop_reason: type: object discriminator: propertyName: type mapping: end_turn: $ref: '#/components/schemas/BetaManagedAgentsSessionEndTurn' requires_action: $ref: '#/components/schemas/BetaManagedAgentsSessionRequiresAction' retries_exhausted: $ref: '#/components/schemas/BetaManagedAgentsSessionRetriesExhausted' budget_reached: $ref: '#/components/schemas/BetaManagedAgentsSessionBudgetReached' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsSessionEndTurn' - $ref: '#/components/schemas/BetaManagedAgentsSessionRequiresAction' - $ref: '#/components/schemas/BetaManagedAgentsSessionRetriesExhausted' - $ref: '#/components/schemas/BetaManagedAgentsSessionBudgetReached' BetaManagedAgentsSessionStatusTerminatedEvent: description: >- Indicates the session has terminated, either due to an error or completion. type: object additionalProperties: false required: - type - id - processed_at properties: type: type: string enum: - session.status_terminated id: description: Unique identifier for this event. type: string processed_at: description: Timestamp of status change. allOf: - $ref: '#/components/schemas/BetaTimestamp' BetaManagedAgentsSessionThreadCreatedEvent: description: >- 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. type: object additionalProperties: false required: - type - id - processed_at - agent_name - session_thread_id properties: type: type: string enum: - session.thread_created examples: - session.thread_created id: description: Unique identifier for this event. type: string examples: - sevt_011CZkZWXb7pJkx1shYaqoCu processed_at: description: Timestamp when the thread was created. allOf: - $ref: '#/components/schemas/BetaTimestamp' examples: - '2026-03-15T10:00:00Z' agent_name: description: Name of the callable agent the thread runs. type: string examples: - Researcher session_thread_id: description: Public `sthr_` ID of the newly created thread. type: string examples: - sthr_011CZkZVWa6oIjw0rgXZpnBt example: type: session.thread_created id: sevt_011CZkZWXb7pJkx1shYaqoCu session_thread_id: sthr_011CZkZVWa6oIjw0rgXZpnBt processed_at: '2026-03-15T10:00:00Z' agent_name: Researcher BetaManagedAgentsSpanOutcomeEvaluationStartEvent: description: Emitted when an outcome evaluation cycle begins. type: object additionalProperties: false required: - type - id - processed_at - iteration - outcome_id properties: type: type: string enum: - span.outcome_evaluation_start examples: - span.outcome_evaluation_start id: description: Unique identifier for this event. type: string examples: - sevt_011CZkZTUy4mGhu8peVXnlzr processed_at: description: Timestamp when outcome evaluation started. allOf: - $ref: '#/components/schemas/BetaTimestamp' examples: - '2026-03-15T10:02:14Z' iteration: description: >- 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. type: integer format: int32 examples: - 0 outcome_id: description: The `outc_` ID of the outcome being evaluated. type: string examples: - outc_011CZkZRSw2kEfs6ncTVljxP example: type: span.outcome_evaluation_start id: sevt_011CZkZTUy4mGhu8peVXnlzr processed_at: '2026-03-15T10:02:14Z' iteration: 0 outcome_id: outc_011CZkZRSw2kEfs6ncTVljxP BetaManagedAgentsSpanOutcomeEvaluationEndEvent: description: >- 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: object additionalProperties: false required: - type - id - processed_at - outcome_evaluation_start_id - iteration - result - explanation - usage - outcome_id properties: type: type: string enum: - span.outcome_evaluation_end examples: - span.outcome_evaluation_end id: description: Unique identifier for this event. type: string examples: - sevt_011CZkZUVz5nHiv9qfWYomas processed_at: description: Timestamp when outcome evaluation ended. allOf: - $ref: '#/components/schemas/BetaTimestamp' examples: - '2026-03-15T10:02:31Z' outcome_evaluation_start_id: description: The id of the corresponding `span.outcome_evaluation_start` event. type: string examples: - sevt_011CZkZTUy4mGhu8peVXnlzr iteration: description: >- 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. type: integer format: int32 examples: - 0 result: description: >- Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress. type: string examples: - satisfied explanation: description: >- Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. type: string examples: - All five sections present with inline citations. usage: description: >- Aggregate token usage for this evaluation cycle. Sums across all grader model requests within the cycle. allOf: - $ref: '#/components/schemas/BetaManagedAgentsSpanModelUsage' examples: - input_tokens: 1842 output_tokens: 213 cache_creation_input_tokens: 0 cache_read_input_tokens: 1536 outcome_id: description: The `outc_` ID of the outcome being evaluated. type: string examples: - outc_011CZkZRSw2kEfs6ncTVljxP example: type: span.outcome_evaluation_end id: sevt_011CZkZUVz5nHiv9qfWYomas processed_at: '2026-03-15T10:02:31Z' outcome_evaluation_start_id: sevt_011CZkZTUy4mGhu8peVXnlzr iteration: 0 result: satisfied explanation: All five sections present with inline citations. usage: input_tokens: 1842 output_tokens: 213 cache_creation_input_tokens: 0 cache_read_input_tokens: 1536 outcome_id: outc_011CZkZRSw2kEfs6ncTVljxP BetaManagedAgentsSpanModelRequestStartEvent: description: Emitted when a model request is initiated by the agent. type: object additionalProperties: false required: - type - id - processed_at properties: type: type: string enum: - span.model_request_start id: description: Unique identifier for this event. type: string processed_at: description: Timestamp when the model request started. allOf: - $ref: '#/components/schemas/BetaTimestamp' BetaManagedAgentsSpanModelRequestEndEvent: description: Emitted when a model request completes. type: object additionalProperties: false required: - type - id - processed_at - is_error - model_usage - model_request_start_id properties: type: type: string enum: - span.model_request_end id: description: Unique identifier for this event. type: string processed_at: description: Timestamp when the model request completed. allOf: - $ref: '#/components/schemas/BetaTimestamp' is_error: description: Whether the model request resulted in an error. type: boolean nullable: true model_usage: description: Token usage for this model request. allOf: - $ref: '#/components/schemas/BetaManagedAgentsSpanModelUsage' model_request_start_id: description: The id of the corresponding `span.model_request_start` event. type: string BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent: description: >- 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: object additionalProperties: false required: - type - id - processed_at - iteration - outcome_id properties: type: type: string enum: - span.outcome_evaluation_ongoing examples: - span.outcome_evaluation_ongoing id: description: Unique identifier for this event. type: string examples: - sevt_011CZkZbCG2uOpc6xmDfvTzh processed_at: description: Timestamp when this heartbeat was emitted. allOf: - $ref: '#/components/schemas/BetaTimestamp' examples: - '2026-03-15T10:02:14Z' iteration: description: >- 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. type: integer format: int32 examples: - 0 outcome_id: description: The `outc_` ID of the outcome being evaluated. type: string examples: - outc_011CZkZRSw2kEfs6ncTVljxP example: type: span.outcome_evaluation_ongoing id: sevt_011CZkZbCG2uOpc6xmDfvTzh processed_at: '2026-03-15T10:02:14Z' iteration: 0 outcome_id: outc_011CZkZRSw2kEfs6ncTVljxP BetaManagedAgentsUserDefineOutcomeEvent: description: >- Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference. type: object additionalProperties: false required: - type - id - processed_at - outcome_id - description - max_iterations - rubric properties: type: type: string enum: - user.define_outcome examples: - user.define_outcome id: description: Unique identifier for this event. type: string examples: - sevt_011CZkZSTx3lFgt7odUWmkyq processed_at: description: Timestamp when the outcome was accepted. allOf: - $ref: '#/components/schemas/BetaTimestamp' examples: - '2026-03-15T10:02:14Z' outcome_id: description: >- Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. type: string examples: - outc_011CZkZRSw2kEfs6ncTVljxP description: description: What the agent should produce. Copied from the input event. type: string examples: - Produce a 2-page summary as summary.md max_iterations: description: Evaluate-then-revise cycles before giving up. Default 3, max 20. type: integer format: int32 nullable: true examples: - 3 rubric: description: >- How to grade the outcome. File rubrics are currently resolved to their text content; clients should handle both variants. allOf: - $ref: '#/components/schemas/BetaManagedAgentsRubric' examples: - type: text content: Must cover all five sections; cite sources inline. example: type: user.define_outcome id: sevt_011CZkZSTx3lFgt7odUWmkyq processed_at: '2026-03-15T10:02:14Z' outcome_id: outc_011CZkZRSw2kEfs6ncTVljxP description: Produce a 2-page summary as summary.md max_iterations: 3 rubric: type: text content: Must cover all five sections; cite sources inline. BetaManagedAgentsSessionDeletedEvent: description: >- Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. type: object additionalProperties: false required: - type - id - processed_at properties: type: type: string enum: - session.deleted id: description: Unique identifier for this event. type: string processed_at: description: Timestamp when the session was deleted. allOf: - $ref: '#/components/schemas/BetaTimestamp' BetaManagedAgentsSessionThreadStatusRunningEvent: description: >- A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. type: object additionalProperties: false required: - type - id - session_thread_id - processed_at - agent_name properties: type: type: string enum: - session.thread_status_running id: description: Unique identifier for this event. type: string session_thread_id: description: Public sthr_ ID of the thread that started running. type: string processed_at: description: Timestamp of the status transition. allOf: - $ref: '#/components/schemas/BetaTimestamp' agent_name: description: Name of the agent the thread runs. type: string BetaManagedAgentsSessionThreadStatusIdleEvent: description: >- 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: object additionalProperties: false required: - type - id - session_thread_id - processed_at - agent_name - stop_reason properties: type: type: string enum: - session.thread_status_idle examples: - session.thread_status_idle id: description: Unique identifier for this event. type: string examples: - sevt_011CZkZXYc8qKly2tiZbrpDv session_thread_id: description: Public sthr_ ID of the thread that went idle. type: string examples: - sthr_011CZkZVWa6oIjw0rgXZpnBt processed_at: description: Timestamp of the status transition. allOf: - $ref: '#/components/schemas/BetaTimestamp' examples: - '2026-03-15T10:00:00Z' agent_name: description: Name of the agent the thread runs. type: string examples: - Researcher stop_reason: type: object discriminator: propertyName: type mapping: end_turn: $ref: '#/components/schemas/BetaManagedAgentsSessionEndTurn' requires_action: $ref: '#/components/schemas/BetaManagedAgentsSessionRequiresAction' retries_exhausted: $ref: '#/components/schemas/BetaManagedAgentsSessionRetriesExhausted' budget_reached: $ref: '#/components/schemas/BetaManagedAgentsSessionBudgetReached' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsSessionEndTurn' - $ref: '#/components/schemas/BetaManagedAgentsSessionRequiresAction' - $ref: '#/components/schemas/BetaManagedAgentsSessionRetriesExhausted' - $ref: '#/components/schemas/BetaManagedAgentsSessionBudgetReached' examples: - type: end_turn example: type: session.thread_status_idle id: sevt_011CZkZXYc8qKly2tiZbrpDv session_thread_id: sthr_011CZkZVWa6oIjw0rgXZpnBt processed_at: '2026-03-15T10:00:00Z' agent_name: Researcher stop_reason: type: end_turn BetaManagedAgentsSessionThreadStatusTerminatedEvent: description: >- 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: object additionalProperties: false required: - type - id - session_thread_id - processed_at - agent_name properties: type: type: string enum: - session.thread_status_terminated id: description: Unique identifier for this event. type: string session_thread_id: description: Public sthr_ ID of the thread that terminated. type: string processed_at: description: Timestamp of the status transition. allOf: - $ref: '#/components/schemas/BetaTimestamp' agent_name: description: Name of the agent the thread runs. type: string BetaManagedAgentsUserToolResultEvent: description: >- Event sent by the client 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. type: object additionalProperties: false required: - type - id - tool_use_id properties: type: type: string enum: - user.tool_result id: description: Unique identifier for this event. type: string tool_use_id: description: >- The id of the `agent.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: string content: description: The result content returned by the tool. type: array items: $ref: '#/components/schemas/BetaManagedAgentsToolResultContentBlock' is_error: description: Whether the tool execution resulted in an error. type: boolean nullable: true processed_at: description: Timestamp when this result was processed. allOf: - $ref: '#/components/schemas/BetaTimestamp' nullable: true session_thread_id: description: >- Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`. type: string nullable: true BetaManagedAgentsSessionThreadStatusRescheduledEvent: description: >- 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: object additionalProperties: false required: - type - id - session_thread_id - processed_at - agent_name properties: type: type: string enum: - session.thread_status_rescheduled id: description: Unique identifier for this event. type: string session_thread_id: description: Public sthr_ ID of the thread that is retrying. type: string processed_at: description: Timestamp of the status transition. allOf: - $ref: '#/components/schemas/BetaTimestamp' agent_name: description: Name of the agent the thread runs. type: string BetaManagedAgentsSessionUpdatedEvent: description: >- Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn. type: object additionalProperties: false required: - type - id - processed_at properties: type: type: string enum: - session.updated id: description: Unique identifier for this event. type: string processed_at: description: Timestamp when the update was applied. allOf: - $ref: '#/components/schemas/BetaTimestamp' title: description: The session's new title. Present only when the update changed it. type: string nullable: true metadata: description: >- The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. type: object additionalProperties: type: string agent: description: >- The session's effective agent configuration after the update. Present only when the update changed `agent` (tools or mcp_servers); when present it is the full materialised snapshot, not a diff. allOf: - $ref: '#/components/schemas/BetaManagedAgentsSessionAgent' nullable: true budget: description: >- The session's budget after the update: the new budget when set or replaced, or null when the update removed it. Present only when the update changed the budget. allOf: - $ref: '#/components/schemas/BetaManagedAgentsBudget' nullable: true BetaManagedAgentsSystemMessageEvent: description: >- A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn. type: object additionalProperties: false required: - type - id - content properties: type: type: string enum: - system.message id: description: Unique identifier for this event. type: string content: description: System content blocks. Text-only. type: array items: $ref: '#/components/schemas/BetaManagedAgentsSystemContentBlock' processed_at: description: Timestamp when this system message was processed. allOf: - $ref: '#/components/schemas/BetaTimestamp' nullable: true BetaManagedAgentsSessionUsageEvent: description: >- Periodic snapshot of the session's cumulative usage and tracked list cost. type: object additionalProperties: false required: - type - id - processed_at - usage properties: type: type: string enum: - session.usage id: description: Unique identifier for this event. type: string processed_at: description: Timestamp when the snapshot was taken. allOf: - $ref: '#/components/schemas/BetaTimestamp' usage: description: The session's cumulative usage at the snapshot time. allOf: - $ref: '#/components/schemas/BetaManagedAgentsSessionUsageSnapshot' budget: description: >- The session's configured budget at the snapshot time, or null when the session has no budget. allOf: - $ref: '#/components/schemas/BetaManagedAgentsBudget' nullable: true BetaManagedAgentsUserContentBlock: description: Content block in a user message. Can be `text`, `image`, or `document`. type: object discriminator: propertyName: type mapping: text: $ref: '#/components/schemas/BetaManagedAgentsTextBlock' image: $ref: '#/components/schemas/BetaManagedAgentsImageBlock' document: $ref: '#/components/schemas/BetaManagedAgentsDocumentBlock' redacted: $ref: '#/components/schemas/BetaManagedAgentsRedactedBlock' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsTextBlock' - $ref: '#/components/schemas/BetaManagedAgentsImageBlock' - $ref: '#/components/schemas/BetaManagedAgentsDocumentBlock' - $ref: '#/components/schemas/BetaManagedAgentsRedactedBlock' BetaManagedAgentsUserToolConfirmationResult: type: string description: UserToolConfirmationResult enum enum: - allow - deny BetaManagedAgentsToolResultContentBlock: description: >- Content block in a tool result. Can be `text`, `image`, `document`, or `search_result`. type: object discriminator: propertyName: type mapping: text: $ref: '#/components/schemas/BetaManagedAgentsTextBlock' image: $ref: '#/components/schemas/BetaManagedAgentsImageBlock' document: $ref: '#/components/schemas/BetaManagedAgentsDocumentBlock' search_result: $ref: '#/components/schemas/BetaManagedAgentsSearchResultBlock' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsTextBlock' - $ref: '#/components/schemas/BetaManagedAgentsImageBlock' - $ref: '#/components/schemas/BetaManagedAgentsDocumentBlock' - $ref: '#/components/schemas/BetaManagedAgentsSearchResultBlock' BetaManagedAgentsStruct: type: object additionalProperties: true BetaManagedAgentsAgentMessageContentBlock: description: Content block in an agent message. type: object discriminator: propertyName: type mapping: text: $ref: '#/components/schemas/BetaManagedAgentsTextBlock' redacted: $ref: '#/components/schemas/BetaManagedAgentsRedactedBlock' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsTextBlock' - $ref: '#/components/schemas/BetaManagedAgentsRedactedBlock' BetaManagedAgentsAgentEvaluatedPermission: type: string description: AgentEvaluatedPermission enum enum: - allow - ask - deny BetaManagedAgentsUnknownError: description: >- 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: object additionalProperties: false required: - type - message - retry_status properties: type: type: string enum: - unknown_error message: description: Human-readable error description. type: string retry_status: description: What the client should do next. allOf: - $ref: '#/components/schemas/BetaManagedAgentsRetryStatus' BetaManagedAgentsModelOverloadedError: description: >- The model is currently overloaded. Emitted after automatic retries are exhausted. type: object additionalProperties: false required: - type - message - retry_status properties: type: type: string enum: - model_overloaded_error message: description: Human-readable error description. type: string retry_status: description: What the client should do next. allOf: - $ref: '#/components/schemas/BetaManagedAgentsRetryStatus' BetaManagedAgentsModelRateLimitedError: description: The model request was rate-limited. type: object additionalProperties: false required: - type - message - retry_status properties: type: type: string enum: - model_rate_limited_error message: description: Human-readable error description. type: string retry_status: description: What the client should do next. allOf: - $ref: '#/components/schemas/BetaManagedAgentsRetryStatus' BetaManagedAgentsModelRequestFailedError: description: >- A model request failed for a reason other than overload or rate-limiting. type: object additionalProperties: false required: - type - message - retry_status properties: type: type: string enum: - model_request_failed_error message: description: Human-readable error description. type: string retry_status: description: What the client should do next. allOf: - $ref: '#/components/schemas/BetaManagedAgentsRetryStatus' BetaManagedAgentsMcpConnectionFailedError: description: Failed to connect to an MCP server. type: object additionalProperties: false required: - type - message - retry_status - mcp_server_name properties: type: type: string enum: - mcp_connection_failed_error message: description: Human-readable error description. type: string retry_status: description: What the client should do next. allOf: - $ref: '#/components/schemas/BetaManagedAgentsRetryStatus' mcp_server_name: description: Name of the MCP server that failed to connect. type: string BetaManagedAgentsMcpAuthenticationFailedError: description: Authentication to an MCP server failed. type: object additionalProperties: false required: - type - message - retry_status - mcp_server_name properties: type: type: string enum: - mcp_authentication_failed_error message: description: Human-readable error description. type: string retry_status: description: What the client should do next. allOf: - $ref: '#/components/schemas/BetaManagedAgentsRetryStatus' mcp_server_name: description: Name of the MCP server that failed authentication. type: string BetaManagedAgentsBillingError: description: >- 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: object additionalProperties: false required: - type - message - retry_status properties: type: type: string enum: - billing_error message: description: Human-readable error description. type: string retry_status: description: What the client should do next. allOf: - $ref: '#/components/schemas/BetaManagedAgentsRetryStatus' BetaManagedAgentsCredentialHostUnreachableError: description: >- An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit. type: object additionalProperties: false required: - type - message - retry_status - vault_id - credential_id properties: type: type: string enum: - credential_host_unreachable_error message: description: Human-readable error description. type: string retry_status: description: What the client should do next. allOf: - $ref: '#/components/schemas/BetaManagedAgentsRetryStatus' vault_id: description: ID of the vault containing the affected credential. type: string credential_id: description: ID of the affected credential. type: string BetaManagedAgentsSessionEndTurn: description: >- The agent completed its turn naturally and is ready for the next user message. type: object additionalProperties: false required: - type properties: type: type: string enum: - end_turn BetaManagedAgentsSessionRequiresAction: description: >- 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: object additionalProperties: false required: - type - event_ids properties: type: type: string enum: - requires_action event_ids: description: >- The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. type: array items: type: string BetaManagedAgentsSessionRetriesExhausted: description: >- The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`. type: object additionalProperties: false required: - type properties: type: type: string enum: - retries_exhausted BetaManagedAgentsSessionBudgetReached: description: >- 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: object additionalProperties: false required: - type properties: type: type: string enum: - budget_reached BetaManagedAgentsSpanModelUsage: description: Token usage for a single model request. type: object additionalProperties: false required: - input_tokens - output_tokens - cache_creation_input_tokens - cache_read_input_tokens properties: input_tokens: description: Input tokens consumed by this request. type: integer format: int32 output_tokens: description: Output tokens generated by this request. type: integer format: int32 cache_creation_input_tokens: description: Tokens used to create prompt cache in this request. type: integer format: int32 cache_read_input_tokens: description: Tokens read from prompt cache in this request. type: integer format: int32 speed: description: >- Inference speed tier this request actually ran at. Mirrors `usage.speed` on /v1/messages. Only present when the fast-mode beta is active. allOf: - $ref: '#/components/schemas/BetaManagedAgentsSpeed' nullable: true BetaManagedAgentsRubric: description: Rubric for grading the quality of an outcome. discriminator: propertyName: type mapping: file: $ref: '#/components/schemas/BetaManagedAgentsFileRubric' text: $ref: '#/components/schemas/BetaManagedAgentsTextRubric' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsFileRubric' - $ref: '#/components/schemas/BetaManagedAgentsTextRubric' BetaManagedAgentsSessionAgent: description: >- Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. type: object additionalProperties: false required: - type - id - version - name - description - model - system - tools - mcp_servers - skills - multiagent properties: type: type: string enum: - agent examples: - agent id: type: string examples: - agent_011CZkYpogX7uDKUyvBTophP version: type: integer format: int32 examples: - 1 name: type: string examples: - My First Agent description: type: string nullable: true examples: - A general-purpose starter agent. model: $ref: '#/components/schemas/BetaManagedAgentsModelConfig' examples: - id: claude-sonnet-4-6 speed: standard system: type: string nullable: true examples: - >- You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end. tools: type: array items: $ref: '#/components/schemas/BetaManagedAgentsAgentTool' examples: - - type: agent_toolset_20260401 default_config: enabled: true permission_policy: type: always_ask configs: [] mcp_servers: type: array items: $ref: '#/components/schemas/BetaManagedAgentsMCPServer' examples: - - type: url name: example-mcp url: https://example-server.modelcontextprotocol.io/sse skills: type: array items: $ref: '#/components/schemas/BetaManagedAgentsSkill' examples: - - type: anthropic skill_id: xlsx version: '1' - type: custom skill_id: skill_011CZkZFNu9hAbo3jZPRgTlx version: '2' multiagent: description: >- Resolved multiagent orchestration configuration. Null when the agent is single-threaded. allOf: - $ref: '#/components/schemas/BetaManagedAgentsSessionMultiagent' nullable: true examples: - null example: type: agent id: agent_011CZkYpogX7uDKUyvBTophP version: 1 name: My First Agent description: A general-purpose starter agent. model: id: claude-sonnet-4-6 speed: standard system: >- You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end. tools: - type: agent_toolset_20260401 default_config: enabled: true permission_policy: type: always_ask configs: [] mcp_servers: - type: url name: example-mcp url: https://example-server.modelcontextprotocol.io/sse skills: - type: anthropic skill_id: xlsx version: '1' - type: custom skill_id: skill_011CZkZFNu9hAbo3jZPRgTlx version: '2' multiagent: null BetaManagedAgentsBudget: description: >- An enforced spend ceiling on a session. Discriminated on `type`; `limit` is the only kind currently supported. type: object discriminator: propertyName: type mapping: limit: $ref: '#/components/schemas/BetaManagedAgentsBudgetLimit' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsBudgetLimit' BetaManagedAgentsSystemContentBlock: description: Content block in a mid-conversation system message. Text-only. type: object discriminator: propertyName: type mapping: text: $ref: '#/components/schemas/BetaManagedAgentsTextBlock' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsTextBlock' BetaManagedAgentsSessionUsageSnapshot: description: Point-in-time snapshot of a session's cumulative usage. type: object additionalProperties: false properties: input_tokens: description: Total input tokens consumed across all turns. type: integer format: int32 output_tokens: description: Total output tokens generated across all turns. type: integer format: int32 cache_read_input_tokens: description: Total tokens read from prompt cache. type: integer format: int32 cache_creation: description: >- Tokens used to create prompt cache entries, broken down by cache TTL. allOf: - $ref: '#/components/schemas/BetaManagedAgentsCacheCreationUsage' list_cost: description: >- Cumulative list cost of the session across all turns, priced at public list rates. allOf: - $ref: '#/components/schemas/BetaMonetaryAmount' server_tool_use: description: Cumulative server-executed tool usage across all turns. allOf: - $ref: '#/components/schemas/BetaManagedAgentsServerToolUsage' active_seconds: description: >- Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once. This is the duration the session's runtime cost is priced on. type: number format: double BetaManagedAgentsTextBlock: description: Regular text content. type: object additionalProperties: false required: - type - text properties: type: type: string enum: - text examples: - text text: description: The text content. type: string minLength: 1 examples: - 'Where is my order #1234?' example: type: text text: 'Where is my order #1234?' BetaManagedAgentsImageBlock: description: >- Image content specified directly as base64 data or as a reference via a URL. type: object additionalProperties: false required: - type - source properties: type: type: string enum: - image source: description: The source of the image data. allOf: - $ref: '#/components/schemas/BetaManagedAgentsImageSource' BetaManagedAgentsDocumentBlock: description: >- Document content, either specified directly as base64 data, as text, or as a reference via a URL. type: object additionalProperties: false required: - type - source properties: type: type: string enum: - document source: description: The source of the document data. allOf: - $ref: '#/components/schemas/BetaManagedAgentsDocumentSource' title: description: The title of the document. type: string nullable: true context: description: Additional context about the document for the model. type: string nullable: true BetaManagedAgentsRedactedBlock: description: Placeholder for content withheld by OMA model policy. type: object additionalProperties: false required: - type properties: type: type: string enum: - redacted BetaManagedAgentsSearchResultBlock: description: A block containing a web search result. type: object additionalProperties: false required: - type - source - title - content - citations properties: type: type: string enum: - search_result source: description: The URL source of the search result. type: string minLength: 1 title: description: The title of the search result. type: string minLength: 1 content: description: Array of text content blocks from the search result. type: array items: $ref: '#/components/schemas/BetaManagedAgentsSearchResultContent' citations: description: Citation settings for this search result. allOf: - $ref: '#/components/schemas/BetaManagedAgentsSearchResultCitations' BetaManagedAgentsRetryStatus: description: What the client should do next in response to this error. type: object discriminator: propertyName: type mapping: retrying: $ref: '#/components/schemas/BetaManagedAgentsRetryStatusRetrying' exhausted: $ref: '#/components/schemas/BetaManagedAgentsRetryStatusExhausted' terminal: $ref: '#/components/schemas/BetaManagedAgentsRetryStatusTerminal' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsRetryStatusRetrying' - $ref: '#/components/schemas/BetaManagedAgentsRetryStatusExhausted' - $ref: '#/components/schemas/BetaManagedAgentsRetryStatusTerminal' BetaManagedAgentsSpeed: type: string description: >- 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. enum: - standard - fast BetaManagedAgentsFileRubric: description: Rubric referenced by a file uploaded via the Files API. type: object additionalProperties: false required: - type - file_id properties: type: type: string enum: - file file_id: description: ID of the rubric file. type: string BetaManagedAgentsTextRubric: description: Rubric content provided inline as text. type: object additionalProperties: false required: - type - content properties: type: type: string enum: - text content: description: >- Rubric content. Plain text or markdown — the grader treats it as freeform text. type: string BetaManagedAgentsModelConfig: description: Model identifier and configuration. type: object additionalProperties: false required: - id properties: id: $ref: '#/components/schemas/BetaManagedAgentsModel' effort: description: >- How hard the model works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. allOf: - $ref: '#/components/schemas/BetaManagedAgentsEffort' examples: - type: low inference_geo: description: >- Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. type: string examples: - inference_geo speed: description: >- Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. allOf: - $ref: '#/components/schemas/BetaManagedAgentsSpeed' examples: - standard example: id: claude-sonnet-4-6 effort: type: low inference_geo: inference_geo speed: standard BetaManagedAgentsAgentTool: description: Union type for tool configurations returned in API responses. type: object discriminator: propertyName: type mapping: agent_toolset_20260401: $ref: '#/components/schemas/BetaManagedAgentsAgentToolset20260401' mcp_toolset: $ref: '#/components/schemas/BetaManagedAgentsMCPToolset' custom: $ref: '#/components/schemas/BetaManagedAgentsCustomTool' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsAgentToolset20260401' - $ref: '#/components/schemas/BetaManagedAgentsMCPToolset' - $ref: '#/components/schemas/BetaManagedAgentsCustomTool' BetaManagedAgentsMCPServer: description: >- Union type for MCP server connection definitions returned in API responses. type: object discriminator: propertyName: type mapping: url: $ref: '#/components/schemas/BetaManagedAgentsMCPServerURLDefinition' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsMCPServerURLDefinition' BetaManagedAgentsSkill: description: Resolved skill as returned in API responses. discriminator: propertyName: type mapping: anthropic: $ref: '#/components/schemas/BetaManagedAgentsAnthropicSkill' custom: $ref: '#/components/schemas/BetaManagedAgentsCustomSkill' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsAnthropicSkill' - $ref: '#/components/schemas/BetaManagedAgentsCustomSkill' BetaManagedAgentsSessionMultiagent: description: >- Resolved multiagent orchestration configuration as returned on a `session`. discriminator: propertyName: type mapping: coordinator: $ref: '#/components/schemas/BetaManagedAgentsSessionMultiagentCoordinator' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsSessionMultiagentCoordinator' BetaManagedAgentsBudgetLimit: description: >- A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`. type: object additionalProperties: false required: - type - max_list_cost properties: type: type: string enum: - limit max_list_cost: description: >- Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. allOf: - $ref: '#/components/schemas/BetaMonetaryAmount' BetaManagedAgentsCacheCreationUsage: description: Prompt-cache creation token usage broken down by cache lifetime. type: object additionalProperties: false properties: ephemeral_1h_input_tokens: description: Tokens used to create 1-hour ephemeral cache entries. type: integer format: int32 ephemeral_5m_input_tokens: description: Tokens used to create 5-minute ephemeral cache entries. type: integer format: int32 BetaMonetaryAmount: description: A monetary amount in a specific currency. type: object additionalProperties: false required: - currency - amount properties: currency: description: >- Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. allOf: - $ref: '#/components/schemas/BetaCurrency' examples: - USD amount: description: >- Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. type: string examples: - '2500' example: currency: USD amount: '2500' BetaManagedAgentsServerToolUsage: description: >- Cumulative count of server-executed tool invocations, broken down by tool. type: object additionalProperties: false properties: web_search_requests: description: Number of server-executed web search requests. type: integer format: int32 examples: - 3 web_fetch_requests: description: Number of server-executed web fetch requests. type: integer format: int32 examples: - 0 example: web_search_requests: 3 web_fetch_requests: 0 BetaManagedAgentsImageSource: description: Union type for image source variants. type: object discriminator: propertyName: type mapping: base64: $ref: '#/components/schemas/BetaManagedAgentsBase64ImageSource' url: $ref: '#/components/schemas/BetaManagedAgentsURLImageSource' file: $ref: '#/components/schemas/BetaManagedAgentsFileImageSource' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsBase64ImageSource' - $ref: '#/components/schemas/BetaManagedAgentsURLImageSource' - $ref: '#/components/schemas/BetaManagedAgentsFileImageSource' BetaManagedAgentsDocumentSource: description: Union type for document source variants. type: object discriminator: propertyName: type mapping: base64: $ref: '#/components/schemas/BetaManagedAgentsBase64DocumentSource' text: $ref: '#/components/schemas/BetaManagedAgentsPlainTextDocumentSource' url: $ref: '#/components/schemas/BetaManagedAgentsURLDocumentSource' file: $ref: '#/components/schemas/BetaManagedAgentsFileDocumentSource' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsBase64DocumentSource' - $ref: '#/components/schemas/BetaManagedAgentsPlainTextDocumentSource' - $ref: '#/components/schemas/BetaManagedAgentsURLDocumentSource' - $ref: '#/components/schemas/BetaManagedAgentsFileDocumentSource' BetaManagedAgentsSearchResultContent: description: Text content within a search result. type: object additionalProperties: false required: - type - text properties: type: type: string enum: - text text: description: The text content. type: string minLength: 1 BetaManagedAgentsSearchResultCitations: description: Citation settings for a search result. type: object additionalProperties: false required: - enabled properties: enabled: description: Whether citations are enabled for this search result. type: boolean BetaManagedAgentsRetryStatusRetrying: description: >- 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: object additionalProperties: false required: - type properties: type: type: string enum: - retrying BetaManagedAgentsRetryStatusExhausted: description: >- This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. type: object additionalProperties: false required: - type properties: type: type: string enum: - exhausted BetaManagedAgentsRetryStatusTerminal: description: >- The session encountered a terminal error and will transition to `terminated` state. type: object additionalProperties: false required: - type properties: type: type: string enum: - terminal BetaManagedAgentsModel: title: BetaManagedAgentsModel description: |- The model that will power your agent. See models for additional details and options. anyOf: - type: string - const: claude-sonnet-5 description: High-performance model for coding and agents x-stainless-nominal: false - const: claude-fable-5 description: >- Next generation of intelligence for the hardest knowledge work and coding problems x-stainless-nominal: false - const: claude-opus-5 description: Powerful intelligence for long-running agents and coding x-stainless-nominal: false - const: claude-opus-4-8 description: Powerful intelligence for long-running agents and coding x-stainless-nominal: false - const: claude-opus-4-7 description: Powerful intelligence for long-running agents and coding x-stainless-nominal: false - const: claude-opus-4-6 description: Powerful intelligence for long-running agents and coding x-stainless-nominal: false - const: claude-sonnet-4-6 description: Best combination of speed and intelligence x-stainless-nominal: false - const: claude-haiku-4-5 description: Fastest model with near-frontier intelligence x-stainless-nominal: false - const: claude-haiku-4-5-20251001 description: Fastest model with near-frontier intelligence x-stainless-nominal: false - const: claude-opus-4-5 description: Powerful intelligence for long-running agents and coding x-stainless-nominal: false - const: claude-opus-4-5-20251101 description: Powerful intelligence for long-running agents and coding x-stainless-nominal: false - const: claude-sonnet-4-5 description: High-performance model for agents and coding x-stainless-nominal: false - const: claude-sonnet-4-5-20250929 description: High-performance model for agents and coding x-stainless-nominal: false BetaManagedAgentsEffort: description: >- How hard the model works on each turn. Sets `output_config.effort` on every Messages call the session makes. type: object discriminator: propertyName: type mapping: low: $ref: '#/components/schemas/BetaManagedAgentsEffortLow' medium: $ref: '#/components/schemas/BetaManagedAgentsEffortMedium' high: $ref: '#/components/schemas/BetaManagedAgentsEffortHigh' xhigh: $ref: '#/components/schemas/BetaManagedAgentsEffortXhigh' max: $ref: '#/components/schemas/BetaManagedAgentsEffortMax' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsEffortLow' - $ref: '#/components/schemas/BetaManagedAgentsEffortMedium' - $ref: '#/components/schemas/BetaManagedAgentsEffortHigh' - $ref: '#/components/schemas/BetaManagedAgentsEffortXhigh' - $ref: '#/components/schemas/BetaManagedAgentsEffortMax' BetaManagedAgentsAgentToolset20260401: type: object additionalProperties: false required: - configs - default_config - type properties: configs: type: array items: $ref: '#/components/schemas/BetaManagedAgentsAgentToolConfig' default_config: $ref: '#/components/schemas/BetaManagedAgentsAgentToolsetDefaultConfig' type: type: string enum: - agent_toolset_20260401 BetaManagedAgentsMCPToolset: type: object additionalProperties: false required: - configs - default_config - mcp_server_name - type properties: configs: type: array items: $ref: '#/components/schemas/BetaManagedAgentsMCPToolConfig' default_config: $ref: '#/components/schemas/BetaManagedAgentsMCPToolsetDefaultConfig' mcp_server_name: type: string type: type: string enum: - mcp_toolset BetaManagedAgentsCustomTool: description: A custom tool as returned in API responses. type: object additionalProperties: false required: - description - input_schema - name - type properties: description: type: string input_schema: $ref: '#/components/schemas/BetaManagedAgentsCustomToolInputSchema' name: type: string type: type: string enum: - custom BetaManagedAgentsMCPServerURLDefinition: description: URL-based MCP server connection as returned in API responses. type: object additionalProperties: false required: - name - type - url properties: name: type: string examples: - example-mcp type: type: string enum: - url examples: - url url: type: string examples: - https://example-server.modelcontextprotocol.io/sse example: type: url name: example-mcp url: https://example-server.modelcontextprotocol.io/sse BetaManagedAgentsAnthropicSkill: description: A resolved OMA-managed skill. type: object additionalProperties: false required: - skill_id - type - version properties: skill_id: type: string examples: - xlsx type: type: string enum: - anthropic examples: - anthropic version: type: string examples: - '1' example: type: anthropic skill_id: xlsx version: '1' BetaManagedAgentsCustomSkill: description: A resolved user-created custom skill. type: object additionalProperties: false required: - skill_id - type - version properties: skill_id: type: string examples: - skill_011CZkZFNu9hAbo3jZPRgTlx type: type: string enum: - custom examples: - custom version: type: string examples: - '2' example: type: custom skill_id: skill_011CZkZFNu9hAbo3jZPRgTlx version: '2' BetaManagedAgentsSessionMultiagentCoordinator: description: >- Resolved coordinator topology with full agent definitions for each roster member. type: object additionalProperties: false required: - type - agents properties: type: type: string enum: - coordinator agents: description: >- Full `agent` definitions the coordinator may spawn as session threads. type: array items: $ref: '#/components/schemas/BetaManagedAgentsSessionRosterEntry' BetaCurrency: type: string enum: - USD BetaManagedAgentsBase64ImageSource: description: Base64-encoded image data. type: object additionalProperties: false required: - type - media_type - data properties: type: type: string enum: - base64 media_type: description: >- MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). type: string minLength: 1 data: description: Base64-encoded image data. type: string minLength: 1 BetaManagedAgentsURLImageSource: description: Image referenced by URL. type: object additionalProperties: false required: - type - url properties: type: type: string enum: - url url: description: URL of the image to fetch. type: string minLength: 1 BetaManagedAgentsFileImageSource: description: Image referenced by file ID. type: object additionalProperties: false required: - type - file_id properties: type: type: string enum: - file file_id: description: ID of a previously uploaded file. type: string minLength: 1 BetaManagedAgentsBase64DocumentSource: description: Base64-encoded document data. type: object additionalProperties: false required: - type - media_type - data properties: type: type: string enum: - base64 media_type: description: MIME type of the document (e.g., "application/pdf"). type: string minLength: 1 data: description: Base64-encoded document data. type: string minLength: 1 BetaManagedAgentsPlainTextDocumentSource: description: Plain text document content. type: object additionalProperties: false required: - type - media_type - data properties: type: type: string enum: - text media_type: description: MIME type of the text content. Must be "text/plain". type: string enum: - text/plain data: description: The plain text content. type: string minLength: 1 BetaManagedAgentsURLDocumentSource: description: Document referenced by URL. type: object additionalProperties: false required: - type - url properties: type: type: string enum: - url url: description: URL of the document to fetch. type: string minLength: 1 BetaManagedAgentsFileDocumentSource: description: Document referenced by file ID. type: object additionalProperties: false required: - type - file_id properties: type: type: string enum: - file file_id: description: ID of a previously uploaded file. type: string minLength: 1 BetaManagedAgentsEffortLow: description: Low effort. Favors latency over reasoning depth. type: object additionalProperties: false required: - type properties: type: type: string enum: - low BetaManagedAgentsEffortMedium: description: Medium effort. Balances latency and reasoning depth. type: object additionalProperties: false required: - type properties: type: type: string enum: - medium BetaManagedAgentsEffortHigh: description: High effort. Favors reasoning depth. type: object additionalProperties: false required: - type properties: type: type: string enum: - high BetaManagedAgentsEffortXhigh: description: Extra-high effort. Not all models accept this level. type: object additionalProperties: false required: - type properties: type: type: string enum: - xhigh BetaManagedAgentsEffortMax: description: Maximum effort. Favors reasoning depth over latency. type: object additionalProperties: false required: - type properties: type: type: string enum: - max BetaManagedAgentsAgentToolConfig: description: Configuration for a specific agent tool. type: object additionalProperties: false required: - enabled - name - permission_policy properties: enabled: type: boolean name: $ref: '#/components/schemas/BetaManagedAgentsAgentToolName' permission_policy: $ref: '#/components/schemas/BetaManagedAgentsPermissionPolicy' BetaManagedAgentsAgentToolsetDefaultConfig: description: Resolved default configuration for agent tools. type: object additionalProperties: false required: - enabled - permission_policy properties: enabled: type: boolean permission_policy: $ref: '#/components/schemas/BetaManagedAgentsPermissionPolicy' BetaManagedAgentsMCPToolConfig: description: Resolved configuration for a specific MCP tool. type: object additionalProperties: false required: - enabled - name - permission_policy properties: enabled: type: boolean name: type: string permission_policy: $ref: '#/components/schemas/BetaManagedAgentsPermissionPolicy' BetaManagedAgentsMCPToolsetDefaultConfig: description: Resolved default configuration for all tools from an MCP server. type: object additionalProperties: false required: - enabled - permission_policy properties: enabled: type: boolean permission_policy: $ref: '#/components/schemas/BetaManagedAgentsPermissionPolicy' BetaManagedAgentsCustomToolInputSchema: additionalProperties: true description: JSON Schema for custom tool input parameters. properties: type: const: object title: Type type: string properties: anyOf: - type: object additionalProperties: true - type: 'null' title: Properties x-stainless-skip: - terraform required: anyOf: - items: type: string type: array - type: 'null' title: Required required: - type type: object BetaManagedAgentsSessionRosterEntry: description: A session-resolved multiagent roster entry. discriminator: propertyName: type mapping: agent: $ref: '#/components/schemas/BetaManagedAgentsSessionThreadAgent' advisor: $ref: '#/components/schemas/BetaManagedAgentsAdvisor' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsSessionThreadAgent' - $ref: '#/components/schemas/BetaManagedAgentsAdvisor' BetaManagedAgentsAgentToolName: type: string description: Built-in agent tool identifier. enum: - bash - edit - read - write - glob - grep - web_fetch - web_search BetaManagedAgentsPermissionPolicy: description: Permission policy for tool execution. type: object discriminator: propertyName: type mapping: always_allow: $ref: '#/components/schemas/BetaManagedAgentsAlwaysAllowPolicy' always_ask: $ref: '#/components/schemas/BetaManagedAgentsAlwaysAskPolicy' oneOf: - $ref: '#/components/schemas/BetaManagedAgentsAlwaysAllowPolicy' - $ref: '#/components/schemas/BetaManagedAgentsAlwaysAskPolicy' BetaManagedAgentsSessionThreadAgent: description: >- Resolved `agent` definition for a single `session_thread`. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from `Session.agent`. type: object additionalProperties: false required: - type - id - version - name - description - model - system - tools - mcp_servers - skills properties: type: type: string enum: - agent examples: - agent id: type: string examples: - agent_011CZkYqphY8vELVzwCUpqiQ version: type: integer format: int32 examples: - 1 name: type: string examples: - Researcher description: type: string nullable: true examples: - A focused research subagent. model: $ref: '#/components/schemas/BetaManagedAgentsModelConfig' examples: - id: claude-sonnet-4-6 speed: standard system: type: string nullable: true examples: - >- You are a research subagent that gathers and summarises sources for the coordinating agent. tools: type: array items: $ref: '#/components/schemas/BetaManagedAgentsAgentTool' examples: - - type: agent_toolset_20260401 default_config: enabled: true permission_policy: type: always_ask configs: [] mcp_servers: type: array items: $ref: '#/components/schemas/BetaManagedAgentsMCPServer' examples: - [] skills: type: array items: $ref: '#/components/schemas/BetaManagedAgentsSkill' examples: - [] example: type: agent id: agent_011CZkYqphY8vELVzwCUpqiQ version: 1 name: Researcher description: A focused research subagent. model: id: claude-sonnet-4-6 speed: standard system: >- You are a research subagent that gathers and summarises sources for the coordinating agent. tools: - type: agent_toolset_20260401 default_config: enabled: true permission_policy: type: always_ask configs: [] mcp_servers: [] skills: [] BetaManagedAgentsAdvisor: description: >- Platform advisor roster entry: a model the session's primary thread may consult mid-turn. type: object additionalProperties: false required: - model - type properties: model: description: The advisor model id. type: string type: type: string enum: - advisor BetaManagedAgentsAlwaysAllowPolicy: description: Tool calls are automatically approved without user confirmation. type: object additionalProperties: false required: - type properties: type: type: string enum: - always_allow BetaManagedAgentsAlwaysAskPolicy: description: Tool calls require user confirmation before execution. type: object additionalProperties: false required: - type properties: type: type: string enum: - always_ask securitySchemes: omaApiKey: type: apiKey in: header name: X-Api-Key description: OMA workspace API key. x-default: sk-ant-local-default omaBearer: type: http scheme: bearer description: OMA workspace API key sent as a bearer token. ````