附录：对象结构与枚举

本附录定义 Cloud SDK 各方法页引用的 171 个具名对象结构和 75 个枚举。在字段表里，点击类型名跳到这里的结构定义；点击允许取值列表后面的“枚举表”链接，或较长枚举的“取值”链接，可逐行查看每个取值。说明译自 OpenAPI 文档；没有说明的字段或取值显示“—”。

对象结构

Schema	类别	使用于
A2AAgentCard	对象	A2A
A2AArtifact	对象	A2A
A2ADataPartOut	对象	A2A
A2AFilePartOut	对象	A2A
A2AMessage	对象	A2A
A2AOutputPart	联合	A2A
A2ATaskStatus	对象	A2A
a2aTaskView	对象	A2A
A2ATextPartOut	对象	A2A
ActiveConversationResponse	对象	会话
AgentAgent	对象	智能体
agentBindDetailsWire	对象	设备绑定
agentBindWire	对象	设备绑定
AgentPage	对象	智能体
AgentPatch	对象	智能体
AgentResponse	对象	智能体
AgentSkill	对象	智能体
AgentSnapshot	对象	智能体
agentTemplateCatalogView	对象	目录
ApprovalModeResult	对象	会话
ApprovalModeResultResponse	对象	会话
ApprovalModeSettings	对象	会话
Binding	对象	身份
BindingNative	变体结构	身份
BindingWeb	变体结构	身份
bindRuntimeWire	对象	设备绑定
CancelConversationInput	对象	会话
CanvasSessionDocument	对象	实例
CanvasShare	对象	画布
CanvasSnapshot	对象	画布
CanvasTicketClaims	对象	实例
CatalogSpec	对象	目录
CatalogSpecValue	对象	目录
CatalogVariant	对象	目录
ClearConversationReceipt	对象	会话
ClearConversationReceiptResponse	对象	会话
ClientSessionInput	对象	身份
ClientSessionInputNative	变体结构	身份
ClientSessionInputWeb	变体结构	身份
ClientSessionResponse	对象	身份
CommandReceipt	对象	会话
CommandReceiptResponse	对象	会话
ConnectURLResponse	对象	实例
Conversation	对象	会话
ConversationPage	对象	会话
ConversationResponse	对象	会话
CreateConversationInput	对象	会话
CreateServerInstanceInput	对象	实例
Deletion	对象	身份
DeletionAccepted	对象	身份
DeployModel	对象	目录
DeployRegion	对象	目录
DeviceBindingErrorResponse	对象	—
ErrorResponse	对象	—
ExternalUserID	string	身份
FileChatUploadContext	对象	文件
FileConfirmInput	对象	文件
FileFile	对象	文件
FileOrigin	对象	文件
FilePage	对象	文件
FilePrepareUploadInput	对象	文件
FileResolution	对象	文件
FileShareResponse	对象	文件
FileSummary	对象	文件
FileTransferDescriptor	对象	文件
InstancePage	对象	实例
InstanceSummary	对象	实例
InstanceTemplate	对象	目录
InstanceTemplatePage	对象	目录
JSONValue	联合	身份, 目录, 实例, 消息, Responses, Harness, 自动化, A2A
Message	对象	消息
MessageContentAgentRefuse	变体结构	消息
MessageContentAgentReply	变体结构	消息
MessageContentChatCancel	变体结构	消息
MessageContentChatMessage	变体结构	消息
MessageContentDeviceCommand	变体结构	消息
MessageContentDeviceError	变体结构	消息
MessageEnvelope	对象	消息
MessageEnvelopeResponse	对象	消息
MessagePage	对象	消息
MessagePartCustom	变体结构	消息
MessagePartFile	变体结构	消息
MessagePartSource	变体结构	消息
MessagePartText	变体结构	消息
MessagePartThinking	变体结构	消息
MessagePartToolResult	变体结构	消息
MessagePartToolUse	变体结构	消息
ModelPage	对象	目录
portalBindWire	对象	设备绑定
ProtoAutomationInput	对象	自动化
ProtoAutomationPatch	对象	自动化
ProtoAutomationRule	对象	自动化
ProtoAutomationRun	对象	自动化
ProtoAutomationRunInput	对象	自动化
ProtoAutomationSchedule	对象	自动化
ProtoAutomationSession	对象	自动化
ProtoAutomationTarget	对象	自动化
ProtoAutomationWebhookInput	对象	自动化
ProtoListAutomationRunsResponse	对象	自动化
ProtoListAutomationsResponse	对象	自动化
Provider	对象	目录
ProviderCapabilities	对象	目录
ProviderPage	对象	目录
RealtimeTicketHeader	对象	实例
ReasoningResult	对象	会话
ReasoningResultResponse	对象	会话
ReasoningSettings	对象	会话
RegionPage	对象	目录
ReplyShareResponse	对象	消息
RuntimeExecResult	对象	实例
RuntimeInstanceResult	对象	实例
RuntimeInstanceStatusResult	对象	实例
RuntimeInstanceSummary	对象	实例
RuntimeLLM	对象	实例
RuntimeLLMModel	对象	实例
RuntimeLLMProvider	对象	实例
RuntimeLLMProviderView	对象	实例
RuntimeLLMView	对象	实例
RuntimeMethodResponse	对象	A2A
RuntimeOperationSummary	对象	实例
RuntimeUpgradeJob	对象	实例
ServerUsageSummary	对象	用量
SetConversationModelInput	对象	会话
TerminalSessionDocument	对象	实例
TerminalTicketClaims	对象	实例
UHPAnnotation	对象	Responses
UHPCapabilities	对象	目录
UHPContentPart	对象	Responses
UHPContentPartOutputText	变体结构	Responses
UHPContentPartSummaryText	变体结构	Responses
UHPCreateResponseRequest	对象	Responses
UHPDiscovery	对象	目录
UHPError	对象	Responses
UHPErrorEnvelope	对象	—
UHPEvent	对象	Responses
UHPEventAnnotationAdded	变体结构	Responses
UHPEventApproval	变体结构	Responses
UHPEventContentPart	变体结构	Responses
UHPEventError	变体结构	Responses
UHPEventFunctionCallArgumentsDelta	变体结构	Responses
UHPEventFunctionCallArgumentsDone	变体结构	Responses
UHPEventOutputItem	变体结构	Responses
UHPEventOutputTextDelta	变体结构	Responses
UHPEventOutputTextDone	变体结构	Responses
UHPEventQuestion	变体结构	Responses
UHPEventReasoningSummaryPart	变体结构	Responses
UHPEventReasoningSummaryTextDelta	变体结构	Responses
UHPEventResponse	变体结构	Responses
UHPHarness	对象	Harness
UHPHarnessCreate	对象	Harness
UHPHarnessModels	对象	Harness
UHPMcpServer	对象	Harness
UHPModel	对象	Harness
UHPModelCatalog	对象	Harness
UHPOutputItem	对象	Responses
UHPOutputItemFunctionCall	变体结构	Responses
UHPOutputItemFunctionCallOutput	变体结构	Responses
UHPOutputItemMessage	变体结构	Responses
UHPOutputItemReasoning	变体结构	Responses
UHPPlugin	对象	Harness
UHPPluginManifest	对象	Harness
UHPPluginMcpServer	对象	Harness
UHPPluginSkill	对象	Harness
UHPPluginSkipped	对象	Harness
UHPResponse	对象	Responses
UHPResponseStatus	枚举	Responses
UHPSkill	对象	Harness
UHPSkillFile	对象	Harness
UHPUsage	对象	Responses
UpdateConversationInput	对象	会话
UpdateServerInstanceInput	对象	实例

A2AAgentCard

—

使用于: A2A

字段	类型	必填	说明
name	string	是	智能体的显示名称。
description	string	是	智能体的描述。
url	string	否	智能体 JSON-RPC 端点的 URL。仅当请求发送 A2A-Version: 0.3 时返回；1.0 版本在 supportedInterfaces 中列出该端点。
version	string	是	智能体的版本：其资源版本，十进制数字。
protocolVersion	string	否	url 所使用的 A2A 协议版本。仅当请求发送 A2A-Version: 0.3 时返回。
defaultInputModes	array<string>	是	智能体接受作为输入的媒体类型，例如 text/plain。
defaultOutputModes	array<string>	是	智能体产出的输出媒体类型，例如 text/plain。
supportedInterfaces	array<object>	否	可以访问该智能体的接口。除非请求发送 A2A-Version: 0.3，否则返回。
supportedInterfaces[].url	string	是	接口的 URL。
supportedInterfaces[].protocolBinding	string	是	该接口使用的传输方式：JSONRPC。
supportedInterfaces[].protocolVersion	string	是	该接口使用的 A2A 协议版本。

A2AArtifact

—

使用于: A2A

字段	类型	必填	说明
artifactId	string	是	产物的 ID。智能体未提供时，服务器使用 <task ID>-a<index>，index 从 0 开始计数。
name	string	否	产物的显示名称。未设置时省略。
description	string	否	产物的描述。未设置时省略。
parts	array<A2AOutputPart>	是	产物的内容，按顺序排列的 part。每个 part 是文本 part、文件 part 或数据 part。
metadata	map<string, JSONValue>	否	附加在产物上的额外元数据。没有时省略。
extensions	array<string>	否	适用于该产物的协议扩展的 URI。没有时省略。

A2ADataPartOut

—

使用于: A2A

字段	类型	必填	说明
data	JSONValue	是	该 part 的结构化内容，可以是任意 JSON 值。 可为 null。
metadata	map<string, JSONValue>	否	附加在该 part 上的额外元数据。没有时省略。

A2AFilePartOut

—

使用于: A2A

字段	类型	必填	说明
url	string	否	可以获取该文件的 URL。未设置时省略。
filename	string	否	文件名。未设置时省略。
mediaType	string	否	文件的媒体类型（MIME 类型）。未设置时省略。
metadata	map<string, JSONValue>	否	附加在该 part 上的额外元数据。没有时省略。

A2AMessage

—

使用于: A2A

字段	类型	必填	说明
messageId	string	是	消息的 ID。服务器为每条渲染的消息生成新的 ID。
role	string	是	消息的作者：ROLE_USER 为调用方，ROLE_AGENT 为智能体。 可选值: "ROLE_USER" — 该消息由调用方撰写; "ROLE_AGENT" — 该消息由智能体撰写. (枚举表)
parts	array<A2AOutputPart>	是	消息的内容，按顺序排列的 part。每个 part 是文本 part、文件 part 或数据 part。
contextId	string	否	消息所属的上下文（会话）的 ID。未设置时省略。
taskId	string	否	消息所属任务的 ID。未设置时省略。
referenceTaskIds	array<string>	否	该消息所引用的其他任务的 ID。没有时省略。
metadata	map<string, JSONValue>	否	附加在消息上的额外元数据。没有时省略。

A2AOutputPart

消息或产物中的一段内容。它是文本 part（text）、文件 part（url、filename、mediaType）或数据 part（data）；具体是哪一种，由它携带的字段决定。

使用于: A2A

联合类型：只会命中其中一种形态。

形态: A2ATextPartOut

字段	类型	必填	说明
text	string	是	该 part 的文本内容。
metadata	map<string, JSONValue>	否	附加在该 part 上的额外元数据。没有时省略。

形态: A2AFilePartOut

字段	类型	必填	说明
url	string	否	可以获取该文件的 URL。未设置时省略。
filename	string	否	文件名。未设置时省略。
mediaType	string	否	文件的媒体类型（MIME 类型）。未设置时省略。
metadata	map<string, JSONValue>	否	附加在该 part 上的额外元数据。没有时省略。

形态: A2ADataPartOut

字段	类型	必填	说明
data	JSONValue	是	该 part 的结构化内容，可以是任意 JSON 值。 可为 null。
metadata	map<string, JSONValue>	否	附加在该 part 上的额外元数据。没有时省略。

A2ATaskStatus

—

使用于: A2A

字段	类型	必填	说明
state	string	是	任务的当前状态。 取值见下表 A2ATaskStatus.state 取值。
message	A2AMessage	否	说明该状态的消息，例如错误文本。它是带一个文本 part 的智能体消息。没有需要报告的内容时省略。 可为 null。
timestamp	string	否	任务最后一次更新的时间；从未更新过则为创建时间，UTC 时间戳，例如 2026-01-02T15:04:05.000Z。

A2ATaskStatus.state 取值

取值	含义
"TASK_STATE_SUBMITTED"	任务已创建，正在等待智能体开始处理。消息送达智能体后也会报告该状态。
"TASK_STATE_WORKING"	智能体正在处理该任务。
"TASK_STATE_COMPLETED"	最终状态。任务成功完成。
"TASK_STATE_FAILED"	最终状态。任务因错误或超时而结束。
"TASK_STATE_CANCELED"	最终状态。任务在完成前被取消。
"TASK_STATE_INPUT_REQUIRED"	任务已暂停：智能体需要调用方提供更多输入才能继续。
"TASK_STATE_REJECTED"	最终状态。智能体拒绝了该任务。
"TASK_STATE_AUTH_REQUIRED"	任务已暂停：智能体需要额外的身份验证才能继续。

a2aTaskView

—

使用于: A2A

字段	类型	必填	说明
id	string	是	任务的 ID。
contextId	string	是	任务所属的上下文（会话）的 ID。
status	A2ATaskStatus	是	任务的当前状态。
artifacts	array<A2AArtifact>	否	智能体为该任务产出的输出。没有时省略。
history	array<A2AMessage>	否	任务的消息。读取单个任务时最多返回其中 history_length 条。没有存储历史时，包含原始请求这一条消息。没有时省略。
metadata	map<string, JSONValue>	否	任务的额外元数据。没有时省略。
caller_principal_id	string	是	提交该任务的主体的 ID。
caller_agent_id	string	是	提交该任务的智能体的 ID（如果有）。
caller_owner_id	string	是	提交方所有者的 ID。Cloud 根据凭证的组织和应用派生该值。调用方不发送终端用户 ID。
target_principal_id	string	是	任务所发送给的主体的 ID。
target_agent_id	string	是	任务所发送给的智能体的 ID。
target_owner_id	string	是	接收方所有者的 ID。
channel_id	string	否	承载该任务流式回复的通道的 ID。任务不使用基于通道的投递时省略。
created_at	string	否	任务的创建时间，UTC 时间戳，例如 2026-01-02T15:04:05.000Z。未知时省略。
updated_at	string	否	任务最后一次更新的时间，格式与 created_at 相同。未知时省略。
completed_at	string	否	任务结束的时间，格式与 created_at 相同。任务结束之前省略。

A2ATextPartOut

—

使用于: A2A

字段	类型	必填	说明
text	string	是	该 part 的文本内容。
metadata	map<string, JSONValue>	否	附加在该 part 上的额外元数据。没有时省略。

ActiveConversationResponse

—

使用于: 会话

字段	类型	必填	说明
response_id	string	是	正在生成的响应的 ID。与 responses API 配合使用。
last_event_id	string	是	为该响应记录的最新事件的 ID。把它作为 Last-Event-ID 发送，即可从该事件之后继续该响应的事件流。
user_message_id	string	否	启动该响应的 chat_message 的 ID。未记录时省略。
reply_message_id	string	否	智能体的回复所写入的消息的 ID。回复消息存在之前省略。

AgentAgent

—

使用于: 智能体

字段	类型	必填	说明
id	string	是	智能体的 ID。
instance_id	string	是	智能体所运行的实例的 ID。
name	string	是	智能体的名称。
avatar_url	string	否	智能体头像图片的 URL。未设置时省略。
display_name	string	否	智能体的可读名称。未设置时省略。
description	string	是	智能体的描述。未设置时为空。
resource_version	integer	是	更新智能体时作为 If-Match 发送的智能体版本，带双引号。读取或更新单个智能体时，ETag header 返回相同的值。
status	string	是	智能体当前是否由其实例提供。 可选值: "active" — 该实例当前提供此智能体; "inactive" — 该实例不再提供此智能体，例如实例已被移除，或已被同名的另一个智能体替换。记录会保留. (枚举表)
visibility	string	是	所有者以外的哪些调用方可以使用该智能体。用更新操作修改。 取值见下表 AgentAgent.visibility 取值。
mcp_enabled	boolean	是	智能体是否通过 BeeOS MCP 端点作为工具发布。
a2a_enabled	boolean	是	智能体是否接受 Agent-to-Agent（A2A）请求。为 false 时，针对该智能体的 A2A 请求会被拒绝，返回 403 a2a_disabled。
capabilities	map<string, boolean>	是	智能体支持的功能，为把功能名映射到 true 或 false 的对象。已知名称包括 canvas、terminal、webSsh、fileSystem、image、audio、mcp、cron、streaming、pushNotifications、a2a、extendedAgentCard、multipleConversations、loadConversation、createConversation、modelsList、modelsSet、skillsList、skillsInstall、skillsUninstall、skillsUpdate 和 automationWake。缺失或为 false 的名称表示智能体不支持该功能。以后可能新增名称，请忽略不认识的名称。
skills	array<AgentSkill>	是	智能体的 skill。
conversation_transport	string	是	会话消息如何到达智能体。以后可能新增取值，请忽略不认识的取值。 可选值: "acp" — 会话消息通过智能体的 ACP 连接与其交换; "message-service" — 会话消息通过 BeeOS 消息服务以消息的形式投递给智能体. (枚举表)
created_at	string	是	智能体的创建时间，RFC 3339 格式。 约束: format=date-time.
updated_at	string	是	智能体最后一次变更的时间，RFC 3339 格式。 约束: format=date-time.

AgentAgent.visibility 取值

取值	含义
"private"	所有者以外的调用方不能调用该智能体或读取其 agent card，也不会出现在目录中。
"unlisted"	所有者以外的调用方只要知道智能体的 ID，就可以调用该智能体并读取其 agent card。它不会出现在目录中。
"org"	保留取值。该值可以提交，但目前不会让所有者以外的调用方获得该智能体的访问权限。
"public"	所有者以外的调用方可以调用该智能体并读取其 agent card，并且它会出现在目录中。
"marketplace"	该智能体会出现在目录中。这是此取值唯一的作用：所有者以外的调用方不能按 ID 调用该智能体或读取其 agent card。

agentBindDetailsWire

—

使用于: 设备绑定

字段	类型	必填	说明
bind_id	string	是	绑定会话的 ID。
hostname	string	是	设备上报的主机名。
fingerprint_short	string	是	设备密钥指纹的前 16 个字符。展示给用户，与设备上的比对。
harness	string	是	设备所运行的 harness，与设备上报的一致。
os_type	string	否	设备上报的操作系统。未上报时省略。
expires_at	integer	是	会话过期的时间，Unix 秒。
status	string	是	绑定会话的状态。已过期的会话会被删除，因此对已过期会话的查询会失败，返回 404 not_found。 可选值: "pending" — 由设备创建，等待用户确认; "confirming" — 用户已确认，正在为该设备创建实例; "bound" — 已确认：实例存在，设备可以连接它. (枚举表)
server_time	integer	是	当前服务器时间，Unix 秒。与 expires_at 比较，可以在没有时钟偏差的情况下得到剩余时间。

agentBindWire

—

使用于: 设备绑定

字段	类型	必填	说明
status	string	是	绑定会话的状态。确认成功后为 bound；仍在等待确认的会话报告 pending。 可选值: "pending" — 由设备创建，等待用户确认。正在确认的会话也报告 pending; "bound" — 已确认：实例存在，设备可以连接它. (枚举表)
bind_id	string	否	绑定会话的 ID。
instance_id	string	否	为设备创建的实例的 ID。会话绑定后出现。
public_key	string	否	设备为该会话注册的公钥。
hostname	string	否	设备上报的主机名。
expires_at	integer	否	会话过期的时间，Unix 秒。
runtime_binding	bindRuntimeWire	否	已绑定的自托管智能体所连接的地址。会话绑定后出现。 可为 null。

AgentPage

—

使用于: 智能体

字段	类型	必填	说明
data	array<AgentAgent>	是	本页的智能体，最新的在前。
total	integer	是	符合过滤条件的智能体总数，跨所有页。

AgentPatch

要修改的暴露设置。至少发送一个字段；省略的字段保持当前值。

使用于: 智能体

字段	类型	必填	说明
visibility	string	否	智能体的新可见性。取值见智能体的 visibility 字段。 取值见下表 AgentPatch.visibility 取值。
mcp_enabled	boolean	否	设为 true 把智能体通过 BeeOS MCP 端点作为工具发布；设为 false 则停止发布。
a2a_enabled	boolean	否	设为 true 让智能体接受 Agent-to-Agent（A2A）请求；设为 false 则拒绝，返回 403 a2a_disabled。

AgentPatch.visibility 取值

取值	含义
"private"	所有者以外的调用方不能调用该智能体或读取其 agent card，也不会出现在目录中。
"unlisted"	所有者以外的调用方只要知道智能体的 ID，就可以调用该智能体并读取其 agent card。它不会出现在目录中。
"org"	保留取值。该值可以提交，但目前不会让所有者以外的调用方获得该智能体的访问权限。
"public"	所有者以外的调用方可以调用该智能体并读取其 agent card，并且它会出现在目录中。
"marketplace"	该智能体会出现在目录中。这是此取值唯一的作用：所有者以外的调用方不能按 ID 调用该智能体或读取其 agent card。

AgentResponse

—

使用于: 智能体

字段	类型	必填	说明
data	AgentSnapshot	是	智能体。

AgentSkill

—

使用于: 智能体

字段	类型	必填	说明
id	string	是	skill 的 ID。实例未上报时为空。
name	string	是	skill 的名称。
description	string	是	该 skill 的作用。
tags	array<string>	是	描述该 skill 的标签。没有时为空。
enabled	boolean	是	该 skill 当前是否已为智能体启用。

AgentSnapshot

—

使用于: 智能体

字段	类型	必填	说明
id	string	是	智能体的 ID。
instance_id	string	是	智能体所运行的实例的 ID。
name	string	是	智能体的名称。
display_name	string	否	智能体的可读名称。未设置时省略。
description	string	是	智能体的描述。未设置时为空。
status	string	是	智能体当前是否由其实例提供。 可选值: "active" — 该实例当前提供此智能体; "inactive" — 该实例不再提供此智能体，例如实例已被移除，或已被同名的另一个智能体替换。记录会保留. (枚举表)
visibility	string	是	所有者以外的哪些调用方可以使用该智能体。用更新操作修改。 取值见下表 AgentSnapshot.visibility 取值。
conversation_transport	string	是	会话消息如何到达智能体。以后可能新增取值，请忽略不认识的取值。 可选值: "acp" — 会话消息通过智能体的 ACP 连接与其交换; "message-service" — 会话消息通过 BeeOS 消息服务以消息的形式投递给智能体. (枚举表)
resource_version	integer	是	更新智能体时作为 If-Match 发送的智能体版本，带双引号。读取或更新单个智能体时，ETag header 返回相同的值。 约束: minimum=1, format=int64.
mcp_enabled	boolean	是	智能体是否通过 BeeOS MCP 端点作为工具发布。
a2a_enabled	boolean	是	智能体是否接受 Agent-to-Agent（A2A）请求。为 false 时，针对该智能体的 A2A 请求会被拒绝，返回 403 a2a_disabled。
capabilities	map<string, boolean>	是	智能体支持的功能，为把功能名映射到 true 或 false 的对象。已知名称包括 canvas、terminal、webSsh、fileSystem、image、audio、mcp、cron、streaming、pushNotifications、a2a、extendedAgentCard、multipleConversations、loadConversation、createConversation、modelsList、modelsSet、skillsList、skillsInstall、skillsUninstall、skillsUpdate 和 automationWake。缺失或为 false 的名称表示智能体不支持该功能。以后可能新增名称，请忽略不认识的名称。
skills	array<AgentSkill>	是	智能体的 skill。
created_at	string	是	智能体的创建时间，RFC 3339 格式。 约束: format=date-time.
updated_at	string	是	智能体最后一次变更的时间，RFC 3339 格式。 约束: format=date-time.

AgentSnapshot.visibility 取值

取值	含义
"private"	所有者以外的调用方不能调用该智能体或读取其 agent card，也不会出现在目录中。
"unlisted"	所有者以外的调用方只要知道智能体的 ID，就可以调用该智能体并读取其 agent card。它不会出现在目录中。
"org"	保留取值。该值可以提交，但目前不会让所有者以外的调用方获得该智能体的访问权限。
"public"	所有者以外的调用方可以调用该智能体并读取其 agent card，并且它会出现在目录中。
"marketplace"	该智能体会出现在目录中。这是此取值唯一的作用：所有者以外的调用方不能按 ID 调用该智能体或读取其 agent card。

agentTemplateCatalogView

—

使用于: 目录

字段	类型	必填	说明
id	string	是	模板的 ID。用该模板创建 harness 时，把它作为 template_id 传入。
display_name	string	是	模板的显示名称；存在翻译时，使用 Accept-Language 的语言。
summary	string	是	一句话概括模板的用途，与 display_name 一样做了本地化。
description	string	是	模板的完整描述，与 display_name 一样做了本地化。
category	string	是	模板所列入的类别。可用作 list 操作的 category 过滤条件。
vibe	string	是	描述该模板所创建的智能体个性的短语，与 display_name 一样做了本地化。
icon_url	string	是	模板图标的 URL。模板没有时为空。
banner_url	string	是	模板横幅图片的 URL。模板没有时为空。
default_model	string	是	模板选为智能体主模型的模型的 ID。
tags	array<string>	是	描述模板的标签。
harness	string	是	模板所适用的 harness（智能体运行时），例如 openclaw。
template_version	string	是	模板包的版本，语义化版本号，例如 1.2.0。

ApprovalModeResult

—

使用于: 会话

字段	类型	必填	说明
approval_mode	string	是	当前对会话生效的审批模式。null 表示使用实例默认值。 可为 null。
metadata_version	integer	是	本次变更之后的会话设置版本。把它带双引号作为下一次更新的 If-Match 发送。ETag header 也会返回它。 约束: minimum=1, format=int64.
status	string	是	调用返回时该变更的结果。 可选值: "completed" — 审批模式已在调用返回前变更.

ApprovalModeResultResponse

—

使用于: 会话

字段	类型	必填	说明
data	ApprovalModeResult	是	变更的结果。

ApprovalModeSettings

—

使用于: 会话

字段	类型	必填	说明
approval_mode	string	是	要为会话设置的审批模式：小写字母、数字和下划线，以字母开头，最多 32 个字符。目前定义的模式有 ask 和 full。以后可能新增模式，智能体会把不认识的模式当作 ask。发送 null 可移除该设置，使用实例默认值。 可为 null。 约束: minLength=1, maxLength=32, pattern=^[a-z][a-z0-9_]*$.

Binding

—

使用于: 身份

字段	类型	必填	说明
client_type	string	是	token 如何绑定到客户端。 可选值: "web" — 绑定到网页来源，在 origin 中返回; "native" — 绑定到设备密钥，其指纹在 cnf_jkt 中返回. (枚举表) 按 client_type 区分的结构：见变体表。
origin	string	否	token 所绑定的来源。client_type 为 web 时返回。 约束: format=uri.
cnf_jkt	string	否	token 所绑定的设备密钥的指纹。client_type 为 native 时返回。

Binding 按 client_type 区分

Binding 的结构取决于它自己的 client_type 值。

client_type 的取值	说明	结构
"web"	绑定到网页来源，在 origin 中返回。	BindingWeb
"native"	绑定到设备密钥，其指纹在 cnf_jkt 中返回。	BindingNative

BindingNative

token 到设备密钥的绑定。

使用于: 身份

字段	类型	必填	说明
client_type	string	是	始终为 native。
cnf_jkt	string	是	token 所绑定的设备密钥的指纹。client_type 为 native 时返回。

接受额外属性。

BindingWeb

token 到网页来源的绑定。

使用于: 身份

字段	类型	必填	说明
client_type	string	是	始终为 web。
origin	string	是	token 所绑定的来源。client_type 为 web 时返回。 约束: format=uri.

接受额外属性。

bindRuntimeWire

—

使用于: 设备绑定

字段	类型	必填	说明
instance_id	string	是	智能体所绑定的实例的 ID。
agent_gateway_url	string	是	智能体为智能体流量所连接的 API 的基础 URL。
message_service_url	string	是	智能体为消息所连接的 API 的基础 URL。

CancelConversationInput

—

使用于: 会话

字段	类型	必填	说明
target_message_id	string	是	要停止其轮次的 chat_message 的 ID，1 到 256 个字符。 约束: minLength=1, maxLength=256.
reason	string	否	停止该轮的原因，自由文本，最多 256 个字符。省略或为空时记录为 user_request。 约束: maxLength=256.

CanvasSessionDocument

—

使用于: 实例

字段	类型	必填	说明
transport	string	是	ticket 的连接方式：始终为 relay。
protocolVersion	integer	是	ticket 协议的版本。目前为 1。
header	RealtimeTicketHeader	是	已签名 ticket 的 header。
relayUrl	string	是	该画布的画布中继 WebSocket URL，以 /ws/{canvasId} 结尾。
ticket	string	是	已签名的一次性 ticket（JWT），授权一次中继连接。有效期为 60 秒。
issuedAt	string	是	ticket 的签发时间，RFC 3339 时间戳。 约束: format=date-time.
expiresAt	string	是	ticket 的过期时间，RFC 3339 时间戳。ticket 的有效期为 60 秒。 约束: format=date-time.
claims	CanvasTicketClaims	是	已签名 ticket 中包含的 claims。

CanvasShare

—

使用于: 画布

字段	类型	必填	说明
id	string	是	分享的唯一 ID。
canvasId	string	是	被分享的画布的 ID。一个画布最多有一个分享。
slug	string	是	分享的公开标识，用于构造分享链接。更新分享时保持不变。
mode	string	是	访客如何获得访问权。password 要求访客输入创建分享时设置的密码。其他任何值（例如 link）表示任何拥有链接的人都可以打开画布。
allowInteraction	boolean	是	访客是否可以与画布交互。为 false 时，访客只能查看。
expiresAt	string	否	分享失效的时间，RFC 3339 时间戳。分享不过期时省略；通过此 API 创建的分享永不过期。
createdAt	string	是	分享首次创建的时间，RFC 3339 时间戳。更新分享不会改变它。

CanvasSnapshot

—

使用于: 画布

字段	类型	必填	说明
id	string	是	快照的唯一 ID。把它传给 restore 操作。
canvasId	string	是	快照所属画布的 ID。
componentsSnapshot	string	否	生成快照时画布的内容，为 base64 编码的 JSON：surface 数组，每个都有 surfaceId、presentation、components 和 root。未捕获内容时省略。
actorType	string	是	做出快照所记录的大部分变更的操作者类型：user 为人（还原点也记录为 user），agent 为智能体，system 为没有已知操作者的自动快照。
actorId	string	是	actorType 所指的操作者的 ID。没有已知操作者的自动快照为 system。
description	string	否	关于快照的简短备注，例如自动快照为 Auto-snapshot，还原点为 Restored from v3。没有时省略。
version	integer	是	快照所记录的画布内容的版本。数字越大越新。
createdAt	string	是	生成快照的时间，RFC 3339 时间戳。

CanvasTicketClaims

—

使用于: 实例

字段	类型	必填	说明
iss	string	是	ticket 的签发者。
sub	string	是	未使用。Cloud 不接受外部用户 ID，因此该声明为空。
jti	string	是	ticket 的唯一 ID。
purpose	string	是	ticket 的用途：始终为 canvas_session。
instance_id	string	是	该画布所属实例的 ID。
platform_agent_id	string	是	该画布会话所针对的 agent 的 ID，即请求中的 platformAgentId。
client_id	string	是	为这次中继客户端连接生成的 ID。
conversation_id	string	是	该画布所属会话的 ID，即请求中的 conversationId。
canvas_id	string	是	ticket 授予访问权限的画布的 ID。
role	string	是	在该画布上授予的访问角色：viewer 或 editor。 可选值: "viewer" — 可以查看画布，但不能修改; "editor" — 可以查看和编辑画布. (枚举表)
session_id	string	是	为该 ticket 创建的实时会话的 ID。
aud	array<string>	是	ticket 的目标受众：画布中继。
iat	integer	是	ticket 的签发时间，Unix 秒。
exp	integer	是	ticket 的过期时间，Unix 秒。

CatalogSpec

—

使用于: 目录

字段	类型	必填	说明
id	string	是	—
name	string	是	—
label	string	是	—
values	array<CatalogSpecValue>	是	—

CatalogSpecValue

—

使用于: 目录

字段	类型	必填	说明
id	string	是	—
name	string	是	—
label	string	是	—
sort_order	integer	是	—

CatalogVariant

—

使用于: 目录

字段	类型	必填	说明
id	string	是	variant 的 ID。创建实例时作为 variant_id 发送。
spec_value_ids	array<string>	是	—
sort_order	integer	是	—

ClearConversationReceipt

—

使用于: 会话

字段	类型	必填	说明
request_id	string	是	清空操作的 ID。用相同的 Idempotency-Key 重试会返回相同的 ID。
conversation_id	string	是	被清空的会话的 ID。
current_generation	integer	是	清空之后的历史代数。更早代数的消息不再属于会话历史。 约束: minimum=0, format=int64.
status	string	是	调用返回时清空操作的结果。 可选值: "completed" — 历史记录已在调用返回前清除.

ClearConversationReceiptResponse

—

使用于: 会话

字段	类型	必填	说明
data	ClearConversationReceipt	是	清空操作的回执。

ClientSessionInput

—

使用于: 身份

字段	类型	必填	说明
client_type	string	是	客户端 token 如何绑定到将使用它的客户端。它决定你发送 origin 还是 device_attestation。 可选值: "web" — 浏览器客户端。token 绑定到你在 origin 中发送的页面来源，该来源必须是应用配置的允许来源之一。不得发送 device_attestation。与此绑定不符的请求返回 403 invalid_origin; "native" — 原生应用。token 绑定到设备密钥，其指纹由你在 device_attestation.jkt 中发送。不得发送 origin。与此绑定不符的请求返回 403 invalid_origin. (枚举表) 按 client_type 区分的结构：见变体表。
requested_capabilities	array<string>	是	客户端 token 可以在 Client API 上执行的操作，1 个或多个互不相同的名称。每个名称必须是 context:read、instances:read、instances:write、agents:read、agents:invoke、files:read、files:write、files:delete、events:read、viewer:connect 和 terminal:connect 之一，并且必须是你应用的客户端所允许的。其他任何名称返回 403 invalid_capability。 约束: minItems=1, uniqueItems.
origin	string	否	将使用该 token 的网页的来源，例如 https://app.example.com。client_type 为 web 时必填，且必须与应用配置的允许来源之一完全一致；否则请求返回 403 invalid_origin。client_type 为 native 时不允许，同样返回 403 invalid_origin。 约束: format=uri.
device_attestation	object	否	token 所绑定的设备密钥的证明。client_type 为 native 时必填；client_type 为 web 时不允许，返回 403 invalid_origin。
device_attestation.jkt	string	是	设备公钥的指纹，即 base64url 编码的 SHA-256 JWK 指纹，至少 16 个字符。之后的 Client API 请求必须用对应的私钥签名。 约束: minLength=16.
ttl_seconds	integer	否	本次签发请求的 token 有效期，单位为秒。显式给出的值若在 60..1800 之外，返回 400 invalid_request。 默认值: 600. 约束: minimum=60, maximum=1800.

ClientSessionInput 按 client_type 区分

ClientSessionInput 的结构取决于它自己的 client_type 值。

client_type 的取值	说明	结构
"web"	浏览器客户端。token 绑定到你在 origin 中发送的页面来源，该来源必须是应用配置的允许来源之一。不得发送 device_attestation。与此绑定不符的请求返回 403 invalid_origin。	ClientSessionInputWeb
"native"	原生应用。token 绑定到设备密钥，其指纹由你在 device_attestation.jkt 中发送。不得发送 origin。与此绑定不符的请求返回 403 invalid_origin。	ClientSessionInputNative

ClientSessionInputNative

绑定到设备密钥的 token 请求。

使用于: 身份

字段	类型	必填	说明
client_type	string	是	始终为 native。
device_attestation	object	是	token 所绑定的设备密钥的证明。client_type 为 native 时必填；client_type 为 web 时不允许，返回 403 invalid_origin。
device_attestation.jkt	string	是	设备公钥的指纹，即 base64url 编码的 SHA-256 JWK 指纹，至少 16 个字符。之后的 Client API 请求必须用对应的私钥签名。 约束: minLength=16.
requested_capabilities	array<string>	是	客户端 token 可以在 Client API 上执行的操作，1 个或多个互不相同的名称。每个名称必须是 context:read、instances:read、instances:write、agents:read、agents:invoke、files:read、files:write、files:delete、events:read、viewer:connect 和 terminal:connect 之一，并且必须是你应用的客户端所允许的。其他任何名称返回 403 invalid_capability。 约束: minItems=1, uniqueItems.
ttl_seconds	integer	否	本次签发请求的 token 有效期，单位为秒。显式给出的值若在 60..1800 之外，返回 400 invalid_request。 默认值: 600. 约束: minimum=60, maximum=1800.

接受额外属性。

ClientSessionInputWeb

绑定到网页来源的 token 请求。

使用于: 身份

字段	类型	必填	说明
client_type	string	是	始终为 web。
origin	string	是	将使用该 token 的网页的来源，例如 https://app.example.com。client_type 为 web 时必填，且必须与应用配置的允许来源之一完全一致；否则请求返回 403 invalid_origin。client_type 为 native 时不允许，同样返回 403 invalid_origin。 约束: format=uri.
requested_capabilities	array<string>	是	客户端 token 可以在 Client API 上执行的操作，1 个或多个互不相同的名称。每个名称必须是 context:read、instances:read、instances:write、agents:read、agents:invoke、files:read、files:write、files:delete、events:read、viewer:connect 和 terminal:connect 之一，并且必须是你应用的客户端所允许的。其他任何名称返回 403 invalid_capability。 约束: minItems=1, uniqueItems.
ttl_seconds	integer	否	本次签发请求的 token 有效期，单位为秒。显式给出的值若在 60..1800 之外，返回 400 invalid_request。 默认值: 600. 约束: minimum=60, maximum=1800.

接受额外属性。

ClientSessionResponse

—

使用于: 身份

字段	类型	必填	说明
access_token	string	是	作为 bearer 凭证发送给 Client API 的客户端 token。它只在本次响应中显示，请在客户端安全保存，切勿记录到日志。 只写。
client_api_url	string	是	接受 access_token 的 Client API 的基础 URL。 可选值: "https://client-api.cloud.beeos.ai/v1" — 生产环境的 Client API.
expires_at	string	是	所签发 token 的实际过期时间，受会话授权剩余有效期的上限约束。 约束: format=date-time.
session_id	string	是	客户端会话的 ID。用它刷新或撤销会话。刷新会为同一会话签发新的 token。
app_id	string	是	会话所属应用的 ID。
external_user_id	string	是	未使用。Cloud 不接受外部用户 ID。已存储的会话将此字段留空。
capabilities	array<string>	是	token 可以在 Client API 上执行的操作。即请求的能力，已去重。
binding	Binding	是	token 如何绑定到客户端，与创建会话时的请求一致。

CommandReceipt

—

使用于: 会话

字段	类型	必填	说明
request_id	string	是	请求的 ID。对于取消和恢复，它标识发给智能体的控制消息；对于模型变更，它是本次 HTTP 请求的 ID。
status	string	是	调用返回时请求的结果。 可选值: "accepted" — 请求已排队等待智能体处理，尚未生效。请读取会话消息以跟踪结果; "completed" — 变更已在调用返回前生效. (枚举表)

CommandReceiptResponse

—

使用于: 会话

字段	类型	必填	说明
data	CommandReceipt	是	请求的回执。

ConnectURLResponse

—

使用于: 实例

字段	类型	必填	说明
data	object	是	所请求服务的连接详情。
data.url	string	是	要连接的 URL。browser 时是浏览器查看端 URL；acp 时是一个 WebSocket URL，访问 ticket 已作为查询参数包含在内。
data.mode	string	是	连接模式：browser 对应 browser-runtime，acp 对应 service-websocket。 可选值: "browser-runtime" — 浏览器查看会话；使用 url 和 token 连接; "service-websocket" — 到智能体服务的 WebSocket 连接；url 已带有访问 ticket. (枚举表)
data.token	string	是	浏览器查看端使用的短期访问 token。acp 不返回。
data.service	string	是	该 URL 所连接的服务：browser 或 acp。 可选值: "browser" — 浏览器查看器; "acp" — 通过 WebSocket 连接智能体. (枚举表)
data.connectivity	string	是	实例中 agent 的可达性：unknown、online 或 offline。 可选值: "unknown" — 尚未确定可达性; "online" — 该实例的智能体已连接; "offline" — 该实例的智能体未连接. (枚举表)
data.stream_session_id	string	是	查看端 client session 的 ID，即请求中发送的 client_id。acp 不返回。
data.browser	object	否	浏览器访问授权。仅在 browser 时返回。
data.browser.grant_id	string	是	浏览器访问授权的 ID。
data.browser.generation	string	是	该授权所绑定的浏览器 generation。如果请求中发送了 generation，则与该值相同。
data.browser.expires_at	string	是	访问授权过期的时间，Unix 毫秒。
data.browser.role	string	是	该授权的访问角色：viewer 或 controller。 可选值: "viewer" — 可以查看浏览器，但不能控制; "controller" — 可以查看并控制浏览器. (枚举表)

Conversation

—

使用于: 会话

字段	类型	必填	说明
id	string	是	会话的 ID。 约束: minLength=1.
agent_id	string	是	会话所对应的智能体的 ID，即 agents API 返回的 id。 约束: minLength=1.
instance_id	string	是	智能体所运行的实例的 ID。 约束: minLength=1.
title	string	是	会话的标题。未设置标题时为空。
state	string	是	会话是否仍接受消息。已关闭的会话仍可读取，但不能接收新消息。 可选值: "open" — 会话接受新消息; "closed" — 会话已关闭，例如被删除。closed_at 已设置，向其发送消息返回 410 conversation_closed. (枚举表)
metadata_version	integer	是	会话设置（标题、模型覆盖、推理和审批模式）的版本。每次变更加一。它始终等于 resource_version。 约束: minimum=1, format=int64.
history_generation	integer	是	会话历史的代数。每次清空历史时加一，因此值越大，表示最近一次清空之前发送的消息不再属于历史。 约束: minimum=0, format=int64.
created_at	string	是	会话的创建时间，RFC 3339 格式。 约束: format=date-time.
last_activity_at	string	否	会话中最近一次活动的时间，RFC 3339 格式。没有记录活动时省略。 约束: format=date-time.
closed_at	string	否	会话关闭的时间，RFC 3339 格式。会话打开期间省略。 约束: format=date-time.
resource_version	integer	是	重命名会话、或修改其模型、推理或审批模式时，作为 If-Match 发送的会话版本，带双引号。读取或更新单个会话时，ETag header 返回相同的值。 约束: minimum=1, format=int64.
model_override_id	string	否	覆盖该会话中智能体默认模型的模型 ID。未设置覆盖时省略。
effective_model_id	string	否	保留字段。Server API 目前不返回该字段；请使用 model_override_id。
active_response	ActiveConversationResponse	否	会话中当前正在生成的响应。只有读取单个会话、且有响应正在进行时才返回。
reasoning	ReasoningSettings	否	为会话设置的推理选择：模型及为其选择的推理选项。未设置时省略。model_override_id 变化时会清除它。
approval_mode	string	否	为会话设置的审批模式。未设置、使用实例默认值时省略。 可为 null。

ConversationPage

—

使用于: 会话

字段	类型	必填	说明
conversations	array<Conversation>	是	本页的会话。
next_cursor	string	否	作为 cursor 传入以获取下一页的游标。has_more 为 false 时为空。
has_more	boolean	是	本页之后是否还有更多会话。

ConversationResponse

—

使用于: 会话

字段	类型	必填	说明
data	Conversation	是	该会话。

CreateConversationInput

—

使用于: 会话

字段	类型	必填	说明
title	string	否	新会话的标题，最多 512 字节的有效 UTF-8。省略则创建没有标题的会话。 约束: maxLength=256.

CreateServerInstanceInput

—

使用于: 实例

字段	类型	必填	说明
name	string	是	实例的显示名称，1 到 128 字节，首尾不能有空白。
variant_id	string	否	用于创建实例的目录 variant 的 ID，最多 128 个字符。可用的 variant 见实例模板目录。未知 ID 返回 404 variant_not_found。
harness	string	否	在实例中运行的 harness。只接受 openclaw。 可选值: "openclaw" — OpenClaw 智能体运行时.
llm	RuntimeLLM	否	实例使用的模型 provider 和模型。当 variant 或 harness 需要调用方提供模型时必填；自带模型的 variant 请省略。Provider API key 为只写。 可为 null。

Deletion

—

使用于: 身份

字段	类型	必填	说明
id	string	是	删除任务的 ID。
status	string	是	删除的状态。轮询直到其为 completed。 可选值: "pending" — 删除已排队，尚未开始; "processing" — 删除正在进行; "failed" — 最近一次尝试因错误而停止，错误见 error_code。删除会自动重试; "completed" — 该用户的全部数据已被删除. (枚举表)
deleted_resources	map<string, integer>	是	目前已删除的条目数量，为把数据种类映射到计数的对象。status 为 completed 时计数为最终值。种类可能新增，因此不要依赖固定的键集合。

DeletionAccepted

—

使用于: 身份

字段	类型	必填	说明
deletion_id	string	是	删除任务的 ID。用它读取删除进度。
status	string	是	请求被接受时删除的状态。 可选值: "pending" — 删除已排队，尚未开始; "processing" — 删除正在进行; "failed" — 最近一次尝试因错误而停止，错误见 error_code。删除会自动重试; "completed" — 该用户的全部数据已被删除. (枚举表)

DeployModel

—

使用于: 目录

字段	类型	必填	说明
id	string	是	模型的 ID，通常为 provider/model 形式。
name	string	是	模型的显示名称。
tier	string	否	—
reasoning	boolean	否	—
input	array<string>	否	—
context_window	integer	否	模型的最大上下文窗口，单位为 token。

DeployRegion

—

使用于: 目录

字段	类型	必填	说明
id	string	是	区域的 ID。
name	string	是	区域的显示名称。
available	boolean	是	该区域当前是否可用。

DeviceBindingErrorResponse

—

使用于: —

字段	类型	必填	说明
error	string	是	机器可读的错误码。设备绑定路由返回 invalid_request、unauthorized、not_found、conflict、binding_unavailable 或 bridge_unavailable。认证和实例错误还可能返回其他错误码，请忽略不认识的错误码。
message	string	是	错误的可读说明。不要解析它。

ErrorResponse

—

使用于: —

字段	类型	必填	说明
code	string	是	稳定的、机器可读的错误码，例如 invalid_request、version_mismatch 或 instance_not_found。
message	string	是	面向人的错误描述。请在代码中用 code 而不是此文本做分支判断。
request_id	string	是	请求的 ID，用于支持与追踪。

ExternalUserID

不透明的应用内标识符。恰为点段的值 '.' 和 '..' 被 T03-20260905-01 保留。

使用于: 身份

类型: string

约束: minLength=1, maxLength=128.

FileChatUploadContext

—

使用于: 文件

字段	类型	必填	说明
instance_id	string	是	文件所上传给的实例的 ID。它必须属于你的应用。
agent_id	string	否	文件所上传给的智能体的 ID。它必须属于该实例。可选。

FileConfirmInput

—

使用于: 文件

字段	类型	必填	说明
checksum_sha256	string	否	已上传内容的小写十六进制 SHA-256 摘要（64 个字符）。可选。发送时，会与已存储对象的摘要比较，不一致则确认失败，返回 409 checksum_mismatch。

FileFile

—

使用于: 文件

字段	类型	必填	说明
file_id	string	是	文件的唯一 ID。
filename	string	是	文件名，不含路径。
content_type	string	是	文件的 MIME 类型，例如 image/png。
size_bytes	integer	是	文件大小，单位字节。
checksum_sha256	string	否	文件内容的小写十六进制 SHA-256 摘要。上传时未提供校验和、且对象上也没有记录时为空。
status	string	是	文件的上传状态。已删除的文件永远不会返回。以后可能新增状态，请忽略不认识的取值。 可选值: "pending_upload" — 上传已准备好，但尚未确认。文件还没有可下载的内容; "ready" — 上传已确认。文件可以下载、重命名、分享和删除. (枚举表)
resource_version	integer	是	文件记录的版本。从 1 开始，在上传被确认、以及文件被重命名或删除时增加。
updated_at	string	是	文件最后一次变更的时间：创建、确认或重命名，取最晚的一次。RFC 3339 时间戳。 约束: format=date-time.
title	string	否	从文档自身元数据中读取的标题。对不超过 8 MiB 的 PDF、docx、xlsx 和 pptx 文件，在首次按 ID 读取时提取；文档没有可用标题时省略。
file_type	string	是	文件的类别，由其 MIME 类型得出；对于 application/octet-stream 这类通用类型，则由扩展名得出。 取值见下表 FileFile.file_type 取值。
created_at	string	是	文件记录的创建时间，即准备上传时。RFC 3339 时间戳。 约束: format=date-time.
confirmed_at	string	否	上传被确认的时间。文件就绪之前省略。RFC 3339 时间戳。 可为 null。 约束: format=date-time.
origin	FileOrigin	否	文件的来源，以及它所属的实例和智能体。 可为 null。

FileFile.file_type 取值

取值	含义
"FILE_TYPE_IMAGE"	图片，例如 PNG、JPEG、GIF、WebP 或 SVG。
"FILE_TYPE_VIDEO"	视频，例如 MP4、MOV 或 WebM。
"FILE_TYPE_AUDIO"	音频文件，例如 MP3、WAV 或 FLAC。
"FILE_TYPE_DOCUMENT"	文本或办公文档，例如纯文本、Markdown、JSON、PDF、Word、Excel、PowerPoint 或 OpenDocument。
"FILE_TYPE_ARCHIVE"	压缩或打包的归档文件，例如 ZIP、TAR、GZIP、7z 或 RAR。
"FILE_TYPE_OTHER"	其他任何文件。

FileOrigin

—

使用于: 文件

字段	类型	必填	说明
source	string	是	文件是如何产生的。以后可能新增取值，请忽略不认识的取值。 可选值: "manual" — 通过 files API 直接上传，不带 upload context。没有记录来源的文件按 manual 报告; "chat_upload" — 带 upload_context 上传，用于与其所指定的智能体的会话; "runtime_generated" — 由智能体在处理请求时生成。operation_id 标识该操作; "template_skill" — 由模板 skill 提供。该文件只读：不能重命名或删除，也不计入存储用量. (枚举表)
instance_id	string	否	文件所属实例的 ID。与实例无关的文件省略。
agent_id	string	否	文件所属智能体的 ID。与智能体无关的文件省略。
operation_id	string	否	生成该文件的智能体操作的 ID。仅当 source 为 runtime_generated 时设置。
instance_name	string	否	实例当前的显示名称，在返回文件时填充。没有实例的文件省略。
agent_name	string	否	智能体当前的显示名称，在返回文件时填充。没有智能体的文件省略。
avatar_url	string	否	智能体头像的 URL。没有智能体的文件省略。
harness	string	否	实例运行的 harness，例如 openclaw。没有实例的文件省略。
destroyed	boolean	否	实例已被终止或删除时为 true。文件仍然可用。为 false 时省略。

FilePage

—

使用于: 文件

字段	类型	必填	说明
data	array<FileFile>	是	本页的文件。
total	integer	是	符合查询条件的文件数量，跨所有页。
next_since	string	否	作为 since 传入以获取下一页的游标。只有默认的按时间顺序列表才返回，且仅在后面还有文件时返回。经过过滤或排序的列表改用 offset 分页。

FilePrepareUploadInput

—

使用于: 文件

字段	类型	必填	说明
upload_context	FileChatUploadContext	否	把上传关联到一个实例，也可以关联到一个智能体。文件归该凭证的组织和应用所有。普通上传请省略该上下文。 可为 null。
filename	string	是	文件名，1 到 255 个字符，首尾不含空白，且不含 /、\ 或控制字符。
content_type	string	是	文件的 MIME 类型，最多 255 个字符，不含控制字符。上传的内容必须是该类型。
size_bytes	integer	是	文件大小，单位为字节，1 到 104857600（100 MiB）。上传的内容必须正好是这个大小。
checksum_sha256	string	否	内容的小写十六进制 SHA-256 摘要（64 个字符）。可选。发送时，上传的内容必须与之一致，确认时会校验。

FileResolution

—

使用于: 文件

字段	类型	必填	说明
file	FileFile	是	该文件。
download	FileTransferDescriptor	是	用于下载内容的预签名描述。文件仍为 pending_upload 时，它不带可用的 URL。

FileShareResponse

—

使用于: 文件

字段	类型	必填	说明
file_id	string	是	被分享文件的 ID。
slug	string	是	分享的公开 slug。把它传给 resolve-share 操作以获取文件。
filename	string	是	被分享文件的当前名称。
content_type	string	是	被分享文件的 MIME 类型。
size_bytes	integer	是	被分享文件的大小，单位为字节。
revoked	boolean	是	分享已被撤销时为 true。已撤销的分享不能再被解析。再次创建分享会重新启用它。

FileSummary

—

使用于: 文件

字段	类型	必填	说明
file_count	integer	是	就绪文件的数量。
storage_file_count	integer	是	计入存储的就绪文件的数量。模板 skill 提供的文件不计入。
used_bytes	integer	是	计入存储的文件的总大小，单位为字节。
image_count	integer	是	FILE_TYPE_IMAGE 类别中就绪文件的数量。
video_count	integer	是	FILE_TYPE_VIDEO 类别中就绪文件的数量。
document_count	integer	是	FILE_TYPE_DOCUMENT 类别中就绪文件的数量。
instances	array<object>	是	就绪文件按所属智能体分组，没有智能体的按实例分组，最大的组在前。
instances[].source	string	是	文件是如何产生的。以后可能新增取值，请忽略不认识的取值。 可选值: "manual" — 通过 files API 直接上传，不带 upload context。没有记录来源的文件按 manual 报告; "chat_upload" — 带 upload_context 上传，用于与其所指定的智能体的会话; "runtime_generated" — 由智能体在处理请求时生成。operation_id 标识该操作; "template_skill" — 由模板 skill 提供。该文件只读：不能重命名或删除，也不计入存储用量. (枚举表)
instances[].instance_id	string	否	文件所属实例的 ID。与实例无关的文件省略。
instances[].agent_id	string	否	文件所属智能体的 ID。与智能体无关的文件省略。
instances[].operation_id	string	否	生成该文件的智能体操作的 ID。仅当 source 为 runtime_generated 时设置。
instances[].instance_name	string	否	实例当前的显示名称，在返回文件时填充。没有实例的文件省略。
instances[].agent_name	string	否	智能体当前的显示名称，在返回文件时填充。没有智能体的文件省略。
instances[].avatar_url	string	否	智能体头像的 URL。没有智能体的文件省略。
instances[].harness	string	否	实例运行的 harness，例如 openclaw。没有实例的文件省略。
instances[].destroyed	boolean	否	实例已被终止或删除时为 true。文件仍然可用。为 false 时省略。
instances[].count	integer	是	该组中就绪文件的数量。

FileTransferDescriptor

—

使用于: 文件

字段	类型	必填	说明
direction	string	是	该 URL 用于上传还是下载文件内容。 可选值: "upload" — 用 http_method 把文件内容发送到 url。准备上传时返回; "download" — 用 http_method 从 url 获取文件内容。读取文件或分享时返回. (枚举表)
file_id	string	是	该传输所针对的文件的 ID。
url	string	是	用于传输文件内容的预签名 URL。该 URL 已签名，因此不要向它发送你的 API key。
http_method	string	是	配合 url 使用的 HTTP 方法：上传用 PUT，下载用 GET。
required_headers	map<string, string>	是	传输请求中要原样发送的 header。不需要时为空。
expires_at	string	是	URL 失效的时间，RFC 3339 时间戳。上传 URL 有效期为 15 分钟，下载 URL 为 5 分钟。 约束: format=date-time.
content_type	string	是	文件的 MIME 类型。
size_bytes	integer	是	文件大小，单位字节。
checksum_sha256	string	否	文件内容的小写十六进制 SHA-256 摘要。不知道摘要时省略。

InstancePage

—

使用于: 实例

字段	类型	必填	说明
data	array<InstanceSummary>	是	本页的实例，最新的在前。
total	integer	是	符合筛选条件的实例总数，跨所有页。

InstanceSummary

—

使用于: 实例

字段	类型	必填	说明
has_ever_run	boolean	是	实例是否曾到达过 running 状态。false 表示它从未提供过运行中的服务。
id	string	是	实例的唯一 ID。
organization_id	string	是	拥有该实例的组织的 ID。
app_id	string	是	实例所属应用的 ID。
developer_id	string	是	创建该实例所用的开发者账号的 ID。
name	string	是	实例的显示名称。
harness	string	是	产品 harness 名称（例如 openclaw），不是 UHP 的 harness_id（chrn_*）。
provider_id	string	是	托管该实例的 provider 的 ID。
region	string	是	实例部署所在的区域。
os_type	string	是	实例的操作系统：linux、windows、android 或 macos。
status	string	是	实例的生命周期阶段：pending、provisioning、running、stopped 或 terminated。 取值见下表 InstanceSummary.status 取值。
desired_status	string	是	实例正被驱动朝向的生命周期阶段：running、stopped 或 terminated。 可选值: "running" — 实例应处于运行状态; "stopped" — 实例应处于停止状态; "terminated" — 实例应被删除. (枚举表)
connectivity	string	是	实例中 agent 的可达性：unknown、online 或 offline。 可选值: "unknown" — 尚未确定可达性; "online" — 该实例的智能体已连接; "offline" — 该实例的智能体未连接. (枚举表)
ms_connection_status	string	是	实例消息通道连接的状态：unknown、connecting、connected、reconnecting、disconnected 或 failed。它独立于 connectivity 上报；实例处于停止或已终止状态、或最近没有上报时为 unknown。
created_at	string	是	实例的创建时间，RFC 3339 UTC 时间戳。
updated_at	string	是	实例的最后更新时间，RFC 3339 UTC 时间戳。
resource_version	integer	是	实例记录的版本，从 1 开始。请在写请求的 If-Match 头中发送它，以便检测并发修改。 约束: minimum=1, format=int64.
image_slot	string	否	Variant 特性。为实例选择执行镜像的键。不是容器仓库名称。
worker_image_id	string	否	Variant 特性。AgentBay worker 镜像。绝不是平台的 image_id。
model_catalog	string	否	Variant 特性。Cloud 响应模型列表和 reasoning 级别请求时为 served，两者都不响应时为 none。空值和未知值按 none 处理。
billing_slot	string	否	Variant 特性。为该实例定价的月费表的键。
icon_key	string	否	Variant 特性。UI 图标选择器。客户端不得从 harness 推导它。
device_control	boolean	否	Variant 特性。实例是否接受设备控制命令。false 表示这些命令会被拒绝。
runtime_profile	string	否	Variant 特性。实例所使用的 agent 运行时的 profile。已知值为 openclaw、hermes 和 beeos-browser。
free_plan	boolean	否	Variant 特性。免费套餐是否允许该实例的 variant。false 表示免费套餐不允许。
cloud_provider	string	否	agentbay、beeos，自托管时为空。

InstanceSummary.status 取值

取值	含义
"pending"	实例已创建，正在等待预配。
"provisioning"	实例正在预配或启动。
"running"	实例正在运行。
"stopped"	实例已停止，可以再次启动。
"terminated"	实例已删除，不能再使用。

InstanceTemplate

—

使用于: 目录

字段	类型	必填	说明
id	string	是	模板的 ID。
name	string	是	模板的显示名称。
description	string	否	模板的描述。
logo_url	string	否	—
sort_order	integer	否	—
harness	string	否	—
provider_id	string	否	—
specs	array<CatalogSpec>	否	—
variants	array<CatalogVariant>	否	模板的可部署 variant。创建实例时，把 variant 的 id 作为 variant_id 发送。

InstanceTemplatePage

—

使用于: 目录

字段	类型	必填	说明
data	array<InstanceTemplate>	是	所请求页上的模板。
total	integer	是	符合过滤条件的模板总数，跨所有页。

JSONValue

真正开放的 JSON 值（provider/插件参数或任意元数据）。

使用于: 身份, 目录, 实例, 消息, Responses, Harness, 自动化, A2A

联合类型：只会命中其中一种形态。

• boolean
• number
• string
• array<JSONValue>
• map<string, JSONValue>

Message

—

使用于: 消息

字段	类型	必填	说明
id	string	是	消息的 ID。
conversation_id	string	是	消息所属会话的 ID。
type	string	是	消息的类型。用它区分调用方的提示、智能体的回复和其他消息。以后可能新增类型，请忽略不认识的取值。 取值见下表 Message.type 取值。
content	JSONValue	是	消息的 JSON 负载。其结构取决于 type，见该字段列出的变体。当前的智能体回复请改读 body 和 parts。服务端返回前会移除其中的 metadata 和 from 键。 按 Message.type 区分的结构：见变体表。
sender	string	是	发送消息的身份。其他发送者显示为各自的身份 ID。
reply_to	string	否	本消息所回复的消息 ID，例如 agent_reply 所回答的 chat_message。不是回复的消息省略此字段。
created_at	string	是	消息的创建时间，RFC 3339 格式。 约束: format=date-time.
offset	integer	是	消息在会话历史中的位置。越新的消息 offset 越大。 约束: format=int64.
history_generation	integer	是	消息所属的会话历史代数。 约束: format=int64.
state	string	否	消息的生命周期状态。消息从 streaming 开始，恰好一次转入某个最终状态；进入最终状态的消息不再变化。在引入状态之前保存的消息 state 为空，视为最终状态。 取值见下表 Message.state 取值。
stop_reason	string	否	消息进入最终状态的原因。只出现在最终状态的消息上；原因未知时可能为空。 取值见下表 Message.stop_reason 取值。
body	string	否	消息文本。对仍在 streaming 的回复，为目前已生成的文本。
parts	array<map<string, JSONValue>>	否	按顺序排列的消息结构化部分，例如推理、工具调用、文件和来源。每个部分都有 type，见该字段元素列出的变体。 按 type 区分的结构：见变体表。
updated_at	string	否	消息最后一次变更的时间，RFC 3339 格式。从未更新过则省略。 约束: format=date-time.
runtime_dispatch	map<string, JSONValue>	否	把消息交给智能体运行时的结果，为包含 status 和 code 的对象。只有为该消息记录了投递结果时才存在，否则省略。
realtime_publish_status	string	否	保留字段。Server API 目前不返回该字段。 可选值: "published", "unconfirmed", "not_republished". (枚举表)

Message.type 取值

取值	含义
"chat_message"	调用方发给智能体的提示。
"agent_reply"	智能体对 chat_message 的回复。state 为 streaming 时回复仍在生成，body 为目前已生成的文本。
"agent_reply_error"	智能体的错误回复，作为独立的消息类型发送，而不是带错误的 agent_reply。
"agent.refuse"	智能体拒绝处理该消息。content 包含 reason（例如智能体正在处理另一轮时为 agent_busy）和可读的 message。
"agent_busy"	agent.refuse 的旧名称，部分智能体运行时仍会发送。按同样方式处理。
"agent_reply_delta"	仍在生成的智能体回复的一个片段。
"agent_reasoning"	智能体的推理（“思考”）文本。它作为独立消息保存在所属 agent_reply 旁边，具有相同的 reply_to，推理文本在 body 中。它永远不是最终答案。
"a2a_status_update"	智能体间（A2A）任务的状态变化。
"a2a_result"	A2A 任务的最终结果，在任务完成或无法派发时发送。
"agent_request"	为 A2A 任务投递给智能体的任务请求。
"a2a_task"	A2A 任务的第一条消息，在任务以队列模式派发时发布。
"chat_cancel"	停止智能体处理较早 chat_message 的这一轮的请求。content 包含 target_message_id 和可选的 reason。
"device_command"	一次用于控制设备或电脑的工具调用，例如截图、点击或输入。智能体直接在设备上执行，不经过模型轮次。
"device_result"	device_command 的成功结果。reply_to 为该命令的 ID。
"device_error"	device_command 的失败结果。content 包含 error 和 code。

Message.state 取值

取值	含义
"streaming"	消息仍在生成中，body 和 parts 还可能变化。
"completed"	消息正常完成。
"failed"	智能体未能完成该消息。
"refused"	智能体拒绝回答。body 为拒绝说明文本。
"cancelled"	消息在完成前被请求中止。

Message.stop_reason 取值

取值	含义
"end_turn"	智能体正常完成了本轮。
"max_tokens"	智能体完成前已达到输出上限。
"tool_use"	智能体为调用工具而停止。
"user_stop"	用户停止了智能体。
"timeout"	智能体完成前已达到时间上限。
"error"	智能体因错误而停止。
"refused"	智能体拒绝回答。
"content_filter"	回复被内容过滤器中止。
"agent_lost"	服务端结束了该消息，因为生成它的智能体已不再运行，例如崩溃或被替换。

Message.content 按 Message.type 区分

Message.content 的结构取决于Message.type。

Message.type 的取值	说明	结构
"chat_message"	调用方发给智能体的提示。	MessageContentChatMessage
"agent_reply"	智能体对 chat_message 的回复。state 为 streaming 时回复仍在生成，body 为目前已生成的文本。	MessageContentAgentReply
"agent_reply_error"	智能体的错误回复，作为独立的消息类型发送，而不是带错误的 agent_reply。	MessageContentAgentReply
"agent.refuse"	智能体拒绝处理该消息。content 包含 reason（例如智能体正在处理另一轮时为 agent_busy）和可读的 message。	MessageContentAgentRefuse
"agent_busy"	agent.refuse 的旧名称，部分智能体运行时仍会发送。按同样方式处理。	MessageContentAgentRefuse
"chat_cancel"	停止智能体处理较早 chat_message 的这一轮的请求。content 包含 target_message_id 和可选的 reason。	MessageContentChatCancel
"device_command"	一次用于控制设备或电脑的工具调用，例如截图、点击或输入。智能体直接在设备上执行，不经过模型轮次。	MessageContentDeviceCommand
"device_error"	device_command 的失败结果。content 包含 error 和 code。	MessageContentDeviceError

Message.parts[] 按 type 区分

Message.parts[] 的结构取决于它自己的 type 值。

type 的取值	说明	结构
"text"	回复文本的一段。	MessagePartText
"thinking"	智能体推理的一段。	MessagePartThinking
"tool_use"	智能体发起的工具调用。	MessagePartToolUse
"tool_result"	工具调用的结果。	MessagePartToolResult
"file"	附加在消息上的文件。图片、音频和视频都是 file 部分，用 mime_type 区分。	MessagePartFile
"source"	被引用的来源或参考。	MessagePartSource
"custom"	没有专用类型的结构化内容的扩展部分。kind 说明它是什么。	MessagePartCustom

MessageContentAgentRefuse

智能体拒绝任务的消息的内容。

使用于: 消息

字段	类型	必填	说明
reason	string	否	智能体拒绝的原因，例如 agent_busy。
message	string	否	可读的说明。

接受额外属性。

MessageContentAgentReply

智能体回复的内容。成功的回复带 text，失败的回复带 error。

使用于: 消息

字段	类型	必填	说明
text	string	否	回复文本。
error	string	否	回复失败时的错误信息。

接受额外属性。

MessageContentChatCancel

停止智能体这一轮的请求的内容。

使用于: 消息

字段	类型	必填	说明
target_message_id	string	是	需要停止其这一轮的 chat_message 的 ID。
reason	string	否	这一轮应当停止的原因：canceled、caller_disconnected 或 timeout。

接受额外属性。

MessageContentChatMessage

发给智能体的提示的内容。

使用于: 消息

字段	类型	必填	说明
message	string	是	提示文本。

接受额外属性。

MessageContentDeviceCommand

设备工具调用的内容。

使用于: 消息

字段	类型	必填	说明
tool	string	否	要运行的设备工具名称，例如 screenshot、click 或 tap。
args	JSONValue	否	工具的参数，取决于具体工具。 可为 null。
channel_id	string	否	命令所属会话的 ID。
context_id	string	否	命令所属会话的 ID。

接受额外属性。

MessageContentDeviceError

设备工具调用失败的内容。

使用于: 消息

字段	类型	必填	说明
error	string	否	可读的错误信息。
code	string	否	设备工具报告的失败类型，例如 unsupported、invalid_args 或 internal_error。

接受额外属性。

MessageEnvelope

—

使用于: 消息

字段	类型	必填	说明
id	string	是	消息的 ID。
conversation_id	string	是	消息所属会话的 ID。
type	string	是	消息的类型。用它区分调用方的提示、智能体的回复和其他消息。以后可能新增类型，请忽略不认识的取值。 取值见下表 MessageEnvelope.type 取值。
sender	string	是	发送消息的身份。其他发送者显示为各自的身份 ID。
reply_to	string	否	本消息所回复的消息 ID，例如 agent_reply 所回答的 chat_message。不是回复的消息省略此字段。
body	string	是	消息文本。对仍在 streaming 的回复，为目前已生成的文本。
parts	array<map<string, JSONValue>>	否	按顺序排列的消息结构化部分，例如推理、工具调用、文件和来源。每个部分都有 type，见该字段元素列出的变体。 按 type 区分的结构：见变体表。
state	string	是	消息的生命周期状态。消息从 streaming 开始，恰好一次转入某个最终状态；进入最终状态的消息不再变化。在引入状态之前保存的消息 state 为空，视为最终状态。 取值见下表 MessageEnvelope.state 取值。
stop_reason	string	否	消息进入最终状态的原因。只出现在最终状态的消息上；原因未知时可能为空。 取值见下表 MessageEnvelope.stop_reason 取值。
content	JSONValue	否	保留字段。Server API 目前不返回该字段；请读取 body 和 parts。
created_at	string	否	消息的创建时间，RFC 3339 格式。 约束: format=date-time.
updated_at	string	否	消息最后一次变更的时间，RFC 3339 格式。从未更新过则省略。 约束: format=date-time.

MessageEnvelope.type 取值

取值	含义
"chat_message"	调用方发给智能体的提示。
"agent_reply"	智能体对 chat_message 的回复。state 为 streaming 时回复仍在生成，body 为目前已生成的文本。
"agent_reply_error"	智能体的错误回复，作为独立的消息类型发送，而不是带错误的 agent_reply。
"agent.refuse"	智能体拒绝处理该消息。content 包含 reason（例如智能体正在处理另一轮时为 agent_busy）和可读的 message。
"agent_busy"	agent.refuse 的旧名称，部分智能体运行时仍会发送。按同样方式处理。
"agent_reply_delta"	仍在生成的智能体回复的一个片段。
"agent_reasoning"	智能体的推理（“思考”）文本。它作为独立消息保存在所属 agent_reply 旁边，具有相同的 reply_to，推理文本在 body 中。它永远不是最终答案。
"a2a_status_update"	智能体间（A2A）任务的状态变化。
"a2a_result"	A2A 任务的最终结果，在任务完成或无法派发时发送。
"agent_request"	为 A2A 任务投递给智能体的任务请求。
"a2a_task"	A2A 任务的第一条消息，在任务以队列模式派发时发布。
"chat_cancel"	停止智能体处理较早 chat_message 的这一轮的请求。content 包含 target_message_id 和可选的 reason。
"device_command"	一次用于控制设备或电脑的工具调用，例如截图、点击或输入。智能体直接在设备上执行，不经过模型轮次。
"device_result"	device_command 的成功结果。reply_to 为该命令的 ID。
"device_error"	device_command 的失败结果。content 包含 error 和 code。

MessageEnvelope.state 取值

取值	含义
"streaming"	消息仍在生成中，body 和 parts 还可能变化。
"completed"	消息正常完成。
"failed"	智能体未能完成该消息。
"refused"	智能体拒绝回答。body 为拒绝说明文本。
"cancelled"	消息在完成前被请求中止。

MessageEnvelope.stop_reason 取值

取值	含义
"end_turn"	智能体正常完成了本轮。
"max_tokens"	智能体完成前已达到输出上限。
"tool_use"	智能体为调用工具而停止。
"user_stop"	用户停止了智能体。
"timeout"	智能体完成前已达到时间上限。
"error"	智能体因错误而停止。
"refused"	智能体拒绝回答。
"content_filter"	回复被内容过滤器中止。
"agent_lost"	服务端结束了该消息，因为生成它的智能体已不再运行，例如崩溃或被替换。

MessageEnvelope.parts[] 按 type 区分

MessageEnvelope.parts[] 的结构取决于它自己的 type 值。

type 的取值	说明	结构
"text"	回复文本的一段。	MessagePartText
"thinking"	智能体推理的一段。	MessagePartThinking
"tool_use"	智能体发起的工具调用。	MessagePartToolUse
"tool_result"	工具调用的结果。	MessagePartToolResult
"file"	附加在消息上的文件。图片、音频和视频都是 file 部分，用 mime_type 区分。	MessagePartFile
"source"	被引用的来源或参考。	MessagePartSource
"custom"	没有专用类型的结构化内容的扩展部分。kind 说明它是什么。	MessagePartCustom

MessageEnvelopeResponse

—

使用于: 消息

字段	类型	必填	说明
data	MessageEnvelope	是	消息。

MessagePage

—

使用于: 消息

字段	类型	必填	说明
messages	array<Message>	是	本页的消息。
next_cursor	string	否	作为 cursor 传入以获取下一页的游标。has_more 为 false 时为空。
has_more	boolean	是	本页之后是否还有更多消息。
latest_offset	integer	是	本页扫描的 offset 上界。它不是历史边界；历史边界请用 history_boundary_offset。 约束: format=int64.
history_generation	integer	是	本页所读取的会话历史代数。 约束: format=int64.
history_boundary_offset	integer	是	当前代数的历史边界 offset：清空或恢复历史后，历史起点被移动到的位置。 约束: format=int64.

MessagePartCustom

没有专用类型的结构化内容的扩展部分。kind 说明它是什么。

使用于: 消息

字段	类型	必填	说明
type	string	是	固定为 custom。
kind	string	否	自定义部分的种类。
data	JSONValue	否	该部分的 JSON 负载，取决于 kind。 可为 null。

接受额外属性。

MessagePartFile

附加在消息上的文件。图片、音频和视频都是 file 部分，用 mime_type 区分。

使用于: 消息

字段	类型	必填	说明
type	string	是	固定为 file。
url	string	否	文件的 URL。
mime_type	string	否	文件的 MIME 类型，例如 image/png。
name	string	否	文件名。
size	integer	否	文件大小，单位字节。 约束: format=int64.

接受额外属性。

MessagePartSource

被引用的来源或参考。

使用于: 消息

字段	类型	必填	说明
type	string	是	固定为 source。
url	string	否	来源的 URL。
title	string	否	来源的标题。
snippet	string	否	来源的摘录。

接受额外属性。

MessagePartText

回复文本的一段。

使用于: 消息

字段	类型	必填	说明
type	string	是	固定为 text。
text	string	否	文本。

接受额外属性。

MessagePartThinking

智能体推理的一段。

使用于: 消息

字段	类型	必填	说明
type	string	是	固定为 thinking。
text	string	否	推理文本。
state	string	否	推理是否仍在生成中。 可选值: "streaming" — 该部分仍在生成中; "done" — 该部分已完成。缺少 state 也表示已完成. (枚举表)

接受额外属性。

MessagePartToolResult

工具调用的结果。

使用于: 消息

字段	类型	必填	说明
type	string	是	固定为 tool_result。
tool_use_id	string	否	该结果所属的 tool_use 部分的 ID。
content	JSONValue	否	工具的结果：JSON 对象或纯字符串。 可为 null。
is_error	boolean	否	工具调用是否失败。

接受额外属性。

MessagePartToolUse

智能体发起的工具调用。

使用于: 消息

字段	类型	必填	说明
type	string	是	固定为 tool_use。
id	string	否	工具调用的 ID。tool_result 部分通过 tool_use_id 引用它。
name	string	否	工具名称。
arguments	JSONValue	否	调用参数，JSON 格式。 可为 null。
state	string	否	参数是否仍在生成中。 可选值: "streaming" — 该部分仍在生成中; "done" — 该部分已完成。缺少 state 也表示已完成. (枚举表)

接受额外属性。

ModelPage

—

使用于: 目录

字段	类型	必填	说明
data	array<DeployModel>	是	符合过滤条件的模型。
total	integer	是	符合过滤条件的模型数量。

portalBindWire

—

使用于: 设备绑定

字段	类型	必填	说明
provider_id	string	否	承载该实例的提供方的 ID。为设备创建了新实例时设置。
bind_id	string	是	绑定会话的 ID。以 portal_ 开头。
short_code	string	是	用户可以在设备上输入的短码，用于代替扫描二维码。使用大写字母和数字，不含易混淆的字符。
status	string	是	portal 绑定会话的状态。已过期的会话会被删除，因此对已过期会话的查询会失败，返回 404 not_found。 取值见下表 portalBindWire.status 取值。
instance_id	string	否	绑定到设备的实例的 ID。会话绑定后出现。
expires_at	integer	是	会话过期的时间，Unix 秒。会话有效期为 10 分钟。
name	string	是	为设备创建的实例的显示名称。默认为 BeeRunner。
qr_payload	string	否	要编码进设备所扫描二维码的链接。仅在创建会话时返回。
api_base_url	string	否	设备所连接的 API 的基础 URL。仅在创建会话时返回。
relay_url	string	否	设备通过其连接的中继的 URL。仅在创建会话时返回。
desired_status	string	否	所创建实例被驱动到的生命周期阶段：running。为设备创建了新实例时设置。
connectivity	string	否	所创建实例的可达性：unknown、online 或 offline。为设备创建了新实例时设置。
resource_version	integer	否	所创建实例的资源版本。为设备创建了新实例时设置。

portalBindWire.status 取值

取值	含义
"pending"	已创建，等待设备扫描二维码或输入短码。
"awaiting_confirmation"	设备已认领该会话。请带 decision 调用 resolve 操作以继续。
"confirming"	决定 create 已被接受，正在为设备创建新实例。
"bound"	设备已绑定到一个实例，由 instance_id 给出。
"revoked"	已用撤销操作撤销。已撤销的会话不能再被认领或处理。

ProtoAutomationInput

—

使用于: 自动化

字段	类型	必填	说明
name	string	否	自动化的显示名称，1 到 256 个字符，且不能为空白。
prompt	string	否	每次运行时发送给智能体的文本，最多 65536 字节，且不能为空白。
target	ProtoAutomationTarget	否	提示所发送给的智能体。必填。
schedule	ProtoAutomationSchedule	否	自动化何时运行。必填。
session	ProtoAutomationSession	否	此 API 不接受：包含它的请求会失败，返回 400 invalid_argument。在这里创建的自动化每次运行都会开启新会话。
validFrom	string	否	运行可以开始的最早时间，RFC 3339 时间戳，含该时刻。省略则没有下限。不得晚于 validUntil。 约束: format=date-time.
validUntil	string	否	运行可以开始的最晚时间，RFC 3339 时间戳，含该时刻。省略则没有上限。过了该时间，自动化变为 expired。 约束: format=date-time.
createdInConversationId	string	否	创建该自动化所基于的会话的 ID（如果有）。它必须是同一终端用户的会话。

ProtoAutomationPatch

—

使用于: 自动化

字段	类型	必填	说明
name	string	否	新的显示名称，1 到 256 个字符，且不能为空白。
prompt	string	否	每次运行时发送给智能体的新提示，最多 65536 字节，且不能为空白。
target	ProtoAutomationTarget	否	提示所发送给的新智能体。
schedule	ProtoAutomationSchedule	否	新的调度。它会替换整个调度，因此请发送该 kind 需要的所有字段，every 还需要 anchorAt。
session	ProtoAutomationSession	否	此 API 不接受：包含它的请求会失败，返回 400 invalid_argument。
validFrom	string	否	运行可以开始的新的最早时间，RFC 3339 时间戳，含该时刻。不能与 clearValidFrom 同时使用。 约束: format=date-time.
validUntil	string	否	运行可以开始的新的最晚时间，RFC 3339 时间戳，含该时刻。不能与 clearValidUntil 同时使用。 约束: format=date-time.
clearValidFrom	boolean	否	设为 true 以移除有效期的下限。不能与 validFrom 同时使用。
clearValidUntil	boolean	否	设为 true 以移除有效期的上限。不能与 validUntil 同时使用。

ProtoAutomationRule

—

使用于: 自动化

字段	类型	必填	说明
id	string	否	自动化的唯一 ID。
name	string	否	自动化的显示名称。
prompt	string	否	每次运行时发送给智能体的文本。
target	ProtoAutomationTarget	否	提示所发送给的智能体。
schedule	ProtoAutomationSchedule	否	自动化何时运行。webhook 自动化为空（kind 未设置）。
session	ProtoAutomationSession	否	运行如何选择其会话。通过此 API 创建的自动化总是使用 new。
validFrom	string	否	运行可以开始的最早时间，RFC 3339 时间戳，含该时刻。没有下限时为 null。 约束: format=date-time.
validUntil	string	否	运行可以开始的最晚时间，RFC 3339 时间戳，含该时刻。没有上限时为 null。 约束: format=date-time.
status	string	否	自动化的状态。 可选值: "enabled" — 活跃。schedule 自动化在 nextFireAt 运行；webhook 自动化响应传入的事件; "paused" — 已用暂停操作暂停。恢复之前不会创建运行; "expired" — 没有剩余运行次数的 schedule 自动化，例如已执行完的 at 调度，或已超过 validUntil. (枚举表)
nextFireAt	string	否	下一次计划运行的时间，RFC 3339 时间戳。自动化已暂停或已过期时，以及 webhook 自动化为 null。 约束: format=date-time.
createdInConversationId	string	否	创建该自动化所基于的会话的 ID。不是基于会话创建时为空。
createdAt	string	否	自动化的创建时间，RFC 3339 时间戳。 约束: format=date-time.
updatedAt	string	否	自动化最后一次变更的时间，RFC 3339 时间戳。 约束: format=date-time.
triggerKind	string	否	什么触发运行。在 webhook 触发器出现之前创建的自动化可能报告空值；请把它当作 schedule。 可选值: "schedule" — 按 schedule 启动运行; "webhook" — 事件源投递事件时启动运行，可用 eventFilter 进一步筛选. (枚举表)
hookId	string	否	接收 webhook 自动化事件的端点的 ID。schedule 自动化和 Gmail 自动化为空。
source	string	否	发送 webhook 自动化事件的平台，例如 github 或 gmail。schedule 自动化为空。
eventFilter	string	否	启动 webhook 自动化运行的事件类型。每个事件都启动运行时为空。
mailbox	string	否	webhook 自动化所监视的 Gmail 地址。其他来源为空。

ProtoAutomationRun

—

使用于: 自动化

字段	类型	必填	说明
id	string	否	运行的唯一 ID。
automationId	string	否	该运行所属自动化的 ID。
triggerType	string	否	是什么创建了该运行。 可选值: "schedule" — 自动化的调度到期; "manual" — 调用方通过 create-run 操作启动; "rerun" — 调用方通过 create-run 操作启动，用于重复 sourceRunId 中的先前运行; "webhook" — webhook 自动化收到了事件. (枚举表)
scheduledAt	string	否	运行到期的时间，RFC 3339 时间戳：定时运行为计划时间，其他为请求或事件的时间。 约束: format=date-time.
createdAt	string	否	运行的创建时间，RFC 3339 时间戳。 约束: format=date-time.
status	string	否	运行的投递状态。它说明提示是否到达智能体的会话，而不是智能体是否完成了工作。 可选值: "scheduled" — 已创建，等待投递。reasonCode 为 dispatch_unconfirmed 表示投递已开始，结果尚未确认; "dispatched" — 提示已被 conversationId 所指的会话接收; "failed" — 在发送提示之前投递就被拒绝。原因见 reasonCode; "skipped" — 未投递，因为运行到期时某个条件已不再成立。原因见 reasonCode. (枚举表)
target	ProtoAutomationTarget	否	运行所投递给的智能体，在创建运行时从自动化复制而来。
session	ProtoAutomationSession	否	运行如何选择其会话，在创建运行时从自动化复制而来。重跑则由 rerunSessionMode 设定。
conversationId	string	否	提示所投递到的会话的 ID。运行绑定到会话之前为空。
wakeMessageId	string	否	携带该提示的会话消息的 ID。它等于运行的 id。
sourceRunId	string	否	该运行所重复的运行的 ID。仅重跑设置。
rerunSessionMode	string	否	重跑被投递到哪个会话。不是重跑的运行为空。 可选值: "original" — 来源运行所投递到的会话; "new" — 新会话. (枚举表)
reasonCode	string	否	运行为何被跳过、失败或未确认。其他情况以及提示被接受之后为空。跳过原因包括 outside_validity、missed_schedule（运行未在其窗口内投递）、automation_paused、automation_deleted 和 preparation_stale（运行创建之后，自动化的智能体或会话发生了变化）。失败的运行带有 API 错误码，例如 target_not_found、permission_denied、conversation_unavailable 或 dependency_unavailable。dispatch_unconfirmed 表示投递已开始，结果未知。以后可能新增错误码，请忽略不认识的错误码。
dispatchedAt	string	否	提示被接受的时间，RFC 3339 时间戳。status 变为 dispatched 之前为 null。 约束: format=date-time.

ProtoAutomationRunInput

—

使用于: 自动化

字段	类型	必填	说明
sourceRunId	string	否	同一自动化中要重复的较早运行的 ID。与 rerunSessionMode 一起发送，或两者都不发送，表示普通的手动运行。
rerunSessionMode	string	否	重跑被投递到哪个会话。发送 sourceRunId 时必填，没有 sourceRunId 时不允许。 可选值: "original" — 来源运行所投递到的会话; "new" — 新会话. (枚举表)

ProtoAutomationSchedule

—

使用于: 自动化

字段	类型	必填	说明
kind	string	否	调度的类型。它决定其他哪些字段必填。 可选值: "at" — 在 at 运行一次; "every" — 重复运行，每隔 intervalSeconds 秒一次，从 anchorAt 起算; "cron" — 按五字段 cron expression 运行，在时区 tz 中计算. (枚举表)
tz	string	否	IANA 时区名称，例如 Asia/Shanghai。每种 kind 都必填；不接受 Local。
at	string	否	单次运行的时间，RFC 3339 时间戳。kind 为 at 时必填；其他 kind 不允许。 约束: format=date-time.
intervalSeconds	string	否	两次运行之间的秒数，十进制字符串。kind 为 every 时必填且大于 0；其他 kind 不允许。
anchorAt	string	否	间隔的起算时间，RFC 3339 时间戳：运行落在 anchorAt 加上间隔的整数倍处。创建 every 调度时默认为创建时间；替换调度时必填。其他 kind 不允许。 约束: format=date-time.
expression	string	否	五字段 cron 表达式：分钟、小时、日、月和星期。kind 为 cron 时必填；其他 kind 不允许。

ProtoAutomationSession

—

使用于: 自动化

字段	类型	必填	说明
mode	string	否	运行如何选择其所投递的会话。 可选值: "new" — 每次运行都与智能体开启一个新会话。通过此 API 创建的自动化总是使用该方式; "bound" — 每次运行都投递到 boundConversationId 所指的会话. (枚举表)
boundConversationId	string	否	运行所投递到的会话的 ID。仅当 mode 为 bound 时设置；否则为空。

ProtoAutomationTarget

—

使用于: 自动化

字段	类型	必填	说明
instanceId	string	否	自动化所运行在的实例的 ID。
agentId	string	否	接收提示的智能体的 ID。它必须是你应用中 instanceId 的活跃智能体。必填。

ProtoAutomationWebhookInput

—

使用于: 自动化

字段	类型	必填	说明
name	string	否	自动化的显示名称，1 到 256 个字符，且不能为空白。
prompt	string	否	每次运行时发送给智能体的文本，最多 65536 字节，且不能为空白。
target	ProtoAutomationTarget	否	提示所发送给的智能体。必填。
session	ProtoAutomationSession	否	此 API 不接受：包含它的请求会失败，返回 400 invalid_argument。在这里创建的自动化每次运行都会开启新会话。
validFrom	string	否	运行可以开始的最早时间，RFC 3339 时间戳，含该时刻。省略则没有下限。 约束: format=date-time.
validUntil	string	否	运行可以开始的最晚时间，RFC 3339 时间戳，含该时刻。省略则没有上限。 约束: format=date-time.
createdInConversationId	string	否	创建该自动化所基于的会话的 ID（如果有）。它必须是同一终端用户的会话。
source	string	否	发送事件的平台，例如 github 或 gmail，最多 64 个字符，不含空白。智能体必须已设置相应的连接器。必填。
events	array<string>	否	要在事件源处订阅的事件名称，例如仓库应投递的 GitHub 事件类型。
repoOwner	string	否	要监视的仓库的所有者。source 为 github 时必填。
repoName	string	否	要监视的仓库名称。source 为 github 时必填。
eventFilter	string	否	启动运行的事件类型。设置后，只有恰好是该类型的事件才启动运行；其他事件被跳过。为空则接受所有事件。
mailbox	string	否	要监视的 Gmail 地址。source 为 gmail 时必填；其他来源请留空。

ProtoListAutomationRunsResponse

—

使用于: 自动化

字段	类型	必填	说明
items	array<ProtoAutomationRun>	否	本页的运行。
nextCursor	string	否	作为 cursor 传入以获取下一页的游标。没有更多运行时为空。

ProtoListAutomationsResponse

—

使用于: 自动化

字段	类型	必填	说明
items	array<ProtoAutomationRule>	否	本页的自动化。
nextCursor	string	否	作为 cursor 传入以获取下一页的游标。没有更多自动化时为空。

Provider

—

使用于: 目录

字段	类型	必填	说明
id	string	是	提供方的 ID。
name	string	是	提供方的显示名称。
description	string	否	—
capabilities	ProviderCapabilities	否	—

ProviderCapabilities

—

使用于: 目录

字段	类型	必填	说明
long_running	boolean	是	—
browser_use	boolean	是	—
code_exec	boolean	是	—
file_system	boolean	是	—
custom_image	boolean	是	—
device	boolean	是	—
max_duration_sec	integer	是	—
cost_model	string	是	—

ProviderPage

—

使用于: 目录

字段	类型	必填	说明
data	array<Provider>	是	符合过滤条件的提供方。
total	integer	是	符合过滤条件的提供方数量。

RealtimeTicketHeader

—

使用于: 实例

字段	类型	必填	说明
alg	string	是	ticket 的签名算法：RS256。
typ	string	是	Token 类型：JWT。
kid	string	是	签署该 ticket 的密钥的 ID。

ReasoningResult

—

使用于: 会话

字段	类型	必填	说明
metadata_version	integer	是	本次变更之后的会话设置版本。把它带双引号作为下一次更新的 If-Match 发送。ETag header 也会返回它。

ReasoningResultResponse

—

使用于: 会话

字段	类型	必填	说明
data	ReasoningResult	是	变更的结果。

ReasoningSettings

—

使用于: 会话

字段	类型	必填	说明
modelId	string	是	reasoningOverrideId 所适用的模型的 ID，1 到 512 个字符。 约束: minLength=1, maxLength=512.
reasoningOverrideId	string	是	配合该模型使用的推理选项的 ID，1 到 64 个字符。发送 null 则使用该模型的默认值。 可为 null。 约束: minLength=1, maxLength=64.

RegionPage

—

使用于: 目录

字段	类型	必填	说明
data	array<DeployRegion>	是	符合过滤条件的区域。
total	integer	是	符合过滤条件的区域数量。

ReplyShareResponse

—

使用于: 消息

字段	类型	必填	说明
data	object	是	被分享的回复。
data.slug	string	是	标识该分享的公开 slug。
data.created_at	string	是	分享的创建时间。
data.agent	object	是	写下该回复的智能体。
data.agent.name	string	是	智能体的显示名称。
data.agent.avatar_url	string	是	智能体头像的 URL。
data.agent.framework	string	是	智能体所在实例使用的智能体框架。
data.reply	object	是	被分享的回复。
data.reply.parts	array<object>	是	回复的内容，包含一个 text 类型的部分。
data.reply.parts[].type	string	是	固定为 text。
data.reply.parts[].text	string	是	回复文本。
data.reply.created_at	string	是	回复消息的创建时间。
data.sources	array<object>	是	回复引用的网页来源。只列出 https 来源。每个来源返回 url、domain（其主机名），以及智能体提供时的 title。
data.sources[].url	string	否	来源的 URL。
data.sources[].title	string	否	来源的标题，智能体提供时才有。
data.files	array<object>	是	回复所链接的文件。只列出由 BeeOS 发布的文件。每个文件返回 name、public_url，以及已知时的 mime_type。
data.files[].file_id	string	否	保留字段。服务器目前不返回该字段；文件由 public_url 标识。
data.files[].filename	string	否	保留字段。服务器目前不返回该字段；文件名以 name 返回。
data.files[].content_type	string	否	保留字段。服务器目前不返回该字段；MIME 类型以 mime_type 返回。
data.files[].size_bytes	integer	否	保留字段。服务器目前不返回该字段。

RuntimeExecResult

—

使用于: 实例

字段	类型	必填	说明
exit_code	integer	是	命令的退出码。
stdout	string	是	命令的标准输出，最多 64 KiB。
stderr	string	是	命令的标准错误，最多 64 KiB。
truncated	boolean	是	输出是否被截断。

RuntimeInstanceResult

—

使用于: 实例

字段	类型	必填	说明
data	RuntimeInstanceSummary	是	本次响应时的实例。
operation	RuntimeOperationSummary	是	本次响应所报告的生命周期操作。

RuntimeInstanceStatusResult

—

使用于: 实例

字段	类型	必填	说明
data	object	是	实例的当前状态。
data.id	string	是	实例的唯一 ID。
data.name	string	是	实例的显示名称。
data.status	string	是	实例的生命周期阶段：pending、provisioning、running、stopped 或 terminated。 取值见下表 RuntimeInstanceStatusResult.data.status 取值。
data.desired_status	string	是	实例正被驱动朝向的生命周期阶段：running、stopped 或 terminated。 可选值: "running" — 实例应处于运行状态; "stopped" — 实例应处于停止状态; "terminated" — 实例应被删除. (枚举表)
data.connectivity	string	是	实例中 agent 的可达性：unknown、online 或 offline。 可选值: "unknown" — 尚未确定可达性; "online" — 该实例的智能体已连接; "offline" — 该实例的智能体未连接. (枚举表)
operation	RuntimeOperationSummary	是	本次响应所报告的生命周期操作。

RuntimeInstanceStatusResult.data.status 取值

取值	含义
"pending"	实例已创建，正在等待预配。
"provisioning"	实例正在预配或启动。
"running"	实例正在运行。
"stopped"	实例已停止，可以再次启动。
"terminated"	实例已删除，不能再使用。

RuntimeInstanceSummary

—

使用于: 实例

字段	类型	必填	说明
id	string	是	实例的唯一 ID。
organization_id	string	是	拥有该实例的组织的 ID。
app_id	string	是	实例所属应用的 ID。
developer_id	string	是	创建该实例所用的开发者账号的 ID。
name	string	是	实例的显示名称。
harness	string	是	产品 harness 名称（例如 openclaw），不是 UHP 的 harness_id（chrn_*）。
provider_id	string	是	托管该实例的 provider 的 ID。
region	string	是	实例部署所在的区域。
os_type	string	是	实例的操作系统：linux、windows、android 或 macos。
status	string	是	实例的生命周期阶段：pending、provisioning、running、stopped 或 terminated。 取值见下表 RuntimeInstanceSummary.status 取值。
desired_status	string	是	实例正被驱动朝向的生命周期阶段：running、stopped 或 terminated。 可选值: "running" — 实例应处于运行状态; "stopped" — 实例应处于停止状态; "terminated" — 实例应被删除. (枚举表)
connectivity	string	是	实例中 agent 的可达性：unknown、online 或 offline。 可选值: "unknown" — 尚未确定可达性; "online" — 该实例的智能体已连接; "offline" — 该实例的智能体未连接. (枚举表)
error_code	string	否	稳定的代码，描述随生命周期结果一起上报的失败或降级状态，例如 quota_exceeded、capacity_pending、provision_failed 或 stop_failed。原始的 provider 错误绝不会导出。
ms_connection_status	string	是	实例消息通道连接的状态：unknown、connecting、connected、reconnecting、disconnected 或 failed。它独立于 connectivity 上报；实例处于停止或已终止状态、或最近没有上报时为 unknown。
image_id	string	否	实例所运行的平台镜像的 ID。
image_version_id	string	否	实例所运行的平台镜像版本的 ID。
image_version	string	否	实例所运行的平台镜像的版本标签。
image_ref	string	否	固定的公开镜像引用。从不包含 provider 配置。
model_primary	string	否	为实例配置的主模型。
models	array<string>	否	为实例配置的模型。
llm	RuntimeLLMView	否	为实例提供的模型 provider 和模型，已移除 API key。 可为 null。
hosting_type	string	否	实例的托管位置：cloud 或 selfhosted。
cloud_provider	string	否	agentbay、beeos，自托管时为空。
image_slot	string	否	Variant 特性。为实例选择执行镜像的键。不是容器仓库名称。
worker_image_id	string	否	Variant 特性。AgentBay worker 镜像。绝不是平台的 image_id。
model_catalog	string	否	Variant 特性。Cloud 响应模型列表和 reasoning 级别请求时为 served，两者都不响应时为 none。空值和未知值按 none 处理。
billing_slot	string	否	Variant 特性。为该实例定价的月费表的键。
icon_key	string	否	Variant 特性。UI 图标选择器。客户端不得从 harness 推导它。
device_control	boolean	是	Variant 特性。实例是否接受设备控制命令。false 表示这些命令会被拒绝。
runtime_profile	string	否	Variant 特性。实例所使用的 agent 运行时的 profile。已知值为 openclaw、hermes 和 beeos-browser。
free_plan	boolean	是	Variant 特性。免费套餐是否允许该实例的 variant。false 表示免费套餐不允许。
resource_version	integer	是	实例记录的版本，从 1 开始。请在写请求的 If-Match 头中发送它，以便检测并发修改。
has_ever_run	boolean	是	实例是否曾到达过 running 状态。false 表示它从未提供过运行中的服务。
created_at	string	是	实例的创建时间，RFC 3339 UTC 时间戳。
updated_at	string	是	实例的最后更新时间，RFC 3339 UTC 时间戳。
capabilities	object	是	实例在预配时声明的能力，以 computer、mobile、device 和 terminal 等标志表示。空对象表示没有声明任何能力。
capabilities.computer	boolean	否	—
capabilities.mobile	boolean	否	—
capabilities.device	boolean	否	—
capabilities.terminal	boolean	否	—

RuntimeInstanceSummary.status 取值

取值	含义
"pending"	实例已创建，正在等待预配。
"provisioning"	实例正在预配或启动。
"running"	实例正在运行。
"stopped"	实例已停止，可以再次启动。
"terminated"	实例已删除，不能再使用。

RuntimeLLM

—

使用于: 实例

字段	类型	必填	说明
providers	array<RuntimeLLMProvider>	是	模型 provider 端点，1 到 8 项。每个 provider 至少要被一个模型引用。
models	array<RuntimeLLMModel>	是	可选择的模型，1 到 256 项。恰好一个具有 default 角色。

RuntimeLLMModel

—

使用于: 实例

字段	类型	必填	说明
provider_id	string	是	提供该模型服务的 provider 的 ID。
model	string	是	provider API 所要求的模型名称。在每个 provider 内唯一。
role	string	是	模型的角色：default、fallback 或 available。恰好一个模型是 default。自动故障转移只使用 fallback 模型。 可选值: "default" — 实例默认使用的模型。只有一个模型具有此角色，其 order 为 0; "fallback" — 默认模型失败时，自动故障切换所切换到的模型; "available" — 可以被选择、但从不用于自动故障切换的模型. (枚举表)
order	integer	是	模型的位置，在所有模型中唯一。default 模型的 order 为 0；fallback 和 available 模型的 order 为 1 或更大。

RuntimeLLMProvider

—

使用于: 实例

字段	类型	必填	说明
id	string	是	由调用方选择、供模型引用的 ID。在请求内唯一，1 到 64 个字符，取自 A-Z、a-z、0-9、_ 和 -。
protocol	string	是	该端点使用的 API 协议：openai 或 anthropic。 可选值: "openai" — OpenAI 兼容 API; "anthropic" — Anthropic Messages API. (枚举表)
base_url	string	是	provider API 的 HTTPS 基础 URL，最多 512 个字符。不得包含凭证、查询字符串或 fragment。
api_key	string	否	该 provider 的 API key，1 到 4096 个字符，不含空白。只写，永远不会返回。 只写。

RuntimeLLMProviderView

—

使用于: 实例

字段	类型	必填	说明
id	string	是	provider 的 ID，即模型所引用的值。
protocol	string	是	该端点使用的 API 协议：openai 或 anthropic。
base_url	string	是	provider API 的 HTTPS 基础 URL。

RuntimeLLMView

—

使用于: 实例

字段	类型	必填	说明
providers	array<RuntimeLLMProviderView>	是	模型 provider 端点，不含 API key。
models	array<RuntimeLLMModel>	是	可选择的模型。

RuntimeMethodResponse

JSON-RPC 2.0 响应。成功时携带 result，失败时携带 error，二者不会同时出现。错误以 HTTP 状态 200 返回。

使用于: A2A

字段	类型	必填	说明
jsonrpc	string	是	JSON-RPC 协议版本：始终为 2.0。 可选值: "2.0" — JSON-RPC 2.0 版本.
id	string | integer	是	该响应所回答的请求的 ID。请求无法读取时为 null。 可为 null。
result	JSONValue	否	方法的结果。仅在成功时出现；其结构取决于方法。 可为 null。
error	object	否	调用的错误。仅在失败时出现。
error.code	integer	是	错误码。-32700 解析错误，-32600 无效请求，-32601 方法不存在，-32602 无效参数，-32603 内部错误，-32001 任务不存在，-32002 任务不可取消，-32003 不支持推送通知，-32004 不支持的操作，-32005 不支持的内容类型，-32006 智能体响应无效，-32007 未配置 agent card，-32008 智能体繁忙，-32009 A2A-Version 不兼容，-32010 任务派发之后连接断开（请读取该任务，不要再次发送），-32011 任务超时，-32012 派发之前连接断开（没有任何运行；可以安全重试）。
error.message	string	是	错误的可读描述。
error.data	JSONValue	否	错误的机器可读详情：包含一个 type.googleapis.com/google.rpc.ErrorInfo 类型对象的列表。其 reason 为错误名称，例如 TASK_NOT_FOUND，其 metadata 重复 code 和 message。 可为 null。

RuntimeOperationSummary

—

使用于: 实例

字段	类型	必填	说明
id	string	是	操作的唯一 ID。
kind	string	是	操作的种类：create、start、stop、delete 或 image_upgrade。 取值见下表 RuntimeOperationSummary.kind 取值。
phase	string	是	操作的阶段：intent、reserved、admitted、provisioning、running、cleanup_pending、failed、stop_pending、stopped、delete_pending、deleted、upgrade_pending 或 rollback_pending。它描述持久化的工作，而不是观测到的实例健康状况。 取值见下表 RuntimeOperationSummary.phase 取值。
error_code	string	否	稳定的失败码，与实例的 error_code 取值相同。原始的 provider 错误绝不会导出。

RuntimeOperationSummary.kind 取值

取值	含义
"create"	创建实例。
"start"	启动已停止的实例。
"stop"	停止实例。
"delete"	删除实例。
"image_upgrade"	把实例升级到另一个平台镜像。

RuntimeOperationSummary.phase 取值

取值	含义
"intent"	创建请求已记录，尚未预留任何资源。
"reserved"	创建请求已被接受，其资源已预留。
"admitted"	创建请求已被受理，正在等待预配。
"provisioning"	实例正在预配或启动。
"running"	创建、启动或镜像升级成功的最终阶段。
"cleanup_pending"	创建失败，它所预留的资源正在清理。
"failed"	操作失败的最终阶段。见 error_code。
"stop_pending"	实例正在停止。
"stopped"	停止成功的最终阶段。
"delete_pending"	实例正在被删除。
"deleted"	删除成功的最终阶段。
"upgrade_pending"	正在应用镜像升级。
"rollback_pending"	镜像升级失败，实例正在回滚到之前的镜像。

RuntimeUpgradeJob

—

使用于: 实例

字段	类型	必填	说明
job_id	string	是	升级任务的唯一 ID。
image_version_id	string	否	—
instance_id	string	是	正在升级的实例的 ID。
status	string	是	任务的状态：upgrade_pending、rollback_pending、failed 或 succeeded。 可选值: "upgrade_pending" — 正在应用镜像升级; "rollback_pending" — 镜像升级失败，实例正在回滚到之前的镜像; "failed" — 镜像升级失败。见 error; "succeeded" — 镜像升级已完成，实例运行目标版本. (枚举表)
target	string	是	实例正在升级到的镜像版本。
created_at	string	是	任务的创建时间，RFC 3339 UTC 时间戳。
completed_at	string	否	任务结束的时间，RFC 3339 UTC 时间戳。任务未结束时省略。 可为 null。
error	string	否	稳定的失败码。只有任务失败时才出现。 可为 null。

ServerUsageSummary

—

使用于: 用量

字段	类型	必填	说明
total_bc	string	是	统计周期内的总费用，单位为 BC micros（BeeOS Credit，即 BC，的百万分之一），十进制字符串。例如 1500000 即 1.5 BC。
total_records	integer	是	统计周期内的用量记录数。
by_category	map<string, string>	是	统计周期内按类别统计的费用，单位为 BC micros，十进制字符串，以类别为键。周期内没有用量的类别不出现。
by_app	map<string, string>	否	按应用统计的费用，单位为 BC micros，十进制字符串。Server API key 只能看到自己的应用，因此不向它们返回该字段。
category_counts	map<string, integer>	是	统计周期内按类别统计的用量记录数，以类别为键。周期内没有用量的类别不出现。

SetConversationModelInput

—

使用于: 会话

字段	类型	必填	说明
model_override_id	string	是	用于该会话的模型 ID，最多 512 个字符。发送 null 可移除覆盖，重新使用智能体的默认模型。覆盖变化时，会话的 reasoning 会被清除。 可为 null。 约束: maxLength=512.

TerminalSessionDocument

—

使用于: 实例

字段	类型	必填	说明
transport	string	是	ticket 的连接方式：始终为 service-websocket。
protocolVersion	integer	是	ticket 协议的版本。目前为 1。
header	RealtimeTicketHeader	是	已签名 ticket 的 header。
websocketUrl	string	是	用于建立终端连接的 WebSocket URL。ticket 已作为查询参数包含在内。
ticket	string	是	已签名的一次性 ticket（JWT），授权一次终端连接。有效期为 60 秒。
issuedAt	string	是	ticket 的签发时间，RFC 3339 时间戳。 约束: format=date-time.
expiresAt	string	是	ticket 的过期时间，RFC 3339 时间戳。ticket 的有效期为 60 秒。 约束: format=date-time.
claims	TerminalTicketClaims	是	已签名 ticket 中包含的 claims。

TerminalTicketClaims

—

使用于: 实例

字段	类型	必填	说明
iss	string	是	ticket 的签发者。
aud	string	是	ticket 的目标受众：终端服务。
sub	string	是	未使用。Cloud 不接受外部用户 ID，因此该声明为空。
jti	string	是	ticket 的唯一 ID。
instance_id	string	是	该终端所属实例的 ID。
platform_agent_id	string	是	该终端会话所针对的 agent 的 ID，即请求中的 platformAgentId。
client_id	string	是	为这次终端客户端连接生成的 ID。
conversation_id	string	否	该终端所附着的会话的 ID。仅当请求发送了 conversationId 时才出现。
resume_terminal_id	string	否	要恢复的终端的 ID。仅当请求发送了 resumeTerminalId 时才出现。
iat	integer	是	ticket 的签发时间，Unix 秒。
exp	integer	是	ticket 的过期时间，Unix 秒。

UHPAnnotation

—

使用于: Responses

字段	类型	必填	说明
type	string	是	注释的类型。 可选值: "container_file_citation" — 文本引用了智能体生成的文件.
container_id	string	否	保存该文件的容器的 ID。BeeOS 目前不设置。
file_id	string	否	文件的 ID。BeeOS 目前不设置。
filename	string	否	文件名。
download_url	string	否	可下载该文件的绝对 URL。 约束: format=uri.
start_index	integer	否	文本中被引用范围的起始位置，按字符计数。BeeOS 将其设为 0。
end_index	integer	否	文本中被引用范围的结束位置，按字符计数。BeeOS 将其设为文本长度。

接受额外属性。

UHPCapabilities

具名布尔值。服务器对自己没有实现的能力报告 false，而不是省略它，这样客户端就能区分“不支持”和“服务器早于该字段”。客户端把缺失的键视为 false。

使用于: 目录

字段	类型	必填	说明
streaming	boolean	否	服务器可以把响应以 server-sent events 流式返回。
sessions	boolean	否	服务器保留会话，后续请求可以继续。
cancellation	boolean	否	正在运行的响应可以被取消。
files_input	boolean	否	服务器接受文件作为请求的输入。
files_output	boolean	否	服务器返回 harness 产出的文件。
session_listing	boolean	否	服务器可以列出现有会话。
harness_management	boolean	否	可以通过 API 创建、更新和删除 harness。
session_sharing	boolean	否	服务器可以与其他调用方分享会话。
idempotency	boolean	否	服务器对接受 Idempotency-Key header 的写操作遵循该 header。
plugins	boolean	否	服务器把 Agent Plugins 包安装到 harness 中，提供其文件，并可把 harness 导出为一个包。在每个级别都是可选的。
environments	boolean	否	服务器持有 environment：一个项目的文件和已安装的依赖，只构建一次，在每个指明它的会话中以固定路径只读挂载。在每个级别都是可选的。
memories	boolean	否	服务器持有 memory：一棵 memory 树，按节点授予访问权限；记录由已连接的 provider 保存；以及 harness 的 agent 访问它们所用的工具。在每个级别都是可选的。

接受额外属性。

UHPContentPart

—

使用于: Responses

字段	类型	必填	说明
type	string	是	该部分的类型。 可选值: "output_text" — message 项的文本，可带注释; "summary_text" — reasoning 项的摘要文本. (枚举表) 按 type 区分的结构：见变体表。
text	string	否	该部分的文本。
annotations	array<UHPAnnotation>	否	指向 text 中某些范围的注释。

接受额外属性。

UHPContentPart 按 type 区分

UHPContentPart 的结构取决于它自己的 type 值。

type 的取值	说明	结构
"output_text"	message 项的文本，可带注释。	UHPContentPartOutputText
"summary_text"	reasoning 项的摘要文本。	UHPContentPartSummaryText

UHPContentPartOutputText

message 项的文本。

使用于: Responses

字段	类型	必填	说明
type	string	是	固定为 output_text。
text	string	否	该部分的文本。
annotations	array<UHPAnnotation>	否	指向 text 中某些范围的注释。

接受额外属性。

UHPContentPartSummaryText

reasoning 项的摘要文本。

使用于: Responses

字段	类型	必填	说明
type	string	是	固定为 summary_text。
text	string	否	该部分的文本。

接受额外属性。

UHPCreateResponseRequest

—

使用于: Responses

字段	类型	必填	说明
input	string | array<map<string, JSONValue>>	是	单个字符串是一条用户消息的简写。
model	string	否	本回合使用的模型 ID。省略表示使用 harness 默认值。所请求的任何 ID 都按原样派发。
metadata	object	否	客户端元数据，Responses 接口的扩展点。harness_id 选择已配置的 harness；environment 指明该任务读取的 environment，覆盖 harness 自己的（能力 environments），在任务开始之前以 environment_not_found 或 environment_not_ready 拒绝。
metadata.harness_id	string	否	运行该任务的 harness 的 ID。范围内恰好有一个 harness 时可选；有多个时必填。
metadata.environment	string	否	供任务读取的环境名称。此服务器不提供环境：非空值会被拒绝，返回 404 environment_not_found。
stream	boolean	否	为 true 时，响应以 server-sent events 流式返回，见 UHPEvent；否则调用返回完成后的响应。默认 false。 默认值: false.
previous_response_id	string	否	要继续的较早响应的 ID。新响应在同一会话中运行。较早的响应必须存在，且属于同一个 harness。 可为 null。
instructions	string	否	放在输入文本之前的指令，与输入文本之间以一行 --- 分隔。
store	boolean	否	是否保留响应以便之后获取。默认 true。 默认值: true.
max_output_tokens	integer	否	保留字段，会被忽略。它会出现在响应的 metadata.ignored_fields 中。 可为 null。
max_step	integer	否	Agent 步数（工具调用轮次）预算. 可为 null。
timeout_seconds	integer	否	墙钟时间预算. 可为 null。
tools	array<map<string, JSONValue>>	否	保留且被忽略。为了线路兼容而接受，从不执行，并在响应的 metadata.ignored_fields 中报告。UHP harness 自己调用并执行工具，并在 output 中报告它们；工具结果没有输入路径，因此该字段所暗示的由客户端执行的工具循环无法由符合规范的服务器完成。请改为在 harness 上配置工具——见 Harnesses §4.1。Tasks §1.4。
include	array<string>	否	保留且被忽略。为了线路兼容而接受，从不执行，并在响应的 metadata.ignored_fields 中报告。没有枚举任何值，因此服务器所识别的任何字符串都是它自己命名的。Tasks §1.4。
background	boolean	否	对非流式请求设为 true 时，调用立即返回，响应仍为 in_progress，之后再获取结果。stream 为 true 时忽略。 默认值: false.

接受额外属性。

UHPDiscovery

—

使用于: 目录

字段	类型	必填	说明
object	string	是	对象类型：始终为 uhp.discovery。 可选值: "uhp.discovery" — 协议发现文档.
protocol	string	是	服务器所使用的协议：始终为 uhp，即 Unified Harness Protocol。 可选值: "uhp" — Unified Harness Protocol.
versions	array<string>	是	服务器所使用的协议版本，作为 UHP-Version header 的值。 约束: minItems=1.
default_version	string	是	请求不发送 UHP-Version header 时，服务器所使用的协议版本。
conformance_class	string	是	服务器的粗粒度一致性级别。请依据 capabilities 中精确的标志分支，而不是依据该级别。 可选值: "core" — 发现、harness 读取、任务和会话; "extended" — Core 加上文件输入和产物获取; "full" — Extended 加上 harness 管理、插件、环境和记忆. (枚举表)
capabilities	UHPCapabilities	是	服务器能做什么。只有背后的端点都能响应时，标志才为 true。
plugin_schemas	array<string>	否	该服务器所安装的 Agent Plugins manifest schema 标识符。当 capabilities.plugins 为 true 时出现且非空。
implementation	object	否	服务器的信息。除 name 和 version 外，还可能带有 availability，说明模型可用性如何计算。
implementation.name	string	否	服务器实现的名称：BeeOS Cloud。
implementation.version	string	否	服务器实现的版本。未知时省略。

接受额外属性。

UHPError

—

使用于: Responses

字段	类型	必填	说明
type	string	是	错误的类别，由 HTTP 状态决定。 取值见下表 UHPError.type 取值。
code	string	是	具体且机器可读。对于本规范未涵盖的情形，服务器可以定义额外的错误码，并且必须用厂商前缀为其命名空间，以免未来版本与之冲突。
message	string	是	一句话，可以安全地展示给用户。不得包含凭证、内部主机名、文件路径或堆栈跟踪。
param	string	否	指向出错字段的点分路径。 可为 null。
detail	map<string, JSONValue>	否	错误的附加结构化详情（如果有）。 可为 null。

UHPError.type 取值

取值	含义
"invalid_request_error"	请求无效，或引用了不存在的对象，或与当前状态冲突。
"authentication_error"	API key 缺失或无效。
"permission_error"	API key 没有该调用所需的 scope。
"rate_limit_error"	请求过多。
"harness_error"	harness 未能完成所请求的操作。
"server_error"	服务端无法处理该请求。

接受额外属性。

UHPErrorEnvelope

—

使用于: —

字段	类型	必填	说明
error	UHPError	是	错误。
detail	string	否	error.message 的人类可读别名，保留给针对早于该信封的实现所编写的客户端。不携带 error 中没有的信息。 已弃用。

接受额外属性。

UHPEvent

一个流式事件。sequence_number 从 0 开始，每个事件恰好加 1，这样客户端可以发现丢失的事件，而不是悄悄地渲染出一个空缺。

使用于: Responses

字段	类型	必填	说明
type	string	是	事件的类型。客户端应忽略不认识的事件类型。response.completed、response.incomplete 和 response.failed 中恰好有一个会结束事件流。 取值见下表 UHPEvent.type 取值。 按 type 区分的结构：见变体表。
sequence_number	integer	是	事件在流中的位置，从 0 开始，每个事件加 1。出现间断说明丢失了事件。 约束: minimum=0.
response	UHPResponse	否	响应的快照。出现在生命周期事件上。
item	UHPOutputItem	否	输出项。出现在 response.output_item.added 和 response.output_item.done 事件上。
part	UHPContentPart	否	内容部分或摘要部分。出现在内容部分和推理摘要部分事件上。
annotation	UHPAnnotation	否	注释。出现在 response.output_text.annotation.added 事件上。
delta	string	否	自上一个 delta 以来新增的文本或函数参数。
text	string	否	完整文本。出现在 response.output_text.done 事件上。
arguments	string	否	完整的函数参数，JSON 字符串。出现在 response.function_call_arguments.done 事件上。
item_id	string	否	事件所属输出项的 ID。
output_index	integer	否	输出项在响应 output 中的位置。 约束: minimum=0.
content_index	integer	否	内容部分在输出项中的索引。 约束: minimum=0.
summary_index	integer	否	摘要部分在输出项中的索引。 约束: minimum=0.
annotation_index	integer	否	注释在内容部分中的索引。 约束: minimum=0.
code	string	否	机器可读的错误码。出现在 error 事件上。
message	string	否	可读的错误信息。出现在 error 事件上。
param	string	否	错误所涉及字段的点分路径，或为 null。出现在 error 事件上。 可为 null。

UHPEvent.type 取值

取值	含义
"response.created"	响应已创建。response 为状态为 in_progress 的初始快照。
"response.in_progress"	响应正在运行。response 为快照。
"response.output_item.added"	新的输出项开始。item 为其初始形态，output_index 为它在 output 中的位置。
"response.output_item.done"	输出项已完成。item 为其最终形态。
"response.content_part.added"	向 message 项添加了一个内容部分。part 为其初始形态。
"response.content_part.done"	message 项的一个内容部分已完成。part 为其最终形态。
"response.output_text.delta"	message 项的文本追加了内容。delta 为新增文本。
"response.output_text.done"	message 项的文本已完整。text 为完整文本。
"response.output_text.annotation.added"	向 message 项的文本添加了注释，例如文件引用。
"response.reasoning_summary_part.added"	向 reasoning 项添加了一个摘要部分。
"response.reasoning_summary_text.delta"	reasoning 项的摘要追加了内容。delta 为新增文本。
"response.reasoning_summary_part.done"	reasoning 项的一个摘要部分已完成。part 为其最终形态。
"response.function_call_arguments.delta"	function_call 项的参数有新内容写入。delta 为参数文本。
"response.function_call_arguments.done"	function_call 项的参数已完整。arguments 以 JSON 字符串给出。
"response.completed"	响应成功完成。这是终止事件：每个流恰好以一个终止事件结束。
"response.incomplete"	响应因达到限制而停止，例如输出上限或时间上限。这是终止事件。
"response.failed"	响应失败或被取消；response.status 为 failed 或 cancelled。这是终止事件。
"error"	未终止响应的错误。code、message 和 param 描述该错误，之后仍会有终止事件。
"beeos.approval.requested"	BeeOS 扩展。智能体请求批准某个操作。approval 属性为审批请求文档。
"beeos.approval.resolved"	BeeOS 扩展。审批请求已被处理。approval 属性为处理结果文档。
"beeos.question.requested"	BeeOS 扩展。智能体向用户提问。question 属性包含提问请求文档。
"beeos.question.resolved"	BeeOS 扩展。一个提问请求已被处理。question 属性包含处理结果文档。

接受额外属性。

UHPEvent 按 type 区分

UHPEvent 的结构取决于它自己的 type 值。

type 的取值	说明	结构
"response.created"	响应已创建。response 为状态为 in_progress 的初始快照。	UHPEventResponse
"response.in_progress"	响应正在运行。response 为快照。	UHPEventResponse
"response.completed"	响应成功完成。这是终止事件：每个流恰好以一个终止事件结束。	UHPEventResponse
"response.incomplete"	响应因达到限制而停止，例如输出上限或时间上限。这是终止事件。	UHPEventResponse
"response.failed"	响应失败或被取消；response.status 为 failed 或 cancelled。这是终止事件。	UHPEventResponse
"response.output_item.added"	新的输出项开始。item 为其初始形态，output_index 为它在 output 中的位置。	UHPEventOutputItem
"response.output_item.done"	输出项已完成。item 为其最终形态。	UHPEventOutputItem
"response.content_part.added"	向 message 项添加了一个内容部分。part 为其初始形态。	UHPEventContentPart
"response.content_part.done"	message 项的一个内容部分已完成。part 为其最终形态。	UHPEventContentPart
"response.reasoning_summary_part.added"	向 reasoning 项添加了一个摘要部分。	UHPEventReasoningSummaryPart
"response.reasoning_summary_part.done"	reasoning 项的一个摘要部分已完成。part 为其最终形态。	UHPEventReasoningSummaryPart
"response.output_text.delta"	message 项的文本追加了内容。delta 为新增文本。	UHPEventOutputTextDelta
"response.reasoning_summary_text.delta"	reasoning 项的摘要追加了内容。delta 为新增文本。	UHPEventReasoningSummaryTextDelta
"response.output_text.done"	message 项的文本已完整。text 为完整文本。	UHPEventOutputTextDone
"response.output_text.annotation.added"	向 message 项的文本添加了注释，例如文件引用。	UHPEventAnnotationAdded
"response.function_call_arguments.delta"	function_call 项的参数有新内容写入。delta 为参数文本。	UHPEventFunctionCallArgumentsDelta
"response.function_call_arguments.done"	function_call 项的参数已完整。arguments 以 JSON 字符串给出。	UHPEventFunctionCallArgumentsDone
"error"	未终止响应的错误。code、message 和 param 描述该错误，之后仍会有终止事件。	UHPEventError
"beeos.approval.requested"	BeeOS 扩展。智能体请求批准某个操作。approval 属性为审批请求文档。	UHPEventApproval
"beeos.approval.resolved"	BeeOS 扩展。审批请求已被处理。approval 属性为处理结果文档。	UHPEventApproval
"beeos.question.requested"	BeeOS 扩展。智能体向用户提问。question 属性包含提问请求文档。	UHPEventQuestion
"beeos.question.resolved"	BeeOS 扩展。一个提问请求已被处理。question 属性包含处理结果文档。	UHPEventQuestion

UHPEventAnnotationAdded

向 message 项的文本添加了一条注释。

使用于: Responses

字段	类型	必填	说明
type	string	是	固定为 response.output_text.annotation.added。
item_id	string	是	事件所属输出项的 ID。
output_index	integer	是	输出项在响应 output 中的位置。 约束: minimum=0.
content_index	integer	是	内容部分在输出项中的索引。 约束: minimum=0.
annotation_index	integer	是	注释在内容部分中的索引。 约束: minimum=0.
annotation	UHPAnnotation	是	注释。出现在 response.output_text.annotation.added 事件上。

接受额外属性。

UHPEventApproval

BeeOS 扩展：审批请求或其处理结果。

使用于: Responses

字段	类型	必填	说明
type	string	是	beeos.approval.requested 或 beeos.approval.resolved 之一。
approval	JSONValue	是	审批文档，从智能体宿主原样透传。 可为 null。

接受额外属性。

UHPEventContentPart

message 项的一个内容部分被添加或完成。

使用于: Responses

字段	类型	必填	说明
type	string	是	response.content_part.added 或 response.content_part.done 之一。
item_id	string	是	事件所属输出项的 ID。
output_index	integer	是	输出项在响应 output 中的位置。 约束: minimum=0.
content_index	integer	是	内容部分在输出项中的索引。 约束: minimum=0.
part	UHPContentPart	是	内容部分或摘要部分。出现在内容部分和推理摘要部分事件上。

接受额外属性。

UHPEventError

未终止响应的错误。

使用于: Responses

字段	类型	必填	说明
type	string	是	固定为 error。
code	string	是	机器可读的错误码。出现在 error 事件上。
message	string	是	可读的错误信息。出现在 error 事件上。
param	string	否	错误所涉及字段的点分路径，或为 null。出现在 error 事件上。 可为 null。

接受额外属性。

UHPEventFunctionCallArgumentsDelta

函数调用的参数有新内容写入。

使用于: Responses

字段	类型	必填	说明
type	string	是	固定为 response.function_call_arguments.delta。
item_id	string	是	事件所属输出项的 ID。
output_index	integer	是	输出项在响应 output 中的位置。 约束: minimum=0.
delta	string	是	自上一个 delta 以来新增的文本或函数参数。

接受额外属性。

UHPEventFunctionCallArgumentsDone

函数调用的参数已完整。

使用于: Responses

字段	类型	必填	说明
type	string	是	固定为 response.function_call_arguments.done。
item_id	string	是	事件所属输出项的 ID。
output_index	integer	是	输出项在响应 output 中的位置。 约束: minimum=0.
arguments	string	是	完整的函数参数，JSON 字符串。出现在 response.function_call_arguments.done 事件上。

接受额外属性。

UHPEventOutputItem

输出项开始或完成。

使用于: Responses

字段	类型	必填	说明
type	string	是	response.output_item.added 或 response.output_item.done 之一。
output_index	integer	是	输出项在响应 output 中的位置。 约束: minimum=0.
item	UHPOutputItem	是	输出项。出现在 response.output_item.added 和 response.output_item.done 事件上。

接受额外属性。

UHPEventOutputTextDelta

message 项的新增文本。

使用于: Responses

字段	类型	必填	说明
type	string	是	固定为 response.output_text.delta。
item_id	string	是	事件所属输出项的 ID。
output_index	integer	是	输出项在响应 output 中的位置。 约束: minimum=0.
content_index	integer	是	内容部分在输出项中的索引。 约束: minimum=0.
delta	string	是	自上一个 delta 以来新增的文本或函数参数。

接受额外属性。

UHPEventOutputTextDone

message 项的文本已完整。

使用于: Responses

字段	类型	必填	说明
type	string	是	固定为 response.output_text.done。
item_id	string	是	事件所属输出项的 ID。
output_index	integer	是	输出项在响应 output 中的位置。 约束: minimum=0.
content_index	integer	是	内容部分在输出项中的索引。 约束: minimum=0.
text	string	是	完整文本。出现在 response.output_text.done 事件上。

接受额外属性。

UHPEventQuestion

BeeOS 扩展：提问请求或其处理结果。

使用于: Responses

字段	类型	必填	说明
type	string	是	beeos.question.requested、beeos.question.resolved 之一。
question	JSONValue	是	提问文档，从智能体宿主透传。 可为 null。

接受额外属性。

UHPEventReasoningSummaryPart

reasoning 项的一个摘要部分被添加或完成。

使用于: Responses

字段	类型	必填	说明
type	string	是	response.reasoning_summary_part.added 或 response.reasoning_summary_part.done 之一。
item_id	string	是	事件所属输出项的 ID。
output_index	integer	是	输出项在响应 output 中的位置。 约束: minimum=0.
summary_index	integer	是	摘要部分在输出项中的索引。 约束: minimum=0.
part	UHPContentPart	是	内容部分或摘要部分。出现在内容部分和推理摘要部分事件上。

接受额外属性。

UHPEventReasoningSummaryTextDelta

reasoning 项的新增摘要文本。

使用于: Responses

字段	类型	必填	说明
type	string	是	固定为 response.reasoning_summary_text.delta。
item_id	string	是	事件所属输出项的 ID。
output_index	integer	是	输出项在响应 output 中的位置。 约束: minimum=0.
summary_index	integer	是	摘要部分在输出项中的索引。 约束: minimum=0.
delta	string	是	自上一个 delta 以来新增的文本或函数参数。

接受额外属性。

UHPEventResponse

携带响应快照的响应生命周期事件。

使用于: Responses

字段	类型	必填	说明
type	string	是	response.created、response.in_progress、response.completed、response.incomplete、response.failed 之一。
response	UHPResponse	是	响应的快照。出现在生命周期事件上。

接受额外属性。

UHPHarness

—

使用于: Harness

字段	类型	必填	说明
id	string	是	harness 的 ID。以 chrn_ 开头，是其他请求中要使用的 harness_id。 约束: pattern=^chrn_.
object	string	否	对象类型：始终为 harness。 可选值: "harness" — 一个 harness 对象.
name	string	是	harness 的显示名称。harness 没有显示名称时使用其名称，再没有则使用其 ID。
base	string	是	不透明。本规范不枚举它——客户端必须把它当作字符串对待，否则每次发布 harness 时协议都需要修订。
baseLabel	string	否	base 的可读名称：openclaw 为 OpenClaw，hermes 为 Hermes。base 没有已知名称时省略。
defaultModel	string	否	harness 用作主模型的模型 ID。没有时省略。
systemPrompt	string	否	harness 的 system prompt。BeeOS Cloud 不支持该字段，因此从不返回。
mcpServers	array<UHPMcpServer>	否	挂载到 harness 的 MCP 服务器。仅在实例运行时读取单个 harness 才返回，且仅当实例支持 MCP 服务器时返回；列表中省略。
skills	array<UHPSkill>	否	harness 上已安装的 skill。仅在实例运行时读取单个 harness 才返回；列表中省略。
plugins	array<UHPPlugin>	否	已安装的插件。它们的服务器和 skill 在每个回合中都与 harness 自己的合并；上面的 mcpServers 和 skills 只报告直接写入它们的内容。
environment	string	否	该 harness 的任务所读取的 environment（henv_），以只读方式挂载在其 mount 处；没有时为空。任务可以用自己的 environment 字段指明另一个。
disabledTools	array<string>	否	为 harness 禁用的工具名称。BeeOS Cloud 不支持该字段，因此从不返回。
maxStep	integer	否	每次运行的最大步数。BeeOS Cloud 不支持该字段，因此从不返回。 可为 null。
timeoutSeconds	integer	否	运行超时，单位为秒。BeeOS Cloud 不支持该字段，因此从不返回。 可为 null。
createdAt	integer	否	Unix 毫秒

接受额外属性。

UHPHarnessCreate

—

使用于: Harness

字段	类型	必填	说明
name	string	否	harness 的显示名称。创建时必填，1 个或多个非空白字符。更新时必须等于当前名称；重命名会被拒绝，返回 422 beeos_field_not_supported。
base	string	是	harness 的 base（智能体运行时）。创建时必须等于 instance_id 所指实例的 harness，否则请求失败，返回 422 unsupported_base。更新时必须等于该 harness 当前的 base，base 不能修改。
default_model	string	否	BeeOS Cloud 只在创建时采用该值；在 PUT 中使用不同的值会返回 422 beeos_field_not_supported，除非同时发送了 template_id。
system_prompt	string	否	system prompt。BeeOS Cloud 不支持：非空值会被拒绝，返回 422 beeos_field_not_supported。
mcp_servers	array<UHPMcpServer>	否	创建时被拒绝（422 beeos_field_not_supported）。PUT 时，该列表会与运行时的 MCP 服务器做差异比较：列出的服务器会被设置，被省略的会被取消设置；只有当实例运行时没有任何 MCP 方法时才返回 422 beeos_mcp_not_supported。
skills	array<UHPSkill>	否	harness 应具有的 skill。创建时不接受。更新时，该列表是完整的期望集合：带有 files、content 或 blob 的 skill 会被安装；列出的已安装 skill 只改变其 enabled 状态；未列出的已安装 skill 会被卸载，内置的除外。
plugins	array<UHPPlugin>	否	需要 plugins 能力。每一项都需要 files 或 blob。
environment	string	否	调用方范围内的 environment ID，或为空。需要 environments 能力。
disabled_tools	array<string>	否	要禁用的工具名称。BeeOS Cloud 不支持：非空列表会被拒绝，返回 422 beeos_field_not_supported。
max_step	integer	否	每次运行的最大步数。BeeOS Cloud 不支持：任何值都会被拒绝，返回 422 beeos_field_not_supported。 可为 null。
timeout_seconds	integer	否	运行超时，单位为秒。BeeOS Cloud 不支持：任何值都会被拒绝，返回 422 beeos_field_not_supported。 可为 null。
instance_id	string	否	BeeOS 扩展。托管新 harness 的实例（仅创建时）。
template_id	string	否	BeeOS 扩展。应用到该 harness 的 agent 模板。

接受额外属性。

UHPHarnessModels

—

使用于: Harness

字段	类型	必填	说明
harness_id	string	否	这些模型所属的 harness 的 ID。
backend	string	否	所列模型都属于的提供方系列：模型 ID 中第一个 / 之前的部分，例如 anthropic。模型属于多个系列或没有系列时省略。
default	string	否	harness 主模型的 ID。没有时省略。
fallback	string	否	请求的模型无法运行时所使用的模型。BeeOS Cloud 不报告它，因此从不返回。
models	array<UHPModel>	是	harness 可以使用的模型，按其实例的模型列表的顺序。该列表为空时，只列出主模型。

UHPMcpServer

附加到 harness 的远程 MCP 服务器。只有已启用的条目会在回合中连接；已禁用的条目完全不得联系。无法访问的服务器不得使任务失败。与 2026-08-11 相比没有变化：进程（stdio）服务器在插件内部声明，见 PluginMcpServer。

使用于: Harness

字段	类型	必填	说明
name	string	是	由服务器清理为对 CLI 安全的标识符。
url	string	是	MCP 服务器的 HTTPS 端点，最多 2048 个字符，不含用户信息或片段。读取时报告为空。 约束: format=uri.
transport	string	否	服务器使用的传输方式。写入时默认为 http。两种传输都不使用的服务器不返回。 可选值: "http" — Streamable HTTP; "sse" — 较早的、基于 server-sent events 的 HTTP 传输. (枚举表) 默认值: "http".
enabled	boolean	否	服务器是否启用。读取时始终报告 true。服务器只能被设置或移除：发送 false 会被拒绝，返回 422 invalid_input。 默认值: true.
headers	map<string, string>	否	发送给服务器的请求 header，例如凭证。header 名称和值必须非空。从不返回。发送 header 或 auth 时还需要 expires_at。
auth	string	否	Bearer token，或由服务器解析的服务端引用。服务器绝不能向客户端返回已解析的凭证。
expires_at	string	否	BeeOS 扩展。所提供的短期凭证的过期时间；调用方通过再次 PUT 来刷新它。 约束: format=date-time.

接受额外属性。

UHPModel

—

使用于: Harness

字段	类型	必填	说明
id	string	是	模型的 ID，通常为 provider/model 形式，例如 anthropic/claude-sonnet-5。
label	string	否	模型的显示名称。BeeOS Cloud 不报告它，因此省略。
backend	string	否	模型的提供方系列：id 中第一个 / 之前的部分。id 中没有 / 时省略。
available	boolean	是	计算得出，而非声明：true 表示服务器此刻可以为该 harness 提供这个模型。把一个模型列为可用、随后却使任务失败，对客户端是最糟糕的结果，因为用户已经选择了它。
default	boolean	否	是否为该 harness 的主模型。

接受额外属性。

UHPModelCatalog

—

使用于: Harness

字段	类型	必填	说明
backends	map<string, object>	是	调用方的 harness 可以使用的模型，按提供方系列分组。每个键是一个提供方系列，即模型 ID 中第一个 / 之前的部分，例如 anthropic。每个值包含该系列的 default 模型 ID 及其 models；ID 中没有系列的模型不在此列出。

UHPOutputItem

客户端必须容忍它不认识的 item 类型。只渲染 message 项并忽略其余项的客户端是合法的客户端。

使用于: Responses

字段	类型	必填	说明
id	string	否	输出项的 ID。
type	string	是	输出项的类型。客户端应忽略不认识的项类型。 可选值: "message" — 智能体写的消息。文本在 content 中; "reasoning" — 智能体的推理。摘要在 summary 中; "function_call" — 智能体发起的工具调用，包含 name 和 arguments; "function_call_output" — 工具调用的结果，在 output 中. (枚举表) 按 type 区分的结构：见变体表。
status	string	否	该项的进度。 可选值: "in_progress" — 该项仍在生成中; "completed" — 该项已完成. (枚举表)
role	string	否	message 项的作者。 可选值: "assistant" — 智能体.
content	array<UHPContentPart>	否	message 项的内容部分。
summary	array<map<string, JSONValue>>	否	reasoning 项的摘要。
call_id	string	否	函数调用的 ID。function_call_output 项通过相同的 call_id 引用它所对应的调用。
name	string	否	智能体所调用函数的名称。
arguments	string	否	JSON，以字符串表示
output	string	否	函数调用的结果，文本形式。

接受额外属性。

UHPOutputItem 按 type 区分

UHPOutputItem 的结构取决于它自己的 type 值。

type 的取值	说明	结构
"message"	智能体写的消息。文本在 content 中。	UHPOutputItemMessage
"reasoning"	智能体的推理。摘要在 summary 中。	UHPOutputItemReasoning
"function_call"	智能体发起的工具调用，包含 name 和 arguments。	UHPOutputItemFunctionCall
"function_call_output"	工具调用的结果，在 output 中。	UHPOutputItemFunctionCallOutput

UHPOutputItemFunctionCall

智能体发起的工具调用。

使用于: Responses

字段	类型	必填	说明
type	string	是	固定为 function_call。
id	string	否	输出项的 ID。
status	string	否	该项的进度。 可选值: "in_progress" — 该项仍在生成中; "completed" — 该项已完成. (枚举表)
call_id	string	否	函数调用的 ID。function_call_output 项通过相同的 call_id 引用它所对应的调用。
name	string	否	智能体所调用函数的名称。
arguments	string	否	JSON，字符串形式

接受额外属性。

UHPOutputItemFunctionCallOutput

工具调用的结果。

使用于: Responses

字段	类型	必填	说明
type	string	是	固定为 function_call_output。
id	string	否	输出项的 ID。
status	string	否	该项的进度。 可选值: "in_progress" — 该项仍在生成中; "completed" — 该项已完成. (枚举表)
call_id	string	否	函数调用的 ID。function_call_output 项通过相同的 call_id 引用它所对应的调用。
output	string	否	函数调用的结果，文本形式。

接受额外属性。

UHPOutputItemMessage

智能体写的消息。

使用于: Responses

字段	类型	必填	说明
type	string	是	固定为 message。
id	string	否	输出项的 ID。
status	string	否	该项的进度。 可选值: "in_progress" — 该项仍在生成中; "completed" — 该项已完成. (枚举表)
role	string	否	message 项的作者。 可选值: "assistant" — 智能体.
content	array<UHPContentPart>	否	message 项的内容部分。

接受额外属性。

UHPOutputItemReasoning

智能体的推理。

使用于: Responses

字段	类型	必填	说明
type	string	是	固定为 reasoning。
id	string	否	输出项的 ID。
status	string	否	该项的进度。 可选值: "in_progress" — 该项仍在生成中; "completed" — 该项已完成. (枚举表)
summary	array<map<string, JSONValue>>	否	reasoning 项的摘要。

接受额外属性。

UHPPlugin

安装到 harness 中的 Agent Plugins 包：根目录下的 plugin.json，mcp.json 中的 MCP 服务器，skills/ 下的 skill。客户端写入 files（或回传 blob），以及可选的 name 和 enabled；服务器在每次写入时从包中推导 manifest、mcpServers、skills 和 skipped，并在输入中忽略这些字段。被拒绝的包不会改变 harness。

使用于: Harness

字段	类型	必填	说明
name	string	是	manifest 的 name。写入时可选；若发送则必须与 manifest 的一致。 约束: maxLength=64, pattern=^(?!.*(--|\.\.))[a-z0-9]([a-z0-9.-]*[a-z0-9])?$.
enabled	boolean	否	false 表示插件保持已安装但处于惰性状态；其中的任何内容都不会被具体化或被联系。 默认值: true.
files	array<UHPSkillFile>	否	该包。根目录下必须包含 plugin.json。
blob	string	否	服务器分配的句柄，用于在行外存储的包。客户端原样回传，并从插件文件端点读取文件。
manifest	UHPPluginManifest	否	插件的 plugin.json，已解析。
mcpServers	array<UHPPluginMcpServer>	否	从 mcp.json 推导。占位符按未展开的形式报告；enabled 始终为 true，由插件自己的 enabled 决定。
skills	array<UHPPluginSkill>	否	从 skills/ 推导，每个包含 SKILL.md 的直接子目录对应一项。
skipped	array<UHPPluginSkipped>	否	服务器发现但无法加载的内容。出现在服务器返回的每个插件对象上，没有被跳过的内容时为空。

接受额外属性。

UHPPluginManifest

解析后的 plugin.json。逐字段对应 Agent Plugins 1.0.0 manifest schema（https://agent-plugins.org/schemas/1.0.0/plugin.schema.json，Apache-2.0），并允许额外属性，因为 UHP 客户端会忽略它不认识的字段。manifest 自身的 $schema 所指明的 schema 具有权威性；服务器据此校验。

使用于: Harness

字段	类型	必填	说明
$schema	string	是	该文件所遵循的清单 schema 的 URI。 约束: format=uri.
name	string	是	插件的名称：1 到 64 个小写字母、数字、点和连字符，以字母或数字开头和结尾。 约束: minLength=1, maxLength=64, pattern=^(?!.*(--|\.\.))[a-z0-9]([a-z0-9.-]*[a-z0-9])?$.
version	string	否	插件的版本。
description	string	否	插件的描述。
author	object	否	插件的作者。
author.name	string	否	作者的姓名。
author.email	string	否	作者的电子邮件地址。
author.url	string	否	作者网页的 URL。
homepage	string	否	插件主页的 URL。
repository	string	否	插件源代码仓库的位置。
license	string	否	插件的许可证。
keywords	array<string>	否	描述插件的关键词。
extensions	map<string, map<string, JSONValue>>	否	按反向域名命名空间索引的客户端特定数据，依据 Agent Plugins §8。

接受额外属性。

UHPPluginMcpServer

插件的 mcp.json 所声明的 MCP 服务器，由服务器推导。即 harness MCP 服务器对象再加 stdio 传输：http 和 sse 需要 url，stdio 需要 command。占位符按未展开的形式报告；enabled 始终为 true，由插件自己的 enabled 决定。

使用于: Harness

字段	类型	必填	说明
name	string	是	服务器的名称，如 mcp.json 中声明的。
transport	string	否	http 是 Streamable HTTP（mcp.json 中为 streamable-http）；sse 是较旧的 HTTP+SSE 传输；stdio 是服务器在 agent 沙箱内启动的进程。 可选值: "http" — Streamable HTTP，在 mcp.json 中写作 streamable-http; "sse" — 较早的、基于 server-sent events 的 HTTP 传输; "stdio" — 由沙箱启动的本地进程，用 command、args、env 和 cwd 配置. (枚举表) 默认值: "http".
url	string	否	端点（http 和 sse）。 约束: format=uri.
headers	map<string, string>	否	固定的请求头（http 和 sse）。绝不进行占位符展开。
command	string	否	一个可执行文件 token（stdio）：在沙箱搜索路径上解析的裸名称，或以 ./ 开头的相对插件的路径。绝不是 shell 字符串，绝不展开。
args	array<string>	否	参数（stdio）。${PLUGIN_ROOT} 和 ${PLUGIN_DATA} 在运行时展开。
env	map<string, string>	否	环境变量覆盖（stdio）。不得指名 PLUGIN_ROOT 或 PLUGIN_DATA；这两个由服务器设置。值在运行时展开。
cwd	string	否	工作目录（stdio）。默认为插件根目录；必须保持在插件根目录或 PLUGIN_DATA 之内。
enabled	boolean	否	服务器是否启用。对于由插件的 mcp.json 派生的服务器，始终为 true。 默认值: true.

接受额外属性。

UHPPluginSkill

—

使用于: Harness

字段	类型	必填	说明
name	string	是	SKILL.md frontmatter 中的 name，与目录名相同。
description	string	否	来自该 skill 的 SKILL.md frontmatter 的描述。

接受额外属性。

UHPPluginSkipped

—

使用于: Harness

字段	类型	必填	说明
path	string	是	在包中的位置，例如 skills/broken、mcp.json#/mcpServers/redline、plugin.json#/vendorField。
reason	string	是	一句话。

接受额外属性。

UHPResponse

—

使用于: Responses

字段	类型	必填	说明
id	string	是	响应的 ID，以 resp_ 开头。 约束: pattern=^resp_.
object	string	是	对象类型。 可选值: "response" — 响应对象.
created_at	integer	是	Unix 秒
status	UHPResponseStatus	是	响应的状态。取值见 UHPResponseStatus。 取值见下表 UHPResponseStatus 取值。
error	UHPError	否	仅当 status 为 failed 时非空。 可为 null。
incomplete_details	map<string, JSONValue>	否	响应不完整的原因。status 为 incomplete 时包含 reason，达到时间限制时为 timeout。协议还为输出长度限制定义了 max_tokens，但本服务目前不会产生它。其他情况为 null。 可为 null。
previous_response_id	string	否	本响应所继续的响应的 ID，仅当请求设置了 previous_response_id 时才有。 可为 null。
model	string	是	实际运行的模型。
output	array<UHPOutputItem>	是	目前已产生的输出项，按顺序排列。
store	boolean	否	响应是否被保留以便之后获取。
usage	UHPUsage	否	服务器无法核算用量时为 null。编造的零会比如实的缺失更糟，因为客户端无法把它与免费任务区分开。 可为 null。
metadata	object	否	关于本次运行的附加信息。
metadata.session_id	string	否	响应所在会话的 ID。通过 previous_response_id 串联的响应共用同一会话。
metadata.environment	string	否	任务所读取的 environment（如果读取了的话）（能力 environments）。
metadata.requested_model	string	否	客户端发送的 ID（如果客户端发送了的话）。
metadata.model_fallback	boolean	否	仅当 harness 报告无法切换到所请求的模型时为 true。
metadata.model_fallback_reason	string	否	harness 为何运行了其默认模型而不是所请求的模型。harness 没有给出原因时，为 The harness ran its default model.
metadata.ignored_fields	array<string>	否	服务器没有执行的请求字段，按名称列出，顺序任意。当请求携带了被保留并忽略的 tools 或 include 时必填。被悄悄忽略的字段与被遵从的字段无法区分。Tasks §1.1 和 §1.4。

UHPResponseStatus 取值

取值	含义
"in_progress"	响应仍在运行。
"completed"	响应成功完成。
"failed"	任务无法完成。
"incomplete"	输出上限或时间上限等限制中止了任务。通常值得继续。
"cancelled"	客户端要求停止。被取消的响应不会被报告为 failed。

接受额外属性。

UHPSkill

skill 是一个文件夹，而不是一个文件。服务器必须把整个文件夹具体化到 agent 可以读取的位置——只具体化 SKILL.md 会破坏每一个带有 references、脚本或数据的 skill。通过 GET 和 PUT 往返一个 harness 不得丢失 skill 的内容。

使用于: Harness

字段	类型	必填	说明
name	string	是	skill 的名称，等于其文件夹的名称。为 1 到 128 个小写字母、数字、点、下划线和连字符，以字母或数字开头。已安装的 skill 为 2 到 64 个小写字母、数字和连字符。
enabled	boolean	否	false 会抑制该 skill，包括从 base 继承的 skill。 默认值: true.
files	array<UHPSkillFile>	否	该 bundle。必须包含 SKILL.md。
content	string	否	单文件 bundle 的简写，其唯一成员是 SKILL.md。
blob	string	否	服务器分配的句柄，用于在行外存储的 bundle。客户端接收它，原样回传，并从 skill 文件端点读取文件。
sha256	string	否	BeeOS 扩展。由 blob 引用的 Files bundle 的 SHA-256。
size_bytes	string	否	BeeOS 扩展。由 blob 引用的 Files bundle 的十进制字节大小。

接受额外属性。

UHPSkillFile

skill 文件夹或插件包中的一个文件。

使用于: Harness

字段	类型	必填	说明
path	string	是	相对于 skill 自己的文件夹或插件根目录；支持嵌套目录。服务器必须拒绝逃出该文件夹的路径。
content	string	否	文本内容。
content_b64	string	否	二进制内容的 Base64；逐字节保留。

接受额外属性。

UHPUsage

—

使用于: Responses

字段	类型	必填	说明
input_tokens	integer	否	输入 token 数。 约束: minimum=0.
output_tokens	integer	否	输出 token 数。 约束: minimum=0.
total_tokens	integer	否	使用的 token 总数。 约束: minimum=0.
cache_read_tokens	integer	否	从缓存读取的输入 token 数。 约束: minimum=0.
cache_write_tokens	integer	否	写入缓存的输入 token 数。 约束: minimum=0.

接受额外属性。

UpdateConversationInput

—

使用于: 会话

字段	类型	必填	说明
title	string	是	会话的新标题，去掉首尾空白后为 1 到 256 个字符。 约束: minLength=1, maxLength=256.

UpdateServerInstanceInput

—

使用于: 实例

字段	类型	必填	说明
name	string	否	新的显示名称，1 到 128 个字符，首尾不能有空白。发送 name、llm 或两者。
llm	RuntimeLLM	否	替换用的模型 provider 和模型。它会替换整个现有的 llm 块。Provider API key 为只写。当同时发送 name 时，先替换 llm 块。

枚举

每张表列出一个字段或参数的全部允许取值。超过 4 个取值、且属于某个对象结构字段的枚举，其取值表紧跟在该结构的字段表之后，这里只提供链接。含义列取自 OpenAPI 文档的 x-enumDescriptions；没有的取值显示“—”。

枚举	取值	定义于
A2AMessage.role 取值	"ROLE_USER", "ROLE_AGENT"	A2AMessage
A2ATaskStatus.state 取值	"TASK_STATE_SUBMITTED", "TASK_STATE_WORKING", "TASK_STATE_COMPLETED", "TASK_STATE_FAILED", "TASK_STATE_CANCELED", "TASK_STATE_INPUT_REQUIRED", "TASK_STATE_REJECTED", "TASK_STATE_AUTH_REQUIRED"	A2ATaskStatus
AgentAgent.conversation_transport 取值	"acp", "message-service"	AgentAgent
AgentAgent.status 取值	"active", "inactive"	AgentAgent
AgentAgent.visibility 取值	"private", "unlisted", "org", "public", "marketplace"	AgentAgent
agentBindDetailsWire.status 取值	"pending", "confirming", "bound"	agentBindDetailsWire
agentBindWire.status 取值	"pending", "bound"	agentBindWire
AgentPatch.visibility 取值	"private", "unlisted", "org", "public", "marketplace"	AgentPatch
AgentSnapshot.conversation_transport 取值	"acp", "message-service"	AgentSnapshot
AgentSnapshot.status 取值	"active", "inactive"	AgentSnapshot
AgentSnapshot.visibility 取值	"private", "unlisted", "org", "public", "marketplace"	AgentSnapshot
Binding.client_type 取值	"web", "native"	Binding
CanvasTicketClaims.role 取值	"viewer", "editor"	CanvasTicketClaims
ClientSessionInput.client_type 取值	"web", "native"	ClientSessionInput
CommandReceipt.status 取值	"accepted", "completed"	CommandReceipt
ConnectURLResponse.data.browser.role 取值	"viewer", "controller"	ConnectURLResponse
ConnectURLResponse.data.connectivity 取值	"unknown", "online", "offline"	ConnectURLResponse
ConnectURLResponse.data.mode 取值	"browser-runtime", "service-websocket"	ConnectURLResponse
ConnectURLResponse.data.service 取值	"browser", "acp"	ConnectURLResponse
Conversation.state 取值	"open", "closed"	Conversation
conversations.list state 取值	"open", "closed", "all"	conversations.list
Deletion.status 取值	"pending", "processing", "failed", "completed"	Deletion
DeletionAccepted.status 取值	"pending", "processing", "failed", "completed"	DeletionAccepted
deviceBindings.resolvePortal request.decision 取值	"recover", "create"	deviceBindings.resolvePortal
FileFile.file_type 取值	"FILE_TYPE_IMAGE", "FILE_TYPE_VIDEO", "FILE_TYPE_AUDIO", "FILE_TYPE_DOCUMENT", "FILE_TYPE_ARCHIVE", "FILE_TYPE_OTHER"	FileFile
FileFile.status 取值	"pending_upload", "ready"	FileFile
FileOrigin.source 取值	"manual", "chat_upload", "runtime_generated", "template_skill"	FileOrigin
FileSummary.instances[].source 取值	"manual", "chat_upload", "runtime_generated", "template_skill"	FileSummary
FileTransferDescriptor.direction 取值	"upload", "download"	FileTransferDescriptor
InstanceSummary.connectivity 取值	"unknown", "online", "offline"	InstanceSummary
InstanceSummary.desired_status 取值	"running", "stopped", "terminated"	InstanceSummary
InstanceSummary.status 取值	"pending", "provisioning", "running", "stopped", "terminated"	InstanceSummary
Message.realtime_publish_status 取值	"published", "unconfirmed", "not_republished"	Message
Message.state 取值	"streaming", "completed", "failed", "refused", "cancelled"	Message
Message.stop_reason 取值	"end_turn", "max_tokens", "tool_use", "user_stop", "timeout", "error", "refused", "content_filter", "agent_lost"	Message
Message.type 取值	"chat_message", "agent_reply", "agent_reply_error", "agent.refuse", "agent_busy", "agent_reply_delta", "agent_reasoning", "a2a_status_update", "a2a_result", "agent_request", "a2a_task", "chat_cancel", "device_command", "device_result", "device_error"	Message
MessageEnvelope.state 取值	"streaming", "completed", "failed", "refused", "cancelled"	MessageEnvelope
MessageEnvelope.stop_reason 取值	"end_turn", "max_tokens", "tool_use", "user_stop", "timeout", "error", "refused", "content_filter", "agent_lost"	MessageEnvelope
MessageEnvelope.type 取值	"chat_message", "agent_reply", "agent_reply_error", "agent.refuse", "agent_busy", "agent_reply_delta", "agent_reasoning", "a2a_status_update", "a2a_result", "agent_request", "a2a_task", "chat_cancel", "device_command", "device_result", "device_error"	MessageEnvelope
MessagePartThinking.state 取值	"streaming", "done"	MessagePartThinking
MessagePartToolUse.state 取值	"streaming", "done"	MessagePartToolUse
portalBindWire.status 取值	"pending", "awaiting_confirmation", "confirming", "bound", "revoked"	portalBindWire
ProtoAutomationRule.status 取值	"enabled", "paused", "expired"	ProtoAutomationRule
ProtoAutomationRule.triggerKind 取值	"schedule", "webhook"	ProtoAutomationRule
ProtoAutomationRun.rerunSessionMode 取值	"original", "new"	ProtoAutomationRun
ProtoAutomationRun.status 取值	"scheduled", "dispatched", "failed", "skipped"	ProtoAutomationRun
ProtoAutomationRun.triggerType 取值	"schedule", "manual", "rerun", "webhook"	ProtoAutomationRun
ProtoAutomationRunInput.rerunSessionMode 取值	"original", "new"	ProtoAutomationRunInput
ProtoAutomationSchedule.kind 取值	"at", "every", "cron"	ProtoAutomationSchedule
ProtoAutomationSession.mode 取值	"new", "bound"	ProtoAutomationSession
RuntimeInstanceStatusResult.data.connectivity 取值	"unknown", "online", "offline"	RuntimeInstanceStatusResult
RuntimeInstanceStatusResult.data.desired_status 取值	"running", "stopped", "terminated"	RuntimeInstanceStatusResult
RuntimeInstanceStatusResult.data.status 取值	"pending", "provisioning", "running", "stopped", "terminated"	RuntimeInstanceStatusResult
RuntimeInstanceSummary.connectivity 取值	"unknown", "online", "offline"	RuntimeInstanceSummary
RuntimeInstanceSummary.desired_status 取值	"running", "stopped", "terminated"	RuntimeInstanceSummary
RuntimeInstanceSummary.status 取值	"pending", "provisioning", "running", "stopped", "terminated"	RuntimeInstanceSummary
RuntimeLLMModel.role 取值	"default", "fallback", "available"	RuntimeLLMModel
RuntimeLLMProvider.protocol 取值	"openai", "anthropic"	RuntimeLLMProvider
RuntimeOperationSummary.kind 取值	"create", "start", "stop", "delete", "image_upgrade"	RuntimeOperationSummary
RuntimeOperationSummary.phase 取值	"intent", "reserved", "admitted", "provisioning", "running", "cleanup_pending", "failed", "stop_pending", "stopped", "delete_pending", "deleted", "upgrade_pending", "rollback_pending"	RuntimeOperationSummary
RuntimeUpgradeJob.status 取值	"upgrade_pending", "rollback_pending", "failed", "succeeded"	RuntimeUpgradeJob
UHPContentPart.type 取值	"output_text", "summary_text"	UHPContentPart
UHPDiscovery.conformance_class 取值	"core", "extended", "full"	UHPDiscovery
UHPError.type 取值	"invalid_request_error", "authentication_error", "permission_error", "rate_limit_error", "harness_error", "server_error"	UHPError
UHPEvent.type 取值	"response.created", "response.in_progress", "response.output_item.added", "response.output_item.done", "response.content_part.added", "response.content_part.done", "response.output_text.delta", "response.output_text.done", "response.output_text.annotation.added", "response.reasoning_summary_part.added", "response.reasoning_summary_text.delta", "response.reasoning_summary_part.done", "response.function_call_arguments.delta", "response.function_call_arguments.done", "response.completed", "response.incomplete", "response.failed", "error", "beeos.approval.requested", "beeos.approval.resolved", "beeos.question.requested", "beeos.question.resolved"	UHPEvent
UHPMcpServer.transport 取值	"http", "sse"	UHPMcpServer
UHPOutputItem.status 取值	"in_progress", "completed"	UHPOutputItem
UHPOutputItem.type 取值	"message", "reasoning", "function_call", "function_call_output"	UHPOutputItem
UHPOutputItemFunctionCall.status 取值	"in_progress", "completed"	UHPOutputItemFunctionCall
UHPOutputItemFunctionCallOutput.status 取值	"in_progress", "completed"	UHPOutputItemFunctionCallOutput
UHPOutputItemMessage.status 取值	"in_progress", "completed"	UHPOutputItemMessage
UHPOutputItemReasoning.status 取值	"in_progress", "completed"	UHPOutputItemReasoning
UHPPluginMcpServer.transport 取值	"http", "sse", "stdio"	UHPPluginMcpServer
UHPResponseStatus 取值	"in_progress", "completed", "failed", "incomplete", "cancelled"	—
usage.getSummary period 取值	"day", "week", "month"	usage.getSummary

A2AMessage.role 取值

消息的作者：ROLE_USER 为调用方，ROLE_AGENT 为智能体。

定义于: A2AMessage

取值	含义
"ROLE_USER"	该消息由调用方撰写。
"ROLE_AGENT"	该消息由智能体撰写。

AgentAgent.conversation_transport 取值

会话消息如何到达智能体。以后可能新增取值，请忽略不认识的取值。

定义于: AgentAgent

取值	含义
"acp"	会话消息通过智能体的 ACP 连接与其交换。
"message-service"	会话消息通过 BeeOS 消息服务以消息的形式投递给智能体。

AgentAgent.status 取值

智能体当前是否由其实例提供。

定义于: AgentAgent

取值	含义
"active"	该实例当前提供此智能体。
"inactive"	该实例不再提供此智能体，例如实例已被移除，或已被同名的另一个智能体替换。记录会保留。

agentBindDetailsWire.status 取值

绑定会话的状态。已过期的会话会被删除，因此对已过期会话的查询会失败，返回 404 not_found。

定义于: agentBindDetailsWire

取值	含义
"pending"	由设备创建，等待用户确认。
"confirming"	用户已确认，正在为该设备创建实例。
"bound"	已确认：实例存在，设备可以连接它。

agentBindWire.status 取值

绑定会话的状态。确认成功后为 bound；仍在等待确认的会话报告 pending。

定义于: agentBindWire

取值	含义
"pending"	由设备创建，等待用户确认。正在确认的会话也报告 pending。
"bound"	已确认：实例存在，设备可以连接它。

AgentSnapshot.conversation_transport 取值

会话消息如何到达智能体。以后可能新增取值，请忽略不认识的取值。

定义于: AgentSnapshot

取值	含义
"acp"	会话消息通过智能体的 ACP 连接与其交换。
"message-service"	会话消息通过 BeeOS 消息服务以消息的形式投递给智能体。

AgentSnapshot.status 取值

智能体当前是否由其实例提供。

定义于: AgentSnapshot

取值	含义
"active"	该实例当前提供此智能体。
"inactive"	该实例不再提供此智能体，例如实例已被移除，或已被同名的另一个智能体替换。记录会保留。

Binding.client_type 取值

token 如何绑定到客户端。

定义于: Binding

取值	含义
"web"	绑定到网页来源，在 origin 中返回。
"native"	绑定到设备密钥，其指纹在 cnf_jkt 中返回。

CanvasTicketClaims.role 取值

在该画布上授予的访问角色：viewer 或 editor。

定义于: CanvasTicketClaims

取值	含义
"viewer"	可以查看画布，但不能修改。
"editor"	可以查看和编辑画布。

ClientSessionInput.client_type 取值

客户端 token 如何绑定到将使用它的客户端。它决定你发送 origin 还是 device_attestation。

定义于: ClientSessionInput

取值	含义
"web"	浏览器客户端。token 绑定到你在 origin 中发送的页面来源，该来源必须是应用配置的允许来源之一。不得发送 device_attestation。与此绑定不符的请求返回 403 invalid_origin。
"native"	原生应用。token 绑定到设备密钥，其指纹由你在 device_attestation.jkt 中发送。不得发送 origin。与此绑定不符的请求返回 403 invalid_origin。

CommandReceipt.status 取值

调用返回时请求的结果。

定义于: CommandReceipt

取值	含义
"accepted"	请求已排队等待智能体处理，尚未生效。请读取会话消息以跟踪结果。
"completed"	变更已在调用返回前生效。

ConnectURLResponse.data.browser.role 取值

该授权的访问角色：viewer 或 controller。

定义于: ConnectURLResponse

取值	含义
"viewer"	可以查看浏览器，但不能控制。
"controller"	可以查看并控制浏览器。

ConnectURLResponse.data.connectivity 取值

实例中 agent 的可达性：unknown、online 或 offline。

定义于: ConnectURLResponse

取值	含义
"unknown"	尚未确定可达性。
"online"	该实例的智能体已连接。
"offline"	该实例的智能体未连接。

ConnectURLResponse.data.mode 取值

连接模式：browser 对应 browser-runtime，acp 对应 service-websocket。

定义于: ConnectURLResponse

取值	含义
"browser-runtime"	浏览器查看会话；使用 url 和 token 连接。
"service-websocket"	到智能体服务的 WebSocket 连接；url 已带有访问 ticket。

ConnectURLResponse.data.service 取值

该 URL 所连接的服务：browser 或 acp。

定义于: ConnectURLResponse

取值	含义
"browser"	浏览器查看器。
"acp"	通过 WebSocket 连接智能体。

Conversation.state 取值

会话是否仍接受消息。已关闭的会话仍可读取，但不能接收新消息。

定义于: Conversation

取值	含义
"open"	会话接受新消息。
"closed"	会话已关闭，例如被删除。closed_at 已设置，向其发送消息返回 410 conversation_closed。

conversations.list state 取值

定义于: conversations.list

取值	含义
"open"	—
"closed"	—
"all"	—

Deletion.status 取值

删除的状态。轮询直到其为 completed。

定义于: Deletion

取值	含义
"pending"	删除已排队，尚未开始。
"processing"	删除正在进行。
"failed"	最近一次尝试因错误而停止，错误见 error_code。删除会自动重试。
"completed"	该用户的全部数据已被删除。

DeletionAccepted.status 取值

请求被接受时删除的状态。

定义于: DeletionAccepted

取值	含义
"pending"	删除已排队，尚未开始。
"processing"	删除正在进行。
"failed"	最近一次尝试因错误而停止，错误见 error_code。删除会自动重试。
"completed"	该用户的全部数据已被删除。

deviceBindings.resolvePortal request.decision 取值

如何处理认领了该会话的设备。必填。

定义于: deviceBindings.resolvePortal

取值	含义
"recover"	把设备绑定到 instance_id 所指的现有实例。
"create"	为设备创建新实例。

FileFile.status 取值

文件的上传状态。已删除的文件永远不会返回。以后可能新增状态，请忽略不认识的取值。

定义于: FileFile

取值	含义
"pending_upload"	上传已准备好，但尚未确认。文件还没有可下载的内容。
"ready"	上传已确认。文件可以下载、重命名、分享和删除。

FileOrigin.source 取值

文件是如何产生的。以后可能新增取值，请忽略不认识的取值。

定义于: FileOrigin

取值	含义
"manual"	通过 files API 直接上传，不带 upload context。没有记录来源的文件按 manual 报告。
"chat_upload"	带 upload_context 上传，用于与其所指定的智能体的会话。
"runtime_generated"	由智能体在处理请求时生成。operation_id 标识该操作。
"template_skill"	由模板 skill 提供。该文件只读：不能重命名或删除，也不计入存储用量。

FileSummary.instances[].source 取值

文件是如何产生的。以后可能新增取值，请忽略不认识的取值。

定义于: FileSummary

取值	含义
"manual"	通过 files API 直接上传，不带 upload context。没有记录来源的文件按 manual 报告。
"chat_upload"	带 upload_context 上传，用于与其所指定的智能体的会话。
"runtime_generated"	由智能体在处理请求时生成。operation_id 标识该操作。
"template_skill"	由模板 skill 提供。该文件只读：不能重命名或删除，也不计入存储用量。

FileTransferDescriptor.direction 取值

该 URL 用于上传还是下载文件内容。

定义于: FileTransferDescriptor

取值	含义
"upload"	用 http_method 把文件内容发送到 url。准备上传时返回。
"download"	用 http_method 从 url 获取文件内容。读取文件或分享时返回。

InstanceSummary.connectivity 取值

实例中 agent 的可达性：unknown、online 或 offline。

定义于: InstanceSummary

取值	含义
"unknown"	尚未确定可达性。
"online"	该实例的智能体已连接。
"offline"	该实例的智能体未连接。

InstanceSummary.desired_status 取值

实例正被驱动朝向的生命周期阶段：running、stopped 或 terminated。

定义于: InstanceSummary

取值	含义
"running"	实例应处于运行状态。
"stopped"	实例应处于停止状态。
"terminated"	实例应被删除。

Message.realtime_publish_status 取值

保留字段。Server API 目前不返回该字段。

定义于: Message

取值	含义
"published"	—
"unconfirmed"	—
"not_republished"	—

MessagePartThinking.state 取值

推理是否仍在生成中。

定义于: MessagePartThinking

取值	含义
"streaming"	该部分仍在生成中。
"done"	该部分已完成。缺少 state 也表示已完成。

MessagePartToolUse.state 取值

参数是否仍在生成中。

定义于: MessagePartToolUse

取值	含义
"streaming"	该部分仍在生成中。
"done"	该部分已完成。缺少 state 也表示已完成。

ProtoAutomationRule.status 取值

自动化的状态。

定义于: ProtoAutomationRule

取值	含义
"enabled"	活跃。schedule 自动化在 nextFireAt 运行；webhook 自动化响应传入的事件。
"paused"	已用暂停操作暂停。恢复之前不会创建运行。
"expired"	没有剩余运行次数的 schedule 自动化，例如已执行完的 at 调度，或已超过 validUntil。

ProtoAutomationRule.triggerKind 取值

什么触发运行。在 webhook 触发器出现之前创建的自动化可能报告空值；请把它当作 schedule。

定义于: ProtoAutomationRule

取值	含义
"schedule"	按 schedule 启动运行。
"webhook"	事件源投递事件时启动运行，可用 eventFilter 进一步筛选。

ProtoAutomationRun.rerunSessionMode 取值

重跑被投递到哪个会话。不是重跑的运行为空。

定义于: ProtoAutomationRun

取值	含义
"original"	来源运行所投递到的会话。
"new"	新会话。

ProtoAutomationRun.status 取值

运行的投递状态。它说明提示是否到达智能体的会话，而不是智能体是否完成了工作。

定义于: ProtoAutomationRun

取值	含义
"scheduled"	已创建，等待投递。reasonCode 为 dispatch_unconfirmed 表示投递已开始，结果尚未确认。
"dispatched"	提示已被 conversationId 所指的会话接收。
"failed"	在发送提示之前投递就被拒绝。原因见 reasonCode。
"skipped"	未投递，因为运行到期时某个条件已不再成立。原因见 reasonCode。

ProtoAutomationRun.triggerType 取值

是什么创建了该运行。

定义于: ProtoAutomationRun

取值	含义
"schedule"	自动化的调度到期。
"manual"	调用方通过 create-run 操作启动。
"rerun"	调用方通过 create-run 操作启动，用于重复 sourceRunId 中的先前运行。
"webhook"	webhook 自动化收到了事件。

ProtoAutomationRunInput.rerunSessionMode 取值

重跑被投递到哪个会话。发送 sourceRunId 时必填，没有 sourceRunId 时不允许。

定义于: ProtoAutomationRunInput

取值	含义
"original"	来源运行所投递到的会话。
"new"	新会话。

ProtoAutomationSchedule.kind 取值

调度的类型。它决定其他哪些字段必填。

定义于: ProtoAutomationSchedule

取值	含义
"at"	在 at 运行一次。
"every"	重复运行，每隔 intervalSeconds 秒一次，从 anchorAt 起算。
"cron"	按五字段 cron expression 运行，在时区 tz 中计算。

ProtoAutomationSession.mode 取值

运行如何选择其所投递的会话。

定义于: ProtoAutomationSession

取值	含义
"new"	每次运行都与智能体开启一个新会话。通过此 API 创建的自动化总是使用该方式。
"bound"	每次运行都投递到 boundConversationId 所指的会话。

RuntimeInstanceStatusResult.data.connectivity 取值

实例中 agent 的可达性：unknown、online 或 offline。

定义于: RuntimeInstanceStatusResult

取值	含义
"unknown"	尚未确定可达性。
"online"	该实例的智能体已连接。
"offline"	该实例的智能体未连接。

RuntimeInstanceStatusResult.data.desired_status 取值

实例正被驱动朝向的生命周期阶段：running、stopped 或 terminated。

定义于: RuntimeInstanceStatusResult

取值	含义
"running"	实例应处于运行状态。
"stopped"	实例应处于停止状态。
"terminated"	实例应被删除。

RuntimeInstanceSummary.connectivity 取值

实例中 agent 的可达性：unknown、online 或 offline。

定义于: RuntimeInstanceSummary

取值	含义
"unknown"	尚未确定可达性。
"online"	该实例的智能体已连接。
"offline"	该实例的智能体未连接。

RuntimeInstanceSummary.desired_status 取值

实例正被驱动朝向的生命周期阶段：running、stopped 或 terminated。

定义于: RuntimeInstanceSummary

取值	含义
"running"	实例应处于运行状态。
"stopped"	实例应处于停止状态。
"terminated"	实例应被删除。

RuntimeLLMModel.role 取值

模型的角色：default、fallback 或 available。恰好一个模型是 default。自动故障转移只使用 fallback 模型。

定义于: RuntimeLLMModel

取值	含义
"default"	实例默认使用的模型。只有一个模型具有此角色，其 order 为 0。
"fallback"	默认模型失败时，自动故障切换所切换到的模型。
"available"	可以被选择、但从不用于自动故障切换的模型。

RuntimeLLMProvider.protocol 取值

该端点使用的 API 协议：openai 或 anthropic。

定义于: RuntimeLLMProvider

取值	含义
"openai"	OpenAI 兼容 API。
"anthropic"	Anthropic Messages API。

RuntimeUpgradeJob.status 取值

任务的状态：upgrade_pending、rollback_pending、failed 或 succeeded。

定义于: RuntimeUpgradeJob

取值	含义
"upgrade_pending"	正在应用镜像升级。
"rollback_pending"	镜像升级失败，实例正在回滚到之前的镜像。
"failed"	镜像升级失败。见 error。
"succeeded"	镜像升级已完成，实例运行目标版本。

UHPContentPart.type 取值

该部分的类型。

定义于: UHPContentPart

取值	含义
"output_text"	message 项的文本，可带注释。
"summary_text"	reasoning 项的摘要文本。

UHPDiscovery.conformance_class 取值

服务器的粗粒度一致性级别。请依据 capabilities 中精确的标志分支，而不是依据该级别。

定义于: UHPDiscovery

取值	含义
"core"	发现、harness 读取、任务和会话。
"extended"	Core 加上文件输入和产物获取。
"full"	Extended 加上 harness 管理、插件、环境和记忆。

UHPMcpServer.transport 取值

服务器使用的传输方式。写入时默认为 http。两种传输都不使用的服务器不返回。

定义于: UHPMcpServer

取值	含义
"http"	Streamable HTTP。
"sse"	较早的、基于 server-sent events 的 HTTP 传输。

UHPOutputItem.status 取值

该项的进度。

定义于: UHPOutputItem

取值	含义
"in_progress"	该项仍在生成中。
"completed"	该项已完成。

UHPOutputItem.type 取值

输出项的类型。客户端应忽略不认识的项类型。

定义于: UHPOutputItem

取值	含义
"message"	智能体写的消息。文本在 content 中。
"reasoning"	智能体的推理。摘要在 summary 中。
"function_call"	智能体发起的工具调用，包含 name 和 arguments。
"function_call_output"	工具调用的结果，在 output 中。

UHPOutputItemFunctionCall.status 取值

该项的进度。

定义于: UHPOutputItemFunctionCall

取值	含义
"in_progress"	该项仍在生成中。
"completed"	该项已完成。

UHPOutputItemFunctionCallOutput.status 取值

该项的进度。

定义于: UHPOutputItemFunctionCallOutput

取值	含义
"in_progress"	该项仍在生成中。
"completed"	该项已完成。

UHPOutputItemMessage.status 取值

该项的进度。

定义于: UHPOutputItemMessage

取值	含义
"in_progress"	该项仍在生成中。
"completed"	该项已完成。

UHPOutputItemReasoning.status 取值

该项的进度。

定义于: UHPOutputItemReasoning

取值	含义
"in_progress"	该项仍在生成中。
"completed"	该项已完成。

UHPPluginMcpServer.transport 取值

http 是 Streamable HTTP（mcp.json 中为 streamable-http）；sse 是较旧的 HTTP+SSE 传输；stdio 是服务器在 agent 沙箱内启动的进程。

定义于: UHPPluginMcpServer

取值	含义
"http"	Streamable HTTP，在 mcp.json 中写作 streamable-http。
"sse"	较早的、基于 server-sent events 的 HTTP 传输。
"stdio"	由沙箱启动的本地进程，用 command、args、env 和 cwd 配置。

usage.getSummary period 取值

定义于: usage.getSummary

取值	含义
"day"	—
"week"	—
"month"	—