BEEOS CLOUD / DEVELOPER REFERENCE

设备绑定

智能体绑定会话与 portal 绑定会话。

概览

device bindings domain 涵盖把智能体与用户连接起来的绑定会话：agent 绑定会话，以及由 portal 创建、读取、撤销和解析的 portal 绑定会话。

6 个操作 · SDK 资源：TypeScript cloud.deviceBindings · Python cloud.device_bindings · Go cloud.DeviceBindings · API 总览

主要对象

agentBindDetailsWire 与 agentBindWire：agent 绑定会话的详情与结果。
portalBindWire：portal 绑定会话。
Binding：最终产生的绑定。

agentBindDetailsWire

字段	类型	必填	说明
`bind_id`	`string`	是	绑定会话的 ID。
`hostname`	`string`	是	设备上报的主机名。
`fingerprint_short`	`string`	是	设备密钥指纹的前 16 个字符。展示给用户，与设备上的比对。
`harness`	`string`	是	设备所运行的 harness，与设备上报的一致。
`os_type`	`string`	否	设备上报的操作系统。未上报时省略。
`expires_at`	`integer`	是	会话过期的时间，Unix 秒。
`status`	`string`	是	绑定会话的状态。已过期的会话会被删除，因此对已过期会话的查询会失败，返回 404 `not_found`。可选值: `"pending"` — 由设备创建，等待用户确认; `"confirming"` — 用户已确认，正在为该设备创建实例; `"bound"` — 已确认：实例存在，设备可以连接它. (枚举表)
`server_time`	`integer`	是	当前服务器时间，Unix 秒。与 `expires_at` 比较，可以在没有时钟偏差的情况下得到剩余时间。

完整字段和使用该对象的方法见附录。

agentBindWire

字段	类型	必填	说明
`status`	`string`	是	绑定会话的状态。确认成功后为 `bound`；仍在等待确认的会话报告 `pending`。可选值: `"pending"` — 由设备创建，等待用户确认。正在确认的会话也报告 `pending`; `"bound"` — 已确认：实例存在，设备可以连接它. (枚举表)
`bind_id`	`string`	否	绑定会话的 ID。
`instance_id`	`string`	否	为设备创建的实例的 ID。会话绑定后出现。
`public_key`	`string`	否	设备为该会话注册的公钥。
`hostname`	`string`	否	设备上报的主机名。
`expires_at`	`integer`	否	会话过期的时间，Unix 秒。
`runtime_binding`	bindRuntimeWire	否	已绑定的自托管智能体所连接的地址。会话绑定后出现。可为 null。

完整字段和使用该对象的方法见附录。

portalBindWire

字段	类型	必填	说明
`provider_id`	`string`	否	承载该实例的提供方的 ID。为设备创建了新实例时设置。
`bind_id`	`string`	是	绑定会话的 ID。以 `portal_` 开头。
`short_code`	`string`	是	用户可以在设备上输入的短码，用于代替扫描二维码。使用大写字母和数字，不含易混淆的字符。
`status`	`string`	是	portal 绑定会话的状态。已过期的会话会被删除，因此对已过期会话的查询会失败，返回 404 `not_found`。取值见下表 portalBindWire.status 取值。
`instance_id`	`string`	否	绑定到设备的实例的 ID。会话绑定后出现。
`expires_at`	`integer`	是	会话过期的时间，Unix 秒。会话有效期为 10 分钟。
`name`	`string`	是	为设备创建的实例的显示名称。默认为 `BeeRunner`。
`qr_payload`	`string`	否	要编码进设备所扫描二维码的链接。仅在创建会话时返回。
`api_base_url`	`string`	否	设备所连接的 API 的基础 URL。仅在创建会话时返回。
`relay_url`	`string`	否	设备通过其连接的中继的 URL。仅在创建会话时返回。
`desired_status`	`string`	否	所创建实例被驱动到的生命周期阶段：`running`。为设备创建了新实例时设置。
`connectivity`	`string`	否	所创建实例的可达性：`unknown`、`online` 或 `offline`。为设备创建了新实例时设置。
`resource_version`	`integer`	否	所创建实例的资源版本。为设备创建了新实例时设置。

portalBindWire.status 取值

取值	含义
`"pending"`	已创建，等待设备扫描二维码或输入短码。
`"awaiting_confirmation"`	设备已认领该会话。请带 `decision` 调用 resolve 操作以继续。
`"confirming"`	决定 `create` 已被接受，正在为设备创建新实例。
`"bound"`	设备已绑定到一个实例，由 `instance_id` 给出。
`"revoked"`	已用撤销操作撤销。已撤销的会话不能再被认领或处理。

完整字段和使用该对象的方法见附录。

Binding

字段	类型	必填	说明
`client_type`	`string`	是	token 如何绑定到客户端。可选值: `"web"` — 绑定到网页来源，在 `origin` 中返回; `"native"` — 绑定到设备密钥，其指纹在 `cnf_jkt` 中返回. (枚举表) 按 `client_type` 区分的结构：见变体表。
`origin`	`string`	否	token 所绑定的来源。`client_type` 为 `web` 时返回。约束: `format=uri`.
`cnf_jkt`	`string`	否	token 所绑定的设备密钥的指纹。`client_type` 为 `native` 时返回。

完整字段和使用该对象的方法见附录。

典型流程

对 agent 绑定会话，先用 deviceBindings.getDetails 读取详情，再用 deviceBindings.confirm 确认。
对 portal，用 deviceBindings.createPortal 创建绑定会话，用 deviceBindings.getPortal 读取。
用 deviceBindings.resolvePortal（decision 为 recover 或 create）或 deviceBindings.revokePortal 结束。

方法

方法	HTTP	摘要
deviceBindings.confirm	`POST /v1/agent/bind/{id}/confirm`	确认一个 agent 绑定会话
deviceBindings.getDetails	`GET /v1/agent/bind/{id}/details`	获取 agent 绑定会话的详情
deviceBindings.createPortal	`POST /v1/agent/portal/bind-sessions`	创建 portal 绑定会话
deviceBindings.getPortal	`GET /v1/agent/portal/bind-sessions/{id}`	获取 portal 绑定会话
deviceBindings.resolvePortal	`POST /v1/agent/portal/bind-sessions/{id}/resolve`	解析 portal 绑定会话
deviceBindings.revokePortal	`POST /v1/agent/portal/bind-sessions/{id}/revoke`	撤销 portal 绑定会话

deviceBindings.confirm

POST /v1/agent/bind/{id}/confirm · Operation ID confirmAgentBind

确认一个 agent 绑定会话

SDK 方法

语言	方法	签名
TypeScript	`cloud.deviceBindings.confirm`	`confirm(id: string, input: Models.ConfirmAgentBindRequest): Promise<Models.ConfirmAgentBindResponse>`
Python	`cloud.device_bindings.confirm`	`def confirm(self, id: str, input: ConfirmAgentBindRequest) -> ConfirmAgentBindResponse`
Go	`cloud.DeviceBindings.Confirm`	`func (r *DeviceBindingsResource) Confirm(ctx context.Context, id string, input ConfirmAgentBindRequest) (ConfirmAgentBindResponse, error)`

参数

参数	位置	类型	必填	说明
`id`	path	`string`	是	要确认的智能体绑定会话的 ID，即设备创建它时返回的 `bind_id`。

请求体

application/json · 必填

字段	类型	必填	说明
`name`	`string`	否	为设备创建的实例的显示名称，最多 128 个字符。默认为设备上报的主机名。
`modelPrimary`	`string`	否	可以提交，但会被忽略。实例沿用服务器的默认模型。
`model_primary`	`string`	否	`modelPrimary` 的 snake-case 别名，同样会被忽略。如果两者都发送，必须相等。

响应

200 · application/json

字段	类型	必填	说明
`success`	`boolean`	是	—
`data`	agentBindWire	是	—

错误

状态码	Schema	说明
其他（default）	DeviceBindingErrorResponse	Cloud Server 错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.deviceBindings.confirm("id_123", {});
console.log(result);

deviceBindings.getDetails

GET /v1/agent/bind/{id}/details · Operation ID getAgentBindDetails

获取 agent 绑定会话的详情

SDK 方法

语言	方法	签名
TypeScript	`cloud.deviceBindings.getDetails`	`getDetails(id: string): Promise<Models.GetAgentBindDetailsResponse>`
Python	`cloud.device_bindings.get_details`	`def get_details(self, id: str) -> GetAgentBindDetailsResponse`
Go	`cloud.DeviceBindings.GetDetails`	`func (r *DeviceBindingsResource) GetDetails(ctx context.Context, id string) (GetAgentBindDetailsResponse, error)`

参数

参数	位置	类型	必填	说明
`id`	path	`string`	是	智能体绑定会话的 ID，即设备创建它时返回的 `bind_id`。

响应

200 · application/json

字段	类型	必填	说明
`success`	`boolean`	是	—
`data`	agentBindDetailsWire	是	—

错误

状态码	Schema	说明
其他（default）	DeviceBindingErrorResponse	Cloud Server 错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.deviceBindings.getDetails("id_123");
console.log(result);

deviceBindings.createPortal

POST /v1/agent/portal/bind-sessions · Operation ID createPortalBind

创建 portal 绑定会话

SDK 方法

语言	方法	签名
TypeScript	`cloud.deviceBindings.createPortal`	`createPortal(input: Models.CreatePortalBindRequest): Promise<Models.CreatePortalBindResponse>`
Python	`cloud.device_bindings.create_portal`	`def create_portal(self, input: CreatePortalBindRequest) -> CreatePortalBindResponse`
Go	`cloud.DeviceBindings.CreatePortal`	`func (r *DeviceBindingsResource) CreatePortal(ctx context.Context, input CreatePortalBindRequest) (CreatePortalBindResponse, error)`

请求体

application/json · 必填

字段	类型	必填	说明
`name`	`string`	否	为设备创建的实例的显示名称，最多 128 个字符。默认为 `BeeRunner`。

响应

200 · application/json

字段	类型	必填	说明
`success`	`boolean`	是	—
`data`	portalBindWire	是	—

错误

状态码	Schema	说明
其他（default）	DeviceBindingErrorResponse	Cloud Server 错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.deviceBindings.createPortal({});
console.log(result);

deviceBindings.getPortal

GET /v1/agent/portal/bind-sessions/{id} · Operation ID getPortalBind

获取 portal 绑定会话

SDK 方法

语言	方法	签名
TypeScript	`cloud.deviceBindings.getPortal`	`getPortal(id: string): Promise<Models.GetPortalBindResponse>`
Python	`cloud.device_bindings.get_portal`	`def get_portal(self, id: str) -> GetPortalBindResponse`
Go	`cloud.DeviceBindings.GetPortal`	`func (r *DeviceBindingsResource) GetPortal(ctx context.Context, id string) (GetPortalBindResponse, error)`

参数

参数	位置	类型	必填	说明
`id`	path	`string`	是	portal 绑定会话的 ID，即创建它时返回的 `bind_id`。以 `portal_` 开头。

响应

200 · application/json

字段	类型	必填	说明
`success`	`boolean`	是	—
`data`	portalBindWire	是	—

错误

状态码	Schema	说明
其他（default）	DeviceBindingErrorResponse	Cloud Server 错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.deviceBindings.getPortal("id_123");
console.log(result);

deviceBindings.resolvePortal

POST /v1/agent/portal/bind-sessions/{id}/resolve · Operation ID resolvePortalBind

解析 portal 绑定会话

SDK 方法

语言	方法	签名
TypeScript	`cloud.deviceBindings.resolvePortal`	`resolvePortal(id: string, input: Models.ResolvePortalBindRequest): Promise<Models.ResolvePortalBindResponse>`
Python	`cloud.device_bindings.resolve_portal`	`def resolve_portal(self, id: str, input: ResolvePortalBindRequest) -> ResolvePortalBindResponse`
Go	`cloud.DeviceBindings.ResolvePortal`	`func (r *DeviceBindingsResource) ResolvePortal(ctx context.Context, id string, input ResolvePortalBindRequest) (ResolvePortalBindResponse, error)`

参数

参数	位置	类型	必填	说明
`id`	path	`string`	是	portal 绑定会话的 ID，即创建它时返回的 `bind_id`。以 `portal_` 开头。

请求体

application/json · 必填

字段	类型	必填	说明
`decision`	`string`	是	如何处理认领了该会话的设备。必填。可选值: `"recover"` — 把设备绑定到 `instance_id` 所指的现有实例; `"create"` — 为设备创建新实例. (枚举表)
`instance_id`	`string`	否	要绑定设备的现有实例的 ID。`decision` 为 `recover` 时必填；`create` 时忽略。

响应

200 · application/json

字段	类型	必填	说明
`success`	`boolean`	是	—
`data`	portalBindWire	是	—

错误

状态码	Schema	说明
其他（default）	DeviceBindingErrorResponse	Cloud Server 错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.deviceBindings.resolvePortal("id_123", { decision: "recover" });
console.log(result);

deviceBindings.revokePortal

POST /v1/agent/portal/bind-sessions/{id}/revoke · Operation ID revokePortalBind

撤销 portal 绑定会话

SDK 方法

语言	方法	签名
TypeScript	`cloud.deviceBindings.revokePortal`	`revokePortal(id: string): Promise<Models.RevokePortalBindResponse>`
Python	`cloud.device_bindings.revoke_portal`	`def revoke_portal(self, id: str) -> RevokePortalBindResponse`
Go	`cloud.DeviceBindings.RevokePortal`	`func (r *DeviceBindingsResource) RevokePortal(ctx context.Context, id string) (RevokePortalBindResponse, error)`

参数

参数	位置	类型	必填	说明
`id`	path	`string`	是	portal 绑定会话的 ID，即创建它时返回的 `bind_id`。以 `portal_` 开头。

响应

200 · application/json

字段	类型	必填	说明
`success`	`boolean`	是	—
`data`	portalBindWire	是	—

错误

状态码	Schema	说明
其他（default）	DeviceBindingErrorResponse	Cloud Server 错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.deviceBindings.revokePortal("id_123");
console.log(result);

按判别字段区分的结构

Binding 按 client_type 区分

Binding 的结构取决于它自己的 client_type 值。

client_type 的取值	说明	结构
`"web"`	绑定到网页来源，在 `origin` 中返回。	BindingWeb
`"native"`	绑定到设备密钥，其指纹在 `cnf_jkt` 中返回。	BindingNative

BeeOS Cloud返回文档首页