構(gòu)化方式向人類(lèi)發(fā)起輸入請(qǐng)求的完整機(jī)制)
Dify Agent Ask Human Layer讓模型以結(jié)構(gòu)化方式向人類(lèi)發(fā)起輸入請(qǐng)求的完整機(jī)制【免費(fèi)下載鏈接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/di/dify本篇圍繞 Dify Agent 的 ask-human layerdify.ask_human展開(kāi)它向模型暴露一個(gè) external deferred tool使 Agent 能在當(dāng)前 run 無(wú)法繼續(xù)時(shí)以結(jié)構(gòu)化請(qǐng)求形式向人類(lèi)要信息并將該請(qǐng)求作為deferred_tool_call隨run_succeeded事件返回給客戶端。讀完本文你將掌握如何組裝包含該 layer 的CreateRunRequest、理解每個(gè)配置字段的護(hù)欄語(yǔ)義、處理延遲工具調(diào)用deferred call并攜人類(lèi)結(jié)果恢復(fù) run 的完整閉環(huán)以及各故障癥狀的排查方法。層契約它做什么、不做什么ask-human layer 的定位是“模型可見(jiàn)的工具層”而不是消息投遞系統(tǒng)。層契約要點(diǎn)如下屬性值Type iddify.ask_human常用 layer 名稱(chēng)ask_humanConfig DTODifyAskHumanLayerConfig模型可見(jiàn)工具默認(rèn)ask_human可用tool_name配置工具類(lèi)型pydantic-aiexternaldeferred tool終止事件run_succeeded終止載荷分支run_succeeded.data.deferred_tool_call關(guān)鍵在于“不暫?！钡恼Z(yǔ)義Agent run 不會(huì)進(jìn)入 paused 狀態(tài)。當(dāng)模型調(diào)用 ask-human 工具時(shí)當(dāng)前 run 以deferred_tool_call代替普通output成功結(jié)束把延遲調(diào)用轉(zhuǎn)成面向人類(lèi)的流程、收集結(jié)果、再發(fā)起帶deferred_tool_results的新 run全部是客戶端的職責(zé)。從源碼 layer.py 的模塊注釋也能印證這一設(shè)計(jì)layer 只貢獻(xiàn)“一個(gè)可選 external 工具 一段 prompt 提示”工具在首次 run 中絕不執(zhí)行 Python下游系統(tǒng)自行決定投遞、接收人、超時(shí)與授權(quán)?；A(chǔ)用法把 layer 加入 run composition將 ask-human layer 與 prompt、history、LLM 以及可選的結(jié)構(gòu)化輸出 layer 放在同一個(gè) composition 中from agenton_collections.layers.plain import PromptLayerConfig from agenton_collections.layers.pydantic_ai import PYDANTIC_AI_HISTORY_LAYER_TYPE_ID from dify_agent.layers.ask_human import DIFY_ASK_HUMAN_LAYER_TYPE_ID, DifyAskHumanLayerConfig from dify_agent.layers.dify_plugin import DifyPluginLLMLayerConfig from dify_agent.layers.execution_context import ( DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, DifyExecutionContextLayerConfig, ) from dify_agent.protocol import DIFY_AGENT_HISTORY_LAYER_ID, DIFY_AGENT_MODEL_LAYER_ID from dify_agent.protocol.schemas import CreateRunRequest, RunComposition, RunLayerSpec request CreateRunRequest( compositionRunComposition( layers[ RunLayerSpec( nameprompt, typeplain.prompt, configPromptLayerConfig( prefixYou can ask a human only when the missing decision is required to continue., userReview the deployment plan and proceed only after getting the required approval., ), ), RunLayerSpec( nameexecution_context, typeDIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, configDifyExecutionContextLayerConfig( tenant_idreplace-with-tenant-id, user_idreplace-with-user-id, user_fromaccount, app_idreplace-with-app-id, agent_modesingle_step, invoke_fromdebugger, ), ), RunLayerSpec( nameDIFY_AGENT_HISTORY_LAYER_ID, typePYDANTIC_AI_HISTORY_LAYER_TYPE_ID, ), RunLayerSpec( nameask_human, typeDIFY_ASK_HUMAN_LAYER_TYPE_ID, configDifyAskHumanLayerConfig( max_fields4, max_actions2, allowed_field_types[paragraph, select], allow_file_fieldsFalse, ), ), RunLayerSpec( nameDIFY_AGENT_MODEL_LAYER_ID, typedify.plugin.llm, deps{execution_context: execution_context}, configDifyPluginLLMLayerConfig( plugin_idlanggenius/openai, model_provideropenai, modelgpt-5.2, ), ), ] ) )組合中各 layer 的角色plain.prompt負(fù)責(zé)業(yè)務(wù)指令execution_context提供租戶/用戶/應(yīng)用上下文PYDANTIC_AI_HISTORY_LAYER_TYPE_ID提供消息歷史dify.plugin.llm是模型 layer通過(guò)deps消費(fèi) execution_context layer。history layer 是恢復(fù)語(yǔ)義的硬前提。只要預(yù)期在人類(lèi)回答后繼續(xù)對(duì)話就必須包含 history layer。懸而未決的工具調(diào)用被存放在 pydantic-ai 消息歷史里因此恢復(fù) run 需要兩樣?xùn)|西上一次返回的session_snapshot以及保持 history layer 仍存在的同一邏輯 composition。runner 側(cè)對(duì)此有明確校驗(yàn)——見(jiàn) runner.pyif deferred_tool_results is not None and history_layer is None: raise AgentRunValidationError( Deferred tool results require a history layer with prior message history. )此外 composition 層面只允許存在一個(gè) ask-human layervalidate_ask_human_layer_compositionlayer.py會(huì)拒絕同名 type 的多個(gè) layer。配置字段與雙層護(hù)欄DifyAskHumanLayerConfig只控制“面向模型的工具身份與護(hù)欄”刻意不包含任何投遞配置。字段定義見(jiàn) configs.py字段類(lèi)型默認(rèn)值含義enabledboolTrue為 false 時(shí)該 layer 既不暴露工具也不注入 prompt 引導(dǎo)tool_namestrask_human模型可見(jiàn)的工具名必須是合法標(biāo)識(shí)符tool_descriptionstr \| None默認(rèn)描述文本可選的模型可見(jiàn)工具描述max_fieldsint8模型可請(qǐng)求的字段數(shù)上限0表示僅允許動(dòng)作型請(qǐng)求max_actionsint4模型可請(qǐng)求的人類(lèi)動(dòng)作數(shù)上限allowed_field_typeslist[paragraph \| select \| file \| file-list][paragraph, select]運(yùn)行時(shí)校驗(yàn)接受的字段類(lèi)型allow_file_fieldsboolFalse未開(kāi)啟時(shí)文件字段類(lèi)型直接拒絕開(kāi)啟后還須列入allowed_field_typesmax_markdown_charsint8000可選markdown正文的最大長(zhǎng)度max_question_charsint1000必填question的最大長(zhǎng)度max_field_label_charsint120每個(gè)字段 label 的最大長(zhǎng)度max_action_label_charsint80每個(gè)動(dòng)作 label 的最大長(zhǎng)度配置上限之上還有服務(wù)端硬上限兩者取較小值生效若配置超過(guò)硬上限請(qǐng)求校驗(yàn)階段即失敗、run 無(wú)法執(zhí)行。硬上限常量定義在 configs.py字段硬上限max_fields16max_actions8max_markdown_chars20000max_question_chars4000max_field_label_chars200max_action_label_chars120實(shí)現(xiàn)上有兩處值得注意tool_name必須是合法標(biāo)識(shí)符。字段校驗(yàn)器用正則^[A-Za-z_][A-Za-z0-9_]*$全匹配校驗(yàn)configs.py非法命名會(huì)在配置校驗(yàn)時(shí)直接報(bào)錯(cuò)。文件字段的“雙開(kāi)關(guān)”策略。_validate_file_field_policy模型校驗(yàn)器要求只有當(dāng)allow_file_fieldsTrue且allowed_field_types中包含file/file-list時(shí)文件字段才合法allow_file_fieldsFalse卻在允許列表里寫(xiě)了文件類(lèi)型配置本身就會(huì)被拒絕configs.py。文件字段變體目前屬于“為前向兼容預(yù)留的詞匯表”默認(rèn)不開(kāi)放。layer 會(huì)把這些上限自動(dòng)轉(zhuǎn)寫(xiě)成 prompt 提示。build_prompt_hintlayer.py生成的文本包含允許的字段類(lèi)型、文件上傳是否啟用、字段/動(dòng)作數(shù)上限、question/markdown與 label 長(zhǎng)度限制并告知模型“若省略 actions系統(tǒng)會(huì)自動(dòng)補(bǔ)一個(gè) primary 樣式的 Submit 動(dòng)作”?？蛻舳艘虼藷o(wú)需在系統(tǒng)提示里重復(fù)羅列限制但可追加業(yè)務(wù)側(cè)指導(dǎo)例如何時(shí)才適合問(wèn)人。模型能請(qǐng)求什么AskHumanToolArgs 契約啟用后layer 暴露一個(gè) external deferred tool其參數(shù)形狀為AskHumanToolArgsschema.py字段類(lèi)型含義titlestr \| None面向人類(lèi)請(qǐng)求的可選短標(biāo)題questionstr必填的問(wèn)題/指令不能為空白markdownstr \| None可選的較長(zhǎng) Markdown 正文應(yīng)按不可信的用戶可見(jiàn)內(nèi)容對(duì)待fieldslist[AskHumanField]供人類(lèi)填寫(xiě)的可選結(jié)構(gòu)化字段name 全局唯一actionslist[AskHumanAction]可選的動(dòng)作按鈕若省略Dify Agent 歸一化為單個(gè) primarySubmit動(dòng)作urgencynormal \| high給下游系統(tǒng)的提示不是投遞策略支持的字段變體判別字段為typeparagraph自由文本輸入支持placeholder、defaultselect單選輸入選項(xiàng)value必須非空且唯一default必須命中某個(gè)選項(xiàng)值schema.pyfile單文件輸入僅在允許文件字段時(shí)可用file-list多文件輸入僅在允許文件字段時(shí)可用可配max_filesschema.py。所有字段和動(dòng)作都執(zhí)行extraforbid即不允許攜帶未知屬性字段name與動(dòng)作id必須滿足標(biāo)識(shí)符規(guī)則。工具參數(shù)在模型調(diào)用后還會(huì)被再校驗(yàn)一次。校驗(yàn)入口_validate_tool_argslayer.py捕獲ValidationError/ValueError并轉(zhuǎn)成ModelRetry——也就是說(shuō)模型一次越界的調(diào)用不會(huì)直接終結(jié) run而是觸發(fā)模型帶著錯(cuò)誤信息重試直到產(chǎn)出合法請(qǐng)求后才可能發(fā)出終止成功事件。歸一化函數(shù)_validate_and_normalize_tool_args具體執(zhí)行的護(hù)欄包括字段數(shù)不超過(guò)max_fields動(dòng)作為空時(shí)補(bǔ)默認(rèn)Submit動(dòng)作數(shù)不超過(guò)max_actionsquestion/markdown/各 label 的長(zhǎng)度上限字段類(lèi)型必須在allowed_field_types內(nèi)未開(kāi)allow_file_fields時(shí)拒絕文件字段layer.py。另一個(gè)值得理解的細(xì)節(jié)工具函數(shù)本體_never_executed_tool只會(huì)拋出RuntimeErrorlayer.py因?yàn)樵摴ぞ咄ㄟ^(guò)_prepare_tool_definition被改寫(xiě)成kindexternal的 deferred 工具layer.py參數(shù) schema 直接取自AskHumanToolArgs.model_json_schema()。它的設(shè)計(jì)意圖就是“永遠(yuǎn)不該在首次 run 中執(zhí)行”真正的返回值來(lái)自人類(lèi)經(jīng)后續(xù) run 注入。處理延遲的人類(lèi)請(qǐng)求像處理普通事件一樣流式或輪詢 run 事件。成功的最終回答帶event.data.output成功的人類(lèi)請(qǐng)求帶event.data.deferred_tool_call兩者恰好只有一個(gè)分支被置值runner 中以result_kind區(qū)分見(jiàn) runner.pydeferred_call None snapshot None async for event in client.stream_events(run_id): if event.type ! run_succeeded: continue snapshot event.data.session_snapshot if event.data.deferred_tool_call is not None: deferred_call event.data.deferred_tool_call else: final_output event.data.output break if deferred_call is not None: # 渲染你自己的面向人類(lèi)的表單、入隊(duì)通知、暫停外層工作流 # 或把請(qǐng)求存起來(lái)稍后處理。Dify Agent 不負(fù)責(zé)這部分。 print(deferred_call.tool_call_id, deferred_call.args)典型的延遲載荷長(zhǎng)這樣{ tool_call_id: call_01H..., tool_name: ask_human, args: { title: Deployment approval, question: Can we deploy version 2026.06.10 to production now?, fields: [ { type: paragraph, name: comment, label: Approval comment, required: false } ], actions: [ {id: approve, label: Approve, style: primary}, {id: reject, label: Reject, style: destructive} ], urgency: normal }, metadata: { layer_type: dify.ask_human, tool_name: ask_human, schema_version: 1 } }metadata的構(gòu)造對(duì)應(yīng)build_deferred_tool_call_payloadlayer.py其中schema_version當(dāng)前為 1該方法還強(qiáng)制三條約束不支持 approval 請(qǐng)求、每次 run 恰好一個(gè) deferred call當(dāng)前版本為 MVP 限制、工具名必須與配置的tool_name一致——這三條正是后續(xù)排障表中故障癥狀的直接來(lái)源。安全提醒a(bǔ)rgs是模型生成的內(nèi)容。渲染給最終用戶之前必須做校驗(yàn)與凈化尤其markdown字段按不可信的用戶可見(jiàn)內(nèi)容對(duì)待。用人類(lèi)結(jié)果恢復(fù) run客戶端收集到人類(lèi)答案后用三要素創(chuàng)建新 run上一次的session_snapshot仍然包含 history layer 與 ask-human layer 的匹配 composition同名同序deferred_tool_results.calls[tool_call_id]中放入人類(lèi)結(jié)果from dify_agent.layers.ask_human import AskHumanToolResult from dify_agent.protocol import DeferredToolResultsPayload human_result AskHumanToolResult( statussubmitted, action{id: approve, label: Approve}, values{comment: Approved for the planned window.}, messageThe human approved the deployment., ) resume_request CreateRunRequest( compositioncomposition_with_same_layer_names_and_order, session_snapshotsnapshot, deferred_tool_resultsDeferredToolResultsPayload( calls{deferred_call.tool_call_id: human_result.model_dump(modejson)}, ), )恢復(fù)結(jié)果的形狀由AskHumanToolResult定義schema.pystatus取值為submitted/timeout/cancelled/unavailable之一除status外還有可選的action含合法標(biāo)識(shí)符id與非空l(shuí)abel、values字段名到值、message與rendered_content。Dify Agent 會(huì)把提供的結(jié)果作為原 external 工具調(diào)用的返回值交回 pydantic-ai模型隨后繼續(xù)運(yùn)行?；謴?fù)的 run 可能產(chǎn)出最終output也可能再次產(chǎn)出deferred_tool_call——即 Agent 還需要又一輪人類(lèi)交互。runner 在恢復(fù) run 中會(huì)跳過(guò)新的 user 輸入注入直接以deferred_tool_results驅(qū)動(dòng)模型runner.py。超時(shí)與“人類(lèi)不可用”也應(yīng)作為工具結(jié)果回傳而不是當(dāng)作 Agent run 失敗處理{ status: timeout, action: {id: __timeout, label: Timeout}, values: {}, message: The human did not respond before the workflow timeout. }客戶端職責(zé)邊界ask-human layer 刻意把產(chǎn)品決策留給調(diào)用方?？蛻舳吮仨氉孕袥Q定如何持久化延遲調(diào)用并與面向人類(lèi)的任務(wù)做關(guān)聯(lián)如何渲染并凈化請(qǐng)求中的字段/動(dòng)作如何選擇接收人、渠道與超時(shí)策略授權(quán)誰(shuí)可以作答如何把人類(lèi)提交轉(zhuǎn)換為AskHumanToolResult如何攜返回的session_snapshot與匹配 composition 恢復(fù) run。反過(guò)來(lái)有一條安全紅線不要把收件人郵箱、workspace 成員 id、公開(kāi) URL、鑒權(quán) token、超時(shí)策略放進(jìn)工具參數(shù)。面向模型的請(qǐng)求是不可信內(nèi)容不應(yīng)讓它反過(guò)來(lái)控制投遞或授權(quán)——這正是DifyAskHumanLayerConfig文檔字符串強(qiáng)調(diào)“Delivery, recipient selection, timeout policy, and other operational behavior are intentionally out of scope”的動(dòng)機(jī)configs.py。排障速查表癥狀檢查項(xiàng)run 報(bào)Deferred tool results require a history layer補(bǔ)上historylayer并攜帶上一次 snapshot 恢復(fù)對(duì)應(yīng) runner.py 的校驗(yàn)run 報(bào)pending tool call can be resumed在首次產(chǎn)生 deferred 調(diào)用的 run 中保持 history layer 處于激活狀態(tài)runner.pyrun 報(bào)exactly one deferred call當(dāng)前版本每次 run 僅支持一個(gè) ask-human 調(diào)用應(yīng)提示模型一次只問(wèn)一個(gè)問(wèn)題layer.pyrun 報(bào)tool name must be ...使用配置的tool_name不要只在下游表單代碼里改名layer.py文件字段被拒絕設(shè)置allow_file_fieldsTrue并在allowed_field_types中包含file或file-listconfigs.pyrun_succeeded.data.output缺失檢查run_succeeded.data.deferred_tool_call——這是“人類(lèi)請(qǐng)求成功”不是 run 失敗小結(jié)ask-human layer 把“Agent 何時(shí)該停下來(lái)問(wèn)人”這件事收斂成一個(gè)模型可見(jiàn)的 external deferred tool配置層用DifyAskHumanLayerConfig聲明護(hù)欄服務(wù)端硬上限兜底運(yùn)行時(shí)層把工具改寫(xiě)為kindexternal、以 prompt 提示 雙重校驗(yàn)ModelRetry 歸一化保證請(qǐng)求合法終止事件用deferred_tool_call與output互斥地表達(dá) run 結(jié)果?？蛻舳藙t承擔(dān)投遞、授權(quán)、渲染與恢復(fù)的全部產(chǎn)品職責(zé)用session_snapshot 相同 composition deferred_tool_results完成閉環(huán)。相關(guān)實(shí)現(xiàn)集中在 dify-agent/src/dify_agent/layers/ask_human/ 包c(diǎn)onfigs.py/schema.py/layer.pyrunner 側(cè)的分支與校驗(yàn)在 dify-agent/src/dify_agent/runtime/runner.py配套文檔為 dify-agent/docs/dify-agent/user-manual/ask-human-layer/index.md?！久赓M(fèi)下載鏈接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/di/dify創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Dify Agent Ask Human Layer：讓模型以結(jié)構(gòu)化方式向人類(lèi)發(fā)起輸入請(qǐng)求的完整機(jī)制
Dify Agent Ask Human Layer讓模型以結(jié)構(gòu)化方式向人類(lèi)發(fā)起輸入請(qǐng)求的完整機(jī)制【免費(fèi)下載鏈接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/di/dify本篇圍繞 Dify Agent 的 ask-human layerdify.ask_human展開(kāi)它向模型暴露一個(gè) external deferred tool使 Agent 能在當(dāng)前 run 無(wú)法繼續(xù)時(shí)以結(jié)構(gòu)化請(qǐng)求形式向人類(lèi)要信息并將該請(qǐng)求作為deferred_tool_call隨run_succeeded事件返回給客戶端。讀完本文你將掌握如何組裝包含該 layer 的CreateRunRequest、理解每個(gè)配置字段的護(hù)欄語(yǔ)義、處理延遲工具調(diào)用deferred call并攜人類(lèi)結(jié)果恢復(fù) run 的完整閉環(huán)以及各故障癥狀的排查方法。層契約它做什么、不做什么ask-human layer 的定位是“模型可見(jiàn)的工具層”而不是消息投遞系統(tǒng)。層契約要點(diǎn)如下屬性值Type iddify.ask_human常用 layer 名稱(chēng)ask_humanConfig DTODifyAskHumanLayerConfig模型可見(jiàn)工具默認(rèn)ask_human可用tool_name配置工具類(lèi)型pydantic-aiexternaldeferred tool終止事件run_succeeded終止載荷分支run_succeeded.data.deferred_tool_call關(guān)鍵在于“不暫?！钡恼Z(yǔ)義Agent run 不會(huì)進(jìn)入 paused 狀態(tài)。當(dāng)模型調(diào)用 ask-human 工具時(shí)當(dāng)前 run 以deferred_tool_call代替普通output成功結(jié)束把延遲調(diào)用轉(zhuǎn)成面向人類(lèi)的流程、收集結(jié)果、再發(fā)起帶deferred_tool_results的新 run全部是客戶端的職責(zé)。從源碼 layer.py 的模塊注釋也能印證這一設(shè)計(jì)layer 只貢獻(xiàn)“一個(gè)可選 external 工具 一段 prompt 提示”工具在首次 run 中絕不執(zhí)行 Python下游系統(tǒng)自行決定投遞、接收人、超時(shí)與授權(quán)?；A(chǔ)用法把 layer 加入 run composition將 ask-human layer 與 prompt、history、LLM 以及可選的結(jié)構(gòu)化輸出 layer 放在同一個(gè) composition 中from agenton_collections.layers.plain import PromptLayerConfig from agenton_collections.layers.pydantic_ai import PYDANTIC_AI_HISTORY_LAYER_TYPE_ID from dify_agent.layers.ask_human import DIFY_ASK_HUMAN_LAYER_TYPE_ID, DifyAskHumanLayerConfig from dify_agent.layers.dify_plugin import DifyPluginLLMLayerConfig from dify_agent.layers.execution_context import ( DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, DifyExecutionContextLayerConfig, ) from dify_agent.protocol import DIFY_AGENT_HISTORY_LAYER_ID, DIFY_AGENT_MODEL_LAYER_ID from dify_agent.protocol.schemas import CreateRunRequest, RunComposition, RunLayerSpec request CreateRunRequest( compositionRunComposition( layers[ RunLayerSpec( nameprompt, typeplain.prompt, configPromptLayerConfig( prefixYou can ask a human only when the missing decision is required to continue., userReview the deployment plan and proceed only after getting the required approval., ), ), RunLayerSpec( nameexecution_context, typeDIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, configDifyExecutionContextLayerConfig( tenant_idreplace-with-tenant-id, user_idreplace-with-user-id, user_fromaccount, app_idreplace-with-app-id, agent_modesingle_step, invoke_fromdebugger, ), ), RunLayerSpec( nameDIFY_AGENT_HISTORY_LAYER_ID, typePYDANTIC_AI_HISTORY_LAYER_TYPE_ID, ), RunLayerSpec( nameask_human, typeDIFY_ASK_HUMAN_LAYER_TYPE_ID, configDifyAskHumanLayerConfig( max_fields4, max_actions2, allowed_field_types[paragraph, select], allow_file_fieldsFalse, ), ), RunLayerSpec( nameDIFY_AGENT_MODEL_LAYER_ID, typedify.plugin.llm, deps{execution_context: execution_context}, configDifyPluginLLMLayerConfig( plugin_idlanggenius/openai, model_provideropenai, modelgpt-5.2, ), ), ] ) )組合中各 layer 的角色plain.prompt負(fù)責(zé)業(yè)務(wù)指令execution_context提供租戶/用戶/應(yīng)用上下文PYDANTIC_AI_HISTORY_LAYER_TYPE_ID提供消息歷史dify.plugin.llm是模型 layer通過(guò)deps消費(fèi) execution_context layer。history layer 是恢復(fù)語(yǔ)義的硬前提。只要預(yù)期在人類(lèi)回答后繼續(xù)對(duì)話就必須包含 history layer。懸而未決的工具調(diào)用被存放在 pydantic-ai 消息歷史里因此恢復(fù) run 需要兩樣?xùn)|西上一次返回的session_snapshot以及保持 history layer 仍存在的同一邏輯 composition。runner 側(cè)對(duì)此有明確校驗(yàn)——見(jiàn) runner.pyif deferred_tool_results is not None and history_layer is None: raise AgentRunValidationError( Deferred tool results require a history layer with prior message history. )此外 composition 層面只允許存在一個(gè) ask-human layervalidate_ask_human_layer_compositionlayer.py會(huì)拒絕同名 type 的多個(gè) layer。配置字段與雙層護(hù)欄DifyAskHumanLayerConfig只控制“面向模型的工具身份與護(hù)欄”刻意不包含任何投遞配置。字段定義見(jiàn) configs.py字段類(lèi)型默認(rèn)值含義enabledboolTrue為 false 時(shí)該 layer 既不暴露工具也不注入 prompt 引導(dǎo)tool_namestrask_human模型可見(jiàn)的工具名必須是合法標(biāo)識(shí)符tool_descriptionstr \| None默認(rèn)描述文本可選的模型可見(jiàn)工具描述max_fieldsint8模型可請(qǐng)求的字段數(shù)上限0表示僅允許動(dòng)作型請(qǐng)求max_actionsint4模型可請(qǐng)求的人類(lèi)動(dòng)作數(shù)上限allowed_field_typeslist[paragraph \| select \| file \| file-list][paragraph, select]運(yùn)行時(shí)校驗(yàn)接受的字段類(lèi)型allow_file_fieldsboolFalse未開(kāi)啟時(shí)文件字段類(lèi)型直接拒絕開(kāi)啟后還須列入allowed_field_typesmax_markdown_charsint8000可選markdown正文的最大長(zhǎng)度max_question_charsint1000必填question的最大長(zhǎng)度max_field_label_charsint120每個(gè)字段 label 的最大長(zhǎng)度max_action_label_charsint80每個(gè)動(dòng)作 label 的最大長(zhǎng)度配置上限之上還有服務(wù)端硬上限兩者取較小值生效若配置超過(guò)硬上限請(qǐng)求校驗(yàn)階段即失敗、run 無(wú)法執(zhí)行。硬上限常量定義在 configs.py字段硬上限max_fields16max_actions8max_markdown_chars20000max_question_chars4000max_field_label_chars200max_action_label_chars120實(shí)現(xiàn)上有兩處值得注意tool_name必須是合法標(biāo)識(shí)符。字段校驗(yàn)器用正則^[A-Za-z_][A-Za-z0-9_]*$全匹配校驗(yàn)configs.py非法命名會(huì)在配置校驗(yàn)時(shí)直接報(bào)錯(cuò)。文件字段的“雙開(kāi)關(guān)”策略。_validate_file_field_policy模型校驗(yàn)器要求只有當(dāng)allow_file_fieldsTrue且allowed_field_types中包含file/file-list時(shí)文件字段才合法allow_file_fieldsFalse卻在允許列表里寫(xiě)了文件類(lèi)型配置本身就會(huì)被拒絕configs.py。文件字段變體目前屬于“為前向兼容預(yù)留的詞匯表”默認(rèn)不開(kāi)放。layer 會(huì)把這些上限自動(dòng)轉(zhuǎn)寫(xiě)成 prompt 提示。build_prompt_hintlayer.py生成的文本包含允許的字段類(lèi)型、文件上傳是否啟用、字段/動(dòng)作數(shù)上限、question/markdown與 label 長(zhǎng)度限制并告知模型“若省略 actions系統(tǒng)會(huì)自動(dòng)補(bǔ)一個(gè) primary 樣式的 Submit 動(dòng)作”?？蛻舳艘虼藷o(wú)需在系統(tǒng)提示里重復(fù)羅列限制但可追加業(yè)務(wù)側(cè)指導(dǎo)例如何時(shí)才適合問(wèn)人。模型能請(qǐng)求什么AskHumanToolArgs 契約啟用后layer 暴露一個(gè) external deferred tool其參數(shù)形狀為AskHumanToolArgsschema.py字段類(lèi)型含義titlestr \| None面向人類(lèi)請(qǐng)求的可選短標(biāo)題questionstr必填的問(wèn)題/指令不能為空白markdownstr \| None可選的較長(zhǎng) Markdown 正文應(yīng)按不可信的用戶可見(jiàn)內(nèi)容對(duì)待fieldslist[AskHumanField]供人類(lèi)填寫(xiě)的可選結(jié)構(gòu)化字段name 全局唯一actionslist[AskHumanAction]可選的動(dòng)作按鈕若省略Dify Agent 歸一化為單個(gè) primarySubmit動(dòng)作urgencynormal \| high給下游系統(tǒng)的提示不是投遞策略支持的字段變體判別字段為typeparagraph自由文本輸入支持placeholder、defaultselect單選輸入選項(xiàng)value必須非空且唯一default必須命中某個(gè)選項(xiàng)值schema.pyfile單文件輸入僅在允許文件字段時(shí)可用file-list多文件輸入僅在允許文件字段時(shí)可用可配max_filesschema.py。所有字段和動(dòng)作都執(zhí)行extraforbid即不允許攜帶未知屬性字段name與動(dòng)作id必須滿足標(biāo)識(shí)符規(guī)則。工具參數(shù)在模型調(diào)用后還會(huì)被再校驗(yàn)一次。校驗(yàn)入口_validate_tool_argslayer.py捕獲ValidationError/ValueError并轉(zhuǎn)成ModelRetry——也就是說(shuō)模型一次越界的調(diào)用不會(huì)直接終結(jié) run而是觸發(fā)模型帶著錯(cuò)誤信息重試直到產(chǎn)出合法請(qǐng)求后才可能發(fā)出終止成功事件。歸一化函數(shù)_validate_and_normalize_tool_args具體執(zhí)行的護(hù)欄包括字段數(shù)不超過(guò)max_fields動(dòng)作為空時(shí)補(bǔ)默認(rèn)Submit動(dòng)作數(shù)不超過(guò)max_actionsquestion/markdown/各 label 的長(zhǎng)度上限字段類(lèi)型必須在allowed_field_types內(nèi)未開(kāi)allow_file_fields時(shí)拒絕文件字段layer.py。另一個(gè)值得理解的細(xì)節(jié)工具函數(shù)本體_never_executed_tool只會(huì)拋出RuntimeErrorlayer.py因?yàn)樵摴ぞ咄ㄟ^(guò)_prepare_tool_definition被改寫(xiě)成kindexternal的 deferred 工具layer.py參數(shù) schema 直接取自AskHumanToolArgs.model_json_schema()。它的設(shè)計(jì)意圖就是“永遠(yuǎn)不該在首次 run 中執(zhí)行”真正的返回值來(lái)自人類(lèi)經(jīng)后續(xù) run 注入。處理延遲的人類(lèi)請(qǐng)求像處理普通事件一樣流式或輪詢 run 事件。成功的最終回答帶event.data.output成功的人類(lèi)請(qǐng)求帶event.data.deferred_tool_call兩者恰好只有一個(gè)分支被置值runner 中以result_kind區(qū)分見(jiàn) runner.pydeferred_call None snapshot None async for event in client.stream_events(run_id): if event.type ! run_succeeded: continue snapshot event.data.session_snapshot if event.data.deferred_tool_call is not None: deferred_call event.data.deferred_tool_call else: final_output event.data.output break if deferred_call is not None: # 渲染你自己的面向人類(lèi)的表單、入隊(duì)通知、暫停外層工作流 # 或把請(qǐng)求存起來(lái)稍后處理。Dify Agent 不負(fù)責(zé)這部分。 print(deferred_call.tool_call_id, deferred_call.args)典型的延遲載荷長(zhǎng)這樣{ tool_call_id: call_01H..., tool_name: ask_human, args: { title: Deployment approval, question: Can we deploy version 2026.06.10 to production now?, fields: [ { type: paragraph, name: comment, label: Approval comment, required: false } ], actions: [ {id: approve, label: Approve, style: primary}, {id: reject, label: Reject, style: destructive} ], urgency: normal }, metadata: { layer_type: dify.ask_human, tool_name: ask_human, schema_version: 1 } }metadata的構(gòu)造對(duì)應(yīng)build_deferred_tool_call_payloadlayer.py其中schema_version當(dāng)前為 1該方法還強(qiáng)制三條約束不支持 approval 請(qǐng)求、每次 run 恰好一個(gè) deferred call當(dāng)前版本為 MVP 限制、工具名必須與配置的tool_name一致——這三條正是后續(xù)排障表中故障癥狀的直接來(lái)源。安全提醒a(bǔ)rgs是模型生成的內(nèi)容。渲染給最終用戶之前必須做校驗(yàn)與凈化尤其markdown字段按不可信的用戶可見(jiàn)內(nèi)容對(duì)待。用人類(lèi)結(jié)果恢復(fù) run客戶端收集到人類(lèi)答案后用三要素創(chuàng)建新 run上一次的session_snapshot仍然包含 history layer 與 ask-human layer 的匹配 composition同名同序deferred_tool_results.calls[tool_call_id]中放入人類(lèi)結(jié)果from dify_agent.layers.ask_human import AskHumanToolResult from dify_agent.protocol import DeferredToolResultsPayload human_result AskHumanToolResult( statussubmitted, action{id: approve, label: Approve}, values{comment: Approved for the planned window.}, messageThe human approved the deployment., ) resume_request CreateRunRequest( compositioncomposition_with_same_layer_names_and_order, session_snapshotsnapshot, deferred_tool_resultsDeferredToolResultsPayload( calls{deferred_call.tool_call_id: human_result.model_dump(modejson)}, ), )恢復(fù)結(jié)果的形狀由AskHumanToolResult定義schema.pystatus取值為submitted/timeout/cancelled/unavailable之一除status外還有可選的action含合法標(biāo)識(shí)符id與非空l(shuí)abel、values字段名到值、message與rendered_content。Dify Agent 會(huì)把提供的結(jié)果作為原 external 工具調(diào)用的返回值交回 pydantic-ai模型隨后繼續(xù)運(yùn)行?；謴?fù)的 run 可能產(chǎn)出最終output也可能再次產(chǎn)出deferred_tool_call——即 Agent 還需要又一輪人類(lèi)交互。runner 在恢復(fù) run 中會(huì)跳過(guò)新的 user 輸入注入直接以deferred_tool_results驅(qū)動(dòng)模型runner.py。超時(shí)與“人類(lèi)不可用”也應(yīng)作為工具結(jié)果回傳而不是當(dāng)作 Agent run 失敗處理{ status: timeout, action: {id: __timeout, label: Timeout}, values: {}, message: The human did not respond before the workflow timeout. }客戶端職責(zé)邊界ask-human layer 刻意把產(chǎn)品決策留給調(diào)用方?？蛻舳吮仨氉孕袥Q定如何持久化延遲調(diào)用并與面向人類(lèi)的任務(wù)做關(guān)聯(lián)如何渲染并凈化請(qǐng)求中的字段/動(dòng)作如何選擇接收人、渠道與超時(shí)策略授權(quán)誰(shuí)可以作答如何把人類(lèi)提交轉(zhuǎn)換為AskHumanToolResult如何攜返回的session_snapshot與匹配 composition 恢復(fù) run。反過(guò)來(lái)有一條安全紅線不要把收件人郵箱、workspace 成員 id、公開(kāi) URL、鑒權(quán) token、超時(shí)策略放進(jìn)工具參數(shù)。面向模型的請(qǐng)求是不可信內(nèi)容不應(yīng)讓它反過(guò)來(lái)控制投遞或授權(quán)——這正是DifyAskHumanLayerConfig文檔字符串強(qiáng)調(diào)“Delivery, recipient selection, timeout policy, and other operational behavior are intentionally out of scope”的動(dòng)機(jī)configs.py。排障速查表癥狀檢查項(xiàng)run 報(bào)Deferred tool results require a history layer補(bǔ)上historylayer并攜帶上一次 snapshot 恢復(fù)對(duì)應(yīng) runner.py 的校驗(yàn)run 報(bào)pending tool call can be resumed在首次產(chǎn)生 deferred 調(diào)用的 run 中保持 history layer 處于激活狀態(tài)runner.pyrun 報(bào)exactly one deferred call當(dāng)前版本每次 run 僅支持一個(gè) ask-human 調(diào)用應(yīng)提示模型一次只問(wèn)一個(gè)問(wèn)題layer.pyrun 報(bào)tool name must be ...使用配置的tool_name不要只在下游表單代碼里改名layer.py文件字段被拒絕設(shè)置allow_file_fieldsTrue并在allowed_field_types中包含file或file-listconfigs.pyrun_succeeded.data.output缺失檢查run_succeeded.data.deferred_tool_call——這是“人類(lèi)請(qǐng)求成功”不是 run 失敗小結(jié)ask-human layer 把“Agent 何時(shí)該停下來(lái)問(wèn)人”這件事收斂成一個(gè)模型可見(jiàn)的 external deferred tool配置層用DifyAskHumanLayerConfig聲明護(hù)欄服務(wù)端硬上限兜底運(yùn)行時(shí)層把工具改寫(xiě)為kindexternal、以 prompt 提示 雙重校驗(yàn)ModelRetry 歸一化保證請(qǐng)求合法終止事件用deferred_tool_call與output互斥地表達(dá) run 結(jié)果?？蛻舳藙t承擔(dān)投遞、授權(quán)、渲染與恢復(fù)的全部產(chǎn)品職責(zé)用session_snapshot 相同 composition deferred_tool_results完成閉環(huán)。相關(guān)實(shí)現(xiàn)集中在 dify-agent/src/dify_agent/layers/ask_human/ 包c(diǎn)onfigs.py/schema.py/layer.pyrunner 側(cè)的分支與校驗(yàn)在 dify-agent/src/dify_agent/runtime/runner.py配套文檔為 dify-agent/docs/dify-agent/user-manual/ask-human-layer/index.md?！久赓M(fèi)下載鏈接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/di/dify創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考