BEEOS CLOUD / DEVELOPER REFERENCE

会话

创建、列出、重命名、删除、取消、恢复与清空会话；设置模型、推理强度与审批模式。

概览

conversations domain 管理某个智能体的会话：创建、列出、读取、重命名和删除，取消或恢复执行，清空历史，并设置模型、推理强度和审批模式。每个操作都以 agent ID 为范围。

11 个操作 · SDK 资源：TypeScript cloud.conversations · Python cloud.conversations · Go cloud.Conversations · API 总览

主要对象

CreateConversationInput 与 UpdateConversationInput：创建和重命名会话的请求。
ConversationResponse：单个会话；ConversationPage 列出会话。
CommandReceiptResponse 与 ClearConversationReceiptResponse：异步命令的回执。
ApprovalModeSettings、ReasoningSettings、SetConversationModelInput：可修改的设置。

CreateConversationInput

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

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

UpdateConversationInput

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

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

ConversationResponse

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

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

ConversationPage

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

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

CommandReceiptResponse

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

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

ClearConversationReceiptResponse

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

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

ApprovalModeSettings

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

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

ReasoningSettings

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

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

SetConversationModelInput

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

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

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。

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

CommandReceipt

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

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

ClearConversationReceipt

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

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

典型流程

用 conversations.create 为智能体创建会话；用 conversations.list 与 conversations.get 查找已有会话。
用 conversations.setModel、conversations.setReasoning、conversations.setApprovalMode 调整。
用 conversations.cancel 停止执行，用 conversations.resume 继续已暂停的会话。
用 conversations.clear 重置，用 conversations.update 重命名，或用 conversations.delete 删除。
通过 messages domain 读取其消息。

方法

方法	HTTP	摘要
conversations.list	`GET /v1/agents/{agentId}/conversations`	列出会话
conversations.create	`POST /v1/agents/{agentId}/conversations`	创建会话
conversations.get	`GET /v1/agents/{agentId}/conversations/{conversationId}`	获取会话
conversations.update	`PATCH /v1/agents/{agentId}/conversations/{conversationId}`	重命名会话
conversations.delete	`DELETE /v1/agents/{agentId}/conversations/{conversationId}`	删除会话
conversations.setApprovalMode	`PUT /v1/agents/{agentId}/conversations/{conversationId}/approval-mode`	设置会话的审批模式
conversations.cancel	`POST /v1/agents/{agentId}/conversations/{conversationId}/cancel`	取消会话的执行
conversations.clear	`POST /v1/agents/{agentId}/conversations/{conversationId}/clear`	清空会话历史
conversations.setModel	`PUT /v1/agents/{agentId}/conversations/{conversationId}/model`	设置会话的模型覆盖
conversations.setReasoning	`PUT /v1/agents/{agentId}/conversations/{conversationId}/reasoning`	设置会话的 reasoning effort
conversations.resume	`POST /v1/agents/{agentId}/conversations/{conversationId}/resume`	恢复已暂停的会话

conversations.list

GET /v1/agents/{agentId}/conversations · Operation ID listAgentConversations

列出会话

所需 scope: conversations:read.

SDK 方法

语言	方法	签名
TypeScript	`cloud.conversations.list`	`list(agentId: string, query?: Models.ListAgentConversationsQuery): Promise<Models.ListAgentConversationsResponse>`
Python	`cloud.conversations.list`	`def list(self, agent_id: str, options: ListAgentConversationsOptions \| None = None) -> ConversationPage`
Go	`cloud.Conversations.List`	`func (r *ConversationsResource) List(ctx context.Context, agentId string, options ListAgentConversationsOptions) (ConversationPage, error)`

参数

参数	位置	类型	必填	说明
`agentId`	path	`string`	是	智能体的 ID，即 agents API 返回的 `id`。
`cursor`	query	`string`	否	上一页 `next_cursor` 返回的游标。省略则获取第一页。最多 4096 个字符。
`limit`	query	`integer`	否	一页中返回的会话的最大数量。默认为 50。接受 1 到 200 的值。约束: `minimum=1`, `maximum=100`.
`state`	query	`string`	否	要列出哪些会话：`open` 为接受消息的会话（默认），`closed` 为已关闭的会话（例如已删除的），`all` 为两者。可选值: `"open"`, `"closed"`, `"all"`.

响应

200 已授权的会话目录 · application/json · Schema: ConversationPage

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

错误

状态码	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.conversations.list("agent_123");
console.log(result);

conversations.create

POST /v1/agents/{agentId}/conversations · Operation ID createAgentConversation

创建会话

所需 scope: conversations:write.

SDK 方法

语言	方法	签名
TypeScript	`cloud.conversations.create`	`create(agentId: string, input: Models.CreateConversationInput, idempotencyKey: string): Promise<Models.CreateAgentConversationResponse>`
Python	`cloud.conversations.create`	`def create(self, agent_id: str, input: CreateConversationInput, options: CreateAgentConversationOptions) -> ConversationResponse`
Go	`cloud.Conversations.Create`	`func (r *ConversationsResource) Create(ctx context.Context, agentId string, input CreateConversationInput, options CreateAgentConversationOptions) (ConversationResponse, error)`

参数

参数	位置	类型	必填	说明
`agentId`	path	`string`	是	智能体的 ID，即 agents API 返回的 `id`。
`Idempotency-Key`	header	`string`	是	让本次请求可以安全重试的 key，8 到 128 个字符，首尾不含空白。用相同的 key 和相同的内容重试会返回原结果；用相同的 key 但内容不同则返回 409 `idempotency_conflict`。约束: `minLength=8`, `maxLength=128`.

请求体

application/json · 必填 · Schema: CreateConversationInput

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

响应

201 已创建或重放的持久会话 · application/json · Schema: ConversationResponse

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

错误

状态码	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.conversations.create("agent_123", {}, "YOUR_IDEMPOTENCY_KEY");
console.log(result);

conversations.get

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

获取会话

所需 scope: conversations:read.

SDK 方法

语言	方法	签名
TypeScript	`cloud.conversations.get`	`get(agentId: string, conversationId: string): Promise<Models.GetConversationResponse>`
Python	`cloud.conversations.get`	`def get(self, agent_id: str, conversation_id: str) -> ConversationResponse`
Go	`cloud.Conversations.Get`	`func (r *ConversationsResource) Get(ctx context.Context, agentId string, conversationId string) (ConversationResponse, error)`

参数

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

响应

200 已授权的会话 · application/json · Schema: ConversationResponse

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

错误

状态码	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.conversations.get("agent_123", "conversation_123");
console.log(result);

conversations.update

PATCH /v1/agents/{agentId}/conversations/{conversationId} · Operation ID updateConversation

重命名会话

所需 scope: conversations:write.

SDK 方法

语言	方法	签名
TypeScript	`cloud.conversations.update`	`update(agentId: string, conversationId: string, input: Models.UpdateConversationInput, version: number): Promise<Models.UpdateConversationResponse>`
Python	`cloud.conversations.update`	`def update(self, agent_id: str, conversation_id: str, input: UpdateConversationInput, options: UpdateConversationOptions) -> ConversationResponse`
Go	`cloud.Conversations.Update`	`func (r *ConversationsResource) Update(ctx context.Context, agentId string, conversationId string, input UpdateConversationInput, options UpdateConversationOptions) (ConversationResponse, error)`

参数

参数	位置	类型	必填	说明
`agentId`	path	`string`	是	智能体的 ID，即 agents API 返回的 `id`。
`conversationId`	path	`string`	是	会话的 ID，即创建或列出会话时返回的 ID。
`If-Match`	header	`string`	是	本次变更所基于的会话版本：其 `resource_version`，带双引号，例如 `"3"`。当前版本不同则返回 412 `resource_version_conflict`；缺少该 header 则返回 428 `precondition_required`。约束: `pattern=^"[1-9][0-9]*"$`.

请求体

application/json · 必填 · Schema: UpdateConversationInput

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

响应

200 会话已重命名 · application/json · Schema: ConversationResponse

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

错误

状态码	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.conversations.update("agent_123", "conversation_123", { title: "example_title" }, 1);
console.log(result);

conversations.delete

DELETE /v1/agents/{agentId}/conversations/{conversationId} · Operation ID deleteConversation

删除会话

所需 scope: conversations:write.

SDK 方法

语言	方法	签名
TypeScript	`cloud.conversations.delete`	`delete(agentId: string, conversationId: string, idempotencyKey: string): Promise<Models.DeleteConversationResponse>`
Python	`cloud.conversations.delete`	`def delete(self, agent_id: str, conversation_id: str, options: DeleteConversationOptions) -> None`
Go	`cloud.Conversations.Delete`	`func (r *ConversationsResource) Delete(ctx context.Context, agentId string, conversationId string, options DeleteConversationOptions) error`

参数

参数	位置	类型	必填	说明
`agentId`	path	`string`	是	智能体的 ID，即 agents API 返回的 `id`。
`conversationId`	path	`string`	是	会话的 ID，即创建或列出会话时返回的 ID。
`Idempotency-Key`	header	`string`	是	让本次请求可以安全重试的 key，8 到 128 个字符，首尾不含空白。用相同的 key 和相同的内容重试会返回原结果；用相同的 key 但内容不同则返回 409 `idempotency_conflict`。约束: `minLength=8`, `maxLength=128`.

响应

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.conversations.delete("agent_123", "conversation_123", "YOUR_IDEMPOTENCY_KEY");
console.log(result);

conversations.setApprovalMode

PUT /v1/agents/{agentId}/conversations/{conversationId}/approval-mode · Operation ID setConversationApprovalMode

设置会话的审批模式

所需 scope: conversations:control.

SDK 方法

语言	方法	签名
TypeScript	`cloud.conversations.setApprovalMode`	`setApprovalMode(agentId: string, conversationId: string, input: Models.ApprovalModeSettings, version: number): Promise<Models.SetConversationApprovalModeResponse>`
Python	`cloud.conversations.set_approval_mode`	`def set_approval_mode(self, agent_id: str, conversation_id: str, input: ApprovalModeSettings, options: SetConversationApprovalModeOptions) -> ApprovalModeResultResponse`
Go	`cloud.Conversations.SetApprovalMode`	`func (r *ConversationsResource) SetApprovalMode(ctx context.Context, agentId string, conversationId string, input ApprovalModeSettings, options SetConversationApprovalModeOptions) (ApprovalModeResultResponse, error)`

参数

参数	位置	类型	必填	说明
`agentId`	path	`string`	是	智能体的 ID，即 agents API 返回的 `id`。
`conversationId`	path	`string`	是	会话的 ID，即创建或列出会话时返回的 ID。
`If-Match`	header	`string`	是	本次变更所基于的会话版本：其 `resource_version`，带双引号，例如 `"3"`。当前版本不同则返回 412 `resource_version_conflict`；缺少该 header 则返回 428 `precondition_required`。约束: `pattern=^"[1-9][0-9]*"$`.

请求体

application/json · 必填 · Schema: ApprovalModeSettings

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

响应

200 已确认审批模式的期望状态 · application/json · Schema: ApprovalModeResultResponse

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

错误

状态码	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.conversations.setApprovalMode("agent_123", "conversation_123", { approval_mode: "example_approval_mode" }, 1);
console.log(result);

conversations.cancel

POST /v1/agents/{agentId}/conversations/{conversationId}/cancel · Operation ID cancelConversation

取消会话的执行

所需 scope: conversations:control.

SDK 方法

语言	方法	签名
TypeScript	`cloud.conversations.cancel`	`cancel(agentId: string, conversationId: string, idempotencyKey: string, input?: JSONValue): Promise<Models.CancelConversationResponse>`
Python	`cloud.conversations.cancel`	`def cancel(self, agent_id: str, conversation_id: str, input: CancelConversationInput, options: CancelConversationOptions) -> CommandReceiptResponse`
Go	`cloud.Conversations.Cancel`	`func (r *ConversationsResource) Cancel(ctx context.Context, agentId string, conversationId string, input CancelConversationInput, options CancelConversationOptions) (CommandReceiptResponse, error)`

参数

参数	位置	类型	必填	说明
`agentId`	path	`string`	是	智能体的 ID，即 agents API 返回的 `id`。
`conversationId`	path	`string`	是	会话的 ID，即创建或列出会话时返回的 ID。
`Idempotency-Key`	header	`string`	是	让本次请求可以安全重试的 key，8 到 128 个字符，首尾不含空白。用相同的 key 和相同的内容重试会返回原结果；用相同的 key 但内容不同则返回 409 `idempotency_conflict`。约束: `minLength=8`, `maxLength=128`.

请求体

application/json · 必填 · Schema: CancelConversationInput

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

响应

202 已接受取消请求 · application/json · Schema: CommandReceiptResponse

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

错误

状态码	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.conversations.cancel("agent_123", "conversation_123", "YOUR_IDEMPOTENCY_KEY");
console.log(result);

conversations.clear

POST /v1/agents/{agentId}/conversations/{conversationId}/clear · Operation ID clearConversation

清空会话历史

所需 scope: conversations:control.

SDK 方法

语言	方法	签名
TypeScript	`cloud.conversations.clear`	`clear(agentId: string, conversationId: string, idempotencyKey: string): Promise<Models.ClearConversationResponse>`
Python	`cloud.conversations.clear`	`def clear(self, agent_id: str, conversation_id: str, options: ClearConversationOptions) -> ClearConversationReceiptResponse`
Go	`cloud.Conversations.Clear`	`func (r *ConversationsResource) Clear(ctx context.Context, agentId string, conversationId string, options ClearConversationOptions) (ClearConversationReceiptResponse, error)`

参数

参数	位置	类型	必填	说明
`agentId`	path	`string`	是	智能体的 ID，即 agents API 返回的 `id`。
`conversationId`	path	`string`	是	会话的 ID，即创建或列出会话时返回的 ID。
`Idempotency-Key`	header	`string`	是	让本次请求可以安全重试的 key，8 到 128 个字符，首尾不含空白。用相同的 key 和相同的内容重试会返回原结果；用相同的 key 但内容不同则返回 409 `idempotency_conflict`。约束: `minLength=8`, `maxLength=128`.

响应

202 已接受清空请求 · application/json · Schema: ClearConversationReceiptResponse

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

错误

状态码	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.conversations.clear("agent_123", "conversation_123", "YOUR_IDEMPOTENCY_KEY");
console.log(result);

conversations.setModel

PUT /v1/agents/{agentId}/conversations/{conversationId}/model · Operation ID setConversationModel

设置会话的模型覆盖

所需 scope: conversations:control.

SDK 方法

语言	方法	签名
TypeScript	`cloud.conversations.setModel`	`setModel(agentId: string, conversationId: string, modelId: string \| null, version: number): Promise<Models.SetConversationModelResponse>`
Python	`cloud.conversations.set_model`	`def set_model(self, agent_id: str, conversation_id: str, input: SetConversationModelInput, options: SetConversationModelOptions) -> CommandReceiptResponse`
Go	`cloud.Conversations.SetModel`	`func (r *ConversationsResource) SetModel(ctx context.Context, agentId string, conversationId string, input SetConversationModelInput, options SetConversationModelOptions) (CommandReceiptResponse, error)`

参数

参数	位置	类型	必填	说明
`agentId`	path	`string`	是	智能体的 ID，即 agents API 返回的 `id`。
`conversationId`	path	`string`	是	会话的 ID，即创建或列出会话时返回的 ID。
`If-Match`	header	`string`	是	本次变更所基于的会话版本：其 `resource_version`，带双引号，例如 `"3"`。当前版本不同则返回 412 `resource_version_conflict`；缺少该 header 则返回 428 `precondition_required`。约束: `pattern=^"[1-9][0-9]*"$`.

请求体

application/json · 必填 · Schema: SetConversationModelInput

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

响应

202 已接受模型变更 · application/json · Schema: CommandReceiptResponse

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

错误

状态码	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.conversations.setModel("agent_123", "conversation_123", "model_override_123", 1);
console.log(result);

conversations.setReasoning

PUT /v1/agents/{agentId}/conversations/{conversationId}/reasoning · Operation ID setConversationReasoning

设置会话的 reasoning effort

所需 scope: conversations:control.

SDK 方法

语言	方法	签名
TypeScript	`cloud.conversations.setReasoning`	`setReasoning(agentId: string, conversationId: string, input: Models.ReasoningSettings, version: number): Promise<Models.SetConversationReasoningResponse>`
Python	`cloud.conversations.set_reasoning`	`def set_reasoning(self, agent_id: str, conversation_id: str, input: ReasoningSettings, options: SetConversationReasoningOptions) -> ReasoningResultResponse`
Go	`cloud.Conversations.SetReasoning`	`func (r *ConversationsResource) SetReasoning(ctx context.Context, agentId string, conversationId string, input ReasoningSettings, options SetConversationReasoningOptions) (ReasoningResultResponse, error)`

参数

参数	位置	类型	必填	说明
`agentId`	path	`string`	是	智能体的 ID，即 agents API 返回的 `id`。
`conversationId`	path	`string`	是	会话的 ID，即创建或列出会话时返回的 ID。
`If-Match`	header	`string`	是	本次变更所基于的会话版本：其 `resource_version`，带双引号，例如 `"3"`。当前版本不同则返回 412 `resource_version_conflict`；缺少该 header 则返回 428 `precondition_required`。约束: `pattern=^"[1-9][0-9]*"$`.

请求体

application/json · 必填 · Schema: ReasoningSettings

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

响应

200 已确认 reasoning 的期望状态 · application/json · Schema: ReasoningResultResponse

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

错误

状态码	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.conversations.setReasoning("agent_123", "conversation_123", { modelId: "model_123", reasoningOverrideId: "reasoning_override_123" }, 1);
console.log(result);

conversations.resume

POST /v1/agents/{agentId}/conversations/{conversationId}/resume · Operation ID resumeConversation

恢复已暂停的会话

SDK 方法

语言	方法	签名
TypeScript	`cloud.conversations.resume`	`resume(agentId: string, conversationId: string, idempotencyKey: string): Promise<Models.ResumeConversationResponse>`
Python	`cloud.conversations.resume`	`def resume(self, agent_id: str, conversation_id: str, options: ResumeConversationOptions) -> ResumeConversationResponse`
Go	`cloud.Conversations.Resume`	`func (r *ConversationsResource) Resume(ctx context.Context, agentId string, conversationId string, options ResumeConversationOptions) (ResumeConversationResponse, error)`

参数

参数	位置	类型	必填	说明
`agentId`	path	`string`	是	智能体的 ID，即 agents API 返回的 `id`。
`conversationId`	path	`string`	是	会话的 ID，即创建或列出会话时返回的 ID。
`Idempotency-Key`	header	`string`	是	让本次请求可以安全重试的 key，8 到 128 个字符，首尾不含空白。用相同的 key 和相同的内容重试会返回原结果；用相同的 key 但内容不同则返回 409 `idempotency_conflict`。

响应

200 · application/json

字段	类型	必填	说明
`data`	`object`	是	—
`data.request_id`	`string`	是	—
`data.status`	`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.conversations.resume("agent_123", "conversation_123", "YOUR_IDEMPOTENCY_KEY");
console.log(result);

BeeOS Cloud返回文档首页