Responses

概览

responses domain 在已配置的 harness 上运行任务并读回结果（UHP）。stream: false 时，服务端在任务到达终态后返回一个 Response 对象；stream: true 时返回 text/event-stream 事件流。

6 个操作 · SDK 资源：TypeScript cloud.responses · Python cloud.responses · Go cloud.Responses · API 总览

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

主要对象

• UHPCreateResponseRequest：要运行的任务（输入、模型、元数据与选项）。
• UHPResponse：任务及其输出项和用量；状态为 UHPResponseStatus。
• UHPEvent：流式响应中的一个事件。

UHPCreateResponseRequest

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

UHPResponse

UHPResponseStatus 取值

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

UHPEvent

一个流式事件。sequence_number 从 0 开始，每个事件恰好加 1，这样客户端可以发现丢失的事件，而不是悄悄地渲染出一个空缺。

UHPEvent.type 取值

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

UHPOutputItem

客户端必须容忍它不认识的 item 类型。只渲染 message 项并忽略其余项的客户端是合法的客户端。

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

UHPContentPart

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

UHPAnnotation

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

典型流程

1. 用 responses.create 运行任务；重试必须携带同一个 Idempotency-Key。
2. 用 responses.get 读回任务，或用 responses.getEvents 跟随或恢复其事件。
3. 用 responses.cancel 停止运行中的任务；取消已结束的任务会成功且不产生任何变化。
4. 用 responses.getInputItems 读取最初的输入。
5. 用 responses.delete 删除已存储的 response；删除不会取消运行中的任务。

方法

responses.create

POST /uhp/v1/responses · Operation ID createResponse

运行一个任务

协议的核心。stream: false 时，任务到达终态后服务器返回一个 Response 对象。stream: true 时返回 text/event-stream，承载“流式传输”一章中定义的事件。 重试必须携带 Idempotency-Key：没有它时，超时后的重试会把任务再运行一次，而第一次可能仍在运行。

SDK 方法

cloud.responses.createStream: 以 stream: true 创建 Response，并把 server-sent events 作为异步可迭代对象返回。方法会展开 input 并强制 stream: true，再以 responseType: "sse" 调用 POST /responses。

cloud.responses.create_stream: 以 stream: True 创建 Response，并逐个产出解码后的 server-sent events（JSON 值）。它复制 input、强制 stream 为 True 后 POST 到 /responses；options 原样作为请求头发送。

cloud.Responses.CreateStream: 以强制 stream=true 创建 Response，并返回 *UHPEventStream。用 Next() 读取事件直到返回 io.EOF，结束时调用 Close()。options 作为请求头发送。

参数

请求体

application/json · 必填 · Schema: UHPCreateResponseRequest

响应

200 已完成的 Response（非流式），或事件流（流式）。 · application/json · Schema: UHPResponse

stream=true 返回 text/event-stream；stream=false 返回 UHPResponse

错误

错误 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.responses.create({ input: "example_input" });
console.log(result);

responses.get

GET /uhp/v1/responses/{response_id} · Operation ID getResponse

读回一个任务

SDK 方法

参数

响应

200 该 Response · application/json · Schema: UHPResponse

错误

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

responses.delete

DELETE /uhp/v1/responses/{response_id} · Operation ID deleteResponse

删除已存储的 response

不得取消正在运行的任务——删除和取消是两种不同的意图。

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.responses.delete("response_123");
console.log(result);

responses.cancel

POST /uhp/v1/responses/{response_id}/cancel · Operation ID cancelResponse

取消一个运行中的任务

幂等。取消一个已处于终态的任务会成功且不产生任何变化——客户端在连接中断后重试取消，不应因为此前已经成功而受到惩罚。

SDK 方法

参数

响应

200 该 Response，现在处于取消中或已终止 · application/json · Schema: UHPResponse

错误

错误 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.responses.cancel("response_123");
console.log(result);

responses.getEvents

GET /uhp/v1/responses/{response_id}/events · Operation ID getResponseEvents

流式获取或续传一个 response 的事件

SDK 方法

参数

响应

200 服务器发送的协议事件 · text/event-stream · Schema: UHPEvent

返回 server-sent events 流。

错误

错误 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 stream = await cloud.responses.getEvents("response_123");
for await (const event of stream) {
  console.log(event);
}

responses.getInputItems

GET /uhp/v1/responses/{response_id}/input_items · Operation ID getResponseInputItems

创建该任务时使用的输入

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.responses.getInputItems("response_123");
console.log(result);

按判别字段区分的结构

UHPContentPart 按 type 区分

UHPContentPart 的结构取决于它自己的 type 值。

UHPEvent 按 type 区分

UHPEvent 的结构取决于它自己的 type 值。

UHPOutputItem 按 type 区分

UHPOutputItem 的结构取决于它自己的 type 值。