原文地址：https://alphahinex.github.io/2026/04/19/trigger-hitl-in-dify/

description: "在官方服務 API 發(fā)布之前的臨時方案"
date: 2026.04.19 10:34
categories:
- AI
tags: [AI, Dify]
keywords: HITL, Human-in-the-loop, form_token, workflow_run_id, Dify

Dify 在 v1.13.0 版本中引入了 Human Input 節(jié)點，以支持在工作流關鍵環(huán)節(jié)進行人工介入與決策，使用場景如表單填寫、流程審批等。

人工節(jié)點的表單投遞渠道，目前支持 Web App 和 Email 兩種方式，但對于通過 API 調用的 Dify 流程，如何提交人工節(jié)點的表單數據，并觸發(fā)流程繼續(xù)執(zhí)行，目前還沒有清晰的文檔說明。

本文以一個實際例子，介紹在 Dify v1.13.3 版本中通過調用接口觸發(fā)包含人工節(jié)點的方式。

示例流程

構造一個簡單的 人工節(jié)點測試.yml 流程，先由 LLM 生成一個計算題，再由人工節(jié)點回答計算結果，最終 LLM 判斷是否計算正確。

API 調用

按照 https://github.com/langgenius/dify/discussions/33449#discussioncomment-16221158 中內容，API 驅動包含人工節(jié)點的流程為：

1. Start workflow/chatflow (streaming mode) → get workflow_run_id and form_token from SSE events
2. Submit form → POST /api/form/human_input/{form_token} (no auth needed)
3. Poll for results → GET /v1/workflows/run/{workflow_run_id} until status === "succeeded"

01 發(fā)送對話消息

curl --request POST \
  --url http://host:port/v1/chat-messages \
  --header 'authorization: Bearer app-xxx' \
  --header 'content-type: application/json' \
  --data '{
  "inputs": {},
  "query": "hi",
  "response_mode": "streaming",
  "conversation_id": "",
  "user": "test"
}'

注意：這里 response_mode 為 blocking 時會得到 400 響應。

得到的響應中，可以獲得 form_token 和 workflow_run_id 參數，供后面兩個接口調用：

{
    "conversation_id": "41f57f05-66bb-4dc7-89bf-4852d0d02bbf",
    "created_at": 1776154089,
    "data": {
        "created_at": 1776154088,
        "elapsed_time": 0.549557,
        "outputs": {},
        "paused_nodes": [
            "1776152782529"
        ],
        "reasons": [
            {
                "TYPE": "human_input_required",
                "actions": [
                    {
                        "button_style": "default",
                        "id": "submit",
                        "title": "交卷"
                    }
                ],
                "display_in_ui": true,
                "form_content": "你好！這是為你準備的一道十以內的計算題：\n\n**5 + 3 = ?**\n\n你可以先在心里算一下，然后再告訴我你的答案！\n\n{{#$output.answer#}}\n",
                "form_id": "019d8b08-96ab-7e1f-ac96-64710927f5eb",
                "form_token": "I73ALdiKLtlQOwDrJfu1YO",
                "inputs": [
                    {
                        "default": {
                            "selector": [],
                            "type": "constant",
                            "value": ""
                        },
                        "output_variable_name": "answer",
                        "type": "paragraph"
                    }
                ],
                "node_id": "1776152782529",
                "node_title": "回答",
                "resolved_default_values": {}
            }
        ],
        "status": "paused",
        "total_steps": 3,
        "total_tokens": 119,
        "workflow_run_id": "bf88e736-46d4-4ab1-ad79-fb04de4a4a70"
    },
    "event": "workflow_paused",
    "message_id": "50c4c7d8-8beb-4438-8d2b-b3fbe8606a9e",
    "task_id": "9afc8422-f7a3-4a45-a985-1e7a0d3ee1bc",
    "workflow_run_id": "bf88e736-46d4-4ab1-ad79-fb04de4a4a70"
}

02 提交表單

curl --request POST \
  --url http://host:port/api/form/human_input/I73ALdiKLtlQOwDrJfu1YO \
  --header 'authorization: Bearer app-xxx' \
  --header 'content-type: application/json' \
  --data '{
  "inputs": {
    "answer": "2"
  },
  "action": "submit"
}'

得到 200 響應碼的響應：

{}

03 查詢流程狀態(tài)

curl --request GET \
  --url http://host:port/v1/workflows/run/bf88e736-46d4-4ab1-ad79-fb04de4a4a70 \
  --header 'authorization: Bearer app-xxx' \
  --header 'content-type: application/json'

{
  "id": "bf88e736-46d4-4ab1-ad79-fb04de4a4a70",
  "workflow_id": "953cd66b-e450-46b7-9bd6-868919b467d5",
  "status": "succeeded",
  "inputs": "{\"sys.files\": [], \"sys.user_id\": \"bruno-test\", \"sys.app_id\": \"fee1dd85-3a58-4adc-9acf-5965148c6657\", \"sys.workflow_id\": \"953cd66b-e450-46b7-9bd6-868919b467d5\", \"sys.workflow_run_id\": \"bf88e736-46d4-4ab1-ad79-fb04de4a4a70\", \"sys.query\": \"hi\", \"sys.dialogue_count\": 1}",
  "outputs": {
    "answer": "計算結果**不正確**。\n\n**分析過程：**\n題目要求的算式是 $5 + 3$。\n- 5 加上 3 等于 **8**。\n- 你提供的計算結果是 **2**。\n\n**結論：**\n正確答案應該是 **8**，而不是 2。\n（注：結果 2 可能是誤算成了 $5 - 3$。）",
    "files": []
  },
  "error": null,
  "total_steps": 6,
  "total_tokens": 632,
  "created_at": 1776329321,
  "finished_at": 1776329377,
  "elapsed_time": 0.84948
}

流程中包含多個人工節(jié)點

當流程中包含多個人工節(jié)點時，第一個人工節(jié)點可按上述方式觸發(fā)執(zhí)行，但后續(xù)人工節(jié)點，按照 https://github.com/langgenius/dify/discussions/33449#discussioncomment-16269242 中給出的方式，在調用 /pause-info 接口時得到的是一個 html，不包含必需的 form_token 信息?？梢姰斍鞍姹鞠拢€不能很好的通過 API 方式驅動包含多個人工節(jié)點的流程。

1. Poll GET /v1/workflows/run/{workflow_run_id} until status === "paused"
2. Call GET /apps/{app_id}/workflow-runs/{run_id}/pause-info to get the new form_token
3. Submit the form and repeat

官方在 #32826 中正在籌備新的 Service API 來更好的支持包含人工節(jié)點的流程，可以關注合并狀態(tài)。

參考資料

1. Help，How to use Human-in-the-loop nodes in an API？
2. How to trigger Human Input Node actions via the Dify Workflow API?
3. feat: add service api of HITL