feat: add stateful responses API

2026-09-07 00:15:32 +08:00
parent ab409ba9c0
commit 43f2cc445e
22 changed files with 2461 additions and 5 deletions
@@ -46,7 +46,7 @@
    "groups": [
      {
        "group": "开始与对接",
-        "pages": ["index", "integrations", "tool-resources", "realtime-protocol"]
+        "pages": ["index", "integrations", "tool-resources", "responses-api", "realtime-protocol"]
      }
    ]
  }
@@ -40,8 +40,9 @@ make db-seed

 保存后，从助手详情页打开语音预览即可测试。

-## 4. 对接 Realtime 协议
+## 4. 对接公开协议

+- [Responses 文本接口](/responses-api)：通过 HTTP 或 SSE 调用 Pipeline 助手，并使用 `previous_response_id` 延续多轮状态。
 - [Realtime 兼容协议设计](/realtime-protocol)：了解后端提供的 OpenAI Realtime 兼容 WebRTC、WebSocket、鉴权与 Interactive Media 扩展协议。

 <Note>
@@ -0,0 +1,135 @@
+---
+title: Stateful Responses 文本接口
+description: 使用 OpenAI Responses 风格的 HTTP 与 SSE 接口调用平台助手。
+---
+
+# Stateful Responses 文本接口
+
+`POST /v1/responses` 为 Pipeline 助手提供文本调用。服务端保存每轮输入和输出，后续请求通过 `previous_response_id` 恢复上下文。语音、视频和长连接交互继续使用 `/v1/realtime`。
+
+接口使用后台创建的长期 `sk-rt-...` API Key。短期 `ek-rt-...` Client Secret 不能调用文本接口。
+
+## 首轮请求
+
+```bash
+curl -X POST "https://api.example.com/v1/responses" \
+  -H "Authorization: Bearer $REALTIME_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "assistant:asst_xxx",
+    "input": "请介绍一下这个产品"
+  }'
+```
+
+响应中的 `id` 是下一轮使用的状态指针：
+
+```json
+{
+  "id": "resp_xxx",
+  "object": "response",
+  "status": "completed",
+  "model": "assistant:asst_xxx",
+  "previous_response_id": null,
+  "output": [
+    {
+      "id": "msg_xxx",
+      "type": "message",
+      "status": "completed",
+      "role": "assistant",
+      "content": [
+        {"type": "output_text", "text": "……", "annotations": []}
+      ]
+    }
+  ]
+}
+```
+
+## 继续多轮对话
+
+后续请求可以省略 `model`。服务端从父响应恢复助手、动态变量、消息和工具上下文：
+
+```bash
+curl -X POST "https://api.example.com/v1/responses" \
+  -H "Authorization: Bearer $REALTIME_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "previous_response_id": "resp_xxx",
+    "input": "它适合哪些行业？"
+  }'
+```
+
+同一个父响应可以创建多个独立分支。Response 只能由创建它的 API Key 查询或继续：
+
+```bash
+curl "https://api.example.com/v1/responses/resp_xxx" \
+  -H "Authorization: Bearer $REALTIME_API_KEY"
+```
+
+## SSE 流式输出
+
+设置 `stream: true` 后返回 `text/event-stream`：
+
+```json
+{
+  "model": "assistant:asst_xxx",
+  "input": "给我一个简短介绍",
+  "stream": true
+}
+```
+
+主要事件依次为 `response.created`、`response.in_progress`、`response.output_text.delta`、`response.output_text.done` 和 `response.completed`。连接中断会取消运行，并把 Response 标记为 `cancelled`。
+
+## 动态变量
+
+首轮可以传入项目扩展字段，后续请求会继承并可增量覆盖：
+
+```json
+{
+  "model": "assistant:asst_xxx",
+  "input": "查询我的权益",
+  "x_interactive_media": {
+    "variables": {
+      "customer_name": "王女士",
+      "membership_level": "gold"
+    }
+  }
+}
+```
+
+## Client Tool 续传
+
+当助手需要调用客户端工具时，Response 的 `output` 会包含 `function_call`：
+
+```json
+{
+  "type": "function_call",
+  "call_id": "call_xxx",
+  "name": "show_message",
+  "arguments": "{\"message\":\"请确认\"}"
+}
+```
+
+客户端执行后，通过父响应和对应的 `call_id` 继续：
+
+```json
+{
+  "previous_response_id": "resp_xxx",
+  "input": [
+    {
+      "type": "function_call_output",
+      "call_id": "call_xxx",
+      "output": "{\"status\":\"ok\",\"data\":{\"action\":\"confirmed\"}}"
+    }
+  ]
+}
+```
+
+如果父链存在多个尚未完成的 Client Tool，本轮必须一次提交全部对应结果。
+
+## 首版边界
+
+- 仅支持 `runtimeMode=pipeline` 的 Prompt、Workflow、Dify 和 FastGPT 助手。
+- 只支持文本 `message` 和 `function_call_output` 输入。
+- `store` 必须为 `true` 或省略。
+- 不支持 `conversation`、`background`、图片、文件以及调用方覆盖 instructions 或 tools。
+- 不提供 `/v1/chat/completions` 兼容接口。