BEEOS CLOUD / DEVELOPER REFERENCE

Harness SDK 总览

Harness SDK 的适用场景、适用对象、支持的语言，以及各项能力在哪里查阅。

Harness SDK 把自定义的智能体运行时（称为 harness）接入 BeeOS Cloud。它发布了 TypeScript 与 Python 两个包，两个包用相同的名字暴露相同的概念。

产品后端调用 Cloud 请使用 Cloud SDK（见 SDK 总览）。

适用场景

向 Cloud 注册运行时，获得短期租约，并用带签名的心跳续租。
以持久化投递的方式接收 session/prompt 等运行时方法调用，确认投递并追加结果。
把聊天回复流式写入 Cloud 预先创建的回复消息，读取会话历史，并订阅实时事件。
用带签名的请求调用 Agent Gateway：文件、画布令牌、智能体间调用、频道、事件、连接器与自动化。
连接画布中继与终端桥，并校验随运行时方法到达的执行授权（仅 TypeScript）。

适用对象

自定义 harness 或智能体运行时的作者：你自己掌握模型循环和入站传输，希望由 BeeOS 提供身份、消息、文件、画布和智能体间调用。它不是面向产品后端的客户端。

支持的语言

语言	包名	版本	运行环境	依赖
TypeScript	`@beeos-ai/cloud-harness-sdk`	1.0.0	Node.js ≥ 22 (ESM)	`centrifuge`, `ws`, `@beeos-ai/beeos-types`
Python	`beeos-cloud-harness-sdk`	1.0.0	Python ≥ 3.11	`httpx`, `cryptography`; 包根只使用标准库

模块

每个模块一页。每个公开的类、函数和方法都有签名、参数表、返回类型和说明。共享的类型与枚举见附录。

模块	覆盖内容	可用语言
安装与鉴权	安装、凭据与初始化	TypeScript 与 Python
注册与租约	注册运行时、用心跳续租，并持久化运行时身份。	TypeScript 与 Python
身份与请求签名	Ed25519 密钥对、请求签名头与规范化哈希。	TypeScript 与 Python
接收运行时方法（投递）	读取、续期、确认投递，追加结果，以及使用租约鉴权的 HTTP 数据面。	TypeScript 与 Python
会话回复与实时通道	发送并流式写入聊天回复、读取历史，以及订阅实时事件。	TypeScript 与 Python
Python 智能体运行时	Python 包根的纯标准库 BeeOSAgentRuntime 门面。	仅 Python
Agent Gateway 客户端	向 Agent Gateway 发送签名请求：文件、画布令牌、智能体、频道、A2A、事件、连接器与自动化。	TypeScript 与 Python
画布中继与终端桥	画布中继与终端桥的 WebSocket 辅助工具。	TypeScript 与 Python
执行授权校验	用 Cloud 发布的公钥校验随运行时方法下发的执行授权。	仅 TypeScript
重试与 HTTP 错误	退避策略、瞬时错误判定与 Cloud HTTP 错误类型。	TypeScript 与 Python
操作表与运行时方法	操作路由表，以及 Cloud 可能投递的运行时方法。	TypeScript 与 Python
附录：类型与枚举	全部共享结构与枚举的字段和取值	TypeScript 与 Python

两种语言的差异

只存在于一种语言中的能力会在对应页面上标注，并列在下面。

模块	仅 TypeScript	仅 Python
注册与租约	`InstanceAuthorityRuntimeRegistrationTransport`, `RuntimeRegistrationAuthoritySource`, `RuntimeTransportFailurePolicy`, `RuntimeRegistrationLeaseExpiredError`	`load_or_create_identity`, `save_identity`, `FENCED_RETRY`, `HEARTBEAT_TRANSPORT_FAILURE_THRESHOLD`, `IDENTITY_FILE_NAME`, `RUNTIME_CURRENT_MANIFEST_DIGEST`, `RUNTIME_RPC_CONTRACT_REVISION`, `RUNTIME_RPC_PROTOCOL_VERSION`, `RuntimeRegistrationError`, `RuntimeRegistrationIntentConflict`
身份与请求签名	`AgentRequestIdentity`, `agentIdentityFromKeyPair`, `agentRequestAuthHeaders`, `authenticatedAgentFetch`	`canonicalize_jcs`, `generate_agent_key_pair`, `runtime_domain_hash`, `sha256_hex`, `signing_path_from_url`, `AGENT_PROJECTION_HASH_DOMAIN`, `HEARTBEAT_HASH_DOMAIN`, `REGISTRATION_HASH_DOMAIN`
接收运行时方法（投递）	`RuntimeDeliveryAuthorityPort`, `RuntimeDeliveryOriginPort`, `RuntimeDeliveryPort`	`create_runtime_delivery_port`
会话回复与实时通道	`BoundRuntimeChatReply`, `CentrifugeClientLike`, `CentrifugeRealtimeFactory`, `RuntimeChatAuthorityPort`, `RuntimeChatClient`, `RuntimeChatHttpPort`, `RuntimeChatRealtimePort`, `RuntimeChatReplyStream`, `RuntimeRealtimeSubscription`, `bindExistingRuntimeChatReply`, `createCentrifugoRealtimePort`, `createRuntimeChatClient`, `createRuntimeChatHttpPort`, `normalizeMessage`, `subscribeRuntimeRealtime`, `RUNTIME_CHAT_PATHS`, `RuntimeChatPreparedClearError`	—
Python 智能体运行时	—	`BeeOSAgentRuntime`, `extract_chat_prompt`, `extract_session_prompt`, `BeeOSAgentError`
执行授权校验	`CloudGatewayGrantJwksVerifier`, `CoreExecutionAuthorizationVerifier`, `GatewayGrantJwksVerifier`, `MessageServiceBoundaryJwksVerifier`, `RuntimeJwksVerifier`, `SplitIssuerRuntimeAuthorizationVerifier`, `createCloudGrantVerifier`, `warmGrantJwks`	—
重试与 HTTP 错误	`abortableSleep`	`TRANSIENT_STATUSES`
操作表与运行时方法	`HarnessOperationId`	`CHAT_PROMPT_METHOD`

有两处差异会影响 harness 的写法。TypeScript 没有注册身份存储：注册 ID、日志存储 ID 和日志代数需要你自己传入，而 Python 的 load_or_create_identity 会把它们保存在文件里。Python 包根还包含 BeeOSAgentRuntime，这是一个小型门面，用一个 bearer 令牌鉴权，而不是 Ed25519 签名和运行时租约。

如何阅读参考

代码块有 TypeScript 与 Python 两个标签页。只存在于一种语言的小节会在标题下注明。
表格中的类型名链接到附录，附录列出每个字段和每个枚举值。
字段表中的名称按 TypeScript 写法给出，Python 名称不同时写在旁边。

源码与版本

本参考描述 @beeos-ai/cloud-harness-sdk@1.0.0 与 beeos-cloud-harness-sdk==1.0.0。源码：beeos-ai/beeos-cloud-harness-sdk-node、beeos-ai/beeos-cloud-harness-sdk-python。

BeeOS Cloud返回文档首页