使用 Dify 绘制 Agent 流程时需要注意什么？

核心回答

在 Dify 中，最容易遗漏的是：连线控制执行走向，节点的变量选择器才指定读取什么数据。应对照每个节点的输入、输出和错误处理配置，检查它在当前路径下能否取得正确类型的值，再用实际运行记录确认。

例如批量处理文档，要先确认提取节点输出的是单份文本还是文本数组，迭代节点逐项读取哪一项，模型结果怎样汇总，以及提取失败或空文件时走哪里。不能因为画布能连到输出节点，就认定所有文档都处理成功。

变量引用要对应运行时的数据

当前实现由工作流配置构建执行图，并准备 VariablePool 与 RuntimeState。初次运行会把系统变量、环境变量和起始输入放进变量池，节点再通过选择器读取需要的值。工作流运行准备可以看到这个过程。具体图调度由该版本接入的 graphon 承接，不能把其他框架的默认行为直接套过来。

因此，修改节点输出字段、输入类型或分支后，要一起核对下游引用。单节点调试中的缓存值可以帮助定位问题，但不能证明正式执行时上游也会产生同样的值；需要用新的实际输入跑完整路径。

检索结果和工具参数要明确映射

知识检索节点按选择器读取查询或附件，并检查查询是否为字符串、附件是否为文件或文件数组；类型不符会返回失败。检索后把结果作为 result 数组输出给下游，而不是自动把全部资料附到任意模型节点。知识检索节点说明了输入检查和输出结构。

画布中还需核对数据集范围、查询来源、Top K、阈值及是否启用重排，并在模型节点配置实际使用的检索上下文。工具节点同样要核对参数来自用户输入、上游字段还是固定配置，返回值怎样进入下游；密钥由受控的工具配置提供，不能让模型自行生成。

分支与迭代要连同错误结果一起设计

Dify 支持的错误处理包括停止、默认值和失败分支。把失败改成默认值只是让流程能继续，不代表业务步骤已经完成：例如查询失败时返回空字符串，后续模型不能据此声称“未查到任何记录”。

迭代还应区分“整批停止”“保留失败位置继续”和“过滤失败输出继续”等策略。过滤掉失败项后，结果数量可能少于输入数量，不能再仅凭数组下标认定结果与原始任务一一对应。并行度也要结合工具限流、费用和共享资源确定。实际可用配置应按部署版本检查。

如果加入人工输入节点，还要测试等待、提交、超时和续跑路径。人工提交值、旧表单默认值与暂停时的变量状态不是同一份数据；不能把重新运行整条流程当成恢复，也不能据此保证外部写操作不会重复。

发布前检查实际结果，而非只看绿色节点

先用单节点结果定位字段、类型和工具响应，再用正常及异常任务检查整条流程。记录期望输出和实际输出，检查是否走了正确分支、是否遗漏条目、是否重复调用外部写操作，以及耗时和调用成本是否在预算内。

编辑后的工作流需要发布更新，正式入口还应再测一次；调试通过不能代替发布版本与正式凭据的验证。对于多轮任务，也应分别检查 Chatflow 的会话状态和单次 Workflow 的输入，避免把某次调试保留的变量当成所有新运行都会具备的值。

对应教程

• 《Dify 案例：客户投诉分类助手》：回看开始输入、分类器输出、模型提示词变量与消息工具参数的衔接；本文进一步展开类型、错误路径和发布验证。

参考资料

• 国内：Datawhale：Dify 智能体搭建实战指南：借鉴分类器、模型与工具分别组成不同任务路径的案例，解释节点职责和工具配置需要与任务边界对应。
• 国内：JavaGuide：AI 工作流中的 Workflow、Graph 与 Loop：采用节点、边与状态的分工，以及错误出口、循环预算和回放检查的讨论，解释画布连接与数据契约为何需要分别核对。
• 国内：zero2Agent：工程化实战与踩坑：参考重复工具调用、状态丢失和结构化输出错误的故障，说明为何需要明确变量、格式校验及有限重试；不沿用其中的示例阈值。
• 国内：AgentGuide：如何落地一个可写进简历的 Agent 项目：采用成功条件、预期与实际结果、工具失败和幂等性的检查方法，组织本文提出的整流程验收。
• 国外：Dify：30-Minute Quick Start：参考结构化数组、文件提取、迭代、缓存变量调试和重新发布的操作，解释数据类型衔接及单节点测试与正式入口测试的区别。
• 国外：Dify：Handle Errors：依据停止、默认值、失败分支与迭代错误模式，说明失败后继续执行时应保留什么状态，以及过滤失败项为何会改变输出数量。