BEEOS CLOUD / DEVELOPER REFERENCE

Agent Gateway client

Signed requests to Agent Gateway: files, canvas tokens, agents, channels, A2A, events, connectors and automations.

AgentGatewayClient signs every request with the harness key, re-signs on each retry, and retries only calls that are safe to replay. Resources hang off the client as namespaces such as files and a2a.

AgentGatewayClient

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

Client for Agent Gateway. It signs every request with the harness identity, only talks to one origin, retries transient failures of idempotent calls, and groups the routes into resources (files, canvas, agents, channels, a2a, events, bridge, connectors, automations, runtime).

class AgentGatewayClient
new AgentGatewayClient(readonly options: AgentGatewayClientOptions)

TypeScript · Constructor

Parameter	Type	Required	Default	Description
`options`	AgentGatewayClientOptions	yes		`baseUrl` of Agent Gateway, the signing `identity`, an optional default `retry` policy (`false` disables retries; default `TRANSIENT_BACKOFF`) and an optional `onRetry` callback.

Python · Constructor

Parameter	Type	Required	Default	Description
`base_url`	`str`	yes		Base URL of Agent Gateway. It must be `http` or `https` without user information.
`keys`	AgentKeyPair	yes		The harness key pair that signs the request.
`client`	`httpx.AsyncClient \| None`	no	`None`	Optional `httpx.AsyncClient` to send requests with; a temporary client is used when omitted.
`timeout`	`float`	no	`30.0`	Timeout in seconds.
`retry`	BackoffPolicy \| None	no	`TRANSIENT_BACKOFF`	Default retry policy for idempotent calls; `None` disables retries.
`on_retry`	`Callable[[str, str, int, int, BaseException], None] \| None`	no	`None`	Called before every retry wait with the method, path, attempt number, delay in milliseconds and error.

Properties

Name	Type	Description
`readonly baseUrl`	`URL`	The gateway origin that requests are sent to.
`readonly files`	GatewayFiles	File calls: list, presign, confirm, resolve, upload and download.
`readonly canvas`	GatewayCanvas	Canvas calls: create a canvas token and build the relay headers.
`readonly agents`	GatewayAgents	Agent calls: synchronise the agent projection and report its template origin.
`readonly channels`	GatewayChannels	Channel calls: create a channel.
`readonly a2a`	GatewayA2a	Agent-to-agent calls: discover agents, send JSON-RPC requests and complete tasks.
`readonly events`	GatewayEvents	Event calls: publish an agent event.
`readonly bridge`	GatewayBridge	Bridge calls: read the bridge configuration.
`readonly connectors`	GatewayConnectors	Connector calls: pass requests through to the connector MCP endpoint.
`readonly automations`	GatewayAutomations	Automation calls: list, create, get and run automations and read their runs.
`readonly runtime`	GatewayRuntime	Runtime calls: register, heartbeat and redeem operation resources.

fetch

Sends a signed request. Network errors and the statuses 408, 425, 429, 500, 502, 503 and 504 are retried for GET and HEAD calls, for calls marked idempotent, and when a retry policy is given for the call. When retries are used up, the last answer is returned.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`target`	`string \| URL`	yes		Path starting with `/`, or an absolute URL on the gateway origin.
`init`	GatewayRequestInit	no	`{}`	Standard `fetch` options (a body must be a string or `Uint8Array`) plus `retry` and `idempotent`.

Returns Promise<Response>

Python · Parameters

Parameter	Type	Required	Default	Description
`method`	`str`	yes		HTTP method.
`path`	`str`	yes		Request path.
`body`	`Any`	no	`None`	Request body of the call, as JSON-compatible data.
`headers`	`Mapping[str, str] \| None`	no	`None`	Additional request headers.
`retry`	BackoffPolicy \| None \| object	no	`_UNSET`	Retry policy for this call. Leave it unset to use the client default; `None` disables retries; an explicit policy also allows retrying a non-GET call.
`idempotent`	`bool`	no	`False`	`True` allows retrying a non-GET call that the gateway deduplicates.
`timeout`	`float \| None`	no	`None`	Timeout in seconds.

Returns httpx.Response

json

Sends a signed JSON request and returns the decoded answer. Throws CloudHttpError for any non-2xx answer.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`method`	`string`	yes		HTTP method.
`path`	`string`	yes		Request path.
`body`	`unknown`	no		Request body of the call, as JSON-compatible data.
`init`	GatewayRequestInit	no	`{}`	Per-call options: `fetch` options plus `retry` and `idempotent`.

Returns Promise<T>

Python · Parameters

Parameter	Type	Required	Default	Description
`method`	`str`	yes		HTTP method.
`path`	`str`	yes		Request path.
`body`	`Any`	no	`None`	Request body of the call, as JSON-compatible data.
`**kwargs`	`Any`	yes		Same options as `fetch`: `headers`, `retry`, `idempotent` and `timeout`.

Returns Any

upgradeHeaders

TypeScript only

Builds the four X-Agent-* headers for a request that you send yourself, such as the canvas relay WebSocket upgrade.

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

TypeScript · Parameters

Parameter	Type	Required	Description
`method`	`string`	yes	HTTP method.
`path`	`string`	yes	Request path.
`body`	`string \| Uint8Array \| null`	no	Request body of the call, as JSON-compatible data.

Returns Record<string, string>

asFetch

TypeScript only

Returns a fetch-style function bound to this client, for components that only need a signed transport.

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

TypeScript · Parameters

No parameters.

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

aclose

Python only

Closes the underlying HTTP client.

async def aclose() -> None

Python · Parameters

No parameters.

Returns None

bytes

Python only

Sends a signed request and returns the answer as raw bytes.

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

Python · Parameters

Parameter	Type	Required	Default	Description
`method`	`str`	yes		HTTP method.
`path`	`str`	yes		Request path.
`body`	`Any`	no	`None`	Request body of the call, as JSON-compatible data.
`**kwargs`	`Any`	yes		Same options as `fetch`: `headers`, `retry`, `idempotent` and `timeout`.

Returns bytes

fetch_sync

Python only

Blocking signed request without retries, for thread-based hosts such as a local HTTP handler.

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

Python · Parameters

Parameter	Type	Required	Default	Description
`method`	`str`	yes		HTTP method.
`path`	`str`	yes		Request path.
`body`	`bytes \| None`	no	`None`	Request body of the call, as JSON-compatible data.
`headers`	`Mapping[str, str] \| None`	no	`None`	Additional request headers.
`timeout`	`float`	no	`60.0`	Timeout in seconds.

Returns httpx.Response

GatewayA2a

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

Agent-to-agent calls through the gateway.

class GatewayA2a
new GatewayA2a(readonly gw: AgentGatewayClient)

TypeScript · Constructor

Parameter	Type	Required	Default	Description
`gw`	AgentGatewayClient	yes		The gateway client that sends the requests.

Python · Constructor

Parameter	Type	Required	Default	Description
`gw`	AgentGatewayClient	yes		The gateway client that sends the requests.

discover

Searches for agents that can be called. limit defaults to 50.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`input`	`{ query?: string; limit?: number }`	yes		`query` text to search for and `limit`, the maximum number of results.
`init`	GatewayRequestInit	no		Per-call options: `fetch` options plus `retry` and `idempotent`.

Returns Promise<Record<string, unknown>>

Python · Parameters

Parameter	Type	Required	Default	Description
`query`	`str \| None`	no	`None`	Text to search for; `None` lists agents without a filter.
`limit`	`int`	no	`50`	Maximum number of results. Defaults to 50.

Returns Any

rpc

Sends a JSON-RPC request to a peer agent. It does not throw on an HTTP or RPC error: inspect ok, status and body of the result.

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

TypeScript · Parameters

Parameter	Type	Required	Description
`agentId`	`string`	yes	Identifier of the peer agent.
`method`	`string`	yes	HTTP method.
`params`	`Record<string, unknown>`	yes	Parameters of the JSON-RPC call.
`init`	GatewayRequestInit & { requestId?: string }	no	Per-call options plus an optional `requestId` for the JSON-RPC id.

Returns Promise<GatewayA2aRpcResult>

Python · Parameters

Parameter	Type	Required	Default	Description
`agent_id`	`str`	yes		Identifier of the peer agent.
`method`	`str`	yes		HTTP method.
`params`	`Mapping[str, Any]`	yes		Parameters of the JSON-RPC call.
`request_id`	`str \| None`	no	`None`	Value of the JSON-RPC `id`; generated when omitted.

Returns dict[str, Any]

completeTask / complete_task

Reports the outcome of an agent-to-agent task.

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

TypeScript · Parameters

Parameter	Type	Required	Description
`taskId`	`string`	yes	Identifier of the task.
`input`	`{ result: string; error: string }`	yes	`result` text and `error` text of the task.
`init`	GatewayRequestInit	no	Per-call options: `fetch` options plus `retry` and `idempotent`.

Returns Promise<void>

Python · Parameters

Parameter	Type	Required	Description
`task_id`	`str`	yes	Identifier of the task.
`result`	`str`	yes	Result text of the task.
`error`	`str`	yes	Error text of the task; empty when it succeeded.

Returns None

GatewayAgents

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

Agent calls through the gateway.

class GatewayAgents
new GatewayAgents(readonly gw: AgentGatewayClient)

TypeScript · Constructor

Parameter	Type	Required	Default	Description
`gw`	AgentGatewayClient	yes		The gateway client that sends the requests.

Python · Constructor

Parameter	Type	Required	Default	Description
`gw`	AgentGatewayClient	yes		The gateway client that sends the requests.

sync

Sends the agent projection to Cloud. You provide the exact JSON body, because that body is signed.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`body`	`string \| object`	yes		Request body of the call, as JSON-compatible data.
`init`	GatewayRequestInit	no		Per-call options: `fetch` options plus `retry` and `idempotent`.

Returns Promise<T>

Python · Parameters

Parameter	Type	Required	Default	Description
`body`	`Mapping[str, Any] \| str`	yes		Request body of the call, as JSON-compatible data.

Returns Any

reportTemplateOrigin / report_template_origin

Reports the template that an agent was created from, once agent.applyTemplate has been durably applied.

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

TypeScript · Parameters

Parameter	Type	Required	Description
`platformAgentId`	`string`	yes	Identifier of the agent that was created from the template.
`templateId`	`string`	yes	Identifier of the template.
`init`	GatewayRequestInit	no	Per-call options: `fetch` options plus `retry` and `idempotent`.

Returns Promise<void>

Python · Parameters

Parameter	Type	Required	Default	Description
`platform_agent_id`	`str`	yes		Identifier of the agent that was created from the template.
`template_id`	`str`	yes		Identifier of the template.

Returns None

GatewayAutomations

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

Automation calls through the gateway. Answers are returned as the gateway sent them; unwrap a data envelope yourself.

class GatewayAutomations
new GatewayAutomations(readonly gw: AgentGatewayClient)

TypeScript · Constructor

Parameter	Type	Required	Default	Description
`gw`	AgentGatewayClient	yes		The gateway client that sends the requests.

Python · Constructor

Parameter	Type	Required	Default	Description
`gw`	AgentGatewayClient	yes		The gateway client that sends the requests.

list

Lists automations.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`query`	`Record<string, string \| number \| undefined>`	no		Query parameters; entries that are undefined or empty are left out.
`init`	GatewayRequestInit	no		Per-call options: `fetch` options plus `retry` and `idempotent`.

Returns Promise<T>

Python · Parameters

Parameter	Type	Required	Default	Description
`query`	`Mapping[str, Any] \| None`	no	`None`	Query parameters; entries that are undefined or empty are left out.

Returns Any

create

Creates an automation.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`body`	`Record<string, unknown>`	yes		Request body of the call, as JSON-compatible data.
`init`	GatewayRequestInit	no		Per-call options: `fetch` options plus `retry` and `idempotent`.

Returns Promise<T>

Python · Parameters

Parameter	Type	Required	Default	Description
`body`	`Mapping[str, Any]`	yes		Request body of the call, as JSON-compatible data.

Returns Any

createWebhook / create_webhook

Creates a webhook for automations.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`body`	`Record<string, unknown>`	yes		Request body of the call, as JSON-compatible data.
`init`	GatewayRequestInit	no		Per-call options: `fetch` options plus `retry` and `idempotent`.

Returns Promise<T>

Python · Parameters

Parameter	Type	Required	Default	Description
`body`	`Mapping[str, Any]`	yes		Request body of the call, as JSON-compatible data.

Returns Any

get

Reads one automation.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`automationId`	`string`	yes		Identifier of the automation.
`init`	GatewayRequestInit	no		Per-call options: `fetch` options plus `retry` and `idempotent`.

Returns Promise<T>

Python · Parameters

Parameter	Type	Required	Default	Description
`automation_id`	`str`	yes		Identifier of the automation.

Returns Any

run

Starts a run of an automation. The idempotency key makes a repeated call return the same run.

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

TypeScript · Parameters

Parameter	Type	Required	Description
`automationId`	`string`	yes	Identifier of the automation.
`body`	`Record<string, unknown>`	yes	Request body of the call, as JSON-compatible data.
`idempotencyKey`	`string`	yes	Idempotency key, sent as `Idempotency-Key`.
`init`	GatewayRequestInit	no	Per-call options: `fetch` options plus `retry` and `idempotent`.

Returns Promise<T>

Python · Parameters

Parameter	Type	Required	Description
`automation_id`	`str`	yes	Identifier of the automation.
`body`	`Mapping[str, Any]`	yes	Request body of the call, as JSON-compatible data.
`idempotency_key`	`str`	yes	Idempotency key, sent as `Idempotency-Key`.

Returns Any

runs

Lists the runs of an automation.

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

TypeScript · Parameters

Parameter	Type	Required	Description
`automationId`	`string`	yes	Identifier of the automation.
`query`	`Record<string, string \| number \| undefined>`	no	Query parameters; entries that are undefined or empty are left out.
`init`	GatewayRequestInit	no	Per-call options: `fetch` options plus `retry` and `idempotent`.

Returns Promise<T>

Python · Parameters

Parameter	Type	Required	Default	Description
`automation_id`	`str`	yes		Identifier of the automation.
`query`	`Mapping[str, Any] \| None`	no	`None`	Query parameters; entries that are undefined or empty are left out.

Returns Any

runDetail / run_detail

Reads one run of an automation.

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

TypeScript · Parameters

Parameter	Type	Required	Description
`automationId`	`string`	yes	Identifier of the automation.
`runId`	`string`	yes	Identifier of the run.
`init`	GatewayRequestInit	no	Per-call options: `fetch` options plus `retry` and `idempotent`.

Returns Promise<T>

Python · Parameters

Parameter	Type	Required	Default	Description
`automation_id`	`str`	yes		Identifier of the automation.
`run_id`	`str`	yes		Identifier of the run.

Returns Any

GatewayBridge

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

Bridge calls through the gateway.

class GatewayBridge
new GatewayBridge(readonly gw: AgentGatewayClient)

TypeScript · Constructor

Parameter	Type	Required	Default	Description
`gw`	AgentGatewayClient	yes		The gateway client that sends the requests.

Python · Constructor

Parameter	Type	Required	Default	Description
`gw`	AgentGatewayClient	yes		The gateway client that sends the requests.

config

Reads the bridge configuration. Returns undefined (None in Python) when the gateway cannot be reached, so you can fall back to a cached value.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`region`	`string`	no		Region to ask for; omitted for the default.
`init`	GatewayRequestInit	no		Per-call options: `fetch` options plus `retry` and `idempotent`.

Returns Promise<GatewayBridgeConfig | undefined>

Python · Parameters

Parameter	Type	Required	Default	Description
`region`	`str \| None`	no	`None`	Region to ask for; omitted for the default.

Returns dict[str, str] \| None

GatewayCanvas

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

Canvas calls through the gateway.

class GatewayCanvas
new GatewayCanvas(readonly gw: AgentGatewayClient)

TypeScript · Constructor

Parameter	Type	Required	Default	Description
`gw`	AgentGatewayClient	yes		The gateway client that sends the requests.

Python · Constructor

Parameter	Type	Required	Default	Description
`gw`	AgentGatewayClient	yes		The gateway client that sends the requests.

token

Creates a canvas connection token and returns it with the relay URL and expiry. The token is not bound to one agent; the association travels with each canvas message.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`init`	GatewayRequestInit	no		Per-call options: `fetch` options plus `retry` and `idempotent`.

Returns Promise<GatewayCanvasToken>

Python · Parameters

No parameters.

Returns dict[str, Any]

relayHeaders / relay_headers

Builds the signed headers for the GET /ws/agent WebSocket upgrade on the relay origin returned with the token.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`path`	`string`	no	`"/ws/agent"`	Request path.

Returns Record<string, string>

Python · Parameters

Parameter	Type	Required	Default	Description
`path`	`str`	no	`'/ws/agent'`	Request path.

Returns dict[str, str]

GatewayChannels

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

Channel calls through the gateway.

class GatewayChannels
new GatewayChannels(readonly gw: AgentGatewayClient)

TypeScript · Constructor

Parameter	Type	Required	Default	Description
`gw`	AgentGatewayClient	yes		The gateway client that sends the requests.

Python · Constructor

Parameter	Type	Required	Default	Description
`gw`	AgentGatewayClient	yes		The gateway client that sends the requests.

create

Creates a channel and returns its id.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`input`	`{ participants: string[]; metadata: Record<string, string> }`	yes		`participants` (identifiers) and `metadata` (string pairs) of the channel.
`init`	GatewayRequestInit	no		Per-call options: `fetch` options plus `retry` and `idempotent`.

Returns Promise<{ id?: string }>

Python · Parameters

Parameter	Type	Required	Default	Description
`participants`	`list[str]`	yes		Identifiers of the participants.
`metadata`	`Mapping[str, str]`	yes		Metadata of the channel as string pairs.

Returns dict[str, Any]

GatewayConnectors

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

Connector calls through the gateway.

class GatewayConnectors
new GatewayConnectors(readonly gw: AgentGatewayClient)

TypeScript · Constructor

Parameter	Type	Required	Default	Description
`gw`	AgentGatewayClient	yes		The gateway client that sends the requests.

Python · Constructor

Parameter	Type	Required	Default	Description
`gw`	AgentGatewayClient	yes		The gateway client that sends the requests.

mcp

Passes a signed request through to the connector MCP endpoint. A streaming body is returned unread.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`init`	GatewayRequestInit	yes		Request options: method, headers and body; retries are off unless you set them.

Returns Promise<Response>

Python · Parameters

Parameter	Type	Required	Default	Description
`body`	`bytes`	yes		Request body of the call, as JSON-compatible data.
`headers`	`Mapping[str, str] \| None`	no	`None`	Additional request headers.

Returns httpx.Response

callJson / call_json

Sends one JSON-RPC request (for example tools/call) and returns the JSON answer. Throws CloudHttpError for a non-2xx answer.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`rpc`	`Record<string, unknown>`	yes		The JSON-RPC request, for example a `tools/call`.
`init`	GatewayRequestInit	no		Per-call options: `fetch` options plus `retry` and `idempotent`.

Returns Promise<T>

Python · Parameters

Parameter	Type	Required	Default	Description
`rpc`	`Mapping[str, Any]`	yes		The JSON-RPC request, for example a `tools/call`.

Returns Any

mcp_sync

Python only

Blocking variant of mcp for thread-based hosts. It is not retried.

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

Python · Parameters

Parameter	Type	Required	Default	Description
`body`	`bytes`	yes		Request body of the call, as JSON-compatible data.
`headers`	`Mapping[str, str] \| None`	no	`None`	Additional request headers.
`timeout`	`float`	no	`60.0`	Timeout in seconds.

Returns httpx.Response

GatewayEvents

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

Event calls through the gateway.

class GatewayEvents
new GatewayEvents(readonly gw: AgentGatewayClient)

TypeScript · Constructor

Parameter	Type	Required	Default	Description
`gw`	AgentGatewayClient	yes		The gateway client that sends the requests.

Python · Constructor

Parameter	Type	Required	Default	Description
`gw`	AgentGatewayClient	yes		The gateway client that sends the requests.

publish

Publishes an agent event.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`event`	`{ type: string; data: unknown }`	yes		The event: its `type` and `data`.
`init`	GatewayRequestInit	no		Per-call options: `fetch` options plus `retry` and `idempotent`.

Returns Promise<void>

Python · Parameters

Parameter	Type	Required	Default	Description
`event_type`	`str`	yes		Type of the event.
`data`	`Any`	yes		Data of the event.

Returns None

GatewayFiles

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

File calls through the gateway.

class GatewayFiles
new GatewayFiles(readonly gw: AgentGatewayClient)

TypeScript · Constructor

Parameter	Type	Required	Default	Description
`gw`	AgentGatewayClient	yes		The gateway client that sends the requests.

Python · Constructor

Parameter	Type	Required	Default	Description
`gw`	AgentGatewayClient	yes		The gateway client that sends the requests.

list

Lists the files of the agent.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`init`	GatewayRequestInit	no		Per-call options: `fetch` options plus `retry` and `idempotent`.

Returns Promise<{ files?: GatewayFileRef[] }>

Python · Parameters

No parameters.

Returns dict[str, Any]

presign

Requests an upload URL for a new file and returns it with the file id.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`input`	`{ fileName: string; mimeType: string }`	yes		`fileName` and `mimeType` of the file.
`init`	GatewayRequestInit	no		Per-call options: `fetch` options plus `retry` and `idempotent`.

Returns Promise<GatewayPresign>

Python · Parameters

Parameter	Type	Required	Default	Description
`file_name`	`str`	yes		Name of the file.
`mime_type`	`str`	yes		MIME type of the file.

Returns dict[str, Any]

confirm

Confirms that the file was uploaded and returns its reference.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`input`	`{ fileId: string }`	yes		`fileId` of the uploaded file.
`init`	GatewayRequestInit	no		Per-call options: `fetch` options plus `retry` and `idempotent`.

Returns Promise<GatewayFileRef>

Python · Parameters

Parameter	Type	Required	Default	Description
`file_id`	`str`	yes		Identifier of the file.

Returns dict[str, Any]

resolve

Resolves a file id into its details, including a download URL.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`fileId`	`string`	yes		Identifier of the file.
`init`	GatewayRequestInit	no		Per-call options: `fetch` options plus `retry` and `idempotent`.

Returns Promise<GatewayFileResolve>

Python · Parameters

Parameter	Type	Required	Default	Description
`file_id`	`str`	yes		Identifier of the file.

Returns dict[str, Any]

upload

Uploads a file in one call: presign, PUT the bytes, then confirm. A single caller-owned signal covers all three steps.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`input`	`{ fileName: string; mimeType: string; data: Uint8Array; signal?: AbortSignal }`	yes		`fileName`, `mimeType`, the `data` bytes and an optional `signal` that covers the whole upload.
`fetchImpl`	`typeof fetch`	no	`fetch`	Replacement for the global `fetch` that performs the upload `PUT`.

Returns Promise<GatewayUploadedFile>

Python · Parameters

Parameter	Type	Required	Description
`file_name`	`str`	yes	Name of the file.
`mime_type`	`str`	yes	MIME type of the file.
`data`	`bytes`	yes	Content of the file.

Returns dict[str, Any]

download

Downloads the bytes of a presigned URL returned by resolve. No gateway signature is attached.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`downloadUrl`	`string`	yes		Download URL that `resolve` returned.
`signal`	`AbortSignal`	no		Aborting this signal cancels the call.
`fetchImpl`	`typeof fetch`	no	`fetch`	Replacement for the global `fetch` that performs the download.

Returns Promise<Uint8Array>

Python · Parameters

Parameter	Type	Required	Default	Description
`download_url`	`str`	yes		Download URL that `resolve` returned.

Returns bytes

GatewayRuntime

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

Runtime calls through the gateway. register and heartbeat (in Python register_runtime and heartbeat_runtime) can serve as the registration transport.

class GatewayRuntime
new GatewayRuntime(readonly gw: AgentGatewayClient)

TypeScript · Constructor

Parameter	Type	Required	Default	Description
`gw`	AgentGatewayClient	yes		The gateway client that sends the requests.

Python · Constructor

Parameter	Type	Required	Default	Description
`gw`	AgentGatewayClient	yes		The gateway client that sends the requests.

register

TypeScript only

Sends the registration request and returns the decoded answer. It is never retried here; the coordinator owns retrying.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`body`	`unknown`	yes		Request body of the call, as JSON-compatible data.
`init`	GatewayRequestInit	no		Per-call options: `fetch` options plus `retry` and `idempotent`. Retries are off by default.

Returns Promise<T>

heartbeat

TypeScript only

Sends a heartbeat for a registration. It is never retried here; the coordinator owns retrying.

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

TypeScript · Parameters

Parameter	Type	Required	Description
`registrationId`	`string`	yes	Identifier of the registration.
`body`	`unknown`	yes	Request body of the call, as JSON-compatible data.
`init`	GatewayRequestInit	no	Per-call options: `fetch` options plus `retry` and `idempotent`. Retries are off by default.

Returns Promise<T>

redeemResource / redeem_resource

Redeems a resource of an operation and returns the raw Response, so you can verify digests and map failures yourself.

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

TypeScript · Parameters

Parameter	Type	Required	Description
`operationId`	`string`	yes	Identifier of the operation.
`kind`	`"skill" \| "mcp"`	yes	Kind of resource: `skill` or `mcp`.
`resourceRef`	`string`	yes	Reference of the resource that is redeemed.
`body`	`unknown`	yes	Request body of the call, as JSON-compatible data.
`init`	GatewayRequestInit	no	Per-call options: `fetch` options plus `retry` and `idempotent`. Retries are off by default.

Returns Promise<Response>

Python · Parameters

Parameter	Type	Required	Default	Description
`operation_id`	`str`	yes		Identifier of the operation.
`kind`	`str`	yes		Kind of resource: `skill` or `mcp`.
`resource_ref`	`str`	yes		Reference of the resource that is redeemed.
`body`	`Mapping[str, Any]`	yes		Request body of the call, as JSON-compatible data.
`timeout`	`float`	no	`120.0`	Timeout in seconds.

Returns httpx.Response

register_runtime

Python only

Sends the registration request and returns the decoded JSON answer.

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

Python · Parameters

Parameter	Type	Required	Default	Description
`body`	`Mapping[str, Any]`	yes		Request body of the call, as JSON-compatible data.

Returns Any

heartbeat_runtime

Python only

Sends a heartbeat for a registration and returns the decoded JSON answer.

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

Python · Parameters

Parameter	Type	Required	Default	Description
`registration_id`	`str`	yes		Identifier of the registration.
`body`	`Mapping[str, Any]`	yes		Request body of the call, as JSON-compatible data.

Returns Any

BeeOS CloudBack to documentation