This reference is currently available in English. The Cloud console remains in your selected language.

BEEOS CLOUD / DEVELOPER REFERENCE

Agents

List and read agents and update their exposure settings.

Overview

The agents domain lists the agents of your product, reads one, and updates its exposure settings.

3 operations · SDK resource: TypeScript cloud.agents · Python cloud.agents · Go cloud.Agents · API overview

Main objects

AgentResponse: one agent; AgentPage lists agents.
AgentPatch: the exposure settings you can change.

AgentResponse

Field	Type	Required	Description
`data`	AgentSnapshot	yes	The agent.

Every field, and the methods that use this object: appendix.

AgentPage

Field	Type	Required	Description
`data`	array<AgentAgent>	yes	Agents on this page, newest first.
`total`	`integer`	yes	Total number of agents that match the filters, across all pages.

Every field, and the methods that use this object: appendix.

AgentPatch

Exposure settings to change. Send at least one field; fields you omit keep their current value.

Field	Type	Required	Description
`visibility`	`string`	no	New visibility of the agent. The values are described on the `visibility` field of the agent. Allowed values: see the table below, AgentPatch.visibility values.
`mcp_enabled`	`boolean`	no	Set to true to publish the agent as a tool through BeeOS MCP endpoints, or to false to stop publishing it.
`a2a_enabled`	`boolean`	no	Set to true to let the agent accept Agent-to-Agent (A2A) requests, or to false to refuse them with 403 `a2a_disabled`.

AgentPatch.visibility values

Value	Meaning
`"private"`	Callers other than the owner cannot invoke the agent or read its agent card. It is not listed in catalogs.
`"unlisted"`	Callers other than the owner can invoke the agent and read its agent card if they know its ID. It is not listed in catalogs.
`"org"`	Reserved. The value is accepted, but it does not currently give callers other than the owner access to the agent.
`"public"`	Callers other than the owner can invoke the agent and read its agent card, and it is listed in catalogs.
`"marketplace"`	The agent is listed in catalogs. That is all this value grants: callers other than the owner cannot invoke the agent or read its agent card by ID.

Every field, and the methods that use this object: appendix.

AgentSnapshot

Field	Type	Required	Description
`id`	`string`	yes	ID of the agent.
`instance_id`	`string`	yes	ID of the instance the agent runs on.
`name`	`string`	yes	Name of the agent.
`display_name`	`string`	no	Human-readable name of the agent. Omitted when none is set.
`description`	`string`	yes	Description of the agent. Empty when none is set.
`status`	`string`	yes	Whether the agent is currently provided by its instance. Allowed values: `"active"` — The instance currently provides the agent; `"inactive"` — The instance no longer provides the agent, for example because it was removed or replaced by another agent with the same name. The record is kept. (enum table)
`visibility`	`string`	yes	Which callers other than the owner can use the agent. Change it with the update operation. Allowed values: see the table below, AgentSnapshot.visibility values.
`conversation_transport`	`string`	yes	How conversation messages reach the agent. New values can be added, so ignore values you do not know. Allowed values: `"acp"` — Conversation messages are exchanged with the agent over its ACP connection; `"message-service"` — Conversation messages are delivered to the agent as messages through BeeOS messaging. (enum table)
`resource_version`	`integer`	yes	Version of the agent to send as `If-Match`, in double quotes, when you update it. The same value is returned in the `ETag` header when you read or update a single agent. Constraints: `minimum=1`, `format=int64`.
`mcp_enabled`	`boolean`	yes	Whether the agent is published as a tool through BeeOS MCP endpoints.
`a2a_enabled`	`boolean`	yes	Whether the agent accepts Agent-to-Agent (A2A) requests. When false, A2A requests for the agent are refused with 403 `a2a_disabled`.
`capabilities`	`map<string, boolean>`	yes	Features the agent supports, as an object that maps a feature name to true or false. Known names include `canvas`, `terminal`, `webSsh`, `fileSystem`, `image`, `audio`, `mcp`, `cron`, `streaming`, `pushNotifications`, `a2a`, `extendedAgentCard`, `multipleConversations`, `loadConversation`, `createConversation`, `modelsList`, `modelsSet`, `skillsList`, `skillsInstall`, `skillsUninstall`, `skillsUpdate` and `automationWake`. A name that is absent or false means the agent does not support the feature. New names can be added, so ignore names you do not know.
`skills`	array<AgentSkill>	yes	Skills of the agent.
`created_at`	`string`	yes	Time the agent was created, in RFC 3339 format. Constraints: `format=date-time`.
`updated_at`	`string`	yes	Time the agent was last changed, in RFC 3339 format. Constraints: `format=date-time`.

AgentSnapshot.visibility values

Value	Meaning
`"private"`	Callers other than the owner cannot invoke the agent or read its agent card. It is not listed in catalogs.
`"unlisted"`	Callers other than the owner can invoke the agent and read its agent card if they know its ID. It is not listed in catalogs.
`"org"`	Reserved. The value is accepted, but it does not currently give callers other than the owner access to the agent.
`"public"`	Callers other than the owner can invoke the agent and read its agent card, and it is listed in catalogs.
`"marketplace"`	The agent is listed in catalogs. That is all this value grants: callers other than the owner cannot invoke the agent or read its agent card by ID.

Every field, and the methods that use this object: appendix.

AgentAgent

Field	Type	Required	Description
`id`	`string`	yes	ID of the agent.
`instance_id`	`string`	yes	ID of the instance the agent runs on.
`name`	`string`	yes	Name of the agent.
`avatar_url`	`string`	no	URL of the agent's avatar image. Omitted when none is set.
`display_name`	`string`	no	Human-readable name of the agent. Omitted when none is set.
`description`	`string`	yes	Description of the agent. Empty when none is set.
`resource_version`	`integer`	yes	Version of the agent to send as `If-Match`, in double quotes, when you update it. The same value is returned in the `ETag` header when you read or update a single agent.
`status`	`string`	yes	Whether the agent is currently provided by its instance. Allowed values: `"active"` — The instance currently provides the agent; `"inactive"` — The instance no longer provides the agent, for example because it was removed or replaced by another agent with the same name. The record is kept. (enum table)
`visibility`	`string`	yes	Which callers other than the owner can use the agent. Change it with the update operation. Allowed values: see the table below, AgentAgent.visibility values.
`mcp_enabled`	`boolean`	yes	Whether the agent is published as a tool through BeeOS MCP endpoints.
`a2a_enabled`	`boolean`	yes	Whether the agent accepts Agent-to-Agent (A2A) requests. When false, A2A requests for the agent are refused with 403 `a2a_disabled`.
`capabilities`	`map<string, boolean>`	yes	Features the agent supports, as an object that maps a feature name to true or false. Known names include `canvas`, `terminal`, `webSsh`, `fileSystem`, `image`, `audio`, `mcp`, `cron`, `streaming`, `pushNotifications`, `a2a`, `extendedAgentCard`, `multipleConversations`, `loadConversation`, `createConversation`, `modelsList`, `modelsSet`, `skillsList`, `skillsInstall`, `skillsUninstall`, `skillsUpdate` and `automationWake`. A name that is absent or false means the agent does not support the feature. New names can be added, so ignore names you do not know.
`skills`	array<AgentSkill>	yes	Skills of the agent.
`conversation_transport`	`string`	yes	How conversation messages reach the agent. New values can be added, so ignore values you do not know. Allowed values: `"acp"` — Conversation messages are exchanged with the agent over its ACP connection; `"message-service"` — Conversation messages are delivered to the agent as messages through BeeOS messaging. (enum table)
`created_at`	`string`	yes	Time the agent was created, in RFC 3339 format. Constraints: `format=date-time`.
`updated_at`	`string`	yes	Time the agent was last changed, in RFC 3339 format. Constraints: `format=date-time`.

AgentAgent.visibility values

Value	Meaning
`"private"`	Callers other than the owner cannot invoke the agent or read its agent card. It is not listed in catalogs.
`"unlisted"`	Callers other than the owner can invoke the agent and read its agent card if they know its ID. It is not listed in catalogs.
`"org"`	Reserved. The value is accepted, but it does not currently give callers other than the owner access to the agent.
`"public"`	Callers other than the owner can invoke the agent and read its agent card, and it is listed in catalogs.
`"marketplace"`	The agent is listed in catalogs. That is all this value grants: callers other than the owner cannot invoke the agent or read its agent card by ID.

Every field, and the methods that use this object: appendix.

Typical flow

List agents with agents.list.
Read one with agents.get.
Change its exposure settings with agents.update.
Use the agent ID to work with its conversations in conversations.list and conversations.create.

Methods

Method	HTTP	Summary
agents.list	`GET /v1/agents`	List agents
agents.get	`GET /v1/agents/{agentId}`	Get an agent
agents.update	`PATCH /v1/agents/{agentId}`	Update agent exposure settings

agents.list

GET /v1/agents · Operation ID listAgents

List agents

Required scopes: agents:read.

SDK methods

Language	Method	Signature
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)`

Parameters

Parameter	In	Type	Required	Description
`instance_id`	query	`string`	no	Only return agents of this instance, at most 128 characters. An instance that does not exist or is not yours returns 404.
`status`	query	`string`	no	Only return agents in this state: `active` or `inactive`. Omit it to return both.
`visibility`	query	`string`	no	Only return agents with this visibility: `private`, `unlisted`, `org`, `public` or `marketplace`. Omit it to return all.
`search`	query	`string`	no	Only return agents whose name, display name or description contains this text, ignoring case. At most 200 characters.
`page`	query	`integer`	no	Page number to return, starting at 1. Defaults to 1. Default: `1`. Constraints: `minimum=1`, `maximum=1000000`.
`page_size`	query	`integer`	no	Number of agents per page, 1 to 100. Defaults to 20. Default: `20`. Constraints: `minimum=1`, `maximum=100`.

Response

200 · application/json · Schema: AgentPage

Field	Type	Required	Description
`data`	array<AgentAgent>	yes	Agents on this page, newest first.
`total`	`integer`	yes	Total number of agents that match the filters, across all pages.

Errors

Status	Schema	Description
other (default)	ErrorResponse	Cloud Server error

The error schemas are described in Errors.

Example

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

Get an agent

Required scopes: agents:read.

SDK methods

Language	Method	Signature
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)`

Parameters

Parameter	In	Type	Required	Description
`agentId`	path	`string`	yes	ID of the agent, the `id` returned by the agents API.

Response

200 · application/json · Schema: AgentResponse

Field	Type	Required	Description
`data`	AgentSnapshot	yes	The agent.

Errors

Status	Schema	Description
other (default)	ErrorResponse	Cloud Server error

The error schemas are described in Errors.

Example

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

Update agent exposure settings

Required scopes: agents:manage.

SDK methods

Language	Method	Signature
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)`

Parameters

Parameter	In	Type	Required	Description
`agentId`	path	`string`	yes	ID of the agent, the `id` returned by the agents API.
`If-Match`	header	`string`	yes	Version of the agent the change is based on: its `resource_version` in double quotes, for example `"3"`. A different current version returns 412 `resource_version_conflict`; a missing header returns 428 `precondition_required`. Constraints: `pattern=^"[1-9][0-9]*"$`.

Request body

application/json · required · Schema: AgentPatch

Field	Type	Required	Description
`visibility`	`string`	no	New visibility of the agent. The values are described on the `visibility` field of the agent. Allowed values: see AgentPatch.visibility values.
`mcp_enabled`	`boolean`	no	Set to true to publish the agent as a tool through BeeOS MCP endpoints, or to false to stop publishing it.
`a2a_enabled`	`boolean`	no	Set to true to let the agent accept Agent-to-Agent (A2A) requests, or to false to refuse them with 403 `a2a_disabled`.

Response

200 · application/json · Schema: AgentResponse

Field	Type	Required	Description
`data`	AgentSnapshot	yes	The agent.

Errors

Status	Schema	Description
other (default)	ErrorResponse	Cloud Server error

The error schemas are described in Errors.

Example

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 CloudBack to documentation