人工介入 API 集成流程

通过 API 处理暂停中的人工介入表单的端到端流程

⚠️ 本文档由 AI 自动翻译。如有任何不准确之处，请参考 英文原版。

当工作流执行到人工介入节点时会暂停，并在流式响应中发出 human_input_required 事件。该事件携带 form_token，集成方可凭其驱动整个表单生命周期，直到工作流恢复执行。

各接口的字段参考，详见 人工介入 API。

​

流程

下方流程同时适用于 Workflow 和 Chatflow 应用。两者仅在第 1 步的入口接口与第 6 步的恢复接口上有所不同。

1. 以流式模式启动应用

   1. Workflow 应用调用 执行工作流，Chatflow 应用调用 发送对话消息。

   2. 在 SSE 流中关注 human_input_required 事件，从 payload 中提取 form_token、form_id 和 task_id。

      若 SSE 流在工作流恢复前关闭，第 6 步会用到 task_id。

2. 获取表单定义

   使用 form_token 调用 获取人工介入表单 接口。响应包含渲染后的 Markdown、输入字段定义、可用操作以及已预填的默认值。将表单呈现给接收人。

3. （仅文件输入）签发上传令牌

   若表单包含 file 或 file-list 输入，调用 签发上传令牌 接口获取短期有效的 upload_token。同一表单的多次上传可复用此令牌。

4. （仅文件输入）上传文件

   针对接收人附加的每个文件，调用其中之一：

   • 上传本地文件 接口处理来自接收人设备的文件（multipart）。
   • 上传远程文件 接口处理你希望后端在提交前抓取并校验的公开 URL。

   两者都会返回一个 id，提交时作为 upload_file_id 引用。

5. 提交响应

   调用 提交人工介入表单 接口，附上接收人输入的值和所选操作。

   文件输入既可使用 {transfer_method: local_file, upload_file_id} 映射（来自第 4 步），也可在提交时直接使用 {transfer_method: remote_url, url} 映射。两种模式的权衡详见 先上传 vs 直接提交远程 URL。

   提交成功后，工作流沿匹配的操作分支恢复执行。

6. 继续监听工作流

   若原 SSE 流已关闭，使用第 1 步中的 task_id 调用 Workflow 或 Chatflow 的订阅工作流事件接口重新连接。

​

先上传 vs 直接提交远程 URL

文件输入支持两种提交模式：

• 先上传，再使用 upload_file_id（推荐）

  后端在上传阶段即校验文件大小、类型和扩展名，接收人可立即看到错误并在提交前重试。

• 使用 transfer_method: remote_url 直接提交

  后端在提交阶段抓取文件。集成更快，但任何大小、类型或抓取失败都会拒绝整次提交，接收人可能需要重填其他字段。

对于需要接收人反馈的交互式表单，优先选择先上传模式。仅当流程完全程序化、无需任何人重新输入时，直接提交模式的代价才能被抵消。

​

鉴权

面向表单的 获取人工介入表单 和 提交人工介入表单 接口不需要鉴权。form_token 本身即访问凭证，相关接口按客户端 IP 限流。

文件上传接口需要在 Authorization 头中使用第 3 步获取的 Bearer upload_token。

​

发送方式要求

人工介入 API 仅支持通过人工介入节点的 WebApp 发送方式投递的表单。仅通过邮件投递的表单不会向 API 暴露 form_token。

​

示例：带文件的提交

本示例的表单包含一个 feedback 段落输入、一个 attachments 文件列表输入，以及 approve / revise 两个操作。

1. 调用 获取人工介入表单 接口获取表单定义：

   GET /form/human_input/<form_token>
   

2. 调用 签发上传令牌 接口获取上传令牌：

   POST /form/human_input/<form_token>/upload-token
   

   返回 {"upload_token": "hitl_upload_...", "expires_at": ...}。

3. 针对每个本地文件，调用 上传本地文件 接口：

   POST /form/human_input/files/upload
   Authorization: Bearer hitl_upload_...
   Content-Type: multipart/form-data
   
   file=<binary>
   

   返回 {"id": "1a77f0df-...", ...}。

4. 调用 提交人工介入表单 接口，附上接收人输入与所选操作：

   POST /form/human_input/<form_token>
   Content-Type: application/json
   
   {
     "inputs": {
       "feedback": "可以发布",
       "attachments": [
         {"transfer_method": "local_file", "upload_file_id": "1a77f0df-..."}
       ]
     },
     "action": "approve",
     "user": "abc-123"
   }
   

   返回 {}。工作流沿 approve 分支恢复执行。