BEEOS CLOUD / DEVELOPER REFERENCE
操作表与运行时方法
操作路由表，以及 Cloud 可能投递的运行时方法。
SDK 用到的每条 Cloud 路由都有稳定的操作 ID。用辅助函数构造路径，路径参数会被百分号编码。
操作表
下表列出 HARNESS_OPERATIONS / OPERATIONS 的全部操作。服务列说明请求发往哪个 Cloud 组件的 origin；路径中的 {name} 是路径参数。
| 操作 ID | HTTP | Path | 目标服务 | 说明 |
|---|---|---|---|---|
runtimeRegister | POST | /api/v1/runtime/registrations | agent-gateway | 注册运行时并返回其租约。 |
runtimeHeartbeat | POST | /api/v1/runtime/registrations/{registrationId}/heartbeat | agent-gateway | 为某个注册续租。 |
runtimeRealtimeTokenCreate | POST | /api/v1/runtime/realtime/token | message-service | 创建实时连接令牌，并给出要订阅的频道。 |
runtimeConversationSync | POST | /api/v1/runtime/conversations | message-service | 创建或更新某个运行时操作的会话。 |
runtimeConversationMessagesList | GET | /api/v1/runtime/conversations/{conversationId}/messages | message-service | 分页列出会话的消息。 |
runtimeConversationMessageCreate | POST | /api/v1/runtime/conversations/{conversationId}/messages | message-service | 向会话发送一条消息。 |
runtimeConversationMessageGet | GET | /api/v1/runtime/conversations/{conversationId}/messages/{messageId} | message-service | 读取会话中的一条消息。 |
runtimeConversationMessagePatch | PATCH | /api/v1/runtime/conversations/{conversationId}/messages/{messageId} | message-service | 修改正在流式写入的消息。 |
runtimeConversationRunStart | POST | /api/v1/runtime/conversations/{conversationId}/runs/start | message-service | 开始会话的一次运行。 |
runtimeConversationRunFinish | POST | /api/v1/runtime/conversations/{conversationId}/runs/finish | message-service | 结束会话的一次运行。 |
runtimeDeliveriesRead | POST | /api/v1/runtime/deliveries/read | message-service | 读取待处理的运行时方法投递。 |
runtimeDeliveriesRenew | POST | /api/v1/runtime/deliveries/renew | message-service | 为仍在处理的投递续期。 |
runtimeDeliveriesAck | POST | /api/v1/runtime/deliveries/ack | message-service | 确认投递。 |
runtimeOperationHistoryGet | GET | /api/v1/runtime/operations/{operationId}/history | message-service | 读取某个操作已保存的历史。 |
runtimeOperationMessageAppend | POST | /api/v1/runtime/operations/{operationId}/messages | message-service | 向某个操作追加一条消息。 |
conversationMessagesList | GET | /api/v2/conversations/{conversationId}/messages | message-service | 列出会话的消息。供 Python 运行时门面使用。 |
conversationMessageSend | POST | /api/v2/conversations/{conversationId}/messages | message-service | 向会话发送一条消息。供 Python 运行时门面使用。 |
agentGet | GET | /api/v1/agents/{agentId} | agent-gateway | 读取一个智能体。 |
agentUpdate | PATCH | /api/v1/agents/{agentId} | agent-gateway | 修改一个智能体。 |
agentSync | POST | /api/v1/agents/sync | agent-gateway | 把智能体定义同步到 Cloud。 |
agentFilesList | GET | /api/v1/agent/files | agent-gateway | 列出智能体的文件。 |
agentFilePresign | POST | /api/v1/agent/files/presign | agent-gateway | 为新文件申请上传 URL。 |
agentFileConfirm | POST | /api/v1/agent/files/confirm | agent-gateway | 确认文件已上传。 |
agentFileResolve | GET | /api/v1/agent/files/{fileId}/resolve | agent-gateway | 把文件 ID 解析为详情，包含下载 URL。 |
canvasTokenCreate | POST | /api/v1/canvas/token | agent-gateway | 创建画布连接令牌。 |
a2aDiscover | GET | /api/v1/a2a/discover | agent-gateway | 搜索可通过智能体间调用访问的智能体。 |
a2aJsonRpc | POST | /api/v1/a2a/{agentId}/jsonrpc | agent-gateway | 向对端智能体发送 JSON-RPC 请求。 |
a2aTaskGet | GET | /api/v1/a2a/tasks/{taskId} | agent-gateway | 读取一个智能体间任务。 |
messagingTokenCreate | POST | /api/v1/messaging/token | agent-gateway | 创建消息令牌。 |
runtimeHistoryBoundaryPrepare | POST | /api/v1/runtime/conversations/{conversationId}/history-boundary/prepare | message-service | 会话的历史边界动作 prepare。 |
runtimeHistoryBoundaryResetting | POST | /api/v1/runtime/conversations/{conversationId}/history-boundary/resetting | message-service | 会话的历史边界动作 resetting。 |
runtimeHistoryBoundaryResetDone | POST | /api/v1/runtime/conversations/{conversationId}/history-boundary/reset_done | message-service | 会话的历史边界动作 reset_done。 |
runtimeHistoryBoundaryCommit | POST | /api/v1/runtime/conversations/{conversationId}/history-boundary/commit | message-service | 会话的历史边界动作 commit。 |
runtimeHistoryBoundaryAbort | POST | /api/v1/runtime/conversations/{conversationId}/history-boundary/abort | message-service | 会话的历史边界动作 abort。 |
runtimeHistoryBoundaryReconcile | POST | /api/v1/runtime/conversations/{conversationId}/history-boundary/reconcile | message-service | 会话的历史边界动作 reconcile。 |
runtimeConversationMetadataModel | POST | /api/v1/runtime/conversations/{conversationId}/metadata/model | message-service | 发布会话的会话模型。 |
runtimeConversationCronDelivery | POST | /api/v1/runtime/conversations/{conversationId}/deliveries/cron | message-service | 把定时任务的结果投递到会话。 |
runtimeClaimNext | POST | /api/v1/runtime/claims/next | message-service | 认领下一个待处理的操作。 |
runtimeClaimExact | POST | /api/v1/runtime/operations/{operationId}/claims | message-service | 认领指定的某个操作。 |
runtimeClaimRenew | POST | /api/v1/runtime/operations/{operationId}/claims/renew | message-service | 为某个操作的认领续期。 |
runtimeClaimRelease | POST | /api/v1/runtime/operations/{operationId}/claims/release | message-service | 释放某个操作的认领。 |
runtimeResourceRedeem | POST | 由 SDK 构造 | agent-gateway | 兑换某个操作的资源（技能或 MCP 资源）。 |
runtimeOutputFilePresign | POST | 由 SDK 构造 | agent-gateway | 为某个操作的输出文件申请上传 URL。 |
runtimeOutputFileConfirm | POST | 由 SDK 构造 | agent-gateway | 确认某个操作的输出文件已上传。 |
runtimeInputFilesResolve | POST | 由 SDK 构造 | agent-gateway | 把某个操作的输入文件解析为可下载的位置。 |
agentTemplateOriginReport | POST | /api/v1/agents/{agentId}/template-origin | agent-gateway | 上报智能体所基于的模板。 |
channelCreate | POST | /api/v1/channels | agent-gateway | 用给定的参与者和元数据创建频道。 |
a2aTaskComplete | POST | /api/v1/a2a/tasks/{taskId}/complete | agent-gateway | 上报一个智能体间任务的结果。 |
agentEventPublish | POST | /api/v1/agent/events | agent-gateway | 发布一个智能体事件。 |
bridgeConfigGet | GET | /api/v1/bridge/config | agent-gateway | 读取桥接配置。 |
agentConnectorMcp | POST | /api/v1/agent/connectors/mcp | agent-gateway | 把 JSON-RPC 请求透传到连接器的 MCP 端点。 |
automationList | GET | /api/v1/automations | agent-gateway | 列出自动化任务。 |
automationCreate | POST | /api/v1/automations | agent-gateway | 创建自动化任务。 |
automationWebhookCreate | POST | /api/v1/automations/webhooks | agent-gateway | 为自动化任务创建 webhook。 |
automationGet | GET | /api/v1/automations/{automationId} | agent-gateway | 读取一个自动化任务。 |
automationRunsList | GET | /api/v1/automations/{automationId}/runs | agent-gateway | 列出某个自动化任务的运行记录。 |
automationRunCreate | POST | /api/v1/automations/{automationId}/runs | agent-gateway | 启动一次自动化任务的运行。 |
automationRunGet | GET | /api/v1/automations/{automationId}/runs/{runId} | agent-gateway | 读取某个自动化任务的一次运行。 |
符号
harnessOperationPath
TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk
返回某个操作的路径，其中每个占位符都被替换为经 URI 编码的取值。
function harnessOperationPath<K extends OperationId>(id: K, ...params: keyof OperationPathParams[K] extends never ? [] : [OperationPathParams[K]]): stringTypeScript · 参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
id | K | 是 | 操作的标识，即 HARNESS_OPERATIONS 的键。 | |
params | keyof OperationPathParams[K] extends never ? [] : [OperationPathParams[K]] | 是 | 路径中 {name} 占位符的取值。路径没有占位符时省略。 |
返回值 string
Python · 参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
operation_id | str | 是 | 操作的标识。 | |
**params | object | 是 | 路径中 {name} 占位符的取值。路径没有占位符时省略。 |
返回值 str
CHAT_PROMPT_METHOD
Python beeos_cloud_harness_sdk · 仅 Python
Cloud 投递每条用户聊天提示所用的运行时方法 session/prompt。回复行由 Cloud 以 streaming 状态创建，由智能体负责收尾。
CHAT_PROMPT_METHOD = 'session/prompt'HARNESS_OPERATIONS
TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk
全部操作的表：每个操作 ID 对应的 HTTP 方法、路径模板和目标服务。
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
HARNESS_OPERATIONS 中全部操作 ID 的字符串字面量联合类型（keyof typeof HARNESS_OPERATIONS），也是 harnessOperationPath 的 id 参数类型。生成源码里它叫 OperationId，包以当前名字导出。
type HarnessOperationId = OperationId类型: OperationId
RuntimeMethod
TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk
Cloud 可能投递给 harness 的运行时方法。每条用户聊天提示都以 session/prompt 到达。
取值: RuntimeMethod
BeeOS Cloud返回文档首页