Harness

概览

harnesses domain 管理实例上已配置的 harness，并列出它们可运行的模型（UHP）。创建和更新是同步的：操作说明写明 Cloud 会提交每个运行时操作并等待后再响应，因此请为这些调用设置至少 60 秒的客户端超时。

7 个操作 · SDK 资源：TypeScript cloud.harnesses · Python cloud.harnesses · Go cloud.Harnesses · API 总览

路径以 /uhp/v1 开头的操作由 https://api.cloud.beeos.ai/uhp/v1 提供，而不是 https://api.cloud.beeos.ai/v1；SDK 会自动切换。

主要对象

• UHPHarnessCreate：创建或更新 harness 时发送的配置。
• UHPHarness：已配置的 harness。
• UHPHarnessModels 与 UHPModelCatalog：单个 harness 的模型，以及按后端分组的模型目录。

UHPHarnessCreate

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

UHPHarness

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

UHPHarnessModels

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

UHPModelCatalog

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

UHPMcpServer

附加到 harness 的远程 MCP 服务器。只有已启用的条目会在回合中连接；已禁用的条目完全不得联系。无法访问的服务器不得使任务失败。与 2026-08-11 相比没有变化：进程（stdio）服务器在插件内部声明，见 PluginMcpServer。

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

UHPSkill

skill 是一个文件夹，而不是一个文件。服务器必须把整个文件夹具体化到 agent 可以读取的位置——只具体化 SKILL.md 会破坏每一个带有 references、脚本或数据的 skill。通过 GET 和 PUT 往返一个 harness 不得丢失 skill 的内容。

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

UHPPlugin

安装到 harness 中的 Agent Plugins 包：根目录下的 plugin.json，mcp.json 中的 MCP 服务器，skills/ 下的 skill。客户端写入 files（或回传 blob），以及可选的 name 和 enabled；服务器在每次写入时从包中推导 manifest、mcpServers、skills 和 skipped，并在输入中忽略这些字段。被拒绝的包不会改变 harness。

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

UHPModel

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

典型流程

1. 用 harnesses.create 创建 harness，再用 harnesses.get 读取，或用 harnesses.list 列出全部。
2. 用 harnesses.update 修改其配置。
3. 用 harnesses.listModels 查看它可运行的模型；harnesses.listAllModels 给出按后端分组的目录。
4. 通过 responses 在该 harness 上运行任务。harnesses.delete 目前不受支持，会返回 422。

更新规则与错误处理见管理 harness。

方法

harnesses.list

GET /uhp/v1/harnesses · Operation ID listHarnesses

列出已配置的 harness

SDK 方法

响应

200 调用方范围内的 harness。可能为空。 · application/json

错误

错误 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.harnesses.list();
console.log(result);

harnesses.create

POST /uhp/v1/harnesses · Operation ID createHarness

创建一个已配置的 harness

同步：Cloud 提交每一项运行时操作并等待（最长 45 秒，因此请将客户端超时设为至少 60 秒）后再响应。502 harness_error 在 error.detail.operations[] 中列出逐项结果；504 beeos_harness_update_in_progress 表示工作仍在继续，请在 Retry-After 之后重试完全相同的请求（没有 Idempotency-Key 的创建不会被重新挂接，会创建第二个 harness）；409 beeos_harness_busy 表示另有不同的写入正在进行，请在 Retry-After 之后重试；409 beeos_idempotency_conflict 表示该 Idempotency-Key 曾用于另一个不同的请求；503 harness_unavailable 表示实例未运行或操作日志不可用；413 表示请求体超过 4 MiB（大型 skill 请作为 Files blob 上传）。可选的 Idempotency-Key 头（1-128 个可见 ASCII 字符）使创建（POST，或带 template_id 的 PUT）可以安全重发：相同的 key 与请求返回同一个 harness。instance_id 和 name 为必填，base 必须等于实例的运行时（422）；template_id 和 template_version 用 agent 模板创建 harness；default_model 仅在此处生效。创建时，非空的 skills 或 mcp_servers 会被拒绝（422 beeos_field_not_supported）；请用 PUT 添加。BeeOS Cloud 尚不支持（422 beeos_field_not_supported）：非空的 system_prompt、disabled_tools、environment 或 plugins，以及任何 max_step 或 timeout_seconds。未改变的 name 和空值会被接受，因此 GET-修改-PUT 的往返可以正常工作。

SDK 方法

参数

请求体

application/json · 必填 · Schema: UHPHarnessCreate

响应

200 已创建的 harness · application/json · Schema: UHPHarness

错误

错误 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.harnesses.create({ base: "example_base" });
console.log(result);

harnesses.get

GET /uhp/v1/harnesses/{harness_id} · Operation ID getHarness

获取单个 harness

SDK 方法

参数

响应

200 该 harness · application/json · Schema: UHPHarness

错误

错误 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.harnesses.get("harness_123");
console.log(result);

harnesses.update

PUT /uhp/v1/harnesses/{harness_id} · Operation ID updateHarness

更新 harness 配置

同步：Cloud 提交每一项运行时操作并等待（最长 45 秒，因此请将客户端超时设为至少 60 秒）后再响应。502 harness_error 在 error.detail.operations[] 中列出逐项结果；504 beeos_harness_update_in_progress 表示工作仍在继续，请在 Retry-After 之后重试完全相同的请求（没有 Idempotency-Key 的创建不会被重新挂接，会创建第二个 harness）；409 beeos_harness_busy 表示另有不同的写入正在进行，请在 Retry-After 之后重试；409 beeos_idempotency_conflict 表示该 Idempotency-Key 曾用于另一个不同的请求；503 harness_unavailable 表示实例未运行或操作日志不可用；413 表示请求体超过 4 MiB（大型 skill 请作为 Files blob 上传）。可选的 Idempotency-Key 头（1-128 个可见 ASCII 字符）使创建（POST，或带 template_id 的 PUT）可以安全重发：相同的 key 与请求返回同一个 harness。缺省的字段保持不变；出现的列表会替换整个列表。出现 skills 时，会与已安装的 skill 做差异比较：列出的、带有 files、content 或 blob（三者恰好一个）的 skill 会被安装；已安装且列出时 enabled 标志不同的 skill 会被更新；已安装但被省略的 skill 会被卸载，随运行时捆绑的除外；列出的、未安装且没有 files、content 或 blob 的 skill 返回 422；对全新安装设置 enabled:false 返回 422。出现 mcp_servers 时，会与运行时的 MCP 服务器做差异比较：随请求带有凭证（headers，或 auth 加 expires_at，最多提前 24 小时）的服务器会被设置，已连接且未带凭证的服务器会被保留，被省略的服务器会被取消设置；url 必须是 https，transport 为 http 或 sse；GET 永远不会返回 url 或凭证。只有当实例运行时没有任何 MCP 方法时才返回 422 beeos_mcp_not_supported。base 不可变；修改 name，或（没有 template_id 时）使 default_model 不同于当前值，会返回 422 beeos_field_not_supported。BeeOS Cloud 尚不支持（422 beeos_field_not_supported）：非空的 system_prompt、disabled_tools、environment 或 plugins，以及任何 max_step 或 timeout_seconds。未改变的 name 和空值会被接受，因此 GET-修改-PUT 的往返可以正常工作。

SDK 方法

参数

请求体

application/json · 必填 · Schema: UHPHarnessCreate

响应

200 已更新的 harness · application/json · Schema: UHPHarness

错误

错误 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.harnesses.update("harness_123", { base: "example_base" });
console.log(result);

harnesses.delete

DELETE /uhp/v1/harnesses/{harness_id} · Operation ID deleteHarness

删除 harness

BeeOS Cloud 尚不支持：找到该 harness 之后返回 422 beeos_harness_delete_not_supported。

SDK 方法

参数

响应

200 已删除 · application/json

错误

错误 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.harnesses.delete("harness_123");
console.log(result);

harnesses.listModels

GET /uhp/v1/harnesses/{harness_id}/models · Operation ID listHarnessModels

该 harness 可以运行的模型

SDK 方法

参数

响应

200 该 harness 允许使用的模型、默认模型和已授权的备选模型 · application/json · Schema: UHPHarnessModels

错误

错误 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.harnesses.listModels("harness_123");
console.log(result);

harnesses.listAllModels

GET /uhp/v1/models · Operation ID listModels

按后端划分的模型目录

SDK 方法

响应

200 按后端分组的模型，每个模型带有计算得出的可用性 · application/json · Schema: UHPModelCatalog

错误

错误 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.harnesses.listAllModels();
console.log(result);