BEEOS CLOUD / DEVELOPER REFERENCE

Agent Gateway 客户端

向 Agent Gateway 发送签名请求：文件、画布令牌、智能体、频道、A2A、事件、连接器与自动化。

AgentGatewayClient 用 harness 密钥给每个请求签名，每次重试都会重新签名，并且只重试可安全重放的调用。各类资源以 files、a2a 等命名空间挂在客户端上。

AgentGatewayClient

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.gateway

Agent Gateway 的客户端。它用 harness 身份为每个请求签名，只与一个 origin 通信，对幂等调用的可重试失败自动重试，并把路由按资源（files、canvas、agents、channels、a2a、events、bridge、connectors、automations、runtime）分组。

class AgentGatewayClient
new AgentGatewayClient(readonly options: AgentGatewayClientOptions)

TypeScript · 构造

参数	类型	必填	默认值	说明
`options`	AgentGatewayClientOptions	是		Agent Gateway 的 `baseUrl`、用于签名的 `identity`、可选的默认 `retry` 策略（`false` 关闭重试，默认 `TRANSIENT_BACKOFF`），以及可选的 `onRetry` 回调。

Python · 构造

参数	类型	必填	默认值	说明
`base_url`	`str`	是		Agent Gateway 的基础 URL，必须是不带用户信息的 `http` 或 `https`。
`keys`	AgentKeyPair	是		为请求签名的 harness 密钥对。
`client`	`httpx.AsyncClient \| None`	否	`None`	可选的 `httpx.AsyncClient`，用于发送请求；省略时使用临时客户端。
`timeout`	`float`	否	`30.0`	超时时间，单位秒。
`retry`	BackoffPolicy \| None	否	`TRANSIENT_BACKOFF`	幂等调用的默认重试策略；`None` 表示关闭重试。
`on_retry`	`Callable[[str, str, int, int, BaseException], None] \| None`	否	`None`	每次重试等待之前调用，参数依次为方法、路径、尝试序号、延迟毫秒数和错误。

属性

名称	类型	说明
`readonly baseUrl`	`URL`	请求所发往的网关 origin。
`readonly files`	GatewayFiles	文件调用：列出、预签名、确认、解析、上传与下载。
`readonly canvas`	GatewayCanvas	画布调用：创建画布令牌、构造中继请求头。
`readonly agents`	GatewayAgents	智能体调用：同步智能体投影、上报其模板来源。
`readonly channels`	GatewayChannels	频道调用：创建频道。
`readonly a2a`	GatewayA2a	智能体间（A2A）调用：发现智能体、发送 JSON-RPC 请求、完成任务。
`readonly events`	GatewayEvents	事件调用：发布智能体事件。
`readonly bridge`	GatewayBridge	桥接调用：读取桥接配置。
`readonly connectors`	GatewayConnectors	连接器调用：把请求透传到连接器的 MCP 端点。
`readonly automations`	GatewayAutomations	自动化调用：列出、创建、读取、运行自动化任务并读取其运行记录。
`readonly runtime`	GatewayRuntime	运行时调用：注册、心跳，以及兑换操作资源。

fetch

发送带签名的请求。对 GET 与 HEAD 调用、标记为 idempotent 的调用，以及单次调用显式给出重试策略的调用，网络错误和 408、425、429、500、502、503、504 状态码会被重试。重试用尽时返回最后一次应答。

async fetch(target: string | URL, init: GatewayRequestInit = {}): Promise<Response>

TypeScript · 参数

参数	类型	必填	默认值	说明
`target`	`string \| URL`	是		以 `/` 开头的路径，或位于网关 origin 上的绝对 URL。
`init`	GatewayRequestInit	否	`{}`	标准 `fetch` 选项（请求体必须是字符串或 `Uint8Array`），外加 `retry` 与 `idempotent`。

返回值 Promise<Response>

Python · 参数

参数	类型	必填	默认值	说明
`method`	`str`	是		HTTP 方法。
`path`	`str`	是		请求路径。
`body`	`Any`	否	`None`	调用的请求体，为与 JSON 兼容的数据。
`headers`	`Mapping[str, str] \| None`	否	`None`	额外的请求头。
`retry`	BackoffPolicy \| None \| object	否	`_UNSET`	本次调用的重试策略。不设置则用客户端默认值；`None` 关闭重试；显式给出策略时，非 GET 调用也允许重试。
`idempotent`	`bool`	否	`False`	为 `True` 时，允许重试网关会去重的非 GET 调用。
`timeout`	`float \| None`	否	`None`	超时时间，单位秒。

返回值 httpx.Response

json

发送带签名的 JSON 请求并返回解码后的应答。任何非 2xx 应答都会抛出 CloudHttpError。

async json<T>(method: string, path: string, body?: unknown, init: GatewayRequestInit = {}): Promise<T>

TypeScript · 参数

参数	类型	必填	默认值	说明
`method`	`string`	是		HTTP 方法。
`path`	`string`	是		请求路径。
`body`	`unknown`	否		调用的请求体，为与 JSON 兼容的数据。
`init`	GatewayRequestInit	否	`{}`	单次调用选项：`fetch` 选项外加 `retry` 与 `idempotent`。

返回值 Promise<T>

Python · 参数

参数	类型	必填	默认值	说明
`method`	`str`	是		HTTP 方法。
`path`	`str`	是		请求路径。
`body`	`Any`	否	`None`	调用的请求体，为与 JSON 兼容的数据。
`**kwargs`	`Any`	是		与 `fetch` 相同的选项：`headers`、`retry`、`idempotent` 与 `timeout`。

返回值 Any

upgradeHeaders

仅 TypeScript

为你自己发送的请求（例如画布中继的 WebSocket 升级）构造四个 X-Agent-* 头。

upgradeHeaders(method: string, path: string, body?: string | Uint8Array | null): Record<string, string>

TypeScript · 参数

参数	类型	必填	说明
`method`	`string`	是	HTTP 方法。
`path`	`string`	是	请求路径。
`body`	`string \| Uint8Array \| null`	否	调用的请求体，为与 JSON 兼容的数据。

返回值 Record<string, string>

asFetch

仅 TypeScript

返回绑定到该客户端的 fetch 风格函数，适合只需要带签名传输的组件。

asFetch(): (url: string | URL, init?: RequestInit) => Promise<Response>

TypeScript · 参数

无参数。

返回值 (url: string \| URL, init?: RequestInit) => Promise<Response>

aclose

仅 Python

关闭底层的 HTTP 客户端。

async def aclose() -> None

Python · 参数

无参数。

返回值 None

bytes

仅 Python

发送带签名的请求，并以原始字节返回应答。

async def bytes(method: str, path: str, body: Any = None, **kwargs: Any) -> bytes

Python · 参数

参数	类型	必填	默认值	说明
`method`	`str`	是		HTTP 方法。
`path`	`str`	是		请求路径。
`body`	`Any`	否	`None`	调用的请求体，为与 JSON 兼容的数据。
`**kwargs`	`Any`	是		与 `fetch` 相同的选项：`headers`、`retry`、`idempotent` 与 `timeout`。

返回值 bytes

fetch_sync

仅 Python

不带重试的阻塞式签名请求，适用于基于线程的宿主（例如本地 HTTP 处理程序）。

def fetch_sync(method: str, path: str, *, body: bytes | None = None, headers: Mapping[str, str] | None = None, timeout: float = 60.0) -> httpx.Response

Python · 参数

参数	类型	必填	默认值	说明
`method`	`str`	是		HTTP 方法。
`path`	`str`	是		请求路径。
`body`	`bytes \| None`	否	`None`	调用的请求体，为与 JSON 兼容的数据。
`headers`	`Mapping[str, str] \| None`	否	`None`	额外的请求头。
`timeout`	`float`	否	`60.0`	超时时间，单位秒。

返回值 httpx.Response

GatewayA2a

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.gateway

通过网关进行的智能体间（A2A）调用。

class GatewayA2a
new GatewayA2a(readonly gw: AgentGatewayClient)

TypeScript · 构造

参数	类型	必填	默认值	说明
`gw`	AgentGatewayClient	是		发送请求的网关客户端。

Python · 构造

参数	类型	必填	默认值	说明
`gw`	AgentGatewayClient	是		发送请求的网关客户端。

discover

搜索可被调用的智能体。limit 默认 50。

async discover(input: { query?: string; limit?: number }, init?: GatewayRequestInit): Promise<Record<string, unknown>>

TypeScript · 参数

参数	类型	必填	默认值	说明
`input`	`{ query?: string; limit?: number }`	是		要搜索的 `query` 文本，以及结果数量上限 `limit`。
`init`	GatewayRequestInit	否		单次调用选项：`fetch` 选项外加 `retry` 与 `idempotent`。

返回值 Promise<Record<string, unknown>>

Python · 参数

参数	类型	必填	默认值	说明
`query`	`str \| None`	否	`None`	要搜索的文本；`None` 表示不过滤。
`limit`	`int`	否	`50`	结果数量上限，默认 50。

返回值 Any

rpc

向对端智能体发送 JSON-RPC 请求。遇到 HTTP 或 RPC 错误时不会抛出，请检查结果中的 ok、status 与 body。

async rpc(agentId: string, method: string, params: Record<string, unknown>, init?: GatewayRequestInit & { requestId?: string }): Promise<GatewayA2aRpcResult>

TypeScript · 参数

参数	类型	必填	说明
`agentId`	`string`	是	对端智能体的标识。
`method`	`string`	是	HTTP 方法。
`params`	`Record<string, unknown>`	是	JSON-RPC 调用的参数。
`init`	GatewayRequestInit & { requestId?: string }	否	单次调用选项，外加可选的 `requestId` 作为 JSON-RPC 的 id。

返回值 Promise<GatewayA2aRpcResult>

Python · 参数

参数	类型	必填	默认值	说明
`agent_id`	`str`	是		对端智能体的标识。
`method`	`str`	是		HTTP 方法。
`params`	`Mapping[str, Any]`	是		JSON-RPC 调用的参数。
`request_id`	`str \| None`	否	`None`	JSON-RPC `id` 的值；省略时自动生成。

返回值 dict[str, Any]

completeTask / complete_task

上报一个智能体间任务的结果。

async completeTask(taskId: string, input: { result: string; error: string }, init?: GatewayRequestInit): Promise<void>

TypeScript · 参数

参数	类型	必填	说明
`taskId`	`string`	是	任务的标识。
`input`	`{ result: string; error: string }`	是	任务的 `result` 文本与 `error` 文本。
`init`	GatewayRequestInit	否	单次调用选项：`fetch` 选项外加 `retry` 与 `idempotent`。

返回值 Promise<void>

Python · 参数

参数	类型	必填	说明
`task_id`	`str`	是	任务的标识。
`result`	`str`	是	任务的结果文本。
`error`	`str`	是	任务的错误文本；成功时为空。

返回值 None

GatewayAgents

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.gateway

通过网关进行的智能体调用。

class GatewayAgents
new GatewayAgents(readonly gw: AgentGatewayClient)

TypeScript · 构造

参数	类型	必填	默认值	说明
`gw`	AgentGatewayClient	是		发送请求的网关客户端。

Python · 构造

参数	类型	必填	默认值	说明
`gw`	AgentGatewayClient	是		发送请求的网关客户端。

sync

把智能体投影发送给 Cloud。请求体由你提供精确的 JSON，因为它会被签名。

async sync<T = Record<string, unknown>>(body: string | object, init?: GatewayRequestInit): Promise<T>

TypeScript · 参数

参数	类型	必填	默认值	说明
`body`	`string \| object`	是		调用的请求体，为与 JSON 兼容的数据。
`init`	GatewayRequestInit	否		单次调用选项：`fetch` 选项外加 `retry` 与 `idempotent`。

返回值 Promise<T>

Python · 参数

参数	类型	必填	默认值	说明
`body`	`Mapping[str, Any] \| str`	是		调用的请求体，为与 JSON 兼容的数据。

返回值 Any

reportTemplateOrigin / report_template_origin

在 agent.applyTemplate 已被持久应用后，上报智能体所基于的模板。

async reportTemplateOrigin(platformAgentId: string, templateId: string, init?: GatewayRequestInit): Promise<void>

TypeScript · 参数

参数	类型	必填	说明
`platformAgentId`	`string`	是	由该模板创建的智能体的标识。
`templateId`	`string`	是	模板的标识。
`init`	GatewayRequestInit	否	单次调用选项：`fetch` 选项外加 `retry` 与 `idempotent`。

返回值 Promise<void>

Python · 参数

参数	类型	必填	默认值	说明
`platform_agent_id`	`str`	是		由该模板创建的智能体的标识。
`template_id`	`str`	是		模板的标识。

返回值 None

GatewayAutomations

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.gateway

通过网关进行的自动化任务调用。应答按网关返回的原样给出；如有 data 外层请自行解包。

class GatewayAutomations
new GatewayAutomations(readonly gw: AgentGatewayClient)

TypeScript · 构造

参数	类型	必填	默认值	说明
`gw`	AgentGatewayClient	是		发送请求的网关客户端。

Python · 构造

参数	类型	必填	默认值	说明
`gw`	AgentGatewayClient	是		发送请求的网关客户端。

list

列出自动化任务。

async list<T = unknown>(query?: Record<string, string | number | undefined>, init?: GatewayRequestInit): Promise<T>

TypeScript · 参数

参数	类型	必填	默认值	说明
`query`	`Record<string, string \| number \| undefined>`	否		查询参数；值为 undefined 或空的条目会被省略。
`init`	GatewayRequestInit	否		单次调用选项：`fetch` 选项外加 `retry` 与 `idempotent`。

返回值 Promise<T>

Python · 参数

参数	类型	必填	默认值	说明
`query`	`Mapping[str, Any] \| None`	否	`None`	查询参数；值为 undefined 或空的条目会被省略。

返回值 Any

create

创建自动化任务。

async create<T = unknown>(body: Record<string, unknown>, init?: GatewayRequestInit): Promise<T>

TypeScript · 参数

参数	类型	必填	默认值	说明
`body`	`Record<string, unknown>`	是		调用的请求体，为与 JSON 兼容的数据。
`init`	GatewayRequestInit	否		单次调用选项：`fetch` 选项外加 `retry` 与 `idempotent`。

返回值 Promise<T>

Python · 参数

参数	类型	必填	默认值	说明
`body`	`Mapping[str, Any]`	是		调用的请求体，为与 JSON 兼容的数据。

返回值 Any

createWebhook / create_webhook

为自动化任务创建 webhook。

async createWebhook<T = unknown>(body: Record<string, unknown>, init?: GatewayRequestInit): Promise<T>

TypeScript · 参数

参数	类型	必填	默认值	说明
`body`	`Record<string, unknown>`	是		调用的请求体，为与 JSON 兼容的数据。
`init`	GatewayRequestInit	否		单次调用选项：`fetch` 选项外加 `retry` 与 `idempotent`。

返回值 Promise<T>

Python · 参数

参数	类型	必填	默认值	说明
`body`	`Mapping[str, Any]`	是		调用的请求体，为与 JSON 兼容的数据。

返回值 Any

get

读取一个自动化任务。

async get<T = unknown>(automationId: string, init?: GatewayRequestInit): Promise<T>

TypeScript · 参数

参数	类型	必填	默认值	说明
`automationId`	`string`	是		自动化任务的标识。
`init`	GatewayRequestInit	否		单次调用选项：`fetch` 选项外加 `retry` 与 `idempotent`。

返回值 Promise<T>

Python · 参数

参数	类型	必填	默认值	说明
`automation_id`	`str`	是		自动化任务的标识。

返回值 Any

run

启动一次自动化任务的运行。幂等键使重复调用得到同一次运行。

async run<T = unknown>(automationId: string, body: Record<string, unknown>, idempotencyKey: string, init?: GatewayRequestInit): Promise<T>

TypeScript · 参数

参数	类型	必填	说明
`automationId`	`string`	是	自动化任务的标识。
`body`	`Record<string, unknown>`	是	调用的请求体，为与 JSON 兼容的数据。
`idempotencyKey`	`string`	是	幂等键，作为 `Idempotency-Key` 发送。
`init`	GatewayRequestInit	否	单次调用选项：`fetch` 选项外加 `retry` 与 `idempotent`。

返回值 Promise<T>

Python · 参数

参数	类型	必填	说明
`automation_id`	`str`	是	自动化任务的标识。
`body`	`Mapping[str, Any]`	是	调用的请求体，为与 JSON 兼容的数据。
`idempotency_key`	`str`	是	幂等键，作为 `Idempotency-Key` 发送。

返回值 Any

runs

列出某个自动化任务的运行记录。

async runs<T = unknown>(automationId: string, query?: Record<string, string | number | undefined>, init?: GatewayRequestInit): Promise<T>

TypeScript · 参数

参数	类型	必填	说明
`automationId`	`string`	是	自动化任务的标识。
`query`	`Record<string, string \| number \| undefined>`	否	查询参数；值为 undefined 或空的条目会被省略。
`init`	GatewayRequestInit	否	单次调用选项：`fetch` 选项外加 `retry` 与 `idempotent`。

返回值 Promise<T>

Python · 参数

参数	类型	必填	默认值	说明
`automation_id`	`str`	是		自动化任务的标识。
`query`	`Mapping[str, Any] \| None`	否	`None`	查询参数；值为 undefined 或空的条目会被省略。

返回值 Any

runDetail / run_detail

读取某个自动化任务的一次运行。

async runDetail<T = unknown>(automationId: string, runId: string, init?: GatewayRequestInit): Promise<T>

TypeScript · 参数

参数	类型	必填	说明
`automationId`	`string`	是	自动化任务的标识。
`runId`	`string`	是	运行的标识。
`init`	GatewayRequestInit	否	单次调用选项：`fetch` 选项外加 `retry` 与 `idempotent`。

返回值 Promise<T>

Python · 参数

参数	类型	必填	默认值	说明
`automation_id`	`str`	是		自动化任务的标识。
`run_id`	`str`	是		运行的标识。

返回值 Any

GatewayBridge

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.gateway

通过网关进行的桥接调用。

class GatewayBridge
new GatewayBridge(readonly gw: AgentGatewayClient)

TypeScript · 构造

参数	类型	必填	默认值	说明
`gw`	AgentGatewayClient	是		发送请求的网关客户端。

Python · 构造

参数	类型	必填	默认值	说明
`gw`	AgentGatewayClient	是		发送请求的网关客户端。

config

读取桥接配置。网关无法访问时返回 undefined（Python 中为 None），以便你回退到缓存值。

async config(region?: string, init?: GatewayRequestInit): Promise<GatewayBridgeConfig | undefined>

TypeScript · 参数

参数	类型	必填	默认值	说明
`region`	`string`	否		要查询的区域；省略则使用默认值。
`init`	GatewayRequestInit	否		单次调用选项：`fetch` 选项外加 `retry` 与 `idempotent`。

返回值 Promise<GatewayBridgeConfig | undefined>

Python · 参数

参数	类型	必填	默认值	说明
`region`	`str \| None`	否	`None`	要查询的区域；省略则使用默认值。

返回值 dict[str, str] \| None

GatewayCanvas

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.gateway

通过网关进行的画布调用。

class GatewayCanvas
new GatewayCanvas(readonly gw: AgentGatewayClient)

TypeScript · 构造

参数	类型	必填	默认值	说明
`gw`	AgentGatewayClient	是		发送请求的网关客户端。

Python · 构造

参数	类型	必填	默认值	说明
`gw`	AgentGatewayClient	是		发送请求的网关客户端。

token

创建画布连接令牌，并连同中继 URL 与过期时间返回。令牌不绑定到某个智能体，关联信息随每条画布消息传递。

async token(init?: GatewayRequestInit): Promise<GatewayCanvasToken>

TypeScript · 参数

参数	类型	必填	默认值	说明
`init`	GatewayRequestInit	否		单次调用选项：`fetch` 选项外加 `retry` 与 `idempotent`。

返回值 Promise<GatewayCanvasToken>

Python · 参数

无参数。

返回值 dict[str, Any]

relayHeaders / relay_headers

为在令牌所附中继 origin 上执行的 GET /ws/agent WebSocket 升级构造带签名的请求头。

relayHeaders(path = "/ws/agent"): Record<string, string>

TypeScript · 参数

参数	类型	必填	默认值	说明
`path`	`string`	否	`"/ws/agent"`	请求路径。

返回值 Record<string, string>

Python · 参数

参数	类型	必填	默认值	说明
`path`	`str`	否	`'/ws/agent'`	请求路径。

返回值 dict[str, str]

GatewayChannels

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.gateway

通过网关进行的频道调用。

class GatewayChannels
new GatewayChannels(readonly gw: AgentGatewayClient)

TypeScript · 构造

参数	类型	必填	默认值	说明
`gw`	AgentGatewayClient	是		发送请求的网关客户端。

Python · 构造

参数	类型	必填	默认值	说明
`gw`	AgentGatewayClient	是		发送请求的网关客户端。

create

创建频道并返回其 ID。

async create(input: { participants: string[]; metadata: Record<string, string> }, init?: GatewayRequestInit): Promise<{ id?: string }>

TypeScript · 参数

参数	类型	必填	默认值	说明
`input`	`{ participants: string[]; metadata: Record<string, string> }`	是		频道的 `participants`（参与者标识）与 `metadata`（字符串键值对）。
`init`	GatewayRequestInit	否		单次调用选项：`fetch` 选项外加 `retry` 与 `idempotent`。

返回值 Promise<{ id?: string }>

Python · 参数

参数	类型	必填	默认值	说明
`participants`	`list[str]`	是		参与者的标识列表。
`metadata`	`Mapping[str, str]`	是		频道的元数据，字符串键值对。

返回值 dict[str, Any]

GatewayConnectors

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.gateway

通过网关进行的连接器调用。

class GatewayConnectors
new GatewayConnectors(readonly gw: AgentGatewayClient)

TypeScript · 构造

参数	类型	必填	默认值	说明
`gw`	AgentGatewayClient	是		发送请求的网关客户端。

Python · 构造

参数	类型	必填	默认值	说明
`gw`	AgentGatewayClient	是		发送请求的网关客户端。

mcp

把带签名的请求透传到连接器的 MCP 端点。流式响应体不会被读取，原样返回。

async mcp(init: GatewayRequestInit): Promise<Response>

TypeScript · 参数

参数	类型	必填	默认值	说明
`init`	GatewayRequestInit	是		请求选项：方法、请求头与请求体；除非你设置，否则不会重试。

返回值 Promise<Response>

Python · 参数

参数	类型	必填	默认值	说明
`body`	`bytes`	是		调用的请求体，为与 JSON 兼容的数据。
`headers`	`Mapping[str, str] \| None`	否	`None`	额外的请求头。

返回值 httpx.Response

callJson / call_json

发送一次 JSON-RPC 请求（例如 tools/call）并返回 JSON 应答。非 2xx 应答会抛出 CloudHttpError。

async callJson<T = unknown>(rpc: Record<string, unknown>, init?: GatewayRequestInit): Promise<T>

TypeScript · 参数

参数	类型	必填	默认值	说明
`rpc`	`Record<string, unknown>`	是		JSON-RPC 请求，例如 `tools/call`。
`init`	GatewayRequestInit	否		单次调用选项：`fetch` 选项外加 `retry` 与 `idempotent`。

返回值 Promise<T>

Python · 参数

参数	类型	必填	默认值	说明
`rpc`	`Mapping[str, Any]`	是		JSON-RPC 请求，例如 `tools/call`。

返回值 Any

mcp_sync

仅 Python

mcp 的阻塞版本，适用于基于线程的宿主。不会重试。

def mcp_sync(body: bytes, headers: Mapping[str, str] | None = None, timeout: float = 60.0) -> httpx.Response

Python · 参数

参数	类型	必填	默认值	说明
`body`	`bytes`	是		调用的请求体，为与 JSON 兼容的数据。
`headers`	`Mapping[str, str] \| None`	否	`None`	额外的请求头。
`timeout`	`float`	否	`60.0`	超时时间，单位秒。

返回值 httpx.Response

GatewayEvents

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.gateway

通过网关进行的事件调用。

class GatewayEvents
new GatewayEvents(readonly gw: AgentGatewayClient)

TypeScript · 构造

参数	类型	必填	默认值	说明
`gw`	AgentGatewayClient	是		发送请求的网关客户端。

Python · 构造

参数	类型	必填	默认值	说明
`gw`	AgentGatewayClient	是		发送请求的网关客户端。

publish

发布一个智能体事件。

async publish(event: { type: string; data: unknown }, init?: GatewayRequestInit): Promise<void>

TypeScript · 参数

参数	类型	必填	默认值	说明
`event`	`{ type: string; data: unknown }`	是		事件：其 `type` 与 `data`。
`init`	GatewayRequestInit	否		单次调用选项：`fetch` 选项外加 `retry` 与 `idempotent`。

返回值 Promise<void>

Python · 参数

参数	类型	必填	默认值	说明
`event_type`	`str`	是		事件类型。
`data`	`Any`	是		事件数据。

返回值 None

GatewayFiles

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.gateway

通过网关进行的文件调用。

class GatewayFiles
new GatewayFiles(readonly gw: AgentGatewayClient)

TypeScript · 构造

参数	类型	必填	默认值	说明
`gw`	AgentGatewayClient	是		发送请求的网关客户端。

Python · 构造

参数	类型	必填	默认值	说明
`gw`	AgentGatewayClient	是		发送请求的网关客户端。

list

列出智能体的文件。

async list(init?: GatewayRequestInit): Promise<{ files?: GatewayFileRef[] }>

TypeScript · 参数

参数	类型	必填	默认值	说明
`init`	GatewayRequestInit	否		单次调用选项：`fetch` 选项外加 `retry` 与 `idempotent`。

返回值 Promise<{ files?: GatewayFileRef[] }>

Python · 参数

无参数。

返回值 dict[str, Any]

presign

为新文件申请上传 URL，并连同文件 ID 一起返回。

async presign(input: { fileName: string; mimeType: string }, init?: GatewayRequestInit): Promise<GatewayPresign>

TypeScript · 参数

参数	类型	必填	默认值	说明
`input`	`{ fileName: string; mimeType: string }`	是		文件的 `fileName` 与 `mimeType`。
`init`	GatewayRequestInit	否		单次调用选项：`fetch` 选项外加 `retry` 与 `idempotent`。

返回值 Promise<GatewayPresign>

Python · 参数

参数	类型	必填	默认值	说明
`file_name`	`str`	是		文件名。
`mime_type`	`str`	是		文件的 MIME 类型。

返回值 dict[str, Any]

confirm

确认文件已上传，并返回其引用。

async confirm(input: { fileId: string }, init?: GatewayRequestInit): Promise<GatewayFileRef>

TypeScript · 参数

参数	类型	必填	默认值	说明
`input`	`{ fileId: string }`	是		已上传文件的 `fileId`。
`init`	GatewayRequestInit	否		单次调用选项：`fetch` 选项外加 `retry` 与 `idempotent`。

返回值 Promise<GatewayFileRef>

Python · 参数

参数	类型	必填	默认值	说明
`file_id`	`str`	是		文件的标识。

返回值 dict[str, Any]

resolve

把文件 ID 解析为详情，包含下载 URL。

async resolve(fileId: string, init?: GatewayRequestInit): Promise<GatewayFileResolve>

TypeScript · 参数

参数	类型	必填	默认值	说明
`fileId`	`string`	是		文件的标识。
`init`	GatewayRequestInit	否		单次调用选项：`fetch` 选项外加 `retry` 与 `idempotent`。

返回值 Promise<GatewayFileResolve>

Python · 参数

参数	类型	必填	默认值	说明
`file_id`	`str`	是		文件的标识。

返回值 dict[str, Any]

upload

一次调用完成文件上传：预签名、PUT 字节、确认。调用方提供的同一个 signal 覆盖这三步。

async upload(input: { fileName: string; mimeType: string; data: Uint8Array; signal?: AbortSignal }, fetchImpl: typeof fetch = fetch): Promise<GatewayUploadedFile>

TypeScript · 参数

参数	类型	必填	默认值	说明
`input`	`{ fileName: string; mimeType: string; data: Uint8Array; signal?: AbortSignal }`	是		`fileName`、`mimeType`、`data` 字节，以及覆盖整个上传过程的可选 `signal`。
`fetchImpl`	`typeof fetch`	否	`fetch`	用于替换全局 `fetch` 来执行上传 `PUT` 的函数。

返回值 Promise<GatewayUploadedFile>

Python · 参数

参数	类型	必填	说明
`file_name`	`str`	是	文件名。
`mime_type`	`str`	是	文件的 MIME 类型。
`data`	`bytes`	是	文件内容。

返回值 dict[str, Any]

download

下载 resolve 返回的预签名 URL 的内容。不会附加网关签名。

async download(downloadUrl: string, signal?: AbortSignal, fetchImpl: typeof fetch = fetch): Promise<Uint8Array>

TypeScript · 参数

参数	类型	必填	默认值	说明
`downloadUrl`	`string`	是		`resolve` 返回的下载 URL。
`signal`	`AbortSignal`	否		中止该信号会取消这次调用。
`fetchImpl`	`typeof fetch`	否	`fetch`	用于替换全局 `fetch` 来执行下载的函数。

返回值 Promise<Uint8Array>

Python · 参数

参数	类型	必填	默认值	说明
`download_url`	`str`	是		`resolve` 返回的下载 URL。

返回值 bytes

GatewayRuntime

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.gateway

通过网关进行的运行时调用。register 与 heartbeat（Python 中为 register_runtime 与 heartbeat_runtime）可用作注册传输。

class GatewayRuntime
new GatewayRuntime(readonly gw: AgentGatewayClient)

TypeScript · 构造

参数	类型	必填	默认值	说明
`gw`	AgentGatewayClient	是		发送请求的网关客户端。

Python · 构造

参数	类型	必填	默认值	说明
`gw`	AgentGatewayClient	是		发送请求的网关客户端。

register

仅 TypeScript

发送注册请求并返回解码后的应答。这里不会重试，重试由协调器负责。

async register<T = unknown>(body: unknown, init?: GatewayRequestInit): Promise<T>

TypeScript · 参数

参数	类型	必填	默认值	说明
`body`	`unknown`	是		调用的请求体，为与 JSON 兼容的数据。
`init`	GatewayRequestInit	否		单次调用选项：`fetch` 选项外加 `retry` 与 `idempotent`。默认不重试。

返回值 Promise<T>

heartbeat

仅 TypeScript

为某个注册发送心跳。这里不会重试，重试由协调器负责。

async heartbeat<T = unknown>(registrationId: string, body: unknown, init?: GatewayRequestInit): Promise<T>

TypeScript · 参数

参数	类型	必填	说明
`registrationId`	`string`	是	注册的标识。
`body`	`unknown`	是	调用的请求体，为与 JSON 兼容的数据。
`init`	GatewayRequestInit	否	单次调用选项：`fetch` 选项外加 `retry` 与 `idempotent`。默认不重试。

返回值 Promise<T>

redeemResource / redeem_resource

兑换某个操作的资源，并返回原始 Response，以便你自行校验摘要和映射失败。

async redeemResource(operationId: string, kind: "skill" | "mcp", resourceRef: string, body: unknown, init?: GatewayRequestInit): Promise<Response>

TypeScript · 参数

参数	类型	必填	说明
`operationId`	`string`	是	操作的标识。
`kind`	`"skill" \| "mcp"`	是	资源类型：`skill` 或 `mcp`。
`resourceRef`	`string`	是	要兑换的资源的引用。
`body`	`unknown`	是	调用的请求体，为与 JSON 兼容的数据。
`init`	GatewayRequestInit	否	单次调用选项：`fetch` 选项外加 `retry` 与 `idempotent`。默认不重试。

返回值 Promise<Response>

Python · 参数

参数	类型	必填	默认值	说明
`operation_id`	`str`	是		操作的标识。
`kind`	`str`	是		资源类型：`skill` 或 `mcp`。
`resource_ref`	`str`	是		要兑换的资源的引用。
`body`	`Mapping[str, Any]`	是		调用的请求体，为与 JSON 兼容的数据。
`timeout`	`float`	否	`120.0`	超时时间，单位秒。

返回值 httpx.Response

register_runtime

仅 Python

发送注册请求并返回解码后的 JSON 应答。

async def register_runtime(body: Mapping[str, Any]) -> Any

Python · 参数

参数	类型	必填	默认值	说明
`body`	`Mapping[str, Any]`	是		调用的请求体，为与 JSON 兼容的数据。

返回值 Any

heartbeat_runtime

仅 Python

为某个注册发送心跳并返回解码后的 JSON 应答。

async def heartbeat_runtime(registration_id: str, body: Mapping[str, Any]) -> Any

Python · 参数

参数	类型	必填	默认值	说明
`registration_id`	`str`	是		注册的标识。
`body`	`Mapping[str, Any]`	是		调用的请求体，为与 JSON 兼容的数据。

返回值 Any

BeeOS Cloud返回文档首页