> ## 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.
# 流式接收会话线程事件
> 通过 OMA API 流式接收会话线程事件。
每个请求都必须发送 `?beta=true`。
响应使用 `text/event-stream`。连接断开后应重新连接；在最终事件到达前，事件增量只应视为尽力而为的预览。
## OpenAPI
````yaml /openapi/oma.zh.json get /v1/sessions/{session_id}/threads/{thread_id}/stream
openapi: 3.1.0
info:
title: OMA API 参考
version: 1.0.0
description: Open Managed Agents 应用 API 参考。
servers:
- url: http://localhost:38080
description: 本地 OMA 服务器
security:
- omaApiKey: []
- omaBearer: []
paths:
/v1/sessions/{session_id}/threads/{thread_id}/stream:
get:
summary: 流式接收会话线程事件
operationId: BetaStreamSessionThreadEvents
parameters:
- name: beta
in: query
required: true
description: 为此接口启用 Beta API 合同，必须为 `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: 用于指定一个或多个 Beta 版本的可选请求头。
items:
$ref: '#/components/schemas/AnthropicBeta'
x-default: managed-agents-2026-04-01
- name: session_id
in: path
required: true
schema:
type: string
description: 会话标识符。
example: sesn_011CZkZAtmR3yMPDzynEDxu7
- name: thread_id
in: path
required: true
schema:
type: string
description: 会话线程标识符。
example: sthr_011CZkZVWa6oIjw0rgXZpnBt
- name: event_deltas[]
in: query
required: false
style: form
explode: true
schema:
type: array
items:
$ref: '#/components/schemas/BetaManagedAgentsEventDeltaType'
description: >-
设置后，该连接还会在事件生成过程中、事件本身到达之前接收流式增量（`event_start`、`event_delta`）。增量是尽力而为的；最终事件生成时会携带完整内容。提前结束的模型请求（出错或被中断）不会产生最终事件——其终止
`span.model_request_end`
会关闭预览。接受一个或多个要预览的事件类型，并且可以重复指定：`agent.message` 流式传输 `content_delta`
片段；`agent.thinking` 仅有开始信号——表示智能体已开始扩展思考，由 `agent.thinking`
事件本身收尾。只发送所请求事件类型的预览。
responses:
'200':
description: 请求成功。
content:
application/json:
schema:
$ref: >-
#/components/schemas/BetaManagedAgentsStreamSessionThreadEvents
'400':
description: Invalid argument - 客户端指定了无效的参数
content:
application/json:
schema:
$ref: '#/components/schemas/BetaErrorResponse'
'401':
description: 未认证 - 请求没有有效的认证凭据
content:
application/json:
schema:
$ref: '#/components/schemas/BetaErrorResponse'
'403':
description: 权限被拒绝 - 调用方没有执行指定操作的权限
content:
application/json:
schema:
$ref: '#/components/schemas/BetaErrorResponse'
'404':
description: 未找到 - 请求的某个实体不存在
content:
application/json:
schema:
$ref: '#/components/schemas/BetaErrorResponse'
'408':
description: 超出截止时间 - 截止时间在操作完成之前已过期
content:
application/json:
schema:
$ref: '#/components/schemas/BetaErrorResponse'
'409':
description: 已中止 - 该操作因并发问题而被中止
content:
application/json:
schema:
$ref: '#/components/schemas/BetaErrorResponse'
'412':
description: 前置条件不满足 - 由于系统未处于所需状态，操作被拒绝
content:
application/json:
schema:
$ref: '#/components/schemas/BetaErrorResponse'
'413':
description: Out of range - 尝试的操作超出了有效范围
content:
application/json:
schema:
$ref: '#/components/schemas/BetaErrorResponse'
'429':
description: 资源耗尽 - 某些资源已被耗尽（限流）
content:
application/json:
schema:
$ref: '#/components/schemas/BetaErrorResponse'
'431':
description: 请求头字段过大 - 请求元数据过大
content:
application/json:
schema:
$ref: '#/components/schemas/BetaErrorResponse'
'499':
description: Cancelled - 操作已被客户端取消
content:
application/json:
schema:
$ref: '#/components/schemas/BetaErrorResponse'
'500':
description: Internal - 内部服务器错误
content:
application/json:
schema:
$ref: '#/components/schemas/BetaErrorResponse'
'501':
description: 未实现 - 该操作未实现或不受支持
content:
application/json:
schema:
$ref: '#/components/schemas/BetaErrorResponse'
'503':
description: 不可用 - 服务当前不可用
content:
application/json:
schema:
$ref: '#/components/schemas/BetaErrorResponse'
'504':
description: 超时 - 上游服务未及时响应
content:
application/json:
schema:
$ref: '#/components/schemas/BetaErrorResponse'
components:
schemas:
BetaManagedAgentsEventDeltaType:
type: string
description: EventDeltaType 枚举
enum:
- agent.message
- agent.thinking
BetaManagedAgentsStreamSessionThreadEvents:
description: 单个线程流中的服务器发送事件。
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'
event_start:
$ref: '#/components/schemas/BetaManagedAgentsEventStartEvent'
event_delta:
$ref: '#/components/schemas/BetaManagedAgentsEventDeltaEvent'
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/BetaManagedAgentsEventStartEvent'
- $ref: '#/components/schemas/BetaManagedAgentsEventDeltaEvent'
- $ref: '#/components/schemas/BetaManagedAgentsSystemMessageEvent'
- $ref: '#/components/schemas/BetaManagedAgentsSessionUsageEvent'
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: 错误
request_id:
anyOf:
- type: string
- type: 'null'
default: null
title: 请求 ID
type:
const: error
default: error
title: 类型
type: string
required:
- error
- request_id
- type
title: ErrorResponse
type: object
BetaManagedAgentsUserMessageEvent:
description: 会话对话中的用户消息事件。
type: object
additionalProperties: false
required:
- type
- id
- content
properties:
type:
type: string
enum:
- user.message
examples:
- user.message
id:
description: 此事件的唯一标识符。
type: string
examples:
- sevt_011CZkZGOp0iBcp4kaQSihUmy
content:
description: 构成用户消息的内容块数组。
type: array
items:
$ref: '#/components/schemas/BetaManagedAgentsUserContentBlock'
examples:
- - type: text
text: '我的订单 #1234 到哪里了？'
processed_at:
description: 智能体完成处理此消息的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
nullable: true
examples:
- '2026-03-15T10:00:00Z'
example:
type: user.message
id: sevt_011CZkZGOp0iBcp4kaQSihUmy
content:
- type: text
text: '我的订单 #1234 到哪里了？'
processed_at: '2026-03-15T10:00:00Z'
BetaManagedAgentsUserInterruptEvent:
description: 暂停智能体执行并将控制权交还给用户的中断事件。
type: object
additionalProperties: false
required:
- type
- id
properties:
type:
type: string
enum:
- user.interrupt
id:
description: 此事件的唯一标识符。
type: string
processed_at:
description: 中断被处理时的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
nullable: true
session_thread_id:
description: 缺省时，中断多智能体会话中所有未归档的线程（在单智能体会话中则仅中断主线程）。存在时，仅中断指定名称的线程。
type: string
nullable: true
BetaManagedAgentsUserToolConfirmationEvent:
description: 用于批准或拒绝待执行工具调用的工具确认事件。
type: object
additionalProperties: false
required:
- type
- id
- tool_use_id
- result
properties:
type:
type: string
enum:
- user.tool_confirmation
id:
description: 此事件的唯一标识符。
type: string
tool_use_id:
description: >-
该结果对应的 `agent.tool_use` 或 `agent.mcp_tool_use` 事件的 ID，可在最近一次
`session.status_idle` 事件的 `stop_reason.event_ids` 字段中找到。
type: string
result:
description: 确认结果：'allow' 或 'deny'。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsUserToolConfirmationResult'
deny_message:
description: 可选消息，为 'deny' 决定提供上下文。仅当 result 为 'deny' 时允许。
type: string
maxLength: 10000
nullable: true
processed_at:
description: 该确认被处理的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
nullable: true
session_thread_id:
description: >-
设置后，确认将路由到该子智能体的线程而非主线程。请从触发本次审批的 `agent.tool_use` 或
`agent.mcp_tool_use` 事件的 `session_thread_id` 原样回传该值。
type: string
nullable: true
BetaManagedAgentsUserCustomToolResultEvent:
description: 由客户端发送的事件，提供自定义工具执行的结果。
type: object
additionalProperties: false
required:
- type
- id
- custom_tool_use_id
properties:
type:
type: string
enum:
- user.custom_tool_result
id:
description: 此事件的唯一标识符。
type: string
custom_tool_use_id:
description: >-
此结果对应的 `agent.custom_tool_use` 事件的 ID，可在最近一次 `session.status_idle`
事件的 `stop_reason.event_ids` 字段中找到。
type: string
content:
description: 工具返回的结果内容。
type: array
items:
$ref: '#/components/schemas/BetaManagedAgentsToolResultContentBlock'
is_error:
description: 工具执行是否出错。
type: boolean
nullable: true
processed_at:
description: 本结果被处理时的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
nullable: true
session_thread_id:
description: >-
将此结果路由到一个子智能体线程。从 `agent.custom_tool_use` 事件的 `session_thread_id`
复制。
type: string
nullable: true
BetaManagedAgentsAgentCustomToolUseEvent:
description: 智能体调用自定义工具时发出的事件。会话将保持空闲状态，直到客户端发送携带结果的 `user.custom_tool_result` 事件。
type: object
additionalProperties: false
required:
- type
- id
- name
- input
- processed_at
properties:
type:
type: string
enum:
- agent.custom_tool_use
id:
description: 此事件的唯一标识符。
type: string
name:
description: 正在调用的自定义工具名称。
type: string
input:
description: 工具调用的输入参数。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsStruct'
processed_at:
description: 本工具调用被处理时的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
session_thread_id:
description: >-
设置后，表示此事件是从子智能体的线程交叉转发而来，用于将其自定义工具调用呈现到主线程的流中。在线程自身的事件上为空。在
`user.custom_tool_result` 事件上回显此值，以将结果路由回去。
type: string
nullable: true
BetaManagedAgentsAgentMessageEvent:
description: 会话对话中的智能体响应事件。
type: object
additionalProperties: false
required:
- type
- id
- content
- processed_at
properties:
type:
type: string
enum:
- agent.message
examples:
- agent.message
id:
description: 此事件的唯一标识符。
type: string
examples:
- sevt_011CZkZHPq1jCdq5lbRTjiVnz
content:
description: 构成智能体响应的文本块数组。
type: array
items:
$ref: '#/components/schemas/BetaManagedAgentsAgentMessageContentBlock'
examples:
- - type: text
text: 'Let me look up order #1234 for you.'
processed_at:
description: 本响应生成时的时间戳。
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: 表示智能体正在通过扩展思考取得进展。这是进度信号，而非内容载体。
type: object
additionalProperties: false
required:
- type
- id
- processed_at
properties:
type:
type: string
enum:
- agent.thinking
id:
description: 此事件的唯一标识符。
type: string
processed_at:
description: 本思考生成时的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
BetaManagedAgentsAgentMcpToolUseEvent:
description: 智能体调用 MCP 服务器提供的工具时发出的事件。
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: 此事件的唯一标识符。
type: string
name:
description: 正在使用的 MCP 工具名称。
type: string
mcp_server_name:
description: 提供该工具的 MCP 服务器的名称。
type: string
input:
description: 工具调用的输入参数。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsStruct'
processed_at:
description: 本事件被处理时的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
evaluated_permission:
description: 此次工具调用经评估后的权限策略。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsAgentEvaluatedPermission'
session_thread_id:
description: >-
设置后，表示此事件是从子智能体的线程交叉转发而来，用于将其权限请求呈现到主线程的流中。在线程自身的事件上为空。在
`user.tool_confirmation` 事件上回显此值，以将批准结果路由回去。
type: string
nullable: true
BetaManagedAgentsAgentMcpToolResultEvent:
description: 表示 MCP 工具执行结果的事件。
type: object
additionalProperties: false
required:
- type
- id
- mcp_tool_use_id
- processed_at
properties:
type:
type: string
enum:
- agent.mcp_tool_result
id:
description: 此事件的唯一标识符。
type: string
mcp_tool_use_id:
description: 此结果对应的 `agent.mcp_tool_use` 事件的 ID。
type: string
content:
description: 工具返回的结果内容。
type: array
items:
$ref: '#/components/schemas/BetaManagedAgentsToolResultContentBlock'
is_error:
description: 工具执行是否出错。
type: boolean
nullable: true
processed_at:
description: 本事件被处理时的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
BetaManagedAgentsAgentToolUseEvent:
description: 智能体调用内置智能体工具时发出的事件。
type: object
additionalProperties: false
required:
- type
- id
- name
- input
- processed_at
properties:
type:
type: string
enum:
- agent.tool_use
id:
description: 此事件的唯一标识符。
type: string
name:
description: 正在使用的智能体工具名称。
type: string
input:
description: 工具调用的输入参数。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsStruct'
processed_at:
description: 本事件被处理时的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
evaluated_permission:
description: 此次工具调用经评估后的权限策略。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsAgentEvaluatedPermission'
session_thread_id:
description: >-
设置后，表示此事件是从子智能体的线程交叉转发而来，用于将其权限请求呈现到主线程的流中。在线程自身的事件上为空。在
`user.tool_confirmation` 事件上回显此值，以将批准结果路由回去。
type: string
nullable: true
BetaManagedAgentsAgentToolResultEvent:
description: 表示智能体工具执行结果的事件。
type: object
additionalProperties: false
required:
- type
- id
- tool_use_id
- processed_at
properties:
type:
type: string
enum:
- agent.tool_result
id:
description: 此事件的唯一标识符。
type: string
tool_use_id:
description: 此结果对应的 `agent.tool_use` 事件的 ID。
type: string
content:
description: 工具返回的结果内容。
type: array
items:
$ref: '#/components/schemas/BetaManagedAgentsToolResultContentBlock'
is_error:
description: 工具执行是否出错。
type: boolean
nullable: true
processed_at:
description: 本事件被处理时的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
BetaManagedAgentsAgentThreadMessageReceivedEvent:
description: 智能体间消息到达时，写入目标线程输入流的投递事件。
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: 此事件的唯一标识符。
type: string
processed_at:
description: 消息被接收时的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
from_agent_name:
description: 此消息来源的可调用智能体的名称。接收自主智能体时不存在。
type: string
nullable: true
content:
description: 消息内容块。
type: array
items:
$ref: '#/components/schemas/BetaManagedAgentsUserContentBlock'
from_session_thread_id:
description: 发送该消息的线程的公开 `sthr_` ID。
type: string
BetaManagedAgentsAgentThreadMessageSentEvent:
description: 发送智能体间消息时，向发送方输出流发出的可观测性事件。
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: 此事件的唯一标识符。
type: string
processed_at:
description: 消息发送的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
to_agent_name:
description: 此消息所发送的可调用智能体的名称。发送给主智能体时不存在。
type: string
nullable: true
content:
description: 消息内容块。
type: array
items:
$ref: '#/components/schemas/BetaManagedAgentsUserContentBlock'
to_session_thread_id:
description: 接收该消息的线程的公开 `sthr_` ID。
type: string
BetaManagedAgentsAgentThreadContextCompactedEvent:
description: 表示会话期间发生了上下文压缩（摘要）。
type: object
additionalProperties: false
required:
- type
- id
- processed_at
properties:
type:
type: string
enum:
- agent.thread_context_compacted
id:
description: 此事件的唯一标识符。
type: string
processed_at:
description: compaction 被处理时的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
BetaManagedAgentsSessionErrorEvent:
description: 表示会话执行期间出现问题的错误事件。
type: object
additionalProperties: false
required:
- type
- id
- processed_at
- error
properties:
type:
type: string
enum:
- session.error
id:
description: 此事件的唯一标识符。
type: string
processed_at:
description: 错误发生的时间戳。
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: 表示该会话正在从错误状态恢复，并已重新调度执行。
type: object
additionalProperties: false
required:
- type
- id
- processed_at
properties:
type:
type: string
enum:
- session.status_rescheduled
id:
description: 此事件的唯一标识符。
type: string
processed_at:
description: 状态变更的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
BetaManagedAgentsSessionStatusRunningEvent:
description: 表示会话正在运行且智能体正在工作。
type: object
additionalProperties: false
required:
- type
- id
- processed_at
properties:
type:
type: string
enum:
- session.status_running
id:
description: 此事件的唯一标识符。
type: string
processed_at:
description: 状态变更的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
BetaManagedAgentsSessionStatusIdleEvent:
description: 表示智能体已暂停并等待用户输入。
type: object
additionalProperties: false
required:
- type
- id
- processed_at
- stop_reason
properties:
type:
type: string
enum:
- session.status_idle
id:
description: 此事件的唯一标识符。
type: string
processed_at:
description: 状态变更的时间戳。
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: 表示会话已终止，可能由于错误或已完成。
type: object
additionalProperties: false
required:
- type
- id
- processed_at
properties:
type:
type: string
enum:
- session.status_terminated
id:
description: 此事件的唯一标识符。
type: string
processed_at:
description: 状态变更的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
BetaManagedAgentsSessionThreadCreatedEvent:
description: 在子智能体作为新线程被创建时发出。该事件会写入父线程的输出流，以便观察该会话的客户端能够看到子线程的创建。
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: 此事件的唯一标识符。
type: string
examples:
- sevt_011CZkZWXb7pJkx1shYaqoCu
processed_at:
description: 线程创建的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
examples:
- '2026-03-15T10:00:00Z'
agent_name:
description: 线程运行的可调用智能体的名称。
type: string
examples:
- Researcher
session_thread_id:
description: 新创建的线程的公开 `sthr_` ID。
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: 在结果评估周期开始时发出。
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: 此事件的唯一标识符。
type: string
examples:
- sevt_011CZkZTUy4mGhu8peVXnlzr
processed_at:
description: 结果评估开始时的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
examples:
- '2026-03-15T10:02:14Z'
iteration:
description: 从 0 开始的修订轮次。0 表示首次评估；1 表示第一次修订后的重新评估；以此类推。
type: integer
format: int32
examples:
- 0
outcome_id:
description: 正在评估的结果的 `outc_` ID。
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: >-
在结果评估周期完成时发出。携带判定结果和汇总的令牌用量。判定为 `needs_revision`
表示将进入下一个评估周期；`satisfied`、`max_iterations_reached`、`failed` 或
`interrupted` 为终态——不会再有后续评估周期。
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: 此事件的唯一标识符。
type: string
examples:
- sevt_011CZkZUVz5nHiv9qfWYomas
processed_at:
description: 结果评估结束时的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
examples:
- '2026-03-15T10:02:31Z'
outcome_evaluation_start_id:
description: 对应的 `span.outcome_evaluation_start` 事件的 ID。
type: string
examples:
- sevt_011CZkZTUy4mGhu8peVXnlzr
iteration:
description: 从 0 开始的修订周期，与对应的 `span.outcome_evaluation_start` 一致。
type: integer
format: int32
examples:
- 0
result:
description: >-
评估裁定。'satisfied'：标准已满足，会话进入空闲。'needs_revision'：标准未满足，将进入下一个修订周期。'max_iterations_reached'：评估预算已耗尽但标准仍未满足——在会话进入空闲前会有一个最终确认回合，但不再进行后续评估。'failed'：评分器判定评分标准不适用于交付成果。'interrupted'：评估进行中用户发送了中断。
type: string
examples:
- satisfied
explanation:
description: 对结论的人类可读说明。对于 `needs_revision`，描述哪些标准未通过及原因。
type: string
examples:
- 五个部分均已完成，并包含行内引用。
usage:
description: 此评估周期的汇总令牌用量。为该周期内所有 grader 模型请求之和。
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: 正在评估的结果的 `outc_` ID。
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: 五个部分均已完成，并包含行内引用。
usage:
input_tokens: 1842
output_tokens: 213
cache_creation_input_tokens: 0
cache_read_input_tokens: 1536
outcome_id: outc_011CZkZRSw2kEfs6ncTVljxP
BetaManagedAgentsSpanModelRequestStartEvent:
description: 智能体发起模型请求时发出。
type: object
additionalProperties: false
required:
- type
- id
- processed_at
properties:
type:
type: string
enum:
- span.model_request_start
id:
description: 此事件的唯一标识符。
type: string
processed_at:
description: 模型请求开始时的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
BetaManagedAgentsSpanModelRequestEndEvent:
description: 模型请求完成时发出。
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: 此事件的唯一标识符。
type: string
processed_at:
description: 模型请求完成时的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
is_error:
description: 模型请求是否出错。
type: boolean
nullable: true
model_usage:
description: 此模型请求的令牌用量。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsSpanModelUsage'
model_request_start_id:
description: 对应的 `span.model_request_start` 事件的 ID。
type: string
BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent:
description: >-
在结果评估周期进行中定期发出的心跳。用于在对应的 `span.outcome_evaluation_start` 与
`span.outcome_evaluation_end` 事件之间区分'评估正在运行'与'评估已卡住'。
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: 此事件的唯一标识符。
type: string
examples:
- sevt_011CZkZbCG2uOpc6xmDfvTzh
processed_at:
description: 本心跳发出时的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
examples:
- '2026-03-15T10:02:14Z'
iteration:
description: 从 0 开始的修订周期，与对应的 `span.outcome_evaluation_start` 一致。
type: integer
format: int32
examples:
- 0
outcome_id:
description: 正在评估的结果的 `outc_` ID。
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: >-
`user.define_outcome` 输入事件的回显。携带由服务端生成的 `outcome_id`，后续的
`span.outcome_evaluation_*` 事件将引用该 ID。
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: 此事件的唯一标识符。
type: string
examples:
- sevt_011CZkZSTx3lFgt7odUWmkyq
processed_at:
description: 结果被接受时的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
examples:
- '2026-03-15T10:02:14Z'
outcome_id:
description: >-
由服务端为该结果生成的 `outc_` ID。会被 `span.outcome_evaluation_*` 事件和会话的
`outcome_evaluations` 列表引用。
type: string
examples:
- outc_011CZkZRSw2kEfs6ncTVljxP
description:
description: 智能体应产出的内容。从输入事件复制而来。
type: string
examples:
- 生成一份两页的摘要并保存为 summary.md
max_iterations:
description: 放弃前的评估后修订循环次数。默认 3 次，最多 20 次。
type: integer
format: int32
nullable: true
examples:
- 3
rubric:
description: 如何对结果进行评分。文件形式的评分标准目前会被解析为其文本内容；客户端应能处理两种变体。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsRubric'
examples:
- type: text
content: 必须涵盖全部五个部分，并在正文中引用来源。
example:
type: user.define_outcome
id: sevt_011CZkZSTx3lFgt7odUWmkyq
processed_at: '2026-03-15T10:02:14Z'
outcome_id: outc_011CZkZRSw2kEfs6ncTVljxP
description: 生成一份 2 页的摘要并保存为 summary.md
max_iterations: 3
rubric:
type: text
content: 必须涵盖全部五个部分，并在正文中引用来源。
BetaManagedAgentsSessionDeletedEvent:
description: 在会话被删除时发出。会终止所有活跃的事件流 —— 不会再为该会话发出任何事件。
type: object
additionalProperties: false
required:
- type
- id
- processed_at
properties:
type:
type: string
enum:
- session.deleted
id:
description: 此事件的唯一标识符。
type: string
processed_at:
description: 会话被删除时的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
BetaManagedAgentsSessionThreadStatusRunningEvent:
description: 会话线程已开始执行。在该线程自身的流上发出；对于子线程，还会交叉发布到主线程的流。
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: 此事件的唯一标识符。
type: string
session_thread_id:
description: 开始运行的线程的公开 sthr_ ID。
type: string
processed_at:
description: 状态转换的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
agent_name:
description: 线程所运行的智能体名称。
type: string
BetaManagedAgentsSessionThreadStatusIdleEvent:
description: 会话线程已让出并正在等待输入。该事件在该线程自身的流上发出，对于子线程还会转发到主流。
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: 此事件的唯一标识符。
type: string
examples:
- sevt_011CZkZXYc8qKly2tiZbrpDv
session_thread_id:
description: 进入空闲状态的线程的公开 sthr_ ID。
type: string
examples:
- sthr_011CZkZVWa6oIjw0rgXZpnBt
processed_at:
description: 状态转换的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
examples:
- '2026-03-15T10:00:00Z'
agent_name:
description: 线程所运行的智能体名称。
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: 会话线程已终止，将不再接受任何输入。该事件在该线程自身的流上发出，对于子线程还会转发到主流。
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: 此事件的唯一标识符。
type: string
session_thread_id:
description: 已终止的线程的公开 sthr_ ID。
type: string
processed_at:
description: 状态转换的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
agent_name:
description: 线程所运行的智能体名称。
type: string
BetaManagedAgentsUserToolResultEvent:
description: >-
由客户端发送的事件，用于提供智能体工具集工具执行的结果。仅在 `self_hosted`
环境上有效，在这些环境中，路由到沙箱的工具由客户端而非服务端执行。
type: object
additionalProperties: false
required:
- type
- id
- tool_use_id
properties:
type:
type: string
enum:
- user.tool_result
id:
description: 此事件的唯一标识符。
type: string
tool_use_id:
description: >-
此结果对应的 `agent.tool_use` 事件的 ID，可在最近一次 `session.status_idle` 事件的
`stop_reason.event_ids` 字段中找到。
type: string
content:
description: 工具返回的结果内容。
type: array
items:
$ref: '#/components/schemas/BetaManagedAgentsToolResultContentBlock'
is_error:
description: 工具执行是否出错。
type: boolean
nullable: true
processed_at:
description: 本结果被处理时的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
nullable: true
session_thread_id:
description: 将此结果路由到一个子智能体线程。从 `agent.tool_use` 事件的 `session_thread_id` 复制。
type: string
nullable: true
BetaManagedAgentsSessionThreadStatusRescheduledEvent:
description: 会话线程遇到瞬时错误，正在自动重试。该事件在该线程自身的流上发出，对于子线程还会转发到主流。
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: 此事件的唯一标识符。
type: string
session_thread_id:
description: 正在重试的线程的公开 sthr_ ID。
type: string
processed_at:
description: 状态转换的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
agent_name:
description: 线程所运行的智能体名称。
type: string
BetaManagedAgentsSessionUpdatedEvent:
description: 当 UpdateSession 请求更改了至少一个字段时发出。仅携带发生更改的字段；缺失的字段不属于本次更新。新配置从下一轮开始生效。
type: object
additionalProperties: false
required:
- type
- id
- processed_at
properties:
type:
type: string
enum:
- session.updated
id:
description: 此事件的唯一标识符。
type: string
processed_at:
description: 更新应用的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
title:
description: 会话的新标题。仅在更新改变了标题时出现。
type: string
nullable: true
metadata:
description: 更新后会话的完整元数据集合。当更新设置了非空元数据时返回；当元数据未变更或被清空时不返回。
type: object
additionalProperties:
type: string
agent:
description: >-
更新后该会话生效的智能体配置。仅当更新更改了 `agent`（tools 或
mcp_servers）时才会出现；出现时为完整的实体化快照，而非差异。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsSessionAgent'
nullable: true
budget:
description: 更新后会话的 budget：设置或替换时为新 budget，更新将其移除时为 null。仅当更新改变了 budget 时才会返回。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsBudget'
nullable: true
BetaManagedAgentsEventStartEvent:
description: >-
打开一个缓冲事件的预览。仅携带被预览事件的 type 和 ID。随后是零个或多个具有相同事件 ID 的 event_delta
事件，通常由携带该 ID
的缓冲事件收尾。如果产生事件的模型请求在没有该事件的情况下结束（中途出错或被中断），其终止跨度.model_request_end
会关闭该预览。仅在通过 event_deltas 选择加入的流式连接上发送；不会出现在事件历史中。
type: object
additionalProperties: false
required:
- type
- event
properties:
type:
type: string
enum:
- event_start
event:
description: >-
被预览事件的类型和 ID。事件类型决定预览的 `event_delta` 事件所携带的增量类型：`agent.message`
事件流式输出 `content_delta` 片段；`agent.thinking` 预览仅有起始事件，没有后续增量，由具有相同 ID
的已缓冲 `agent.thinking` 事件作结。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsEventStartEvent_Event'
BetaManagedAgentsEventDeltaEvent:
description: >-
对仍在流式传输中的事件的增量更新。增量是尽力而为的，可能提前停止；当生成 ID == event_id
的缓冲事件时，其内容即为完整内容。提前结束的模型请求（出错或中断）不会产生缓冲事件——其终态跨度.model_request_end
会关闭预览。仅在通过 event_deltas 选择启用的流连接上发送；不会出现在事件历史中。
type: object
additionalProperties: false
required:
- type
- event_id
- delta
properties:
type:
type: string
enum:
- event_delta
event_id:
description: 正在预览的事件的 ID。与对应 event_start 以及用于对账该预览的缓冲事件上的 event.ID 一致。
type: string
delta:
description: >-
被预览事件的一个片段。增量类型根据被预览的事件命名：`agent.message` 事件流式传输 `content_delta`
片段，每个片段都是 `content` 数组中的一个部分元素。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsEventDeltaEvent_Delta'
BetaManagedAgentsSystemMessageEvent:
description: '会话中途的 system 消息事件。携带 system 角色的内容，该内容会以 `role: "system"` 轮次的形式追加到会话中。'
type: object
additionalProperties: false
required:
- type
- id
- content
properties:
type:
type: string
enum:
- system.message
id:
description: 此事件的唯一标识符。
type: string
content:
description: 系统内容块。仅文本。
type: array
items:
$ref: '#/components/schemas/BetaManagedAgentsSystemContentBlock'
processed_at:
description: 此系统消息被处理的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
nullable: true
BetaManagedAgentsSessionUsageEvent:
description: 会话累计用量与已跟踪目录价费用的定期快照。
type: object
additionalProperties: false
required:
- type
- id
- processed_at
- usage
properties:
type:
type: string
enum:
- session.usage
id:
description: 此事件的唯一标识符。
type: string
processed_at:
description: 快照创建的时间戳。
allOf:
- $ref: '#/components/schemas/BetaTimestamp'
usage:
description: 会话在快照时间点的累计用量。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsSessionUsageSnapshot'
budget:
description: 快照时刻该会话已配置的预算；会话无预算时为 null。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsBudget'
nullable: true
BetaAPIError:
properties:
message:
default: Internal server error
title: 消息
type: string
type:
const: api_error
default: api_error
title: 类型
type: string
required:
- message
- type
title: APIError
type: object
BetaAuthenticationError:
properties:
message:
default: Authentication error
title: 消息
type: string
type:
const: authentication_error
default: authentication_error
title: 类型
type: string
required:
- message
- type
title: AuthenticationError
type: object
BetaBillingError:
properties:
message:
default: Billing error
title: 消息
type: string
type:
const: billing_error
default: billing_error
title: 类型
type: string
required:
- message
- type
title: BillingError
type: object
BetaInvalidRequestError:
properties:
message:
default: Invalid request
title: 消息
type: string
type:
const: invalid_request_error
default: invalid_request_error
title: 类型
type: string
required:
- message
- type
title: InvalidRequestError
type: object
BetaNotFoundError:
properties:
message:
default: Not found
title: 消息
type: string
type:
const: not_found_error
default: not_found_error
title: 类型
type: string
required:
- message
- type
title: NotFoundError
type: object
BetaOverloadedError:
properties:
message:
default: Overloaded
title: 消息
type: string
type:
const: overloaded_error
default: overloaded_error
title: 类型
type: string
required:
- message
- type
title: OverloadedError
type: object
BetaPermissionError:
properties:
message:
default: Permission denied
title: 消息
type: string
type:
const: permission_error
default: permission_error
title: 类型
type: string
required:
- message
- type
title: PermissionError
type: object
BetaRateLimitError:
properties:
message:
default: Rate limited
title: 消息
type: string
type:
const: rate_limit_error
default: rate_limit_error
title: 类型
type: string
required:
- message
- type
title: RateLimitError
type: object
BetaGatewayTimeoutError:
properties:
message:
default: Request timeout
title: 消息
type: string
type:
const: timeout_error
default: timeout_error
title: 类型
type: string
required:
- message
- type
title: GatewayTimeoutError
type: object
BetaManagedAgentsUserContentBlock:
description: 用户消息中的内容块。可以是 `text`、`image` 或 `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'
BetaTimestamp:
description: RFC 3339 格式的时间戳
type: string
format: date-time
BetaManagedAgentsUserToolConfirmationResult:
type: string
description: UserToolConfirmationResult 枚举
enum:
- allow
- deny
BetaManagedAgentsToolResultContentBlock:
description: 工具结果中的内容块。可以是 `text`、`image`、`document` 或 `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: 智能体消息中的内容块。
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:
- allow
- ask
- deny
BetaManagedAgentsUnknownError:
description: >-
会话执行期间发生了未知或意外的错误。这是一个兜底变体；无法识别新错误码的客户端可以仅根据 `retry_status` 和 `message`
进行匹配。
type: object
additionalProperties: false
required:
- type
- message
- retry_status
properties:
type:
type: string
enum:
- unknown_error
message:
description: 人类可读的错误描述。
type: string
retry_status:
description: 客户端接下来应执行的操作。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsRetryStatus'
BetaManagedAgentsModelOverloadedError:
description: 模型当前已过载。在自动重试耗尽后发出。
type: object
additionalProperties: false
required:
- type
- message
- retry_status
properties:
type:
type: string
enum:
- model_overloaded_error
message:
description: 人类可读的错误描述。
type: string
retry_status:
description: 客户端接下来应执行的操作。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsRetryStatus'
BetaManagedAgentsModelRateLimitedError:
description: 模型请求已被限流。
type: object
additionalProperties: false
required:
- type
- message
- retry_status
properties:
type:
type: string
enum:
- model_rate_limited_error
message:
description: 人类可读的错误描述。
type: string
retry_status:
description: 客户端接下来应执行的操作。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsRetryStatus'
BetaManagedAgentsModelRequestFailedError:
description: 模型请求因过载或限流以外的原因失败。
type: object
additionalProperties: false
required:
- type
- message
- retry_status
properties:
type:
type: string
enum:
- model_request_failed_error
message:
description: 人类可读的错误描述。
type: string
retry_status:
description: 客户端接下来应执行的操作。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsRetryStatus'
BetaManagedAgentsMcpConnectionFailedError:
description: 连接到 MCP 服务器失败。
type: object
additionalProperties: false
required:
- type
- message
- retry_status
- mcp_server_name
properties:
type:
type: string
enum:
- mcp_connection_failed_error
message:
description: 人类可读的错误描述。
type: string
retry_status:
description: 客户端接下来应执行的操作。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsRetryStatus'
mcp_server_name:
description: 连接失败的 MCP 服务器名称。
type: string
BetaManagedAgentsMcpAuthenticationFailedError:
description: MCP 服务器身份验证失败。
type: object
additionalProperties: false
required:
- type
- message
- retry_status
- mcp_server_name
properties:
type:
type: string
enum:
- mcp_authentication_failed_error
message:
description: 人类可读的错误描述。
type: string
retry_status:
description: 客户端接下来应执行的操作。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsRetryStatus'
mcp_server_name:
description: 认证失败的 MCP 服务器名称。
type: string
BetaManagedAgentsBillingError:
description: 调用方的组织或工作区无法发起模型请求——额度已用完或已达到消费上限。使用相同凭据重试不会成功；调用方必须解决账单状态问题。
type: object
additionalProperties: false
required:
- type
- message
- retry_status
properties:
type:
type: string
enum:
- billing_error
message:
description: 人类可读的错误描述。
type: string
retry_status:
description: 客户端接下来应执行的操作。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsRetryStatus'
BetaManagedAgentsCredentialHostUnreachableError:
description: >-
`environment_variable` credential 的 `auth.networking.allowed_hosts`
中包含了该环境的网络策略不允许的主机。
type: object
additionalProperties: false
required:
- type
- message
- retry_status
- vault_id
- credential_id
properties:
type:
type: string
enum:
- credential_host_unreachable_error
message:
description: 人类可读的错误描述。
type: string
retry_status:
description: 客户端接下来应执行的操作。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsRetryStatus'
vault_id:
description: 包含受影响 credential 的密钥库的 ID。
type: string
credential_id:
description: 受影响凭据的 ID。
type: string
BetaManagedAgentsSessionEndTurn:
description: 智能体已自然完成本轮对话，准备好接收下一条用户消息。
type: object
additionalProperties: false
required:
- type
properties:
type:
type: string
enum:
- end_turn
BetaManagedAgentsSessionRequiresAction:
description: 智能体处于空闲状态，等待一个或多个阻塞式用户输入事件（工具确认、自定义工具结果等）。全部解决后，会话将转回 running 状态。
type: object
additionalProperties: false
required:
- type
- event_ids
properties:
type:
type: string
enum:
- requires_action
event_ids:
description: 智能体正被阻塞等待的事件 ID 列表。若只解决了部分事件，将就剩余事件重新发出 `session.status_idle`。
type: array
items:
type: string
BetaManagedAgentsSessionRetriesExhausted:
description: '该轮次已结束，原因是重复错误耗尽了重试预算，或某个错误升级为 `retry_status: ''exhausted''`。'
type: object
additionalProperties: false
required:
- type
properties:
type:
type: string
enum:
- retries_exhausted
BetaManagedAgentsSessionBudgetReached:
description: >-
智能体已停止，原因是会话跟踪的目录价格花费已达到其预算，或其用量中包含没有目录价格的模型（预算无法度量该模型）。请提高预算以继续——如果因某个模型没有目录价格而无法提高，请移除预算。
type: object
additionalProperties: false
required:
- type
properties:
type:
type: string
enum:
- budget_reached
BetaManagedAgentsSpanModelUsage:
description: 单次模型请求的令牌用量。
type: object
additionalProperties: false
required:
- input_tokens
- output_tokens
- cache_creation_input_tokens
- cache_read_input_tokens
properties:
input_tokens:
description: 此请求消耗的输入令牌数。
type: integer
format: int32
output_tokens:
description: 本次请求生成的输出令牌数。
type: integer
format: int32
cache_creation_input_tokens:
description: 本次请求中用于创建提示缓存的令牌数。
type: integer
format: int32
cache_read_input_tokens:
description: 本次请求中从提示缓存读取的令牌数。
type: integer
format: int32
speed:
description: >-
本次请求实际运行的推理速度档位。与 /v1/messages 上的 `usage.speed` 相对应。仅在快速模式 Beta
启用时存在。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsSpeed'
nullable: true
BetaManagedAgentsRubric:
description: 用于评估结果质量的评分标准。
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: 已解析的 `session` 所用 `agent` 定义。`session` 创建时该 `agent` 的快照。
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:
- 我的第一个智能体
description:
type: string
nullable: true
examples:
- 一个通用入门智能体。
model:
$ref: '#/components/schemas/BetaManagedAgentsModelConfig'
examples:
- id: claude-sonnet-4-6
speed: standard
system:
type: string
nullable: true
examples:
- 你是一个通用智能体，可以研究问题、编写代码、运行命令并使用已连接的工具，端到端地完成用户任务。
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: 已解析的多智能体编排配置。当智能体为单线程时为 Null。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsSessionMultiagent'
nullable: true
examples:
- null
example:
type: agent
id: agent_011CZkYpogX7uDKUyvBTophP
version: 1
name: 我的第一个智能体
description: 通用入门智能体。
model:
id: claude-sonnet-4-6
speed: standard
system: 你是一个通用智能体，可以研究问题、编写代码、运行命令并使用已连接的工具，端到端地完成用户任务。
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: 对会话强制执行的消费上限。按 `type` 区分；`limit` 是目前唯一支持的类型。
type: object
discriminator:
propertyName: type
mapping:
limit:
$ref: '#/components/schemas/BetaManagedAgentsBudgetLimit'
oneOf:
- $ref: '#/components/schemas/BetaManagedAgentsBudgetLimit'
BetaManagedAgentsEventStartEvent_Event:
type: object
discriminator:
propertyName: type
mapping:
agent.message:
$ref: >-
#/components/schemas/BetaManagedAgentsEventStartEvent_AgentMessagePreview
agent.thinking:
$ref: >-
#/components/schemas/BetaManagedAgentsEventStartEvent_AgentThinkingPreview
oneOf:
- $ref: >-
#/components/schemas/BetaManagedAgentsEventStartEvent_AgentMessagePreview
- $ref: >-
#/components/schemas/BetaManagedAgentsEventStartEvent_AgentThinkingPreview
BetaManagedAgentsEventDeltaEvent_Delta:
type: object
discriminator:
propertyName: type
mapping:
content_delta:
$ref: '#/components/schemas/BetaManagedAgentsEventDeltaEvent_ContentDelta'
oneOf:
- $ref: '#/components/schemas/BetaManagedAgentsEventDeltaEvent_ContentDelta'
BetaManagedAgentsSystemContentBlock:
description: 对话中途的 system 消息中的内容块。仅支持文本。
type: object
discriminator:
propertyName: type
mapping:
text:
$ref: '#/components/schemas/BetaManagedAgentsTextBlock'
oneOf:
- $ref: '#/components/schemas/BetaManagedAgentsTextBlock'
BetaManagedAgentsSessionUsageSnapshot:
description: 会话累计用量的时间点快照。
type: object
additionalProperties: false
properties:
input_tokens:
description: 所有轮次消耗的输入令牌总数。
type: integer
format: int32
output_tokens:
description: 所有轮次生成的输出令牌总数。
type: integer
format: int32
cache_read_input_tokens:
description: 从提示缓存读取的令牌总数。
type: integer
format: int32
cache_creation:
description: 用于创建提示缓存条目的令牌数量，按缓存 TTL 细分。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsCacheCreationUsage'
list_cost:
description: 会话所有轮次的累计目录价费用，按公开目录价格计算。
allOf:
- $ref: '#/components/schemas/BetaMonetaryAmount'
server_tool_use:
description: 所有轮次中服务端执行工具的累计用量。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsServerToolUsage'
active_seconds:
description: 该会话至少有一个线程处于 running 状态的累计时长（以秒计）。并发线程的重叠活动只计一次。这是会话运行时成本的计费时长。
type: number
format: double
BetaManagedAgentsTextBlock:
description: 普通文本内容。
type: object
additionalProperties: false
required:
- type
- text
properties:
type:
type: string
enum:
- text
examples:
- text
text:
description: 文本内容。
type: string
minLength: 1
examples:
- '我的订单 #1234 到哪里了？'
example:
type: text
text: '我的订单 #1234 到哪里了？'
BetaManagedAgentsImageBlock:
description: 直接以 base64 数据指定，或通过 URL 引用指定的图片内容。
type: object
additionalProperties: false
required:
- type
- source
properties:
type:
type: string
enum:
- image
source:
description: 图像数据的来源。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsImageSource'
BetaManagedAgentsDocumentBlock:
description: 文档内容，可直接指定为 base64 数据、文本，或通过 URL 引用。
type: object
additionalProperties: false
required:
- type
- source
properties:
type:
type: string
enum:
- document
source:
description: 文档数据的来源。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsDocumentSource'
title:
description: 文档的标题。
type: string
nullable: true
context:
description: 为模型提供的有关该文档的附加上下文。
type: string
nullable: true
BetaManagedAgentsRedactedBlock:
description: 被 OMA 模型策略屏蔽的内容的占位符。
type: object
additionalProperties: false
required:
- type
properties:
type:
type: string
enum:
- redacted
BetaManagedAgentsSearchResultBlock:
description: 包含网页搜索结果的块。
type: object
additionalProperties: false
required:
- type
- source
- title
- content
- citations
properties:
type:
type: string
enum:
- search_result
source:
description: 搜索结果的 URL 来源。
type: string
minLength: 1
title:
description: 搜索结果的标题。
type: string
minLength: 1
content:
description: 来自搜索结果的文本内容块数组。
type: array
items:
$ref: '#/components/schemas/BetaManagedAgentsSearchResultContent'
citations:
description: 此搜索结果的引用设置。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsSearchResultCitations'
BetaManagedAgentsRetryStatus:
description: 客户端针对此错误接下来应执行的操作。
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: 推理速度模式。`fast` 以较高价格提供显著更快的输出令牌生成速度。并非所有模型都支持 `fast`；无效组合会在创建时被拒绝。
enum:
- standard
- fast
BetaManagedAgentsFileRubric:
description: 通过文件 API 上传的文件所引用的评分标准。
type: object
additionalProperties: false
required:
- type
- file_id
properties:
type:
type: string
enum:
- file
file_id:
description: rubric 文件的 ID。
type: string
BetaManagedAgentsTextRubric:
description: 以文本形式内联提供的评分标准内容。
type: object
additionalProperties: false
required:
- type
- content
properties:
type:
type: string
enum:
- text
content:
description: 评分标准内容。纯文本或 markdown — 评分器将其视为自由格式文本。
type: string
BetaManagedAgentsModelConfig:
description: 模型标识符和配置。
type: object
additionalProperties: false
required:
- id
properties:
id:
$ref: '#/components/schemas/BetaManagedAgentsModel'
effort:
description: >-
模型在每次推理调用中的努力程度。取值为 `low`、`medium`、`high`、`xhigh`、`max`
之一。始终存在；未提供时会在保存时解析为对应模型的默认值。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsEffort'
examples:
- type: low
inference_geo:
description: 模型推理的地理区域。未设置时，请求将回退到工作区的 default_inference_geo。
type: string
examples:
- inference_geo
speed:
description: >-
推理速度模式。`fast` 以较高价格提供显著更快的输出令牌生成速度。默认为 `standard`。并非所有模型都支持
`fast`；无效组合会在创建时被拒绝。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsSpeed'
examples:
- standard
example:
id: claude-sonnet-4-6
effort:
type: low
inference_geo: inference_geo
speed: standard
BetaManagedAgentsAgentTool:
description: API 响应中返回的工具配置的联合类型。
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: API 响应中返回的 MCP 服务器连接定义的联合类型。
type: object
discriminator:
propertyName: type
mapping:
url:
$ref: '#/components/schemas/BetaManagedAgentsMCPServerURLDefinition'
oneOf:
- $ref: '#/components/schemas/BetaManagedAgentsMCPServerURLDefinition'
BetaManagedAgentsSkill:
description: API 响应中返回的已解析技能。
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: 在 `session` 上返回的已解析多智能体编排配置。
discriminator:
propertyName: type
mapping:
coordinator:
$ref: '#/components/schemas/BetaManagedAgentsSessionMultiagentCoordinator'
oneOf:
- $ref: '#/components/schemas/BetaManagedAgentsSessionMultiagentCoordinator'
BetaManagedAgentsBudgetLimit:
description: 硬性支出上限。一旦跟踪到的列表价成本达到 `max_list_cost`，会话便停止发起新的模型请求。
type: object
additionalProperties: false
required:
- type
- max_list_cost
properties:
type:
type: string
enum:
- limit
max_list_cost:
description: 会话可累计的最高标价费用。无论是否存在协商折扣，均按标价计算，因此该上限会在实际费用达到之时或之前触发。
allOf:
- $ref: '#/components/schemas/BetaMonetaryAmount'
BetaManagedAgentsEventStartEvent_AgentMessagePreview:
type: object
additionalProperties: false
required:
- type
- id
properties:
type:
type: string
enum:
- agent.message
id:
description: >-
缓冲中的 `agent.message` 若被发出，将携带此 ID。该值与预览的 `event_delta` 事件中的
`event_id` 匹配。
type: string
BetaManagedAgentsEventStartEvent_AgentThinkingPreview:
type: object
additionalProperties: false
required:
- type
- id
properties:
type:
type: string
enum:
- agent.thinking
id:
description: >-
若被发出，缓冲的 `agent.thinking` 将携带此 ID。这里只会发出开始事件，不会有后续的 `event_delta`
事件。
type: string
BetaManagedAgentsEventDeltaEvent_ContentDelta:
type: object
additionalProperties: false
required:
- type
- content
properties:
type:
type: string
enum:
- content_delta
index:
description: 此片段落入被预览事件的内容数组中的哪个条目。当该 index 为新值时，将内容作为该条目插入；否则追加到现有条目中。
type: integer
format: uint32
content:
description: >-
`index` 所指位置处 `content` 数组的部分元素，其类型与该元素本身一致，与缓冲的 `agent.message` 在
`content` 中携带的结构相同。
allOf:
- $ref: '#/components/schemas/BetaManagedAgentsTextBlock'
BetaManagedAgentsCacheCreationUsage:
description: 按缓存存活时间细分的提示缓存创建令牌用量。
type: object
additionalProperties: false
properties:
ephemeral_1h_input_tokens:
description: 用于创建 1 小时期临时缓存条目的令牌。
type: integer
format: int32
ephemeral_5m_input_tokens:
description: 用于创建 5 分钟期临时缓存条目的令牌。
type: integer
format: int32
BetaMonetaryAmount:
description: 特定货币的金额。
type: object
additionalProperties: false
required:
- currency
- amount
properties:
currency:
description: 大写的 ISO-4217 货币代码。`USD` 是目前唯一支持的货币；可接受的集合是封闭的，仅在为新货币定价时才会扩充。
allOf:
- $ref: '#/components/schemas/BetaCurrency'
examples:
- USD
amount:
description: >-
以货币最小单位表示的金额，为不带前导零的十进制整数字符串："2500" 表示 $25.00，"50" 表示 50
美分。使用字符串而非数字，以避免应用任何浮点舍入。
type: string
examples:
- '2500'
example:
currency: USD
amount: '2500'
BetaManagedAgentsServerToolUsage:
description: 由服务器执行的工具调用的累计次数，按工具分别统计。
type: object
additionalProperties: false
properties:
web_search_requests:
description: 服务器执行的网页搜索请求数。
type: integer
format: int32
examples:
- 3
web_fetch_requests:
description: 服务器执行的网页抓取请求数。
type: integer
format: int32
examples:
- 0
example:
web_search_requests: 3
web_fetch_requests: 0
BetaManagedAgentsImageSource:
description: 图片来源变体的联合类型。
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: 文档来源变体的联合类型。
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: 搜索结果中的文本内容。
type: object
additionalProperties: false
required:
- type
- text
properties:
type:
type: string
enum:
- text
text:
description: 文本内容。
type: string
minLength: 1
BetaManagedAgentsSearchResultCitations:
description: 搜索结果的引用设置。
type: object
additionalProperties: false
required:
- enabled
properties:
enabled:
description: 此搜索结果是否启用了引用。
type: boolean
BetaManagedAgentsRetryStatusRetrying:
description: >-
服务端正在自动重试。客户端应等待；同一错误类型可能会再次以 retrying 状态出现，然后在重试预算耗尽时以 exhausted
状态出现一次。
type: object
additionalProperties: false
required:
- type
properties:
type:
type: string
enum:
- retrying
BetaManagedAgentsRetryStatusExhausted:
description: 该轮次已失效；排队中的输入被清空，会话恢复为空闲状态。客户端可发送新的提示。
type: object
additionalProperties: false
required:
- type
properties:
type:
type: string
enum:
- exhausted
BetaManagedAgentsRetryStatusTerminal:
description: 会话遇到了终态错误，将转换为 `terminated` 状态。
type: object
additionalProperties: false
required:
- type
properties:
type:
type: string
enum:
- terminal
BetaManagedAgentsModel:
title: BetaManagedAgentsModel
description: |-
为你的智能体提供支持的模型。
更多详情和选项请参阅[模型列表](/docs/zh/api/models/list-models)。
anyOf:
- type: string
- const: claude-sonnet-5
description: 面向编程与智能体的高性能模型
x-stainless-nominal: false
- const: claude-fable-5
description: 面向最艰难的知识工作与编程问题的下一代智能
x-stainless-nominal: false
- const: claude-opus-5
description: 面向长时间运行智能体和编程的强大智能
x-stainless-nominal: false
- const: claude-opus-4-8
description: 面向长时间运行智能体和编程的强大智能
x-stainless-nominal: false
- const: claude-opus-4-7
description: 面向长时间运行智能体和编程的强大智能
x-stainless-nominal: false
- const: claude-opus-4-6
description: 面向长时间运行智能体和编程的强大智能
x-stainless-nominal: false
- const: claude-sonnet-4-6
description: 速度与智能的最佳组合
x-stainless-nominal: false
- const: claude-haiku-4-5
description: 具备接近前沿智能的最快模型
x-stainless-nominal: false
- const: claude-haiku-4-5-20251001
description: 具备接近前沿智能的最快模型
x-stainless-nominal: false
- const: claude-opus-4-5
description: 面向长时间运行智能体和编程的强大智能
x-stainless-nominal: false
- const: claude-opus-4-5-20251101
description: 面向长时间运行智能体和编程的强大智能
x-stainless-nominal: false
- const: claude-sonnet-4-5
description: 面向智能体与编程的高性能模型
x-stainless-nominal: false
- const: claude-sonnet-4-5-20250929
description: 面向智能体与编程的高性能模型
x-stainless-nominal: false
BetaManagedAgentsEffort:
description: 模型在每轮中的努力程度。为该会话发起的每个 Messages 调用设置 `output_config.effort`。
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: API 响应中返回的自定义工具。
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: API 响应中返回的基于 URL 的 MCP 服务器连接。
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: 已解析的 OMA 托管技能。
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: 已解析的用户创建的自定义技能。
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: 已解析的协调器拓扑，包含每个名册成员的完整智能体定义。
type: object
additionalProperties: false
required:
- type
- agents
properties:
type:
type: string
enum:
- coordinator
agents:
description: 协调器可能作为会话线程启动的完整 `agent` 定义。
type: array
items:
$ref: '#/components/schemas/BetaManagedAgentsSessionRosterEntry'
BetaCurrency:
type: string
enum:
- USD
BetaManagedAgentsBase64ImageSource:
description: Base64 编码的图像数据。
type: object
additionalProperties: false
required:
- type
- media_type
- data
properties:
type:
type: string
enum:
- base64
media_type:
description: 图片的 MIME 类型（例如 "image/png"、"image/jpeg"、"image/gif"、"image/webp"）。
type: string
minLength: 1
data:
description: Base64 编码的图像数据。
type: string
minLength: 1
BetaManagedAgentsURLImageSource:
description: 通过 URL 引用的图片。
type: object
additionalProperties: false
required:
- type
- url
properties:
type:
type: string
enum:
- url
url:
description: 要获取的图像 URL。
type: string
minLength: 1
BetaManagedAgentsFileImageSource:
description: 通过文件 ID 引用的图像。
type: object
additionalProperties: false
required:
- type
- file_id
properties:
type:
type: string
enum:
- file
file_id:
description: 先前上传文件的 ID。
type: string
minLength: 1
BetaManagedAgentsBase64DocumentSource:
description: Base64 编码的文档数据。
type: object
additionalProperties: false
required:
- type
- media_type
- data
properties:
type:
type: string
enum:
- base64
media_type:
description: 文档的 MIME 类型（例如 "application/pdf"）。
type: string
minLength: 1
data:
description: Base64 编码的文档数据。
type: string
minLength: 1
BetaManagedAgentsPlainTextDocumentSource:
description: 纯文本文档内容。
type: object
additionalProperties: false
required:
- type
- media_type
- data
properties:
type:
type: string
enum:
- text
media_type:
description: 文本内容的 MIME 类型。必须为 "text/plain"。
type: string
enum:
- text/plain
data:
description: 纯文本内容。
type: string
minLength: 1
BetaManagedAgentsURLDocumentSource:
description: 通过 URL 引用的文档。
type: object
additionalProperties: false
required:
- type
- url
properties:
type:
type: string
enum:
- url
url:
description: 要获取的文档 URL。
type: string
minLength: 1
BetaManagedAgentsFileDocumentSource:
description: 按文件 ID 引用的文档。
type: object
additionalProperties: false
required:
- type
- file_id
properties:
type:
type: string
enum:
- file
file_id:
description: 先前上传文件的 ID。
type: string
minLength: 1
BetaManagedAgentsEffortLow:
description: 低推理强度。优先考虑延迟而非推理深度。
type: object
additionalProperties: false
required:
- type
properties:
type:
type: string
enum:
- low
BetaManagedAgentsEffortMedium:
description: 中等努力级别。平衡延迟与推理深度。
type: object
additionalProperties: false
required:
- type
properties:
type:
type: string
enum:
- medium
BetaManagedAgentsEffortHigh:
description: 高努力级别。偏向推理深度。
type: object
additionalProperties: false
required:
- type
properties:
type:
type: string
enum:
- high
BetaManagedAgentsEffortXhigh:
description: 超高努力级别。并非所有模型都接受此级别。
type: object
additionalProperties: false
required:
- type
properties:
type:
type: string
enum:
- xhigh
BetaManagedAgentsEffortMax:
description: 最高努力级别。倾向于推理深度而非延迟。
type: object
additionalProperties: false
required:
- type
properties:
type:
type: string
enum:
- max
BetaManagedAgentsAgentToolConfig:
description: 特定智能体工具的配置。
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: 智能体工具的已解析默认配置。
type: object
additionalProperties: false
required:
- enabled
- permission_policy
properties:
enabled:
type: boolean
permission_policy:
$ref: '#/components/schemas/BetaManagedAgentsPermissionPolicy'
BetaManagedAgentsMCPToolConfig:
description: 特定 MCP 工具的已解析配置。
type: object
additionalProperties: false
required:
- enabled
- name
- permission_policy
properties:
enabled:
type: boolean
name:
type: string
permission_policy:
$ref: '#/components/schemas/BetaManagedAgentsPermissionPolicy'
BetaManagedAgentsMCPToolsetDefaultConfig:
description: 已解析的来自 MCP 服务器的所有工具的默认配置。
type: object
additionalProperties: false
required:
- enabled
- permission_policy
properties:
enabled:
type: boolean
permission_policy:
$ref: '#/components/schemas/BetaManagedAgentsPermissionPolicy'
BetaManagedAgentsCustomToolInputSchema:
additionalProperties: true
description: 自定义工具输入参数的 JSON 架构。
properties:
type:
const: object
title: 类型
type: string
properties:
anyOf:
- type: object
additionalProperties: true
- type: 'null'
title: 属性
x-stainless-skip:
- terraform
required:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: 必填字段
required:
- type
type: object
BetaManagedAgentsSessionRosterEntry:
description: 由会话解析的 multiagent 名册条目。
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: 内置智能体工具标识符。
enum:
- bash
- edit
- read
- write
- glob
- grep
- web_fetch
- web_search
BetaManagedAgentsPermissionPolicy:
description: 工具执行的权限策略。
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: >-
单个 `session_thread` 所解析出的 `agent` 定义，是线程创建时该智能体的快照。多智能体名册不会在此重复；请从
`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:
- 一个专注于研究的子智能体。
model:
$ref: '#/components/schemas/BetaManagedAgentsModelConfig'
examples:
- id: claude-sonnet-4-6
speed: standard
system:
type: string
nullable: true
examples:
- 你是一个研究型子智能体，负责为协调智能体收集并总结资料来源。
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: 一个专注的调研子智能体。
model:
id: claude-sonnet-4-6
speed: standard
system: 你是一个研究型子智能体，负责为协调智能体收集并总结资料来源。
tools:
- type: agent_toolset_20260401
default_config:
enabled: true
permission_policy:
type: always_ask
configs: []
mcp_servers: []
skills: []
BetaManagedAgentsAdvisor:
description: 平台顾问名册条目：会话主线程在轮次中可咨询的模型。
type: object
additionalProperties: false
required:
- model
- type
properties:
model:
description: 顾问模型 ID。
type: string
type:
type: string
enum:
- advisor
BetaManagedAgentsAlwaysAllowPolicy:
description: 工具调用无需用户确认即自动批准。
type: object
additionalProperties: false
required:
- type
properties:
type:
type: string
enum:
- always_allow
BetaManagedAgentsAlwaysAskPolicy:
description: 工具调用在执行前需要用户确认。
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 工作区 API 密钥。
x-default: sk-ant-local-default
omaBearer:
type: http
scheme: bearer
description: 以 Bearer 令牌形式发送的 OMA 工作区 API 密钥。
````