This reference is currently available in English. The Cloud console remains in your selected language.
BEEOS CLOUD / DEVELOPER REFERENCE
Operations and runtime methods
The operation route table and the runtime methods Cloud may deliver.
Every Cloud route the SDK uses has a stable operation id. Build paths with the helper so path parameters are percent-encoded.
Operation table
Every operation of HARNESS_OPERATIONS / OPERATIONS. The service column names the Cloud component whose origin receives the request; {name} in a path is a path parameter.
| Operation id | HTTP | Path | Target service | Description |
|---|---|---|---|---|
runtimeRegister | POST | /api/v1/runtime/registrations | agent-gateway | Registers a runtime and returns its lease. |
runtimeHeartbeat | POST | /api/v1/runtime/registrations/{registrationId}/heartbeat | agent-gateway | Renews the lease of a registration. |
runtimeRealtimeTokenCreate | POST | /api/v1/runtime/realtime/token | message-service | Creates a realtime connection token with the channels to follow. |
runtimeConversationSync | POST | /api/v1/runtime/conversations | message-service | Creates or updates the conversation of a runtime operation. |
runtimeConversationMessagesList | GET | /api/v1/runtime/conversations/{conversationId}/messages | message-service | Lists the messages of a conversation, one page at a time. |
runtimeConversationMessageCreate | POST | /api/v1/runtime/conversations/{conversationId}/messages | message-service | Posts a message to a conversation. |
runtimeConversationMessageGet | GET | /api/v1/runtime/conversations/{conversationId}/messages/{messageId} | message-service | Reads one message of a conversation. |
runtimeConversationMessagePatch | PATCH | /api/v1/runtime/conversations/{conversationId}/messages/{messageId} | message-service | Changes a message that is being streamed. |
runtimeConversationRunStart | POST | /api/v1/runtime/conversations/{conversationId}/runs/start | message-service | Starts a run of a conversation. |
runtimeConversationRunFinish | POST | /api/v1/runtime/conversations/{conversationId}/runs/finish | message-service | Finishes a run of a conversation. |
runtimeDeliveriesRead | POST | /api/v1/runtime/deliveries/read | message-service | Reads pending runtime-method deliveries. |
runtimeDeliveriesRenew | POST | /api/v1/runtime/deliveries/renew | message-service | Renews deliveries that are still being handled. |
runtimeDeliveriesAck | POST | /api/v1/runtime/deliveries/ack | message-service | Acknowledges deliveries. |
runtimeOperationHistoryGet | GET | /api/v1/runtime/operations/{operationId}/history | message-service | Reads the stored history of an operation. |
runtimeOperationMessageAppend | POST | /api/v1/runtime/operations/{operationId}/messages | message-service | Appends a message to an operation. |
conversationMessagesList | GET | /api/v2/conversations/{conversationId}/messages | message-service | Lists the messages of a conversation. Used by the Python runtime facade. |
conversationMessageSend | POST | /api/v2/conversations/{conversationId}/messages | message-service | Posts a message to a conversation. Used by the Python runtime facade. |
agentGet | GET | /api/v1/agents/{agentId} | agent-gateway | Reads an agent. |
agentUpdate | PATCH | /api/v1/agents/{agentId} | agent-gateway | Changes an agent. |
agentSync | POST | /api/v1/agents/sync | agent-gateway | Synchronises the agent definition with Cloud. |
agentFilesList | GET | /api/v1/agent/files | agent-gateway | Lists the files of the agent. |
agentFilePresign | POST | /api/v1/agent/files/presign | agent-gateway | Requests an upload URL for a new file. |
agentFileConfirm | POST | /api/v1/agent/files/confirm | agent-gateway | Confirms that a file was uploaded. |
agentFileResolve | GET | /api/v1/agent/files/{fileId}/resolve | agent-gateway | Resolves a file id into its details, including a download URL. |
canvasTokenCreate | POST | /api/v1/canvas/token | agent-gateway | Creates a canvas connection token. |
a2aDiscover | GET | /api/v1/a2a/discover | agent-gateway | Searches for agents that can be called through agent-to-agent calls. |
a2aJsonRpc | POST | /api/v1/a2a/{agentId}/jsonrpc | agent-gateway | Sends a JSON-RPC request to a peer agent. |
a2aTaskGet | GET | /api/v1/a2a/tasks/{taskId} | agent-gateway | Reads an agent-to-agent task. |
messagingTokenCreate | POST | /api/v1/messaging/token | agent-gateway | Creates a messaging token. |
runtimeHistoryBoundaryPrepare | POST | /api/v1/runtime/conversations/{conversationId}/history-boundary/prepare | message-service | History-boundary action prepare of a conversation. |
runtimeHistoryBoundaryResetting | POST | /api/v1/runtime/conversations/{conversationId}/history-boundary/resetting | message-service | History-boundary action resetting of a conversation. |
runtimeHistoryBoundaryResetDone | POST | /api/v1/runtime/conversations/{conversationId}/history-boundary/reset_done | message-service | History-boundary action reset_done of a conversation. |
runtimeHistoryBoundaryCommit | POST | /api/v1/runtime/conversations/{conversationId}/history-boundary/commit | message-service | History-boundary action commit of a conversation. |
runtimeHistoryBoundaryAbort | POST | /api/v1/runtime/conversations/{conversationId}/history-boundary/abort | message-service | History-boundary action abort of a conversation. |
runtimeHistoryBoundaryReconcile | POST | /api/v1/runtime/conversations/{conversationId}/history-boundary/reconcile | message-service | History-boundary action reconcile of a conversation. |
runtimeConversationMetadataModel | POST | /api/v1/runtime/conversations/{conversationId}/metadata/model | message-service | Publishes the session model of a conversation. |
runtimeConversationCronDelivery | POST | /api/v1/runtime/conversations/{conversationId}/deliveries/cron | message-service | Delivers a scheduled-task result into a conversation. |
runtimeClaimNext | POST | /api/v1/runtime/claims/next | message-service | Claims the next pending operation. |
runtimeClaimExact | POST | /api/v1/runtime/operations/{operationId}/claims | message-service | Claims one specific operation. |
runtimeClaimRenew | POST | /api/v1/runtime/operations/{operationId}/claims/renew | message-service | Renews the claim of an operation. |
runtimeClaimRelease | POST | /api/v1/runtime/operations/{operationId}/claims/release | message-service | Releases the claim of an operation. |
runtimeResourceRedeem | POST | built by the SDK | agent-gateway | Redeems a resource (a skill or an MCP resource) of an operation. |
runtimeOutputFilePresign | POST | built by the SDK | agent-gateway | Requests upload URLs for the output files of an operation. |
runtimeOutputFileConfirm | POST | built by the SDK | agent-gateway | Confirms that the output files of an operation were uploaded. |
runtimeInputFilesResolve | POST | built by the SDK | agent-gateway | Resolves the input files of an operation into download locations. |
agentTemplateOriginReport | POST | /api/v1/agents/{agentId}/template-origin | agent-gateway | Reports the template that an agent was created from. |
channelCreate | POST | /api/v1/channels | agent-gateway | Creates a channel with the given participants and metadata. |
a2aTaskComplete | POST | /api/v1/a2a/tasks/{taskId}/complete | agent-gateway | Reports the outcome of an agent-to-agent task. |
agentEventPublish | POST | /api/v1/agent/events | agent-gateway | Publishes an agent event. |
bridgeConfigGet | GET | /api/v1/bridge/config | agent-gateway | Reads the bridge configuration. |
agentConnectorMcp | POST | /api/v1/agent/connectors/mcp | agent-gateway | Passes a JSON-RPC request through to the connector MCP endpoint. |
automationList | GET | /api/v1/automations | agent-gateway | Lists automations. |
automationCreate | POST | /api/v1/automations | agent-gateway | Creates an automation. |
automationWebhookCreate | POST | /api/v1/automations/webhooks | agent-gateway | Creates a webhook for automations. |
automationGet | GET | /api/v1/automations/{automationId} | agent-gateway | Reads one automation. |
automationRunsList | GET | /api/v1/automations/{automationId}/runs | agent-gateway | Lists the runs of an automation. |
automationRunCreate | POST | /api/v1/automations/{automationId}/runs | agent-gateway | Starts a run of an automation. |
automationRunGet | GET | /api/v1/automations/{automationId}/runs/{runId} | agent-gateway | Reads one run of an automation. |
Symbols
harnessOperationPath
TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk
Returns the path of an operation with every placeholder replaced by its URI-encoded value.
function harnessOperationPath<K extends OperationId>(id: K, ...params: keyof OperationPathParams[K] extends never ? [] : [OperationPathParams[K]]): stringTypeScript · Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
id | K | yes | Identifier of the operation, a key of HARNESS_OPERATIONS. | |
params | keyof OperationPathParams[K] extends never ? [] : [OperationPathParams[K]] | yes | Values for the {name} placeholders in the path. Omit it for a path without placeholders. |
Returns string
Python · Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
operation_id | str | yes | Identifier of the operation. | |
**params | object | yes | Values for the {name} placeholders in the path. Omit it for a path without placeholders. |
Returns str
CHAT_PROMPT_METHOD
Python beeos_cloud_harness_sdk · Python only
The runtime method, session/prompt, in which Cloud delivers every user chat prompt. The reply row is created by Cloud in the streaming state, and the agent finishes it.
CHAT_PROMPT_METHOD = 'session/prompt'HARNESS_OPERATIONS
TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk
Table of all operations: for each operation id the HTTP method, the path template and the target service.
const HARNESS_OPERATIONS: { readonly runtimeRegister: { readonly method: "POST"; readonly path: "/api/v1/runtime/registrations"; readonly service: "agent-gateway"; }; readonly runtimeHeartbeat: { readonly method: "POST"; readonly path: "/api/v1/runtime/registrations/{registrationId}/heartbeat"; readonly service: "agent-gateway"; }; readonly runtimeRealtimeTokenCreate: { readonly method: "POST"; readonly path: "/api/v1/runtime/realtime/token"; readonly service: "message-service"; }; readonly runtimeConversationSync: { readonly method: "POST"; readonly path: "/api/v1/runtime/conversations"; readonly service: "message-service"; }; readonly runtimeConversationMessagesList: { readonly method: "GET"; readonly path: "/api/v1/runtime/conversations/{conversationId}/messages"; readonly service: "message-service"; }; readonly runtimeConversationMessageCreate: { readonly method: "POST"; readonly path: "/api/v1/runtime/conversations/{conversationId}/messages"; readonly service: "message-service"; }; readonly runtimeConversationMessageGet: { readonly method: "GET"; readonly path: "/api/v1/runtime/conversations/{conversationId}/messages/{messageId}"; readonly service: "message-service"; }; readonly runtimeConversationMessagePatch: { readonly method: "PATCH"; readonly path: "/api/v1/runtime/conversations/{conversationId}/messages/{messageId}"; readonly service: "message-service"; }; readonly runtimeConversationRunStart: { readonly method: "POST"; readonly path: "/api/v1/runtime/conversations/{conversationId}/runs/start"; readonly service: "message-service"; }; readonly runtimeConversationRunFinish: { readonly method: "POST"; readonly path: "/api/v1/runtime/conversations/{conversationId}/runs/finish"; readonly service: "message-service"; }; readonly runtimeDeliveriesRead: { readonly method: "POST"; readonly path: "/api/v1/runtime/deliveries/read"; readonly service: "message-service"; }; readonly runtimeDeliveriesRenew: { readonly method: "POST"; readonly path: "/api/v1/runtime/deliveries/renew"; readonly service: "message-service"; }; readonly runtimeDeliveriesAck: { readonly method: "POST"; readonly path: "/api/v1/runtime/deliveries/ack"; readonly service: "message-service"; }; readonly runtimeOperationHistoryGet: { readonly method: "GET"; readonly path: "/api/v1/runtime/operations/{operationId}/history"; readonly service: "message-service"; }; readonly runtimeOperationMessageAppend: { readonly method: "POST"; readonly path: "/api/v1/runtime/operations/{operationId}/messages"; readonly service: "message-service"; }; readonly conversationMessagesList: { readonly method: "GET"; readonly path: "/api/v2/conversations/{conversationId}/messages"; readonly service: "message-service"; }; readonly conversationMessageSend: { readonly method: "POST"; readonly path: "/api/v2/conversations/{conversationId}/messages"; readonly service: "message-service"; }; readonly agentGet: { readonly method: "GET"; readonly path: "/api/v1/agents/{agentId}"; readonly service: "agent-gateway"; }; readonly agentUpdate: { readonly method: "PATCH"; readonly path: "/api/v1/agents/{agentId}"; readonly service: "agent-gateway"; }; readonly agentSync: { readonly method: "POST"; readonly path: "/api/v1/agents/sync"; readonly service: "agent-gateway"; }; readonly agentFilesList: { readonly method: "GET"; readonly path: "/api/v1/agent/files"; readonly service: "agent-gateway"; }; readonly agentFilePresign: { readonly method: "POST"; readonly path: "/api/v1/agent/files/presign"; readonly service: "agent-gateway"; }; readonly agentFileConfirm: { readonly method: "POST"; readonly path: "/api/v1/agent/files/confirm"; readonly service: "agent-gateway"; }; readonly agentFileResolve: { readonly method: "GET"; readonly path: "/api/v1/agent/files/{fileId}/resolve"; readonly service: "agent-gateway"; }; readonly canvasTokenCreate: { readonly method: "POST"; readonly path: "/api/v1/canvas/token"; readonly service: "agent-gateway"; }; readonly a2aDiscover: { readonly method: "GET"; readonly path: "/api/v1/a2a/discover"; readonly service: "agent-gateway"; }; readonly a2aJsonRpc: { readonly method: "POST"; readonly path: "/api/v1/a2a/{agentId}/jsonrpc"; readonly service: "agent-gateway"; }; readonly a2aTaskGet: { readonly method: "GET"; readonly path: "/api/v1/a2a/tasks/{taskId}"; readonly service: "agent-gateway"; }; readonly messagingTokenCreate: { readonly method: "POST"; readonly path: "/api/v1/messaging/token"; readonly service: "agent-gateway"; }; readonly runtimeHistoryBoundaryPrepare: { readonly method: "POST"; readonly path: "/api/v1/runtime/conversations/{conversationId}/history-boundary/prepare"; readonly service: "message-service"; }; readonly runtimeHistoryBoundaryResetting: { readonly method: "POST"; readonly path: "/api/v1/runtime/conversations/{conversationId}/history-boundary/resetting"; readonly service: "message-service"; }; readonly runtimeHistoryBoundaryResetDone: { readonly method: "POST"; readonly path: "/api/v1/runtime/conversations/{conversationId}/history-boundary/reset_done"; readonly service: "message-service"; }; readonly runtimeHistoryBoundaryCommit: { readonly method: "POST"; readonly path: "/api/v1/runtime/conversations/{conversationId}/history-boundary/commit"; readonly service: "message-service"; }; readonly runtimeHistoryBoundaryAbort: { readonly method: "POST"; readonly path: "/api/v1/runtime/conversations/{conversationId}/history-boundary/abort"; readonly service: "message-service"; }; readonly runtimeHistoryBoundaryReconcile: { readonly method: "POST"; readonly path: "/api/v1/runtime/conversations/{conversationId}/history-boundary/reconcile"; readonly service: "message-service"; }; readonly runtimeConversationMetadataModel: { readonly method: "POST"; readonly path: "/api/v1/runtime/conversations/{conversationId}/metadata/model"; readonly service: "message-service"; }; readonly runtimeConversationCronDelivery: { readonly method: "POST"; readonly path: "/api/v1/runtime/conversations/{conversationId}/deliveries/cron"; readonly service: "message-service"; }; readonly runtimeClaimNext: { readonly method: "POST"; readonly path: "/api/v1/runtime/claims/next"; readonly service: "message-service"; }; readonly runtimeClaimExact: { readonly method: "POST"; readonly path: "/api/v1/runtime/operations/{operationId}/claims"; readonly service: "message-service"; }; readonly runtimeClaimRenew: { readonly method: "POST"; readonly path: "/api/v1/runtime/operations/{operationId}/claims/renew"; readonly service: "message-service"; }; readonly runtimeClaimRelease: { readonly method: "POST"; readonly path: "/api/v1/runtime/operations/{operationId}/claims/release"; readonly service: "message-service"; }; readonly runtimeResourceRedeem: { readonly method: "POST"; readonly path: "(built by the SDK)"; readonly service: "agent-gateway"; }; readonly runtimeOutputFilePresign: { readonly method: "POST"; readonly path: "(built by the SDK)"; readonly service: "agent-gateway"; }; readonly runtimeOutputFileConfirm: { readonly method: "POST"; readonly path: "(built by the SDK)"; readonly service: "agent-gateway"; }; readonly runtimeInputFilesResolve: { readonly method: "POST"; readonly path: "(built by the SDK)"; readonly service: "agent-gateway"; }; readonly agentTemplateOriginReport: { readonly method: "POST"; readonly path: "/api/v1/agents/{agentId}/template-origin"; readonly service: "agent-gateway"; }; readonly channelCreate: { readonly method: "POST"; readonly path: "/api/v1/channels"; readonly service: "agent-gateway"; }; readonly a2aTaskComplete: { readonly method: "POST"; readonly path: "/api/v1/a2a/tasks/{taskId}/complete"; readonly service: "agent-gateway"; }; readonly agentEventPublish: { readonly method: "POST"; readonly path: "/api/v1/agent/events"; readonly service: "agent-gateway"; }; readonly bridgeConfigGet: { readonly method: "GET"; readonly path: "/api/v1/bridge/config"; readonly service: "agent-gateway"; }; readonly agentConnectorMcp: { readonly method: "POST"; readonly path: "/api/v1/agent/connectors/mcp"; readonly service: "agent-gateway"; }; readonly automationList: { readonly method: "GET"; readonly path: "/api/v1/automations"; readonly service: "agent-gateway"; }; readonly automationCreate: { readonly method: "POST"; readonly path: "/api/v1/automations"; readonly service: "agent-gateway"; }; readonly automationWebhookCreate: { readonly method: "POST"; readonly path: "/api/v1/automations/webhooks"; readonly service: "agent-gateway"; }; readonly automationGet: { readonly method: "GET"; readonly path: "/api/v1/automations/{automationId}"; readonly service: "agent-gateway"; }; readonly automationRunsList: { readonly method: "GET"; readonly path: "/api/v1/automations/{automationId}/runs"; readonly service: "agent-gateway"; }; readonly automationRunCreate: { readonly method: "POST"; readonly path: "/api/v1/automations/{automationId}/runs"; readonly service: "agent-gateway"; }; readonly automationRunGet: { readonly method: "GET"; readonly path: "/api/v1/automations/{automationId}/runs/{runId}"; readonly service: "agent-gateway"; }; }HarnessOperationId
TypeScript @beeos-ai/cloud-harness-sdk · TypeScript only
The string-literal union of every operation id in HARNESS_OPERATIONS (keyof typeof HARNESS_OPERATIONS), and the type of the id argument of harnessOperationPath. The generated source declares it as OperationId; the package exports it under this name.
type HarnessOperationId = OperationIdType: OperationId
RuntimeMethod
TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk
The runtime methods that Cloud may deliver to a harness. Every user chat prompt arrives as session/prompt.
Value: RuntimeMethod
BeeOS CloudBack to documentation