多Agent协作架构#

使用 Multi-Agent 的核心场景：

1. 任务复杂度超过单 Agent 能力上限：任务需要的工具太多，Context 装不下
2. 并行化加速：任务可分解为相互独立的子任务，并行执行（如同时分析多份报告）
3. 专业化分工：不同 Agent 针对不同领域优化（如代码 Agent、文档 Agent、数据 Agent）
4. 长流程任务：避免单次对话 Context 超限
5. 对抗验证：一个 Agent 生成结果，另一个 Agent 负责验证/批评

协作模式：

1. Supervisor 模式（主从模式）

用户请求
  → Supervisor（主控 Agent，负责任务分解和调度）
      → Sub-Agent A（专注子任务1）
      → Sub-Agent B（专注子任务2）
      → Sub-Agent C（专注子任务3）
  → Supervisor 汇总结果 → 返回用户

• Supervisor 负责：理解用户意图、分解任务、选择子 Agent、汇总结果
• 子 Agent 负责：执行具体任务，返回结果给 Supervisor

2. Pipeline 模式（流水线）

• A → B → C，每个 Agent 处理上一个的输出
• 适合有明确顺序依赖的任务（如：提取信息 → 分析 → 生成报告）

3. 平行（Parallel）模式

• 多个 Agent 同时处理，结果合并
• 适合并行处理大量相同类型任务

4. Debate 模式（辩论）

• 多个 Agent 对同一问题给出不同答案，再由裁判 Agent 综合判断
• 提升准确性，降低单点误差

多Agent协作是解决单Agent能力瓶颈的架构方案。使用多Agent的典型场景有：任务复杂度超过单Agent的Context窗口或工具数量限制、需要并行处理加速、不同子任务需要专业化分工。常见的协作模式有四种：Supervisor模式由一个主控Agent负责任务分解和调度，把子任务分配给专业Agent执行后汇总结果，类似项目经理分活；Pipeline模式是顺序流水线，A的输出作为B的输入，适合有明确依赖关系的场景比如信息提取到分析到报告生成；Parallel模式多个Agent并行处理同类任务再合并，适合批量处理；Debate模式多个Agent对同一问题给出不同答案再由裁判综合判断，通过对抗提升准确性。选型原则是能用单Agent就不用多Agent，多Agent带来的通信开销、状态同步、错误传播都是额外复杂度。

追问方向：

• 多 Agent 之间的通信开销怎么控制？上下文怎么传递？ → 只传递必要的结构化结果（不传原始对话历史），用共享状态对象或消息队列解耦。DocMind 用 ThreadLocal 侧信道传递工具结果
• 一个 Agent/Worker 失败了怎么办？错误传播怎么处理？ → Worker 级别独立超时 + 失败降级为空结果而非抛异常，不阻塞其他 Worker。关键 Worker 可设重试，非关键 Worker 直接跳过
• 什么时候该用多 Agent 而不是单 Agent？判断标准是什么？ → 两个信号：①单 Agent 工具数超过 15-20 个（Context 装不下）②子任务需要不同的 System Prompt 和专业角色。否则用单 Agent 更简单
• Supervisor 模式和 Pipeline 模式怎么选？ → Supervisor 适合需要动态分解与结果汇总的子任务（可串可并）；Pipeline 适合有严格依赖链的顺序任务（A 的输出是 B 的输入）

易错点：

• ❌ 为了用多 Agent 而用 → 简单任务单 Agent 更快更稳，多 Agent 的编排开销可能得不偿失
• ❌ 忽略 Agent 间状态同步 → 多个 Worker 并发访问共享状态需要同步机制（如 synchronized/CAS）
• ❌ 没有降级方案 → 某个 Worker 挂了不能影响整体，需要设计 Worker 级别的 fallback

项目实践（DocMind）： 采用 Supervisor-Worker 模式，SupervisorAgent 编排 4 个 Worker（Retrieval/Web/Memory/Analysis）。关键设计：Worker 失败不阻塞其他 Worker，每个 Worker 独立超时，失败时降级为空结果而非抛异常。上下文传递通过 AgentToolContext（ThreadLocal 侧信道），避免 Spring AI Function Calling 固定签名的限制。