BEEOS CLOUD / DEVELOPER REFERENCE
A2A
Agent-to-Agent JSON-RPC requests, agent cards, and tasks.
Overview
The A2A domain exposes an agent over the Agent-to-Agent protocol: it sends JSON-RPC requests to an agent, serves the agent card, and lists, reads, and cancels A2A tasks.
6 operations · SDK resource: TypeScript cloud.a2a · Python cloud.a2a · Go cloud.A2a · API overview
Main objects
A2AAgentCard: the card that describes the agent.RuntimeMethodResponse: the result of a JSON-RPC request.a2aTaskView: a task, withA2ATaskStatus,A2AMessage, andA2AArtifact.
A2AAgentCard
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Display name of the agent. |
description | string | yes | Description of the agent. |
url | string | no | URL of the agent's JSON-RPC endpoint. Returned only when the request sends A2A-Version: 0.3; version 1.0 lists the endpoint in supportedInterfaces. |
version | string | yes | Version of the agent: its resource version, a decimal number. |
protocolVersion | string | no | A2A protocol version spoken at url. Returned only when the request sends A2A-Version: 0.3. |
defaultInputModes | array<string> | yes | Media types the agent accepts as input, for example text/plain. |
defaultOutputModes | array<string> | yes | Media types the agent produces as output, for example text/plain. |
supportedInterfaces | array<object> | no | Interfaces through which the agent can be reached. Returned unless the request sends A2A-Version: 0.3. |
supportedInterfaces[].url | string | yes | URL of the interface. |
supportedInterfaces[].protocolBinding | string | yes | Transport the interface uses: JSONRPC. |
supportedInterfaces[].protocolVersion | string | yes | A2A protocol version the interface speaks. |
Every field, and the methods that use this object: appendix.
RuntimeMethodResponse
JSON-RPC 2.0 response. It carries result on success and error on failure, never both. Errors are returned with HTTP status 200.
| Field | Type | Required | Description |
|---|---|---|---|
jsonrpc | string | yes | JSON-RPC protocol version: always 2.0. Allowed values: "2.0" — JSON-RPC version 2.0. |
id | string | integer | yes | ID of the request that this response answers. It is null when the request could not be read. Nullable. |
result | JSONValue | no | Result of the method. Present only on success; its shape depends on the method. Nullable. |
error | object | no | Error of the call. Present only on failure. |
error.code | integer | yes | Error code. -32700 parse error, -32600 invalid request, -32601 method not found, -32602 invalid params, -32603 internal error, -32001 task not found, -32002 task not cancelable, -32003 push notifications not supported, -32004 unsupported operation, -32005 content type not supported, -32006 invalid agent response, -32007 agent card not configured, -32008 agent busy, -32009 incompatible A2A-Version, -32010 the connection dropped after the task was dispatched (read the task instead of sending it again), -32011 task timed out, -32012 the connection dropped before dispatch (nothing ran; safe to retry). |
error.message | string | yes | Human-readable description of the error. |
error.data | JSONValue | no | Machine-readable detail of the error: a list with one object of type type.googleapis.com/google.rpc.ErrorInfo. Its reason is the error name, for example TASK_NOT_FOUND, and its metadata repeats the code and message. Nullable. |
Every field, and the methods that use this object: appendix.
a2aTaskView
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | ID of the task. |
contextId | string | yes | ID of the context (conversation) the task belongs to. |
status | A2ATaskStatus | yes | Current status of the task. |
artifacts | array<A2AArtifact> | no | Outputs the agent produced for the task. Omitted while there are none. |
history | array<A2AMessage> | no | Messages of the task. A single-task read returns at most history_length of them. When no history is stored it holds the original request as one message. Omitted when there are none. |
metadata | map<string, JSONValue> | no | Extra metadata of the task. Omitted when there is none. |
caller_principal_id | string | yes | ID of the principal that submitted the task. |
caller_agent_id | string | yes | ID of the agent that submitted the task, if any. |
caller_owner_id | string | yes | ID of the owner of the submitting side. Cloud derives it from the credential's organization and app. Callers do not send an end-user id. |
target_principal_id | string | yes | ID of the principal the task was sent to. |
target_agent_id | string | yes | ID of the agent the task was sent to. |
target_owner_id | string | yes | ID of the owner of the receiving side. |
channel_id | string | no | ID of the channel that carries the streaming replies of the task. Omitted when the task does not use channel-based delivery. |
created_at | string | no | Time the task was created, as a UTC timestamp such as 2026-01-02T15:04:05.000Z. Omitted when it is not known. |
updated_at | string | no | Time the task was last updated, in the same format as created_at. Omitted when it is not known. |
completed_at | string | no | Time the task finished, in the same format as created_at. Omitted until the task is finished. |
Every field, and the methods that use this object: appendix.
A2ATaskStatus
| Field | Type | Required | Description |
|---|---|---|---|
state | string | yes | Current state of the task. Allowed values: see the table below, A2ATaskStatus.state values. |
message | A2AMessage | no | Message that explains the state, such as an error text. It is an agent message with one text part. Omitted when there is nothing to report. Nullable. |
timestamp | string | no | Time of the last update of the task, or its creation time when it was never updated, as a UTC timestamp such as 2026-01-02T15:04:05.000Z. |
A2ATaskStatus.state values
| Value | Meaning |
|---|---|
"TASK_STATE_SUBMITTED" | The task was created and is waiting for the agent to start. It is also reported once the message has reached the agent. |
"TASK_STATE_WORKING" | The agent is processing the task. |
"TASK_STATE_COMPLETED" | Final state. The task finished successfully. |
"TASK_STATE_FAILED" | Final state. The task finished with an error or timed out. |
"TASK_STATE_CANCELED" | Final state. The task was canceled before it finished. |
"TASK_STATE_INPUT_REQUIRED" | The task is paused: the agent needs more input from the caller to continue. |
"TASK_STATE_REJECTED" | Final state. The agent declined the task. |
"TASK_STATE_AUTH_REQUIRED" | The task is paused: the agent needs additional authentication to continue. |
Every field, and the methods that use this object: appendix.
A2AMessage
| Field | Type | Required | Description |
|---|---|---|---|
messageId | string | yes | ID of the message. The server generates a new ID for every message it renders. |
role | string | yes | Who wrote the message: ROLE_USER for the caller or ROLE_AGENT for the agent. Allowed values: "ROLE_USER" — The message was written by the caller; "ROLE_AGENT" — The message was written by the agent. (enum table) |
parts | array<A2AOutputPart> | yes | Content of the message as parts, in order. Each part is a text part, a file part or a data part. |
contextId | string | no | ID of the context (conversation) the message belongs to. Omitted when it is not set. |
taskId | string | no | ID of the task the message belongs to. Omitted when it is not set. |
referenceTaskIds | array<string> | no | IDs of other tasks this message refers to. Omitted when there are none. |
metadata | map<string, JSONValue> | no | Extra metadata attached to the message. Omitted when there is none. |
Every field, and the methods that use this object: appendix.
A2AArtifact
| Field | Type | Required | Description |
|---|---|---|---|
artifactId | string | yes | ID of the artifact. When the agent supplies none, the server uses <task ID>-a<index>, counting from 0. |
name | string | no | Display name of the artifact. Omitted when it is not set. |
description | string | no | Description of the artifact. Omitted when it is not set. |
parts | array<A2AOutputPart> | yes | Content of the artifact as parts, in order. Each part is a text part, a file part or a data part. |
metadata | map<string, JSONValue> | no | Extra metadata attached to the artifact. Omitted when there is none. |
extensions | array<string> | no | URIs of the protocol extensions that apply to the artifact. Omitted when there are none. |
Every field, and the methods that use this object: appendix.
Typical flow
- Read the agent card with
a2a.getAgentCard(a2a.getAgentCardLegacyserves the legacy path). - Send a JSON-RPC request with
a2a.invoke. - Follow the work with
a2a.listTasksanda2a.getTask, and stop it witha2a.cancelTask.
Methods
| Method | HTTP | Summary |
|---|---|---|
| a2a.invoke | POST /v1/a2a/{agentId} | Send an A2A JSON-RPC request |
| a2a.getAgentCard | GET /v1/a2a/{agentId}/.well-known/agent-card.json | Get the A2A agent card |
| a2a.getAgentCardLegacy | GET /v1/a2a/{agentId}/.well-known/agent.json | Get the A2A agent card (legacy path) |
| a2a.listTasks | GET /v1/a2a/{agentId}/tasks | List A2A tasks |
| a2a.getTask | GET /v1/a2a/{agentId}/tasks/{taskId} | Get an A2A task |
| a2a.cancelTask | POST /v1/a2a/{agentId}/tasks/{taskId}/cancel | Cancel an A2A task |
a2a.invoke
POST /v1/a2a/{agentId} · Operation ID invokeA2A
Send an A2A JSON-RPC request
SDK methods
| Language | Method | Signature |
|---|---|---|
| TypeScript | cloud.a2a.invoke | invoke(agentId: string, input: Models.InvokeA2ARequest): Promise<Models.InvokeA2AResponse> |
| Python | cloud.a2a.invoke | def invoke(self, agent_id: str, input: InvokeA2ARequest) -> RuntimeMethodResponse |
| Go | cloud.A2a.Invoke | func (r *A2aResource) Invoke(ctx context.Context, agentId string, input InvokeA2ARequest) (RuntimeMethodResponse, error) |
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
agentId | path | string | yes | ID of the agent. It must belong to your app. For JSON-RPC and agent card requests the agent must also have its A2A protocol enabled, otherwise the request returns 403 a2a_disabled; task reads work either way. |
Request body
application/json · required
| Field | Type | Required | Description |
|---|---|---|---|
jsonrpc | string | yes | JSON-RPC protocol version: must be 2.0. Allowed values: "2.0". |
id | string | no | ID of the request, echoed in the id of the response. |
method | string | yes | A2A method to call. Each method has an A2A 1.0 name and an A2A 0.3 alias: SendMessage (message/send) sends a message to the agent and creates a task; SendStreamingMessage (message/stream) does the same and streams updates as server-sent events; SubscribeToTask (tasks/resubscribe) resumes the update stream of a task; GetTask (tasks/get), CancelTask (tasks/cancel) and ListTasks (tasks/list) read and cancel tasks; CompleteTask (tasks/complete) finishes a task with a result or an error message; UpdateStatus (tasks/updateStatus) sets the state of a task; CreateTaskPushNotificationConfig (SetPushNotificationConfig, tasks/pushNotification/set), GetTaskPushNotificationConfig (GetPushNotificationConfig, tasks/pushNotification/get), ListTaskPushNotificationConfigs (ListPushNotificationConfigs, tasks/pushNotification/list) and DeleteTaskPushNotificationConfig (DeletePushNotificationConfig, tasks/pushNotification/delete) manage push notification settings of a task. An unknown method returns error -32601. |
params | JSONValue | no | Parameters of the method. Their shape depends on method, as defined by the A2A protocol. Nullable. |
Response
200 · application/json · Schema: RuntimeMethodResponse
| Field | Type | Required | Description |
|---|---|---|---|
jsonrpc | string | yes | JSON-RPC protocol version: always 2.0. Allowed values: "2.0" — JSON-RPC version 2.0. |
id | string | integer | yes | ID of the request that this response answers. It is null when the request could not be read. Nullable. |
result | JSONValue | no | Result of the method. Present only on success; its shape depends on the method. Nullable. |
error | object | no | Error of the call. Present only on failure. |
error.code | integer | yes | Error code. -32700 parse error, -32600 invalid request, -32601 method not found, -32602 invalid params, -32603 internal error, -32001 task not found, -32002 task not cancelable, -32003 push notifications not supported, -32004 unsupported operation, -32005 content type not supported, -32006 invalid agent response, -32007 agent card not configured, -32008 agent busy, -32009 incompatible A2A-Version, -32010 the connection dropped after the task was dispatched (read the task instead of sending it again), -32011 task timed out, -32012 the connection dropped before dispatch (nothing ran; safe to retry). |
error.message | string | yes | Human-readable description of the error. |
error.data | JSONValue | no | Machine-readable detail of the error: a list with one object of type type.googleapis.com/google.rpc.ErrorInfo. Its reason is the error name, for example TASK_NOT_FOUND, and its metadata repeats the code and message. Nullable. |
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.a2a.invoke("agent_123", { jsonrpc: "2.0", method: "example_method" });
console.log(result);a2a.getAgentCard
GET /v1/a2a/{agentId}/.well-known/agent-card.json · Operation ID getA2AAgentCard
Get the A2A agent card
SDK methods
| Language | Method | Signature |
|---|---|---|
| TypeScript | cloud.a2a.getAgentCard | getAgentCard(agentId: string): Promise<Models.GetA2AAgentCardResponse> |
| Python | cloud.a2a.get_agent_card | def get_agent_card(self, agent_id: str) -> A2AAgentCard |
| Go | cloud.A2a.GetAgentCard | func (r *A2aResource) GetAgentCard(ctx context.Context, agentId string) (A2AAgentCard, error) |
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
agentId | path | string | yes | ID of the agent. It must belong to your app. For JSON-RPC and agent card requests the agent must also have its A2A protocol enabled, otherwise the request returns 403 a2a_disabled; task reads work either way. |
Response
200 · application/json · Schema: A2AAgentCard
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Display name of the agent. |
description | string | yes | Description of the agent. |
url | string | no | URL of the agent's JSON-RPC endpoint. Returned only when the request sends A2A-Version: 0.3; version 1.0 lists the endpoint in supportedInterfaces. |
version | string | yes | Version of the agent: its resource version, a decimal number. |
protocolVersion | string | no | A2A protocol version spoken at url. Returned only when the request sends A2A-Version: 0.3. |
defaultInputModes | array<string> | yes | Media types the agent accepts as input, for example text/plain. |
defaultOutputModes | array<string> | yes | Media types the agent produces as output, for example text/plain. |
supportedInterfaces | array<object> | no | Interfaces through which the agent can be reached. Returned unless the request sends A2A-Version: 0.3. |
supportedInterfaces[].url | string | yes | URL of the interface. |
supportedInterfaces[].protocolBinding | string | yes | Transport the interface uses: JSONRPC. |
supportedInterfaces[].protocolVersion | string | yes | A2A protocol version the interface speaks. |
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.a2a.getAgentCard("agent_123");
console.log(result);a2a.getAgentCardLegacy
GET /v1/a2a/{agentId}/.well-known/agent.json · Operation ID getA2AAgentCardLegacy
Get the A2A agent card (legacy path)
SDK methods
| Language | Method | Signature |
|---|---|---|
| TypeScript | cloud.a2a.getAgentCardLegacy | getAgentCardLegacy(agentId: string): Promise<Models.GetA2AAgentCardLegacyResponse> |
| Python | cloud.a2a.get_agent_card_legacy | def get_agent_card_legacy(self, agent_id: str) -> A2AAgentCard |
| Go | cloud.A2a.GetAgentCardLegacy | func (r *A2aResource) GetAgentCardLegacy(ctx context.Context, agentId string) (A2AAgentCard, error) |
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
agentId | path | string | yes | ID of the agent. It must belong to your app. For JSON-RPC and agent card requests the agent must also have its A2A protocol enabled, otherwise the request returns 403 a2a_disabled; task reads work either way. |
Response
200 · application/json · Schema: A2AAgentCard
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Display name of the agent. |
description | string | yes | Description of the agent. |
url | string | no | URL of the agent's JSON-RPC endpoint. Returned only when the request sends A2A-Version: 0.3; version 1.0 lists the endpoint in supportedInterfaces. |
version | string | yes | Version of the agent: its resource version, a decimal number. |
protocolVersion | string | no | A2A protocol version spoken at url. Returned only when the request sends A2A-Version: 0.3. |
defaultInputModes | array<string> | yes | Media types the agent accepts as input, for example text/plain. |
defaultOutputModes | array<string> | yes | Media types the agent produces as output, for example text/plain. |
supportedInterfaces | array<object> | no | Interfaces through which the agent can be reached. Returned unless the request sends A2A-Version: 0.3. |
supportedInterfaces[].url | string | yes | URL of the interface. |
supportedInterfaces[].protocolBinding | string | yes | Transport the interface uses: JSONRPC. |
supportedInterfaces[].protocolVersion | string | yes | A2A protocol version the interface speaks. |
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.a2a.getAgentCardLegacy("agent_123");
console.log(result);a2a.listTasks
GET /v1/a2a/{agentId}/tasks · Operation ID listA2ATasks
List A2A tasks
SDK methods
| Language | Method | Signature |
|---|---|---|
| TypeScript | cloud.a2a.listTasks | listTasks(agentId: string, query?: Models.ListA2ATasksQuery): Promise<Models.ListA2ATasksResponse> |
| Python | cloud.a2a.list_tasks | def list_tasks(self, agent_id: str, options: ListA2ATasksOptions | None = None) -> ListA2ATasksResponse |
| Go | cloud.A2a.ListTasks | func (r *A2aResource) ListTasks(ctx context.Context, agentId string, options ListA2ATasksOptions) (ListA2ATasksResponse, error) |
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
agentId | path | string | yes | ID of the agent. It must belong to your app. For JSON-RPC and agent card requests the agent must also have its A2A protocol enabled, otherwise the request returns 403 a2a_disabled; task reads work either way. |
direction | query | string | no | sent lists tasks that the agent submitted and received lists tasks that were submitted to it. When omitted, both are listed. Any other value is rejected. |
agent_id | query | string | no | Return only tasks exchanged with this other agent, at most 128 characters. Whether it is matched as the submitter or the receiver depends on direction. |
cursor | query | string | no | Opaque cursor for the next page: the next_cursor of the previous response, at most 4096 bytes. |
limit | query | integer | no | Number of tasks per page, from 1 to 100. Defaults to 20. |
Response
200 · application/json
| Field | Type | Required | Description |
|---|---|---|---|
tasks | array<a2aTaskView> | yes | — |
total | integer | yes | — |
next_cursor | string | yes | — |
has_more | boolean | yes | — |
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.a2a.listTasks("agent_123");
console.log(result);a2a.getTask
GET /v1/a2a/{agentId}/tasks/{taskId} · Operation ID getA2ATask
Get an A2A task
SDK methods
| Language | Method | Signature |
|---|---|---|
| TypeScript | cloud.a2a.getTask | getTask(agentId: string, taskId: string, query?: Models.GetA2ATaskQuery): Promise<Models.GetA2ATaskResponse> |
| Python | cloud.a2a.get_task | def get_task(self, agent_id: str, task_id: str, options: GetA2ATaskOptions | None = None) -> a2aTaskView |
| Go | cloud.A2a.GetTask | func (r *A2aResource) GetTask(ctx context.Context, agentId string, taskId string, options GetA2ATaskOptions) (a2aTaskView, error) |
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
agentId | path | string | yes | ID of the agent. It must belong to your app. For JSON-RPC and agent card requests the agent must also have its A2A protocol enabled, otherwise the request returns 403 a2a_disabled; task reads work either way. |
taskId | path | string | yes | ID of the task, at most 256 characters. |
history_length | query | integer | no | Maximum number of history messages to return, from 0 to 200. Defaults to 50. |
Response
200 · application/json · Schema: a2aTaskView
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | ID of the task. |
contextId | string | yes | ID of the context (conversation) the task belongs to. |
status | A2ATaskStatus | yes | Current status of the task. |
artifacts | array<A2AArtifact> | no | Outputs the agent produced for the task. Omitted while there are none. |
history | array<A2AMessage> | no | Messages of the task. A single-task read returns at most history_length of them. When no history is stored it holds the original request as one message. Omitted when there are none. |
metadata | map<string, JSONValue> | no | Extra metadata of the task. Omitted when there is none. |
caller_principal_id | string | yes | ID of the principal that submitted the task. |
caller_agent_id | string | yes | ID of the agent that submitted the task, if any. |
caller_owner_id | string | yes | ID of the owner of the submitting side. Cloud derives it from the credential's organization and app. Callers do not send an end-user id. |
target_principal_id | string | yes | ID of the principal the task was sent to. |
target_agent_id | string | yes | ID of the agent the task was sent to. |
target_owner_id | string | yes | ID of the owner of the receiving side. |
channel_id | string | no | ID of the channel that carries the streaming replies of the task. Omitted when the task does not use channel-based delivery. |
created_at | string | no | Time the task was created, as a UTC timestamp such as 2026-01-02T15:04:05.000Z. Omitted when it is not known. |
updated_at | string | no | Time the task was last updated, in the same format as created_at. Omitted when it is not known. |
completed_at | string | no | Time the task finished, in the same format as created_at. Omitted until the task is finished. |
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.a2a.getTask("agent_123", "task_123");
console.log(result);a2a.cancelTask
POST /v1/a2a/{agentId}/tasks/{taskId}/cancel · Operation ID cancelA2ATask
Cancel an A2A task
SDK methods
| Language | Method | Signature |
|---|---|---|
| TypeScript | cloud.a2a.cancelTask | cancelTask(agentId: string, taskId: string): Promise<Models.CancelA2ATaskResponse> |
| Python | cloud.a2a.cancel_task | def cancel_task(self, agent_id: str, task_id: str) -> a2aTaskView |
| Go | cloud.A2a.CancelTask | func (r *A2aResource) CancelTask(ctx context.Context, agentId string, taskId string) (a2aTaskView, error) |
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
agentId | path | string | yes | ID of the agent. It must belong to your app. For JSON-RPC and agent card requests the agent must also have its A2A protocol enabled, otherwise the request returns 403 a2a_disabled; task reads work either way. |
taskId | path | string | yes | ID of the task, at most 256 characters. |
Response
200 · application/json · Schema: a2aTaskView
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | ID of the task. |
contextId | string | yes | ID of the context (conversation) the task belongs to. |
status | A2ATaskStatus | yes | Current status of the task. |
artifacts | array<A2AArtifact> | no | Outputs the agent produced for the task. Omitted while there are none. |
history | array<A2AMessage> | no | Messages of the task. A single-task read returns at most history_length of them. When no history is stored it holds the original request as one message. Omitted when there are none. |
metadata | map<string, JSONValue> | no | Extra metadata of the task. Omitted when there is none. |
caller_principal_id | string | yes | ID of the principal that submitted the task. |
caller_agent_id | string | yes | ID of the agent that submitted the task, if any. |
caller_owner_id | string | yes | ID of the owner of the submitting side. Cloud derives it from the credential's organization and app. Callers do not send an end-user id. |
target_principal_id | string | yes | ID of the principal the task was sent to. |
target_agent_id | string | yes | ID of the agent the task was sent to. |
target_owner_id | string | yes | ID of the owner of the receiving side. |
channel_id | string | no | ID of the channel that carries the streaming replies of the task. Omitted when the task does not use channel-based delivery. |
created_at | string | no | Time the task was created, as a UTC timestamp such as 2026-01-02T15:04:05.000Z. Omitted when it is not known. |
updated_at | string | no | Time the task was last updated, in the same format as created_at. Omitted when it is not known. |
completed_at | string | no | Time the task finished, in the same format as created_at. Omitted until the task is finished. |
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.a2a.cancelTask("agent_123", "task_123");
console.log(result);BeeOS CloudBack to documentation