BEEOS CLOUD / DEVELOPER REFERENCE

智能体

列出、读取智能体并更新其暴露设置。

概览

agents domain 列出你的产品的智能体、读取单个智能体，并更新其暴露设置。

3 个操作 · SDK 资源：TypeScript cloud.agents · Python cloud.agents · Go cloud.Agents · API 总览

主要对象

AgentResponse：单个智能体；AgentPage 列出智能体。
AgentPatch：可修改的暴露设置。

AgentResponse

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

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

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。

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

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。

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

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。

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

典型流程

用 agents.list 列出智能体。
用 agents.get 读取其中一个。
用 agents.update 修改其暴露设置。
用该智能体的 ID 在 conversations.list 与 conversations.create 中操作其会话。

方法

方法	HTTP	摘要
agents.list	`GET /v1/agents`	列出智能体
agents.get	`GET /v1/agents/{agentId}`	获取智能体
agents.update	`PATCH /v1/agents/{agentId}`	更新智能体的暴露设置

agents.list

GET /v1/agents · Operation ID listAgents

列出智能体

所需 scope: agents:read.

SDK 方法

语言	方法	签名
TypeScript	`cloud.agents.list`	`list(query?: Models.ListAgentsQuery): Promise<Models.ListAgentsResponse>`
Python	`cloud.agents.list`	`def list(self, options: ListAgentsOptions \| None = None) -> AgentPage`
Go	`cloud.Agents.List`	`func (r *AgentsResource) List(ctx context.Context, options ListAgentsOptions) (AgentPage, error)`

参数

参数	位置	类型	必填	说明
`instance_id`	query	`string`	否	只返回该实例的智能体，最多 128 个字符。不存在或不属于你的实例返回 404。
`status`	query	`string`	否	只返回处于该状态的智能体：`active` 或 `inactive`。省略则两者都返回。
`visibility`	query	`string`	否	只返回该可见性的智能体：`private`、`unlisted`、`org`、`public` 或 `marketplace`。省略则全部返回。
`search`	query	`string`	否	只返回名称、显示名称或描述包含该文本的智能体，不区分大小写。最多 200 个字符。
`page`	query	`integer`	否	要返回的页码，从 1 开始。默认为 1。默认值: `1`. 约束: `minimum=1`, `maximum=1000000`.
`page_size`	query	`integer`	否	每页的智能体数量，1 到 100。默认为 20。默认值: `20`. 约束: `minimum=1`, `maximum=100`.

响应

200 · application/json · Schema: AgentPage

字段	类型	必填	说明
`data`	array<AgentAgent>	是	本页的智能体，最新的在前。
`total`	`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.agents.list();
console.log(result);

agents.get

GET /v1/agents/{agentId} · Operation ID getAgent

获取智能体

所需 scope: agents:read.

SDK 方法

语言	方法	签名
TypeScript	`cloud.agents.get`	`get(id: string): Promise<Models.GetAgentResponse>`
Python	`cloud.agents.get`	`def get(self, agent_id: str) -> AgentResponse`
Go	`cloud.Agents.Get`	`func (r *AgentsResource) Get(ctx context.Context, agentId string) (AgentResponse, error)`

参数

参数	位置	类型	必填	说明
`agentId`	path	`string`	是	智能体的 ID，即 agents API 返回的 `id`。

响应

200 · application/json · Schema: AgentResponse

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

错误

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

agents.update

PATCH /v1/agents/{agentId} · Operation ID updateAgent

更新智能体的暴露设置

所需 scope: agents:manage.

SDK 方法

语言	方法	签名
TypeScript	`cloud.agents.update`	`update(id: string, patch: Models.AgentPatch, resourceVersion: number): Promise<Models.UpdateAgentResponse>`
Python	`cloud.agents.update`	`def update(self, agent_id: str, input: AgentPatch, options: UpdateAgentOptions) -> AgentResponse`
Go	`cloud.Agents.Update`	`func (r *AgentsResource) Update(ctx context.Context, agentId string, input AgentPatch, options UpdateAgentOptions) (AgentResponse, error)`

参数

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

请求体

application/json · 必填 · Schema: 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`。

响应

200 · application/json · Schema: AgentResponse

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

错误

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

BeeOS Cloud返回文档首页