后端调用自定义 harness

本指南把同一场景的两端连起来：运行你自己的智能体循环的智能体进程，以及向它发送任务的产品后端。两端使用不同的 SDK，文档分属不同章节；本页是它们唯一交汇的地方。

Harness 侧：注册自定义 harness

智能体进程运行你的智能体循环，并把它作为 harness 注册到 BeeOS Cloud。这一侧只使用 Harness SDK：注册运行时、接收 Cloud 路由过来的聊天消息并完成回复。设置与处理函数契约见 Harness SDK 文档；自定义循环的步骤见构建自定义智能体。

注册成功后，该 harness 会出现在它所属实例的列表中。记下它的 harness ID：后端需要用到它，它与实例 ID 不同。

Cloud 侧：从产品后端发送任务

产品后端使用 Cloud SDK，且只在可信的后端代码中使用。客户端与 Key 的用法见安装与鉴权。用 harnesses.list 选出已注册的 harness，再发送一个 metadata.harness_id 为该 ID 的 Response。

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

const cloud = new BeeOSClient({
  baseURL: process.env.BEEOS_CLOUD_API_URL!, // https://api.cloud.beeos.ai/v1
  apiKey: process.env.BEEOS_API_KEY!, // bsk_…，只放后端
});

// 从列表中选出已注册的自定义 harness，把它的 ID 放进 BEEOS_HARNESS_ID。
const harnesses = await cloud.harnesses.list();

const response = await cloud.responses.create({
  input: "Hello from my product",
  metadata: { harness_id: process.env.BEEOS_HARNESS_ID! },
}, crypto.randomUUID());
console.log(response.output);

Response 有独立 ID、状态和输出。继续下一回合时传 previous_response_id；后台工作设置 background: true，再用 responses.get 查询进度。responses domain 列出了每个操作和字段，管理 harness 说明如何从后端修改技能或应用模板。Key 只放后端；浏览器或移动应用如何拿到结果，见产品前端集成。