Dify多Agent协作架构：任务编排实战指南
在Dify中构建多Agent协作系统，需要将Agent（自治执行单元）、Workflow（条件驱动拓扑结构）和Orchestrator（调度中枢）彻底解耦。三者各司其职，通过动态协商完成复杂任务。
要在Dify中打造可投入生产的多Agent系统，必须先避开一个典型误区：试图让单一Agent处理所有任务，或手动编码固定执行路径。正确做法是，让不同角色的Agent基于结构化消息自主协商下一步行动。核心要点有三：清晰界定每个Agent的职责范围；利用Workflow构建动态路由拓扑；由Orchestrator在后台承担上下文管理和熔断预案的调度职责。三者缺一不可。
Agent、Workflow与Orchestrator的角色解耦原理
首先看Agent。它并非一个“万能模型”，而是一个“绑定了专属提示词、工具集合、知识库以及记忆范围的独立执行单元”。Agent接收结构化输入（例如消息中包含sender、content、tool_calls等字段），并输出一个带有status字段的JSON结果。它不关心上游来源或下游去向——这些都由上层调度接管。
再看Workflow。它不是执行脚本，而是一张“声明式拓扑图”。这张图只定义触发条件：在什么情况下由哪个节点触发哪个下游节点，例如“如果A任务成功则启动B”。至于A或B的具体执行逻辑，Workflow不负责。注意，YAML中的condition字段仅支持基于上游输出的键值进行字符串匹配或布尔判断，不支持复杂Python表达式——平台会直接忽略。
最后是Orchestrator。作为隐形的调度中枢，它承担最关键的工作：每次用户请求到达时，自动生成唯一workflow_ref，并将该引用注入所有参与Agent的记忆空间，使整个流程感知同一会话上下文。同时，Orchestrator全局监控：若某个Agent超时（默认30秒）或抛出异常，立即触发预设的熔断或降级策略。要与之正确协作，每个Agent返回的响应体必须包含明确的"status": "success"或"status": "error"字段，否则Orchestrator无法判定执行结果。
创建具备协作能力的Agent实例
操作步骤直观：登录Dify控制台 → 进入「工作室」→ 点击「创建应用」→ 选择「Agent」类型。配置每个Agent时，需重点落实以下三项关键设置。
第一，【role描述必须精确到动词+领域+输出约束】。避免编写“负责订单查询”这类模糊表述，应明确为“从ERP系统拉取近7天订单原始数据，返回标准JSON数组，每项包含order_id、amount、status字段”。描述越具体，Agent行为越可控。第二，模型选择需按任务匹配。路由、解析等轻量任务，gpt-4o-mini即可胜任；内容生成与校验等关键环节，再启用gpt-4o更稳妥。第三，工具绑定应克制，仅绑定该Agent实际调用的API或插件，过多工具反而会干扰决策。
保存前务必开启「Shared Memory」开关，并指定一个全局唯一的键名（如session_id）。这是Agent之间传递上下文信息的唯一桥梁。若不开启，每个Agent将独立处理会话，协作无从建立。
使用YAML定义条件驱动的工作流
接下来进入配置环节。进入「Orchestration → Workflows」→ 新建工作流 → 切换至「YAML 编排模式」。
第一步，声明入口Agent以及所有参与者。以下是一个内容创作流程的YAML示例：
name: content_creation_flow
entry_agent: planner
agents:
- name: planner
role: "将用户需求分解为可执行子任务，返回JSON格式的任务列表，包含research、draft、review"
- name: researcher
role: "调用知识库检索关键词，返回包含source_url的摘要集合"
- name: writer
role: "基于research结果生成初稿，字数严格控制在800±50字"
第二步，定义条件路由逻辑。这是Workflow的核心，决定了在何种条件下由哪个Agent接替执行。
workflow:
start: planner
edges:
- from: planner
to: researcher
condition: "{{planner.tasks.includes('research')}}"
- from: researcher
to: writer
condition: "{{researcher.status == 'success'}}"
第三步，粘贴完整的YAML配置，点击「部署」。Dify Runtime会自动校验格式并注册到消息总线，无需重启服务。
验证多Agent协同是否实际生效
部署完成后，如何确认系统是真正协同而非简单串行？以下两种验证方法可供参考。
方法一：使用UI调试面板。在Workflow编辑页点击右上角「调试」按钮，输入一个用户原始问题，然后观察「Execution Trace」面板。重点关注三点：每个Agent节点是否显示绿色健康状态（success）；上下游的data字段是否自动传递（例如researcher检索到的urls是否出现在writer的输入中）；时间戳是否呈现有序流水线，而非并发执行。
方法二：调用管理API查看日志。执行curl命令，检查返回的每个span的attributes中，workflow_ref与shared_memory_key字段值是否一致。若发现某Agent返回的JSON缺少status字段，或trace中shared_memory_key为空，则说明协作链路断开，需返回修改对应Agent的输出模板。
配置可观测性与异常熔断机制
系统上线只是开始，监控与容灾能力才是工程水平的体现。在Dify根目录的.env文件中添加以下两行配置即可开启追踪：
DIFY_WORKFLOW_TRACE_ENABLED=true
DIFY_WORKFLOW_TRACE_SAMPLING_RATE=1.0
重启服务后，所有Agent调用链路将以OpenTelemetry格式生成span，可直接接入Jaeger或Datadog等监控平台。需持续关注以下核心指标：planner对意图解析的准确率、下游Agent在30秒内的超时率、以及路由条件匹配失败的次数。任一指标异常上升，均表明职责划分存在缺陷或消息契约失效。
熔断逻辑不能嵌入YAML，必须通过环境变量管控。例如，设置DIFY_ORCHESTRATOR_FALLBACK_AGENT=recovery_bot，可在任意Agent连续失败3次后自动切换到备用Agent；设置DIFY_ORCHESTRATOR_RETRY_LIMIT=2，则对HTTP调用类Agent自动重试2次，而对LLM类Agent不重试，以避免重复调用放大幻觉问题。