BEEOS CLOUD / DEVELOPER REFERENCE

消息

列出、读取会话消息并管理回复分享链接。

概览

messages domain 读取会话的消息，并管理回复的分享链接。

6 个操作 · SDK 资源：TypeScript cloud.messages · Python cloud.messages · Go cloud.Messages · API 总览

主要对象

MessageEnvelopeResponse：单条消息；MessagePage 列出消息。
ReplyShareResponse：分享链接所指向的回复。

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

完整字段和使用该对象的方法见附录。

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`	否	保留字段。服务器目前不返回该字段。

完整字段和使用该对象的方法见附录。

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"`	服务端结束了该消息，因为生成它的智能体已不再运行，例如崩溃或被替换。

完整字段和使用该对象的方法见附录。

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"`	服务端结束了该消息，因为生成它的智能体已不再运行，例如崩溃或被替换。

完整字段和使用该对象的方法见附录。

典型流程

用 messages.list 列出会话的消息，用 messages.get 读取其中一条。
用 messages.createShare 分享某条回复；用 messages.getShare 读取已有链接。
拿到 slug 的人可以通过 messages.resolveShare 打开该回复。
用 messages.revokeShare 撤回链接。

方法

方法	HTTP	摘要
messages.list	`GET /v1/agents/{agentId}/conversations/{conversationId}/messages`	列出会话消息
messages.get	`GET /v1/agents/{agentId}/conversations/{conversationId}/messages/{messageId}`	获取一条会话消息
messages.getShare	`GET /v1/agents/{agentId}/conversations/{conversationId}/messages/{messageId}/share`	获取回复分享链接
messages.createShare	`POST /v1/agents/{agentId}/conversations/{conversationId}/messages/{messageId}/share`	创建回复分享链接
messages.revokeShare	`DELETE /v1/agents/{agentId}/conversations/{conversationId}/messages/{messageId}/share`	撤销回复分享链接
messages.resolveShare	`GET /v1/reply-shares/{slug}`	解析回复分享链接

messages.list

GET /v1/agents/{agentId}/conversations/{conversationId}/messages · Operation ID listConversationMessages

列出会话消息

所需 scope: messages:read.

SDK 方法

语言	方法	签名
TypeScript	`cloud.messages.list`	`list(agentId: string, conversationId: string, query?: Models.ListConversationMessagesQuery): Promise<Models.ListConversationMessagesResponse>`
Python	`cloud.messages.list`	`def list(self, agent_id: str, conversation_id: str, options: ListConversationMessagesOptions \| None = None) -> MessagePage`
Go	`cloud.Messages.List`	`func (r *MessagesResource) List(ctx context.Context, agentId string, conversationId string, options ListConversationMessagesOptions) (MessagePage, error)`

参数

参数	位置	类型	必填	说明
`agentId`	path	`string`	是	智能体的 ID，即 agents API 返回的 `id`。
`conversationId`	path	`string`	是	会话的 ID，即创建或列出会话时返回的 ID。
`cursor`	query	`string`	否	上一页 `next_cursor` 返回的游标。省略则获取第一页。最多 4096 个字符。
`limit`	query	`integer`	否	一页中返回的消息的最大数量。默认为 50。服务器接受 1 到 200 的值。约束: `minimum=1`, `maximum=100`.

响应

200 权威的消息历史页 · application/json · Schema: 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`.

错误

状态码	Schema	说明
其他（default）	ErrorResponse	Cloud Server 错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.messages.list("agent_123", "conversation_123");
console.log(result);

messages.get

GET /v1/agents/{agentId}/conversations/{conversationId}/messages/{messageId} · Operation ID getConversationMessage

获取一条会话消息

所需 scope: messages:read.

SDK 方法

语言	方法	签名
TypeScript	`cloud.messages.get`	`get(agentId: string, conversationId: string, messageId: string): Promise<Models.GetConversationMessageResponse>`
Python	`cloud.messages.get`	`def get(self, agent_id: str, conversation_id: str, message_id: str) -> MessageEnvelopeResponse`
Go	`cloud.Messages.Get`	`func (r *MessagesResource) Get(ctx context.Context, agentId string, conversationId string, messageId string) (MessageEnvelopeResponse, error)`

参数

参数	位置	类型	必填	说明
`agentId`	path	`string`	是	智能体的 ID，即 agents API 返回的 `id`。
`conversationId`	path	`string`	是	会话的 ID，即创建或列出会话时返回的 ID。
`messageId`	path	`string`	是	消息的 ID。

响应

200 权威的 v3 消息快照 · application/json · Schema: MessageEnvelopeResponse

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

错误

状态码	Schema	说明
其他（default）	ErrorResponse	Cloud Server 错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.messages.get("agent_123", "conversation_123", "message_123");
console.log(result);

messages.getShare

GET /v1/agents/{agentId}/conversations/{conversationId}/messages/{messageId}/share · Operation ID getShareReply

获取回复分享链接

SDK 方法

语言	方法	签名
TypeScript	`cloud.messages.getShare`	`getShare(agentId: string, conversationId: string, messageId: string): Promise<Models.GetShareReplyResponse>`
Python	`cloud.messages.get_share`	`def get_share(self, agent_id: str, conversation_id: str, message_id: str) -> GetShareReplyResponse`
Go	`cloud.Messages.GetShare`	`func (r *MessagesResource) GetShare(ctx context.Context, agentId string, conversationId string, messageId string) (GetShareReplyResponse, error)`

参数

参数	位置	类型	必填	说明
`agentId`	path	`string`	是	智能体的 ID，即 agents API 返回的 `id`。
`conversationId`	path	`string`	是	会话的 ID，即创建或列出会话时返回的 ID。
`messageId`	path	`string`	是	消息的 ID。

响应

200 · application/json

字段	类型	必填	说明
`data`	`object`	是	该回复的分享。
`data.slug`	`string`	是	标识该分享的公开 slug。用它通过回复分享查询来解析被分享的回复。
`data.created_at`	`string`	是	分享的创建时间。

错误

状态码	Schema	说明
其他（default）	ErrorResponse	Cloud Server 错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.messages.getShare("agent_123", "conversation_123", "message_123");
console.log(result);

messages.createShare

POST /v1/agents/{agentId}/conversations/{conversationId}/messages/{messageId}/share · Operation ID createShareReply

创建回复分享链接

SDK 方法

语言	方法	签名
TypeScript	`cloud.messages.createShare`	`createShare(agentId: string, conversationId: string, messageId: string): Promise<Models.CreateShareReplyResponse>`
Python	`cloud.messages.create_share`	`def create_share(self, agent_id: str, conversation_id: str, message_id: str) -> CreateShareReplyResponse`
Go	`cloud.Messages.CreateShare`	`func (r *MessagesResource) CreateShare(ctx context.Context, agentId string, conversationId string, messageId string) (CreateShareReplyResponse, error)`

参数

参数	位置	类型	必填	说明
`agentId`	path	`string`	是	智能体的 ID，即 agents API 返回的 `id`。
`conversationId`	path	`string`	是	会话的 ID，即创建或列出会话时返回的 ID。
`messageId`	path	`string`	是	消息的 ID。

响应

200 · application/json

字段	类型	必填	说明
`data`	`object`	是	该回复的分享。
`data.slug`	`string`	是	标识该分享的公开 slug。用它通过回复分享查询来解析被分享的回复。
`data.created_at`	`string`	是	分享的创建时间。

错误

状态码	Schema	说明
其他（default）	ErrorResponse	Cloud Server 错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.messages.createShare("agent_123", "conversation_123", "message_123");
console.log(result);

messages.revokeShare

DELETE /v1/agents/{agentId}/conversations/{conversationId}/messages/{messageId}/share · Operation ID revokeShareReply

撤销回复分享链接

SDK 方法

语言	方法	签名
TypeScript	`cloud.messages.revokeShare`	`revokeShare(agentId: string, conversationId: string, messageId: string): Promise<Models.RevokeShareReplyResponse>`
Python	`cloud.messages.revoke_share`	`def revoke_share(self, agent_id: str, conversation_id: str, message_id: str) -> None`
Go	`cloud.Messages.RevokeShare`	`func (r *MessagesResource) RevokeShare(ctx context.Context, agentId string, conversationId string, messageId string) error`

参数

参数	位置	类型	必填	说明
`agentId`	path	`string`	是	智能体的 ID，即 agents API 返回的 `id`。
`conversationId`	path	`string`	是	会话的 ID，即创建或列出会话时返回的 ID。
`messageId`	path	`string`	是	消息的 ID。

响应

204

无响应体。

错误

状态码	Schema	说明
其他（default）	ErrorResponse	Cloud Server 错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.messages.revokeShare("agent_123", "conversation_123", "message_123");
console.log(result);

messages.resolveShare

GET /v1/reply-shares/{slug} · Operation ID resolveReplyShare

解析回复分享链接

SDK 方法

语言	方法	签名
TypeScript	`cloud.messages.resolveShare`	`resolveShare(slug: string): Promise<Models.ResolveReplyShareResponse>`
Python	`cloud.messages.resolve_share`	`def resolve_share(self, slug: str) -> ReplyShareResponse`
Go	`cloud.Messages.ResolveShare`	`func (r *MessagesResource) ResolveShare(ctx context.Context, slug string) (ReplyShareResponse, error)`

参数

参数	位置	类型	必填	说明
`slug`	path	`string`	是	分享回复的公开 slug，即创建分享时返回的 `data.slug`。

响应

200 · application/json · Schema: 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`	否	保留字段。服务器目前不返回该字段。

错误

状态码	Schema	说明
其他（default）	ErrorResponse	Cloud Server 错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.messages.resolveShare("share_slug");
console.log(result);

按判别字段区分的结构

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

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

BeeOS Cloud返回文档首页