> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 人工介入 API 集成流程

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

当工作流执行到 [人工介入](/zh/3.10.x/use/nodes/human-input) 节点时会暂停，并在流式响应中发出 `human_input_required` 事件。该事件携带 `form_token`，集成方可凭其驱动整个表单生命周期，直到工作流恢复执行。

各接口的字段参考，详见 [人工介入 API](/zh/3.10.x/develop/api/human-input/get-human-input-form)。

## 流程

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

<Steps>
  <Step title="以流式模式启动应用">
    1. Workflow 应用调用 [执行工作流](/zh/3.10.x/develop/api/workflow-runs/run-workflow)，Chatflow 应用调用 [发送对话消息](/zh/3.10.x/develop/api/chat-messages/send-chat-message)，并传入终端用户的 `user` 标识。
    2. 在 SSE 流中关注 `human_input_required` 事件，提取其中的 `form_token`。

       若 `form_token` 为 `null`，说明表单使用邮件投递，无法通过 API 驱动（见 [提交方式要求](#提交方式要求)）。

       `human_input_required` 事件同时携带本次运行的 `workflow_run_id`；请保留它，以便在第 4 步需要时恢复监听。
  </Step>

  <Step title="获取表单定义">
    使用 `form_token` 调用 [获取人工介入表单](/zh/3.10.x/develop/api/human-input/get-human-input-form) 接口。响应包含渲染后的 Markdown、输入字段定义、可用操作、已预填的默认值，以及一个 `expiration_time`，超过该时间后表单将无法再提交。将表单呈现给接收者。

    若表单在提交前过期，暂停的运行会按节点配置的超时行为处理；恢复后的事件流中携带的是 `human_input_form_timeout`，而非 `human_input_form_filled`。
  </Step>

  <Step title="提交响应">
    调用 [提交人工介入表单](/zh/3.10.x/develop/api/human-input/submit-human-input-form) 接口，附上接收者输入的值、所选的 `action` 以及你的 `user`。`action` 必须是第 2 步表单定义中的某个操作。

    提交一旦成功即为最终结果：表单随之关闭，工作流沿匹配的操作分支恢复执行，同一个 `form_token` 无法再次提交。

    若提交被拒绝（操作无效或缺少必填输入），表单保持不变，修正输入后可用同一个 `form_token` 重新提交。
  </Step>

  <Step title="继续监听工作流">
    若原 SSE 流已关闭，可调用 [流式获取工作流事件](/zh/3.10.x/develop/api/workflow-runs/stream-workflow-events) 重新连接：使用第 1 步中的 `workflow_run_id`，并携带启动运行时的同一个 `user`（`user` 不一致会返回 404）。

    恢复后的事件流会先携带确认提交的 `human_input_form_filled`（表单过期时则是 `human_input_form_timeout`），随后像从未暂停过一样，继续输出其余节点事件直至完成。

    如需先重放已执行节点的状态，可附带 `include_state_snapshot=true`。若工作流串联了多个人工介入节点，流默认会在每次暂停时关闭；传入 `continue_on_pause=true` 可让同一条流跨越所有暂停保持连接。
  </Step>
</Steps>

## 提交方式要求

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

## 示例：表单提交

本示例的表单包含一个 `feedback` 段落输入，以及 `approve` / `reject` 两个操作。

1. 调用 [获取人工介入表单](/zh/3.10.x/develop/api/human-input/get-human-input-form) 接口获取表单定义：

   ```http theme={null}
   GET /form/human_input/<form_token>
   Authorization: Bearer {api-key}
   ```

   返回表单定义：

   ```json theme={null}
   {
     "form_content": "Please review the draft and confirm or request changes.",
     "inputs": [
       {
         "type": "paragraph",
         "output_variable_name": "feedback",
         "default": {
           "type": "constant",
           "selector": [],
           "value": ""
         }
       }
     ],
     "resolved_default_values": {},
     "user_actions": [
       {
         "id": "approve",
         "title": "Approve",
         "button_style": "primary"
       },
       {
         "id": "reject",
         "title": "Request changes",
         "button_style": "default"
       }
     ],
     "expiration_time": 1745510400
   }
   ```

2. 调用 [提交人工介入表单](/zh/3.10.x/develop/api/human-input/submit-human-input-form) 接口，附上接收者输入与所选操作：

   ```http theme={null}
   POST /form/human_input/<form_token>
   Authorization: Bearer {api-key}
   Content-Type: application/json

   {
     "inputs": {
       "feedback": "可以发布"
     },
     "action": "approve",
     "user": "abc-123"
   }
   ```

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

3. 调用 [流式获取工作流事件](/zh/3.10.x/develop/api/workflow-runs/stream-workflow-events) 重新连接运行的事件流，跟踪至运行完成，与上文流程的最后一步相同。