在 dify 中构建多 agent 协作系统需解耦 agent（自治单元）、workflow（条件驱动拓扑）与 orchestrator（调度中枢），三者协同实现动态协商执行。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
要在 Dify 中构建可落地的多 Agent 协作系统，必须绕开单智能体硬编码逻辑陷阱，让不同角色的 Agent 基于结构化消息自主协商执行路径，而不是靠人工预设死链路。这要求你准确理解 Agent 的职责封装边界、Workflow 的动态编排机制，以及 Orchestrator 如何在运行时注入会话上下文与熔断策略——三者缺一不可。
理解 Agent、Workflow 与 Orchestrator 的角色解耦
Agent 不是“能干活的模型”，而是【绑定专属提示词、工具集、知识库和记忆作用域的自治单元】。它接收结构化输入（含 sender、content、tool_calls），输出带 status 字段的 JSON，不关心上游是谁、下游去哪。
Workflow 是声明式拓扑定义，不是执行脚本。它只规定“谁在什么条件下触发谁”，不写具体调用逻辑。YAML 中的 condition 字段必须基于上游输出的 key 值做字符串匹配或布尔判断，不能写 Python 表达式。
Orchestrator 是隐藏在后台的调度中枢：自动为每次用户请求生成唯一 workflow_ref，将该 ref 注入所有参与 Agent 的 memory scope，同时监听超时（固定 30 秒）、失败状态并启动 fallback 策略。你无法直接调用它，但必须确保每个 Agent 响应体含 "status": "success" 或 "error" 字段，否则 Orchestrator 无法识别执行结果。
创建可协作的 Agent 实例
登录 Dify 控制台 → 进入「工作室」→ 点击「创建应用」→ 选择「Agent」类型。
为每个 Agent 明确填写三项核心配置：【role 描述必须精确到动词+领域+输出约束】，例如“从 ERP 系统拉取近 7 天订单原始数据，返回标准 JSON 数组，每项含 order_id、amount、status 字段”；模型选型需匹配职责——gpt-4o-mini 足够处理路由与解析，gpt-4o 更适合生成与校验；工具绑定仅限当前 Agent 实际需要的 API 或插件，多绑会导致决策噪声。
保存前务必启用「Shared Memory」开关，并指定一个全局唯一 key 名（如 session_id），这是后续跨 Agent 传递上下文的唯一通道。不开启则所有 Agent 看到的都是孤立会话。
用 YAML 定义条件驱动的工作流
进入「Orchestration → Workflows」→ 新建工作流 → 切换至「YAML 编排模式」。
第一步：声明入口 Agent 和全部参与者
name: content_creation_flow
entry_agent: planner
agents:
- name: planner
role: "拆解用户需求为子任务，输出 JSON：{'tasks': ['research', 'draft', 'review']}"
- name: researcher
role: "调用知识库搜索关键词，返回带 source_url 的摘要列表"
- name: writer
role: "根据 research 结果生成初稿，严格控制字数在 800±50 字"
第二步：定义条件路由逻辑
Dify 3.9.2更新重点增强系统安全性，引入 Chainguard 安全基础镜像并同步社区版 CVE 修复，同时优化 OpenSearch 向量存储兼容性、插件参数传输机制及 Helm 部署配置。新增工作流模型节点缓存能力，可减少重复凭证查询，显著提升复杂工作流初始化速度，为企业级 AI 应用提供更稳定、高效的运行体验。
workflow:
start: planner
edges:
- from: planner
to: researcher
condition: "{{planner.tasks.includes('research')}}"
- from: researcher
to: writer
condition: "{{researcher.status == 'success'}}"
第三步：粘贴完整 YAML 后点击「部署」。Dify Runtime 将自动校验 schema 并注册消息总线，无需重启服务。
验证协同是否真正生效
方法一：通过 UI 调试面板发起测试请求
在 Workflow 编辑页点击右上角「调试」按钮 → 输入原始用户问题 → 查看 Execution Trace 面板。重点确认三点：每个 Agent 节点是否显示绿色 success 状态；上下游 data 字段是否自动透传（如 researcher 输出的 urls 是否出现在 writer 的 input 中）；时间戳是否呈现流水线式递进而非并发堆叠。
方法二：调用管理 API 获取实时链路日志
执行 curl -H "Authorization: Bearer YOUR_ADMIN_TOKEN" http://localhost:5001/v1/workflows/{workflow_id}/traces | jq '.data[-1].spans[] | select(.name=="agent_exec")'，检查每个 span 的 attributes 是否包含 workflow_ref 和 shared_memory_key 字段值一致。
若发现某 Agent 响应体缺失 status 字段，或 shared_memory_key 在 trace 中为空，则协同中断，必须回退修改对应 Agent 的输出模板。
配置可观测性与异常熔断
在 Dify 根目录的 .env 文件中添加两行：
DIFY_WORKFLOW_TRACE_ENABLED=true
DIFY_WORKFLOW_TRACE_SAMPLING_RATE=1.0
重启服务后，所有 Agent 调用链将生成 OpenTelemetry 格式 span，可直连 Jaeger 或 Datadog。关键指标必须监控：planner 的 intent 解析准确率、下游 Agent 的 30 秒内超时率、router 条件匹配失败次数。任一指标突增都表明职责划分失衡或消息契约破裂。
熔断配置不可写在 YAML 中，必须通过环境变量控制：设置 DIFY_ORCHESTRATOR_FALLBACK_AGENT=recovery_bot 可在任意 Agent 连续失败 3 次后自动切入备用 Agent；设置 DIFY_ORCHESTRATOR_RETRY_LIMIT=2 则对 HTTP 类 Agent 默认重试 2 次，LLM 类 Agent 不重试（避免幻觉叠加）。
