Orchestrator 配置指南

Orchestrator（编排器）是 Sira AI 的核心，负责协调多个 Agent 协同工作。本指南详细讲解 8 种编排模式的配置和使用。

Orchestrator 是什么？

Orchestrator 定义了 Agent 之间的协作方式：

Orchestrator = 编排模式 + Agent组合 + 执行策略 + 配置参数

核心概念

编排引擎：基于 LangGraph 的状态机
状态管理：Redis Checkpointer 持久化
流式执行：双模式——OpenAI / LangGraph / Web 走"直接 yield"高性能 SSE；企微 AI Bot 走 Redis Stream 适配 5 秒回调约束
错误恢复：自动重试和降级

八种编排模式

模式	说明	适用场景	复杂度
Single	单个Agent直接执行	简单问答	⭐
Supervisor	监督者动态调度Worker	复杂任务分解	⭐⭐⭐⭐
Collaboration	多Agent平等协作	多角度分析	⭐⭐⭐
Workflow	预定义固定流程	标准流程	⭐⭐
Conditional	基于规则路由	意图识别	⭐⭐
External	集成Dify/n8n	复用已有应用	⭐⭐
Deep Agents 🆕	高级多步骤任务管理	复杂项目、报告生成	⭐⭐⭐⭐⭐
Knowledge Base 🆕	直答型 RAG（不调度 Agent）	FAQ、政策查询、文档问答	⭐

发布生命周期（草稿 / 发布 / 版本 / 回滚 / 试运行）

无论选哪种编排模式，编排器都遵循同一套草稿 → 发布生命周期，在设计器顶栏操作：

动作	说明
保存草稿	改动先存为草稿（⌘S / Ctrl+S 同效），不影响线上
试运行	不发布就跑一次，可对草稿或已发布版本运行，上线前验证
发布	把草稿正式发布为新版本，需填一段版本说明
版本历史 → 回滚到此	列出所有已发布版本，一键回退

渠道 / Webhook / Cron 只跑「已发布」版本

设计器里的改动只是草稿，不点发布不会生效。线上渠道、Webhook 触发、定时任务跑的始终是上一个已发布版本。

可选审批门

组织启用资源审批后，发布按钮变为提交审核，提交后显示审核中并可撤回审核，审批通过才真正发布。

Single 模式（单体模式）

概述

最简单的模式，一个 Agent 直接处理请求。

用户请求 → Single Orchestrator → Agent → LLM → 响应

适用场景

✅ 简单的问答助手
✅ 单一职责的服务
✅ 快速原型验证
❌ 不适合复杂任务分解
❌ 不适合需要多角度分析

配 Skill 时自动透明路由到 DeepAgents

当所选 Agent 配置了 Skill 包（skill_ids 非空）时，引擎会自动把这次执行交给 DeepAgents 执行器，从而获得 Backend（filesystem / local_shell / sandpod 沙箱）和 Skill 脚本能力。您不需要把编排器改成 DeepAgents 类型，依然在这里选 SINGLE 即可。

创建步骤

步骤 1：进入 Orchestrator 管理

点击 Agent System → Orchestrators
点击 创建 Orchestrator

步骤 2：选择 Single 模式

编排类型选择：SINGLE
填写基本信息：

yaml

名称: simple_qa
显示名称: 简单问答
描述: 单Agent问答系统

步骤 3：配置 Single Agent

在 Single 配置 部分：

yaml

Agent: customer_service  # 选择已创建的Agent

步骤 4：保存和测试

yaml

保存配置 → 创建Application → 测试对话

配置示例

示例 1：客服助手

yaml

Orchestrator:
  名称: customer_service_single
  类型: SINGLE
  配置:
    agent_id: customer_service_agent

Agent:
  名称: customer_service_agent
  模型: gpt-4o
  提示词: "你是专业的客服助手..."
  工具: [知识库]

效果：

用户问题 → Agent 回答
简单直接，响应快

示例 2：技术文档助手

yaml

Orchestrator:
  名称: tech_docs_single
  类型: SINGLE
  配置:
    agent_id: tech_expert

Agent:
  名称: tech_expert
  模型: gpt-4o
  提示词: "你是技术文档专家..."
  工具: [Context7, WebSearch]

效果：

查询最新技术文档
提供代码示例
引用官方文档

多模态支持

✅ 完全支持

yaml

Agent:
  模型类型: [LLM, VISION]

用户输入:
  文本: "分析这张架构图"
  图片: http://example.com/architecture.png

执行流程:
  1. multimodal_content 传递给 Agent
  2. Agent 使用 Vision 模型分析
  3. 返回图片分析结果

最佳实践

✅ 推荐做法：

提示词清晰明确
合理配置工具和知识库
设置合适的 temperature

❌ 避免：

让单个Agent承担过多职责
处理需要多步骤的复杂任务

Supervisor 模式（监督者模式）

概述

Supervisor 动态分解任务，调度多个 Worker Agent 完成。

用户请求 → Supervisor Agent
           ↓
        分析任务
           ↓
    委派 Worker 1 → 完成子任务1
           ↓
    委派 Worker 2 → 完成子任务2
           ↓
    委派 Worker 3 → 完成子任务3
           ↓
        汇总结果 → 响应

适用场景

✅ 复杂任务需要分解
✅ 任务步骤不固定（动态决策）
✅ 需要不同专家协作
❌ 简单固定流程（用 Workflow）
❌ 纯并行任务（用 Collaboration）

核心概念

Supervisor Agent（监督者）

职责：

理解用户需求
分解任务步骤
选择合适的 Worker
汇总最终结果

Worker Agent（工作者）

职责：

接收 Supervisor 委派的任务
完成特定子任务
返回结果给 Supervisor

创建步骤

步骤 1：创建 Supervisor Agent

yaml

Agent 名称: task_supervisor
系统提示词: |
  你是任务协调专家，负责分解复杂任务并调度专家完成。

  【可用专家】
  - data_analyst: 数据分析专家，擅长SQL查询和数据分析
  - report_writer: 报告撰写专家，擅长撰写专业报告
  - chart_maker: 图表制作专家，擅长数据可视化

  【任务分解流程】
  1. 理解用户需求
  2. 拆分为多个子任务
  3. 按顺序委派给合适的专家
  4. 汇总专家的结果

  【委派格式】
  当需要委派任务时，使用以下格式：

  委派给：data_analyst
  任务：分析本月销售数据，计算总销售额和增长率

  【注意事项】
  - 一次只委派一个任务
  - 等待专家完成后再决定下一步
  - 如果任务简单，可以直接回答

步骤 2：创建 Worker Agents

Worker 1: 数据分析专家

yaml

名称: data_analyst
提示词: |
  你是数据分析专家。
  擅长SQL查询、数据清洗、统计分析。
  收到任务后，专注完成数据分析工作。
工具: [Database, Calculator]

Worker 2: 报告撰写专家

yaml

名称: report_writer
提示词: |
  你是报告撰写专家。
  擅长撰写专业的分析报告和业务文档。
  基于数据分析结果，撰写清晰的报告。

Worker 3: 图表制作专家

yaml

名称: chart_maker
提示词: |
  你是数据可视化专家。
  擅长制作各类图表（柱状图、折线图、饼图等）。
  基于数据选择最合适的图表类型。
工具: [ChartGenerator]

步骤 3：创建 Supervisor Orchestrator

yaml

Orchestrator:
  名称: task_decomposition
  类型: SUPERVISOR

Supervisor 配置:
  Supervisor Agent: task_supervisor
  Worker Agents:
    - data_analyst
    - report_writer
    - chart_maker
  启用汇总: ✓

执行流程示例

场景：销售数据分析报告

用户请求：

分析本月销售数据并生成报告，包含图表展示

执行流程：

yaml

Step 1: Supervisor 分析
  思考: 这个任务需要三个步骤
  1. 数据分析（data_analyst）
  2. 撰写报告（report_writer）
  3. 制作图表（chart_maker）

Step 2: 委派 → data_analyst
  任务: "分析本月销售数据，计算总额、增长率、TOP10产品"

  Worker 执行:
    - 查询数据库
    - 计算指标
    - 返回结果: "总销售额500万，环比增长15%..."

Step 3: Supervisor 收到结果
  思考: 数据分析完成，接下来撰写报告

Step 4: 委派 → report_writer
  任务: "基于以下数据撰写销售分析报告：[数据分析结果]"

  Worker 执行:
    - 撰写报告
    - 返回结果: "【销售分析报告】本月销售表现..."

Step 5: Supervisor 收到结果
  思考: 报告完成，最后制作图表

Step 6: 委派 → chart_maker
  任务: "制作本月销售趋势图和TOP10产品图"

  Worker 执行:
    - 生成图表
    - 返回结果: "图表已生成：[chart_urls]"

Step 7: Supervisor 汇总
  整合所有结果，返回完整报告

配置参数

enable_summarization（启用汇总）

yaml

enable_summarization: true

true: Supervisor 会汇总所有 Worker 的结果
false: 直接返回最后一个 Worker 的结果

推荐设置：通常为 true

多模态支持

⚠️ 部分支持

✅ Supervisor 可以看到图片
❌ Worker 无法接收图片（LangGraph handoff 限制）

解决方案：

Supervisor 完成图片分析
将分析结果传递给 Worker

yaml

场景: 分析图片并撰写报告

Step 1: Supervisor 收到图片
  - 自己分析图片内容
  - 提取关键信息: "图片显示销售趋势上升..."

Step 2: 委派 Worker
  - 将分析结果（文本）传递给 report_writer
  - Worker 基于文本信息撰写报告

最佳实践

1. Supervisor 提示词设计

✅ 好的设计：

【可用专家】清楚列出所有 Worker
【委派规则】明确何时委派、如何委派
【任务分解】给出分解思路
【示例】提供委派示例

❌ 不好的设计：

"你是协调者，调度其他Agent完成任务"
（太模糊，Supervisor 不知道如何操作）

2. Worker 专业化

每个 Worker 专注一个领域：

yaml

✅ 好的设计:
  Worker 1: 数据分析（只做分析）
  Worker 2: 报告撰写（只写报告）
  Worker 3: 图表制作（只做图表）

❌ 不好的设计:
  Worker: 万能助手（什么都做，但不专业）

3. 任务传递

Supervisor 传递任务时要具体：

yaml

✅ 具体任务:
  "分析2024年1月的销售数据，计算总销售额、环比增长率、TOP10产品"

❌ 模糊任务:
  "帮我分析一下数据"

4. 成本控制

Supervisor 模式 Token 消耗较大：

总消耗 = Supervisor调用次数 × Supervisor成本
        + Worker调用次数 × Worker成本

优化建议：

简单任务不用 Supervisor（用 Single）
Worker 使用更便宜的模型
限制委派次数（设置 max_iterations）

Collaboration 模式（协作模式）

概述

多个 Agent 平等协作，共享信息，从不同角度分析问题。

用户请求 → Collaboration Orchestrator
              ↓
       Agent 1 (技术视角)
              ↓
       Agent 2 (产品视角)
              ↓
       Agent 3 (市场视角)
              ↓
         汇总所有观点 → 响应

两种策略

Sequential（顺序执行）

Agent 依次执行，后面的能看到前面的结果：

Agent 1 → Agent 2 → Agent 3 → 汇总

优点：

Agent 可以参考他人观点
逐步完善分析

缺点：

执行时间长（串行）

Parallel（并行执行）

Agent 同时执行，互不影响：

    ┌→ Agent 1 ┐
请求 ├→ Agent 2 ├→ 汇总
    └→ Agent 3 ┘

优点：

执行快（并行）
观点独立，不受影响

缺点：

无法参考其他 Agent 的观点

创建步骤

步骤 1：创建多个专家 Agent

Agent 1: 技术专家

yaml

名称: tech_expert
提示词: |
  你是技术专家，从技术角度分析问题。

  【分析重点】
  - 技术可行性
  - 技术架构设计
  - 技术风险评估
  - 技术成本估算

  【输出格式】
  【技术分析】
  - 可行性：...
  - 架构建议：...
  - 风险点：...

Agent 2: 产品专家

yaml

名称: product_expert
提示词: |
  你是产品专家，从产品角度分析问题。

  【分析重点】
  - 用户需求和痛点
  - 产品功能设计
  - 用户体验优化
  - 竞品对比分析

Agent 3: 市场专家

yaml

名称: market_expert
提示词: |
  你是市场专家，从市场角度分析问题。

  【分析重点】
  - 市场需求和趋势
  - 目标用户群体
  - 营销策略建议
  - 商业价值评估

步骤 2：创建 Collaboration Orchestrator

yaml

Orchestrator:
  名称: multi_expert_analysis
  类型: COLLABORATION

Collaboration 配置:
  Agents:
    - tech_expert
    - product_expert
    - market_expert
  协作策略: SEQUENTIAL  # 或 PARALLEL
  共享记忆: ✓
  启用汇总: ✓

Sequential 执行示例

场景：分析新功能

用户请求：

我们想开发一个AI视频生成功能，请分析可行性

执行流程：

yaml

Agent 1 (技术专家):
  输入: "AI视频生成功能可行性分析"
  输出: |
    【技术分析】
    - 可行性：技术已成熟，有Runway、Pika等方案
    - 建议架构：调用第三方API或自建模型
    - 成本：API调用约0.5元/秒视频
    - 风险：生成速度慢、质量不稳定

Agent 2 (产品专家):
  输入: "AI视频生成功能可行性分析"
  可见内容: 技术专家的分析（↑）
  输出: |
    【产品分析】
    结合技术专家的分析，从产品角度：
    - 用户需求：内容创作者需要快速生成素材
    - 功能设计：简单文本描述 → 生成短视频
    - 用户体验：需要预览、编辑、导出功能
    - 差异化：比竞品更快或更便宜

Agent 3 (市场专家):
  输入: "AI视频生成功能可行性分析"
  可见内容: 技术专家 + 产品专家的分析（↑）
  输出: |
    【市场分析】
    综合技术和产品的分析：
    - 市场规模：AI内容生成市场增长迅速
    - 目标用户：自媒体、短视频创作者
    - 定价策略：按时长计费，会员优惠
    - 营销重点：强调生成速度和质量

汇总:
  整合三位专家的观点，给出综合建议

Parallel 执行示例

yaml

同时执行:
  - Agent 1 分析技术可行性
  - Agent 2 分析产品设计
  - Agent 3 分析市场前景

三位专家同时工作，互不影响
最后汇总所有观点

选择策略建议

场景	推荐策略	理由
多角度分析	Sequential	后续专家可参考前面的观点
独立评审	Parallel	避免观点相互影响
时间敏感	Parallel	并行执行更快
逐步完善	Sequential	逐层深入分析

多模态支持

✅ 完全支持

yaml

场景: 分析产品设计图

用户输入:
  文本: "评价这个设计方案"
  图片: http://example.com/design.png

执行流程:
  Agent 1 (设计专家): 分析视觉设计
  Agent 2 (UX专家): 分析用户体验
  Agent 3 (技术专家): 分析实现难度

所有 Agent 都能看到图片

最佳实践

1. Agent 角色差异化

✅ 好的设计：

yaml

Agent 1: 技术视角（关注可行性）
Agent 2: 产品视角（关注用户价值）
Agent 3: 商业视角（关注ROI）
→ 三个不同维度，互补

❌ 不好的设计：

yaml

Agent 1: 分析问题
Agent 2: 分析问题
Agent 3: 分析问题
→ 角色重复，浪费资源

2. 控制 Agent 数量

yaml

✅ 推荐: 2-4 个 Agent
⚠️ 谨慎: 5-7 个 Agent
❌ 避免: 8+ 个 Agent

原因：

Agent 越多，Token 消耗越大
过多观点难以汇总
执行时间过长

3. 汇总质量

启用 enable_summarization 后，系统会自动汇总：

默认汇总格式：

综合各专家的观点：

【技术专家】
...

【产品专家】
...

【市场专家】
...

自定义汇总：创建专门的"汇总 Agent"（高级用法）

Workflow 模式（工作流模式）

概述

Workflow 是一张 React-Flow 可视化画布——你拖入节点、用连线把它们连起来，数据沿边在节点间流动。它不是"步骤 1 → 2 → 3、每步选一个 Agent"的线性列表：支持并发分发、条件分支、循环回边等非线性结构。

用户请求 → [start] → 节点（沿边流动，可分支 / 并发 / 循环）→ [end]

适用场景

✅ 规则清晰、节点间数据流明确的业务（审批、批处理、ETL、规则引擎）
✅ 需要把 Agent / HTTP / 判断 / 循环 / 数据查询等异构步骤编排在一起
✅ 需要节点级 retry / timeout / on_error 鲁棒性
❌ 需要开放式动态决策（用 Supervisor / DeepAgents）

节点 / 连线模型

工作流画布提供 11 种可添加节点（外加默认的开始 / 结束）：

节点	作用
🤖 智能体(agent)	调一个 Agent 跑一次推理
🎛️ 嵌套编排(orchestrator)	调另一个 Orchestrator
🔀 条件判断(conditional)	keyword / regex / expression 分支路由
🔁 有界循环(loop)	计数器，配合 conditional 回边实现循环
🔂 数组遍历(for_each)	对数组逐元素跑模板（纯模板，无 LLM）
🙋 人工确认(human_input)	暂停推卡片给用户（HITL）
🌐 HTTP(http_request)	调外部 REST API
🔧 数据整形(transform)	纯模板渲染，不调 LLM
📚 知识库查询(kb_query)	直接查 RAG，不走 LLM 包装层
🗃️ 数据查询(data_query)	直调数据工具(SQL / NoSQL / 图)，省一次 LLM 往返
🔌 MCP 调用(mcp_call)	直调一个 MCP 工具

连线规则：一个节点拉多条出线 = 并发执行；conditional 的出线是条件边；loop 需要 conditional 回边才会真正循环。各节点可单独配 retry / timeout / on_error（失败兜底跳转）。

完整搭建指南

工作流的可视化搭建是个体系（进画布、加节点、连线、模板变量与自动补全、调试运行、循环模板、节点鲁棒性、故障排查），本教程不再展开 YAML 配置——请直接看操作手册的工作流编辑器参考：

📖 操作手册《工作流编辑器使用指南》（操作手册 01-agent-system §1.1.3）

多模态支持

✅ 节点（如 agent）可处理图片；调试输入栏支持附加图片（最多 10 张，每张 ≤ 6MB）。

Conditional 模式（条件路由）

概述

基于规则将请求路由到不同 Agent。

用户请求 → 路由决策
           ├→ 规则1匹配 → Agent A
           ├→ 规则2匹配 → Agent B
           ├→ 规则3匹配 → Agent C
           └→ 无匹配 → Default Agent

适用场景

✅ 意图识别和分类
✅ 多部门/多场景路由
✅ 快速分流
❌ 不适合需要多Agent协作
❌ 不适合复杂决策逻辑

路由规则类型

1. 关键词匹配

yaml

规则:
  关键词: ["技术", "bug", "报错"]
  Agent: tech_support

2. 正则表达式

yaml

规则:
  正则: "\\d{4}-\\d{2}-\\d{2}"  # 匹配日期格式
  Agent: date_handler

3. 自定义条件

yaml

规则:
  条件: "message_length > 100"
  Agent: detailed_handler

创建步骤

步骤 1：创建各领域 Agent

技术支持

yaml

名称: tech_support
提示词: "你是技术支持，解决技术问题..."

销售咨询

yaml

名称: sales_consultant
提示词: "你是销售顾问，解答购买咨询..."

售后服务

yaml

名称: after_sales
提示词: "你是售后服务，处理退换货..."

通用客服（默认）

yaml

名称: general_service
提示词: "你是通用客服，处理一般咨询..."

步骤 2：创建 Conditional Orchestrator

yaml

Orchestrator:
  名称: smart_routing
  类型: CONDITIONAL

Conditional 配置:
  路由规则:
    - 名称: 技术支持
      关键词: ["技术", "bug", "报错", "安装", "配置", "故障"]
      Agent: tech_support
      优先级: 1

    - 名称: 销售咨询
      关键词: ["价格", "购买", "优惠", "试用", "订购"]
      Agent: sales_consultant
      优先级: 2

    - 名称: 售后服务
      关键词: ["退款", "退货", "换货", "售后", "投诉"]
      Agent: after_sales
      优先级: 3

  默认 Agent: general_service

执行流程示例

yaml

示例 1:
  用户: "系统报错了怎么办？"
  匹配规则: 技术支持（关键词：报错）
  路由到: tech_support

示例 2:
  用户: "你们的产品多少钱？"
  匹配规则: 销售咨询（关键词：多少钱）
  路由到: sales_consultant

示例 3:
  用户: "我要退货"
  匹配规则: 售后服务（关键词：退货）
  路由到: after_sales

示例 4:
  用户: "你好"
  匹配规则: 无匹配
  路由到: general_service (默认)

高级规则

组合条件

yaml

规则:
  名称: VIP客户技术支持
  条件:
    AND:
      - 关键词: ["技术"]
      - 用户标签: "VIP"
  Agent: vip_tech_support

优先级

多个规则匹配时，按优先级选择：

yaml

规则1:
  关键词: ["技术"]
  优先级: 1  # 高优先级

规则2:
  关键词: ["技术问题"]
  优先级: 2  # 低优先级

用户输入: "技术问题"
→ 匹配规则1和规则2
→ 选择规则1（优先级高）

多模态支持

✅ Agent 支持，路由不考虑

✅ 路由后的 Agent 可以处理图片
❌ 路由决策不基于图片内容（只看文本）

yaml

用户输入: "分析图片 http://example.com/chart.png"
路由决策: 基于文本"分析图片"
路由到: image_analyst
Agent: 处理图片和文本

最佳实践

1. 关键词设计

✅ 全面覆盖：

yaml

技术支持:
  ["技术", "bug", "报错", "崩溃", "闪退", "卡顿", "安装", "配置"]

❌ 覆盖不足：

yaml

技术支持:
  ["技术", "bug"]

2. 默认Agent

必须配置默认 Agent：

yaml

默认 Agent: general_service

作用: 处理无法分类的请求

3. 规则测试

创建测试用例验证路由：

yaml

测试用例:
  - 输入: "系统崩溃了"
    期望: tech_support

  - 输入: "有优惠活动吗"
    期望: sales_consultant

  - 输入: "你好"
    期望: general_service

External 模式（外部集成）

概述

集成 Dify 或 n8n 的现有应用。

用户请求 → External Orchestrator
          → Dify/n8n API
          → 返回响应

适用场景

✅ 复用已有 Dify/n8n 应用
✅ 快速集成现有工作流
✅ 利用 Dify 的 workflow 能力
❌ 不需要复杂编排（用其他模式）

集成 Dify

步骤 1：获取 Dify 应用信息

在 Dify 平台：

创建或选择应用
进入 API 访问
获取：
- API Key: app-xxx
- API URL: https://api.dify.ai/v1
- 应用类型: CHAT / COMPLETION / WORKFLOW

步骤 2：创建 External Orchestrator

yaml

Orchestrator:
  名称: dify_customer_service
  类型: EXTERNAL

External 配置:
  集成类型: DIFY
  API URL: https://api.dify.ai/v1
  API Key: app-xxxxxxxxxxxxx
  应用类型: CHAT

  高级配置:
    inputs: {}  # 自定义输入变量
    response_mode: streaming  # 流式响应

步骤 3：测试集成

yaml

用户输入: "你好"
→ 发送到 Dify API
→ Dify 处理
→ 返回响应（支持流式）

Dify 特性支持

流式响应

✅ 完全支持

yaml

配置:
  response_mode: streaming

效果:
  - 实时打字机效果
  - SSE 推送
  - 支持 Agent Thoughts 显示

Conversation ID

✅ 自动管理

yaml

系统自动:
  - 首次对话：无 conversation_id
  - Dify 返回: conversation_id
  - 保存到 Redis: 24小时
  - 后续对话：自动带上 conversation_id

效果: 多轮对话记忆

Workflow 进度

✅ 实时显示

yaml

Dify Workflow 节点:
  - 节点开始: 🔄 正在执行 [节点名称]
  - 节点完成: ✅ [节点名称] 完成
  - 工具调用: 🔧 正在使用 [工具名称]

集成 n8n

步骤 1：准备 n8n Webhook

在 n8n：

创建 Workflow
添加 Webhook 触发器
获取 Webhook URL

步骤 2：创建 External Orchestrator

yaml

Orchestrator:
  名称: n8n_data_processor
  类型: EXTERNAL

External 配置:
  集成类型: N8N
  Webhook URL: https://n8n.example.com/webhook/xxx
  认证方式: HEADER_AUTH
  认证配置:
    header_name: Authorization
    header_value: Bearer xxx

多模态支持

✅ 支持（取决于 Dify/n8n 应用）

yaml

Dify Vision 应用:
  - 支持图片输入
  - 自动传递 image_urls

最佳实践

1. 选择合适的集成类型

yaml

使用 Dify:
  - 需要复杂的 AI workflow
  - 需要使用 Dify 的插件生态
  - 团队已有 Dify 应用

使用 n8n:
  - 需要连接企业系统
  - 需要复杂的数据处理
  - 需要定时任务

2. Conversation ID 管理

yaml

✅ 推荐: 使用 Sira AI 自动管理
  - 自动保存 conversation_id
  - 自动续传
  - 24小时 TTL

❌ 手动管理:
  - 容易出错
  - 需要额外开发

3. 错误处理

yaml

Dify/n8n 异常时:
  - 显示友好错误信息
  - 提供重试机制
  - 记录日志便于排查

Deep Agents 模式 🆕

概述

Deep Agents 是基于 LangChain Deep Agents 框架的高级编排模式，提供强大的中间件系统，让 AI 能够像人类一样管理复杂的多步骤任务。

用户请求 → Deep Agent
         ↓
    创建 Todo List
         ↓
    执行任务步骤
         ↓
    创建/编辑文件
         ↓
    委托子智能体
         ↓
    返回完整结果

适用场景

✅ 需要多步骤规划的复杂任务
✅ 需要创建和保存文件（报告、代码等）
✅ 需要将任务委托给专业子智能体
✅ 长对话需要自动总结
❌ 简单的单次问答
❌ 对成本敏感的场景

核心能力

1. Todo List 中间件

自动管理任务清单：

yaml

用户: "生成一份市场研究报告"

Deep Agent 创建待办:
✅ 1. 收集市场数据
□ 2. 分析竞争对手
□ 3. 识别市场趋势
□ 4. 撰写报告
□ 5. 生成图表

逐步完成并更新状态

2. Filesystem 中间件

创建和编辑文件：

yaml

支持操作:
  - 创建文件: create_file()
  - 读取文件: read_file()
  - 编辑文件: edit_file()
  - 列出文件: list_files()

3. SubAgents 中间件

委托给专业子智能体：

yaml

子智能体类型:
  - agent_ref: 引用平台中的其他 Agent
  - predefined: 使用预定义的子智能体

示例:
  研究任务 → 委托给"研究专家" Agent
  报告撰写 → 委托给"文案专家" Agent

4. Summarization 中间件

自动总结长对话：

yaml

当对话历史超过阈值:
  - 自动生成摘要
  - 保留关键信息
  - 压缩历史记录

创建步骤

步骤 1：创建 Deep Agents Orchestrator

yaml

Orchestrator:
  名称: deep_research_assistant
  类型: DEEP_AGENTS

Deep Agents 配置:
  AI 模型: claude-3-5-sonnet-20241022

  系统提示词: |
    你是一个深度研究助手，擅长复杂任务的规划和执行。

    你的能力：
    - 创建和管理待办清单（Todo List）
    - 创建、读取、编辑文件
    - 将任务委托给专业子智能体

    工作流程：
    1. 理解用户需求
    2. 创建详细的任务清单
    3. 逐步执行任务
    4. 必要时委托给子智能体
    5. 将结果保存为文件
    6. 汇总并返回结果

  启用中间件:
    ✓ Todo List
    ✓ Filesystem
    ✓ SubAgents
    ✓ Summarization

步骤 2：配置子智能体（可选）

如果启用 SubAgents 中间件：

yaml

子智能体列表:
  - type: agent_ref
    agent_id: research_expert
    description: "研究专家，擅长搜索和整理信息"

  - type: agent_ref
    agent_id: data_analyst
    description: "数据分析专家，擅长数据分析和可视化"

  - type: agent_ref
    agent_id: report_writer
    description: "报告撰写专家，擅长撰写专业文档"

步骤 3：配置存储后端

yaml

存储后端: store  # 推荐生产环境使用

PostgreSQL 配置:
  host: localhost
  port: 5432
  database: sira_ai
  user: sira
  password: ******

执行流程示例

场景：生成市场研究报告

用户请求：

生成一份智能手机市场研究报告，包括市场规模、竞争格局、趋势分析

执行流程：

yaml

Step 1: 创建任务清单
Deep Agent:
  "我将为您生成市场研究报告，创建任务清单："

  Todo List:
  □ 1. 收集智能手机市场数据
  □ 2. 分析主要竞争对手
  □ 3. 识别市场趋势
  □ 4. 撰写分析报告
  □ 5. 生成图表和可视化

Step 2: 执行任务 1 - 收集数据
Deep Agent:
  "开始收集市场数据..."
  [更新] ✅ 1. 收集智能手机市场数据

  委托 → research_expert
  研究专家收集数据并返回结果

Step 3: 执行任务 2 - 分析竞争对手
Deep Agent:
  "分析竞争格局..."
  [更新] ✅ 2. 分析主要竞争对手

  委托 → data_analyst
  数据专家分析竞争数据

Step 4: 执行任务 3 - 识别趋势
Deep Agent:
  "识别市场趋势..."
  [更新] ✅ 3. 识别市场趋势

  基于收集的数据分析趋势

Step 5: 执行任务 4 - 撰写报告
Deep Agent:
  "撰写报告..."
  [更新] ✅ 4. 撰写分析报告

  委托 → report_writer
  文案专家撰写报告

Step 6: 保存文件
Deep Agent:
  "保存报告到文件..."

  创建文件: /reports/smartphone_market_report_2024.md

  [更新] ✅ 5. 生成图表和可视化

Step 7: 返回结果
Deep Agent:
  "市场研究报告已完成！

  主要发现：
  - 市场规模：XXX亿美元
  - TOP3厂商：Apple、Samsung、小米
  - 主要趋势：AI功能、折叠屏、续航提升

  完整报告已保存至：/reports/smartphone_market_report_2024.md"

配置参数

middlewares（中间件配置）

yaml

middlewares:
  todo_list:
    enabled: true

  filesystem:
    enabled: true
    base_path: "/workspace"  # 文件保存路径

  subagents:
    enabled: true
    max_delegation: 5  # 最大委托次数

  summarization:
    enabled: true
    max_tokens: 8000  # 触发总结的阈值

backend（存储后端）

yaml

backend:
  type: store  # state | store | filesystem | composite

  # PostgreSQL 配置 (store/composite)
  postgres:
    connection_string: "postgresql://user:pass@host:5432/db"

多模态支持

✅ 完全支持

yaml

用户输入:
  文本: "分析这个架构图并生成优化方案"
  图片: http://example.com/architecture.png

Deep Agent:
  1. 分析图片内容
  2. 创建优化任务清单
  3. 逐步生成优化方案
  4. 保存方案到文件

最佳实践

1. 提示词设计

明确说明能力：

你的能力：
- 创建和管理待办清单
- 创建、读取、编辑文件
- 将任务委托给专业子智能体

提供工作流程：

工作流程：
1. 理解需求
2. 创建任务清单
3. 逐步执行
4. 保存结果

2. 子智能体设计

yaml

✅ 专业化:
  - 研究专家（搜索和整理）
  - 数据分析师（数据分析）
  - 报告撰写者（文档撰写）

❌ 通用化:
  - 通用助手（什么都做）

3. 成本控制

Deep Agents Token 消耗较高：

yaml

优化建议:
  - 主 Agent 使用强模型（Claude/GPT-4o）
  - 子 Agent 使用便宜模型（DeepSeek）
  - 限制委托次数（max_delegation）
  - 使用缓存避免重复任务

详细文档：Deep Agents 完整指南

Knowledge Base 模式 🆕

概述

Knowledge Base 模式专注于结构化问答对（QA Pairs）的检索，提供精准可控的知识来源。

用户问题 → Knowledge Base Orchestrator
         ↓
    检索相关 QA 对
         ↓
    返回标准答案

适用场景

✅ FAQ 标准问答
✅ 政策制度查询
✅ 产品手册问答
✅ 需要精准可控的答案
❌ 需要理解长篇文档
❌ 需要推理和分析

核心能力

1. 精准匹配

完全匹配问题关键词：

yaml

用户: "如何重置密码？"
匹配: "如何重置密码？"（精准匹配）
返回: 标准答案

2. 语义搜索

基于语义相似度匹配：

yaml

用户: "忘记密码怎么办？"
匹配: "如何重置密码？"（语义相似）
相似度: 0.92
返回: 标准答案

3. 分类过滤

按分类查找：

yaml

分类结构:
  账号管理/
    ├─ 注册登录
    ├─ 密码找回
    └─ 账号注销

  产品功能/
    ├─ 基础功能
    └─ 高级功能

4. 渠道隔离

不同渠道不同答案：

yaml

问题: "如何联系客服？"

企业微信渠道:
  答案: "在企业微信发送消息给客服 Bot"

Web渠道:
  答案: "点击右下角聊天图标联系在线客服"

创建步骤

步骤 1：创建 QA 知识库

进入 知识库管理
创建知识库，类型选择 QA 问答库
创建分类结构
添加问答对：

yaml

问题: 如何重置密码？
答案: |
  密码重置步骤：
  1. 点击登录页面的"忘记密码"
  2. 输入注册邮箱
  3. 查收验证邮件
  4. 点击链接设置新密码

  注意：验证邮件24小时内有效

分类: 账号管理
标签: [密码, 重置, 登录]
优先级: 高
渠道: 全渠道

步骤 2：批量导入（可选）

CSV 格式：

csv

question,answer,category,tags,priority
如何注册账号?,访问注册页面填写信息,账号管理,注册|账号,high
如何修改邮箱?,进入设置页面修改,账号管理,邮箱|设置,medium

步骤 3：创建 Knowledge Base Orchestrator

yaml

Orchestrator:
  名称: faq_bot
  类型: KNOWLEDGE_BASE

Knowledge Base 配置:
  知识库: product_faq (选择已创建的QA知识库)

  检索模式: hybrid  # precise | semantic | hybrid

  检索参数:
    top_k: 3           # 返回前3个最相关的QA
    threshold: 0.8     # 相似度阈值（0-1）
    channel: all       # 渠道过滤

  响应配置:
    include_source: true      # 显示来源
    format_as_markdown: true  # Markdown格式

执行流程示例

场景：产品 FAQ 客服

用户问题：

我忘记密码了怎么办？

执行流程：

yaml

Step 1: 向量化问题
  问题文本 → Embedding 向量

Step 2: 检索 QA 对
  检索模式: hybrid (混合检索)

  向量检索结果:
    1. "如何重置密码？" (相似度: 0.95)
    2. "忘记密码怎么办？" (相似度: 0.93)
    3. "密码找回方法" (相似度: 0.88)

  关键词匹配:
    - 匹配: "忘记", "密码"
    - 增强: 第1、2条结果

Step 3: 重排序
  综合评分后最终排序:
    1. "忘记密码怎么办？" (综合分: 0.96)
    2. "如何重置密码？" (综合分: 0.94)
    3. "密码找回方法" (综合分: 0.87)

Step 4: 返回答案
  选择第1条（相似度最高）:

  "密码重置步骤：
  1. 点击登录页面的'忘记密码'
  2. 输入注册邮箱
  3. 查收验证邮件
  4. 点击链接设置新密码

  注意：验证邮件24小时内有效"

检索模式

1. Precise（精准匹配）

yaml

模式: precise
特点: 完全匹配关键词
适用: 标准化问题

示例:
  用户: "如何重置密码？"
  匹配: "如何重置密码？"（完全匹配）
  ✅ 返回答案

  用户: "忘记密码了"
  匹配: 无完全匹配
  ❌ 无结果

2. Semantic（语义搜索）

yaml

模式: semantic
特点: 基于语义相似度
适用: 问题表达多样

示例:
  用户: "忘记密码了"
  相似: "如何重置密码？"（语义相似）
  ✅ 返回答案

3. Hybrid（混合检索）

yaml

模式: hybrid（推荐）
特点: 结合关键词和语义
适用: 大多数场景

流程:
  1. 向量检索找相似问题
  2. 关键词匹配增强
  3. 综合排序
  4. 返回最佳答案

配置参数

retrieval_config（检索配置）

yaml

retrieval_config:
  mode: hybrid         # precise | semantic | hybrid
  top_k: 3            # 返回结果数
  threshold: 0.8      # 相似度阈值

  # 混合检索权重
  vector_weight: 0.6
  keyword_weight: 0.4

  # 重排序
  enable_rerank: true
  rerank_model: bge-reranker-large

channel_filter（渠道过滤）

yaml

channel_filter:
  channel: wechat     # 只返回企业微信渠道的QA

或:
  channel: all        # 返回所有渠道

多模态支持

❌ 不需要

Knowledge Base 模式专注于文本问答，不涉及图片处理。

最佳实践

1. 问答对设计

问题覆盖多种表达：

yaml

标准问题: "如何重置密码？"
同义问题:
  - "忘记密码怎么办？"
  - "密码找回方法"
  - "无法登录怎么办？"

答案结构化：

yaml

✅ 好的答案:
  步骤清晰：
  1. 第一步
  2. 第二步
  3. 第三步

  注意事项：...

❌ 差的答案:
  你可以通过忘记密码功能来重置...（不够清晰）

2. 分类组织

yaml

按用户场景分类:
  账号管理/
    ├─ 注册登录
    ├─ 密码找回
    └─ 账号注销

  订单管理/
    ├─ 下单购买
    ├─ 订单查询
    └─ 退换货

控制分类深度: 2-3层即可

3. 检索优化

yaml

初始配置（宽松）:
  top_k: 5
  threshold: 0.75

观察效果后调整:
  - 结果太多且不相关 → 提高 threshold
  - 结果太少找不到答案 → 降低 threshold
  - 最佳答案不在第一位 → 启用 rerank

4. 持续维护

yaml

定期任务:
  - 收集未命中问题
  - 分析用户反馈
  - 新增/更新QA对
  - 删除过时内容

详细文档：知识库 QA 管理完整指南

性能和成本

Token 消耗对比

模式	Token 消耗	说明
Single	1x	基准
Conditional	1x	仅路由开销（极小）
Knowledge Base 🆕	0.1x	仅检索，不调用LLM
Workflow	3x	3个步骤 = 3次调用
Collaboration (Sequential)	3x+	3个Agent + 汇总
Collaboration (Parallel)	3x+	同时调用，但总量相同
Supervisor	5x+	Supervisor调用 + Worker调用
Deep Agents 🆕	8x+	主Agent + 中间件 + 子Agent
External	取决于外部系统	Dify/n8n 的消耗

响应时间对比

模式	响应时间	说明
Knowledge Base 🆕	0.5-1秒	仅向量检索，无LLM
Single	3-5秒	一次 LLM 调用
Conditional	3-5秒	路由后等同 Single
Collaboration (Parallel)	3-5秒	并行执行
Collaboration (Sequential)	10-15秒	3个Agent串行
Workflow	10-15秒	3步串行
Supervisor	15-30秒	多次往返调用
Deep Agents 🆕	30-60秒+	多步骤 + 文件操作 + 子Agent

优化建议

1. 模式选择

yaml

FAQ问答 → Knowledge Base (最快、最便宜、最准确) 🆕
简单任务 → Single (快、便宜)
固定流程 → Workflow
多角度分析 → Collaboration Parallel (快)
复杂分解 → Supervisor (贵但灵活)
多步骤项目 → Deep Agents (最强大、最贵) 🆕

2. 模型选择

yaml

Supervisor Agent: 使用强模型 (GPT-4o)
Worker Agent: 使用便宜模型 (GPT-3.5, DeepSeek)

示例:
  Supervisor: gpt-4o ($5/1M tokens)
  Worker: deepseek-chat ($0.27/1M tokens)
  节省成本 95%

3. 缓存策略

yaml

相同问题缓存结果:
  - 减少 LLM 调用
  - 降低成本
  - 提高响应速度

下一步

掌握 Orchestrator 配置后，继续学习：

Application 接入指南 - 将 Orchestrator 暴露给用户
完整使用场景 - 端到端实战案例
MCP 工具使用 - 增强 Agent 能力
Deep Agents 详细指南 🆕 - 掌握高级多步骤任务管理
知识库 QA 管理 🆕 - 创建精准的FAQ问答系统
GenAI Toolbox 🆕 - 为AI提供数据库访问能力

💡 提示：

从 Single 或 Knowledge Base 开始，逐步尝试复杂模式
根据业务需求选择合适的模式（参考性能和成本对比）
FAQ问答优先使用 Knowledge Base 模式
复杂项目管理可以尝试 Deep Agents 模式
关注成本和性能平衡
善用测试功能验证编排效果

Orchestrator 配置指南 ​

Orchestrator 是什么？ ​

核心概念 ​

八种编排模式 ​

发布生命周期（草稿 / 发布 / 版本 / 回滚 / 试运行） ​

Single 模式（单体模式） ​

概述 ​

适用场景 ​

创建步骤 ​

步骤 1：进入 Orchestrator 管理 ​

步骤 2：选择 Single 模式 ​

步骤 3：配置 Single Agent ​

步骤 4：保存和测试 ​

配置示例 ​

示例 1：客服助手 ​

示例 2：技术文档助手 ​

多模态支持 ​

最佳实践 ​

Supervisor 模式（监督者模式） ​

概述 ​

适用场景 ​

核心概念 ​

Supervisor Agent（监督者） ​

Worker Agent（工作者） ​

创建步骤 ​

步骤 1：创建 Supervisor Agent ​

步骤 2：创建 Worker Agents ​

步骤 3：创建 Supervisor Orchestrator ​

执行流程示例 ​

场景：销售数据分析报告 ​

配置参数 ​

enable_summarization（启用汇总） ​

多模态支持 ​

最佳实践 ​

1. Supervisor 提示词设计 ​

2. Worker 专业化 ​

3. 任务传递 ​

4. 成本控制 ​

Collaboration 模式（协作模式） ​

概述 ​

两种策略 ​

Sequential（顺序执行） ​

Parallel（并行执行） ​

创建步骤 ​

步骤 1：创建多个专家 Agent ​

步骤 2：创建 Collaboration Orchestrator ​

Sequential 执行示例 ​

场景：分析新功能 ​

Parallel 执行示例 ​

选择策略建议 ​

多模态支持 ​

最佳实践 ​

1. Agent 角色差异化 ​

2. 控制 Agent 数量 ​

3. 汇总质量 ​

Workflow 模式（工作流模式） ​

概述 ​

适用场景 ​

节点 / 连线模型 ​

完整搭建指南 ​

多模态支持 ​

Conditional 模式（条件路由） ​

概述 ​

适用场景 ​

路由规则类型 ​

1. 关键词匹配 ​

2. 正则表达式 ​

3. 自定义条件 ​

创建步骤 ​

步骤 1：创建各领域 Agent ​

步骤 2：创建 Conditional Orchestrator ​

执行流程示例 ​

高级规则 ​

组合条件 ​

优先级 ​

多模态支持 ​

最佳实践 ​

1. 关键词设计 ​

2. 默认Agent ​

3. 规则测试 ​

Orchestrator 配置指南

Orchestrator 是什么？

核心概念

八种编排模式

发布生命周期（草稿 / 发布 / 版本 / 回滚 / 试运行）

Single 模式（单体模式）

概述

适用场景

创建步骤

步骤 1：进入 Orchestrator 管理

步骤 2：选择 Single 模式

步骤 3：配置 Single Agent

步骤 4：保存和测试

配置示例

示例 1：客服助手

示例 2：技术文档助手

多模态支持

最佳实践

Supervisor 模式（监督者模式）

概述

适用场景

核心概念

Supervisor Agent（监督者）

Worker Agent（工作者）

创建步骤

步骤 1：创建 Supervisor Agent

步骤 2：创建 Worker Agents

步骤 3：创建 Supervisor Orchestrator

执行流程示例

场景：销售数据分析报告

配置参数

enable_summarization（启用汇总）

多模态支持

最佳实践

1. Supervisor 提示词设计

2. Worker 专业化

3. 任务传递

4. 成本控制

Collaboration 模式（协作模式）

概述

两种策略

Sequential（顺序执行）

Parallel（并行执行）

创建步骤

步骤 1：创建多个专家 Agent

步骤 2：创建 Collaboration Orchestrator

Sequential 执行示例

场景：分析新功能

Parallel 执行示例

选择策略建议

多模态支持

最佳实践

1. Agent 角色差异化

2. 控制 Agent 数量

3. 汇总质量

Workflow 模式（工作流模式）

概述

适用场景

节点 / 连线模型

完整搭建指南

多模态支持

Conditional 模式（条件路由）

概述

适用场景

路由规则类型

1. 关键词匹配

2. 正则表达式

3. 自定义条件

创建步骤

步骤 1：创建各领域 Agent

步骤 2：创建 Conditional Orchestrator

执行流程示例

高级规则

组合条件

优先级

多模态支持

最佳实践

1. 关键词设计

2. 默认Agent

3. 规则测试