AI Agent 开发实战（十一）：Multi-Agent 协作编排

AI Agent 开发实战（十一）：Multi-Agent 协作编排

一、为什么需要 Multi-Agent？

单个 Agent 的局限：

单 Agent 瓶颈│├── 1. 上下文窗口有限│ └── 塞太多指令 → 遵循率下降│├── 2. 工具集臃肿│ └── 100 个工具选哪个？选择成本高│├── 3. 角色混乱│ └── 让一个 Agent 同时写代码 + 做测试 + 写文档 → 质量全拉│└── 4. 容错差└── 一个环节出错，整个链路崩

Multi-Agent 的核心思想：拆职责、专精化、可组合。

Multi-Agent 优势│├── 职责单一 → 每个 Agent 只做一件事，Prompt 更精准├── 工具隔离 → 每个 Agent 只访问自己需要的工具├── 并行执行 → 无依赖的步骤可以同时跑├── 容错兜底 → 单个 Agent 失败不影响整体└── 可测试性 → 每个 Agent 可以独立测试和优化

二、四种经典编排模式

2.1 顺序链（Pipeline）

最简单的模式：Agent A 的输出作为 Agent B 的输入，逐级传递。

顺序链│├── 输入 → [翻译Agent] → [润色Agent] → [排版Agent] → 输出│├── 特点│ ├── 简单可靠│ ├── 每步只依赖上一步│ └── 延迟 = 各步之和│└── 适用场景├── 内容生产流水线└── 数据处理管道

代码示例：

public class PipelineOrchestrator {private final List agents;public String execute(String input) {String current = input;for (Agent agent : agents) {current = agent.run(current);if (current == null) {throw new AgentException("Agent [" + agent.getName() + "] returned null");}}return current;}}

2.2 分发-聚合（Fan-out / Fan-in）

一个协调者把任务分给多个专业 Agent，各自独立完成后汇总。

分发-聚合│├── 协调者│ ├── → [代码审查Agent]│ ├── → [安全扫描Agent]│ ├── → [性能分析Agent]│ └── → [风格检查Agent]│├── 各 Agent 并行执行│├── 协调者聚合结果│ ├── 合并各 Agent 报告│ ├── 去重和冲突处理│ └── 生成最终报告│└── 适用场景├── 代码审查├── 多维度分析└── 并行信息收集

代码示例：

public class FanOutOrchestrator {private final List workers;private final Agent aggregator;public String execute(String input) {// 1. 并行分发给所有 WorkerList> futures = workers.stream().map(worker -> CompletableFuture.supplyAsync(() -> worker.run(input))).toList();// 2. 等待所有 Worker 完成List results = futures.stream().map(CompletableFuture::join).toList();// 3. 聚合结果String combinedInput = String.join("n---n", results);return aggregator.run(combinedInput);}}

2.3 路由模式（Router）

一个路由 Agent 根据输入判断该交给谁处理，类似微服务网关。

以路由模式为例，其核心架构设计如下：

路由模式│├── 输入 → [路由Agent]│ ││ ├── 技术问题 → [技术支持Agent]│ ├── 订单相关 → [订单处理Agent]│ ├── 投诉建议 → [客服Agent]│ └── 无法判断 → [通用Agent]│├── 特点│ ├── 动态选择，按需分发│ ├── 路由 Agent 的判断力是关键│ └── 可以多级路由│└── 适用场景├── 客服系统├── 智能工单分配└── 多技能助手

代码示例：

public class RouterOrchestrator {private final Agent router;private final Map routeTable;public String execute(String input) {// 1. 路由 Agent 决定走哪条路String route = router.run(input);// 2. 查表获取目标 AgentAgent target = routeTable.get(route);if (target == null) {target = routeTable.get("default");}// 3. 执行目标 Agentreturn target.run(input);}}

2.4 辩论-裁决（Debate / Jury）

多个 Agent 对同一问题给出不同方案，由一个裁决 Agent 或投票机制选最优。

辩论-裁决│├── 输入 → [方案A Agent] → 方案 A│→ [方案B Agent] → 方案 B│→ [方案C Agent] → 方案 C│├── [裁决Agent] 评估各方案│ ├── 打分│ ├── 指出各方案优劣│ └── 选出最佳或合并│├── 特点│ ├── 提高决策质量│ ├── 适合开放性、创造性问题│ └── 成本高（多次 LLM 调用）│└── 适用场景├── 方案评审├── 代码架构设计└── 创意生成

三、编排模式对比

四、状态管理：Agent 间怎么传数据？

Multi-Agent 最大的坑不是编排，而是状态传递。

4.1 三种状态传递方式

状态传递方式│├── 1. 直接传参（最简单）│ ├── Agent A 的输出 → Agent B 的输入│ ├── 适合简单字符串传递│ └── 问题：结构复杂时容易丢信息│├── 2. 共享上下文（最常用）│ ├── 所有 Agent 读写同一个 Context 对象│ ├── 类似黑板模式（Blackboard Pattern）│ └── 问题：并发写入、覆盖冲突│└── 3. 消息总线（最解耦）├── Agent 通过消息队列通信├── 发布-订阅模式└── 问题：实现复杂、调试难

4.2 共享上下文实现

public class AgentContext {private final Map data = new ConcurrentHashMap<>();private final List executionLog = new CopyOnWriteArrayList<>();// 存数据public void put(String key, Object value) {data.put(key, value);executionLog.add(Thread.currentThread().getName() + " set " + key);}// 取数据@SuppressWarnings("unchecked")public T get(String key, Class type) {return (T) data.get(key);}// 获取执行日志（调试用）public List getExecutionLog() {return Collections.unmodifiableList(executionLog);}}

4.3 上下文设计原则

五、错误处理：一个 Agent 挂了怎么办？

5.1 三级容错策略

容错策略│├── Level 1: 重试│ ├── 对失败 Agent 自动重试（最多 N 次）│ ├── 适合：LLM 调用超时、网络抖动│ └── 不适合：逻辑错误、参数错误│├── Level 2: 降级│ ├── 主 Agent 失败 → 切换到备选 Agent│ ├── 复杂 Agent 失败 → 切换到简单版本│ └── 适合：非核心路径│└── Level 3: 隔离├── 失败 Agent 的结果标记为 error├── 其他 Agent 继续执行└── 适合：分发-聚合模式

5.2 容错代码示例

public class ResilientOrchestrator {private static final int MAX_RETRY = 2;public String executeWithRetry(Agent agent, String input) {Exception lastError = null;for (int i = 0; i <= MAX_RETRY; i++) {try {return agent.run(input);} catch (AgentException e) {lastError = e;log.warn("Agent [{}] attempt {} failed: {}",agent.getName(), i + 1, e.getMessage());}}// 重试耗尽，走降级Agent fallback = agent.getFallback();if (fallback != null) {log.warn("Falling back to [{}] for input",fallback.getName());return fallback.run(input);}throw new AgentException("All retries exhausted", lastError);}}

六、实战：代码审查 Multi-Agent 系统

把四种模式组合起来，设计一个完整的代码审查系统。

6.1 系统架构

代码审查 Multi-Agent 架构│├── [路由Agent] 判断变更类型│ ├── 前端变更 → [前端审查组]│ │ ├── [样式检查Agent]│ │ ├── [组件规范Agent]│ │ └── [可访问性Agent]│ ││ ├── 后端变更 → [后端审查组]│ │ ├── [代码规范Agent]│ │ ├── [安全扫描Agent]│ │ └── [性能分析Agent]│ ││ └── 全栈变更 → 两组都执行│├── [聚合Agent] 汇总各组结果│ ├── 去重│ ├── 按严重度排序│ └── 生成审查报告│└── [辩论Agent]（可选）└── 对冲突意见进行裁决

6.2 核心实现

public class CodeReviewOrchestrator {private final Agent router;private final Map> reviewGroups;private final Agent aggregator;public ReviewResult review(String codeDiff) {// 1. 路由：判断走哪个审查组String group = router.run(codeDiff);// 2. 分发：并行执行对应审查组List agents = reviewGroups.getOrDefault(group,reviewGroups.get("backend")); // 默认后端审查List> futures =agents.stream().map(agent -> CompletableFuture.supplyAsync(() -> {try {return agent.run(codeDiff);} catch (AgentException e) {return ReviewResult.error(agent.getName(), e);}})).toList();// 3. 聚合：汇总所有结果List results = futures.stream().map(CompletableFuture::join).toList();// 4. 合并String combined = results.stream().map(ReviewResult::getReport).collect(Collectors.joining("nn"));return aggregator.run(combined);}}

6.3 Agent Prompt 设计示例

安全扫描 Agent 的 System Prompt：

你扮演的是代码安全审查专家，职责范围很明确：1. 排查 SQL 注入风险2. 排查 XSS 漏洞3. 排查硬编码密钥或密码4. 排查不安全的反序列化5. 排查权限绕过风险输出时请按这个格式来：- 严重级别：CRITICAL / HIGH / MEDIUM / LOW- 问题描述- 所在位置（行号）- 修复建议仅报告安全问题，代码风格不在本次审查范围内。

七、编排框架对比

7.1 主流框架

7.2 Spring AI 实现 Multi-Agent

@Configurationpublic class MultiAgentConfig {@Beanpublic Agent codeReviewAgent(ChatClient chatClient,List tools) {return Agent.builder().name("code-reviewer").chatClient(chatClient).systemPrompt("""你是代码审查专家，重点关注安全与规范，并且必须严格按审查清单逐项核查。""").tools(tools).build();}@Beanpublic Agent securityAgent(ChatClient chatClient) {return Agent.builder().name("security-scanner").chatClient(chatClient).systemPrompt("""你是安全扫描专家，注意力只放在安全漏洞上。""").build();}@Beanpublic Agent aggregatorAgent(ChatClient chatClient) {return Agent.builder().name("aggregator").chatClient(chatClient).systemPrompt("""你是审查报告聚合器，负责合并多份审查结果、完成去重，并按严重级别排序输出。""").build();}}

八、踩坑实录

坑 1：Agent 间上下文泄露

问题：Agent A 的中间状态被泄露进了 Agent B 的 Prompt原因：上下文对象被共享，但没有做命名空间隔离修复：├── 每个 Agent 只读写自己的 namespace├── 敏感中间状态不要写入共享上下文└── 聚合前先做数据脱敏

坑 2：无限递归

问题：路由 Agent 把请求又路由回自己 → 形成无限循环原因：路由表配置有误修复：├── 设置最大路由深度（例如 3 层）├── 将路由历史写入 Context，用于检测循环└── 一旦无法路由，强制走 default

坑 3：聚合结果矛盾

问题：安全 Agent 给出"拒绝"，性能 Agent 却给出"通过"原因：不同 Agent 的优化目标并不一致修复：├── 先把优先级定清楚：安全 > 正确 > 性能 > 风格├── 由聚合 Agent 按优先级做最终裁决└── 如果存在冲突，则标记为"需人工确认"

坑 4：成本爆炸

问题：4 个 Agent 并行审查 × 3 轮辩论 = 12 次 LLM 调用原因：缺少成本预算机制修复：├── 设置 Token 上限├── 非核心路径优先使用小模型├── 对相同输入结果做缓存└── 辩论最多保留 2 轮，避免没完没了地讨论

九、设计 Checklist

十、面试速答模板

Q：Multi-Agent 和单 Agent 有什么区别？

Q：Multi-Agent 编排有哪些模式？

Q：Agent 间状态怎么传？

下一篇我们聊 Agent 可观测性与调试：Multi-Agent 系统出了问题怎么查？执行日志怎么设计？如何给 Agent 加"黑匣子"？让每个决策都有据可查。

本文是 AI Agent 开发实战系列第 11 篇，系列目录：

1. AI Agent 核心概念与架构
2. 三大基石之 LLM 调用与 Prompt 工程
3. 三大基石之记忆系统
4. 三大基石之工具调用
5. Java 生态 Agent 框架横评
6. 用 Spring AI 搭建第一个 Agent
7. Harness Engineering 与约束管理
8. 输出 Schema 约束与结构化输出
9. Grill Me 反问式规划
10. Agent 设计模式（ReAct / Plan-Execute / Reflection）
11. 本文：Multi-Agent 协作编排