Multi-Agent：多智能体协作架构

PM + Architect + Coder + Reviewer —— 四个 Agent 分工协作，完成软件开发项目

单 Agent 的天花板

单 Agent 的问题

  • Prompt 过长 —— 所有能力塞进一个 System Prompt
  • 上下文污染 —— 多种视角混在一起，注意力分散
  • 难以维护 —— 改一处可能影响全局行为
  • 质量上限 —— 只有一个 LLM 的视角，没有互相审查

Multi-Agent 的优势

  • ✅ 分工明确 —— 每个 Agent 只专注一件事
  • ✅ Prompt 简短 —— 每个 Agent 只看相关信息
  • ✅ 独立迭代 —— 改一个不影响其他
  • ✅ 互相审查 —— Reviewer 发现 Coder 的问题
  • ✅ 线性扩展 —— 加功能 = 加 Agent

四种 Agent 协作

📋
PM Agent
需求分析
任务拆解
优先级排序
分析层
🏗️
Architect Agent
技术选型
数据模型
接口设计
设计层
💻
Coder Agent
代码实现
异常处理
可运行交付
实现层
🔍
Reviewer Agent
质量审查
需求覆盖
安全检测
质量层

单一职责原则

每个 Agent 只做一件事，System Prompt 明确禁止越界。

维度PMArchitectCoderReviewer
核心职责 需求分析 架构设计 代码实现 质量审查
输出物 P0/P1/P2 任务列表 技术方案 + 数据模型 + API 可运行代码 评分 + approved/revise
不能做 设计架构、写代码 写代码 改架构 自己改代码
System Prompt 关键指令 "只拆解需求，不涉及技术选型" "严格基于 PM 的任务列表" "严格遵循架构设计" "只指出问题，不修改代码"
为什么 Architect 和 Coder 必须分开？
如果合并为一个 Agent，LLM 容易跳过架构思考直接写代码，导致结构混乱。强制分成两步，让架构决策显式化、可审查。

通信媒介：共享 State

所有 Agent 通过 State 通信。Agent 从 State 读取上游产出，完成后写入 State。State 就是"项目交接单"。

State 结构

class TeamState(TypedDict):
    messages: list          # 消息流（add_messages reducer）
    next_agent: str         # Supervisor 路由决策

    # 各 Agent 产出（渐进填充）
    requirement: str        # 用户输入
    task_breakdown: str     # PM → 任务列表
    architecture: str       # Architect → 架构设计
    code: str               # Coder → 代码

    # Reviewer 产出
    review_result: str      # "approved" / "revise"
    review_feedback: str    # 具体意见

    # 循环控制
    revision_count: int     # 防无限循环
    back_to_architect: bool # 问题在架构层还是代码层

State 演进过程

0 {} → requirement 有值，其他字段空
1 PM 写入 task_breakdown
2 Architect 写入 architecture
3 Coder 写入 code
4 Reviewer 写入 review_result + feedback
5 revise? → Coder 修改 code，revision_count++
6 approved → Supervisor → FINISH

Supervisor = 动态路由器

Supervisor 不做具体工作，只决策"下一步派谁"。它不是硬编码的 if-else，而是让 LLM 根据 State 状态做路由决策。

图结构

                    ┌──────────────────┐
                    │    Supervisor    │
                    │  (LLM 路由决策)   │
                    └────────┬─────────┘
                             │
       ┌─────────────────────┼─────────────────────┐
       │                     │                     │
       ▼                     ▼                     ▼
  ┌─────────┐          ┌─────────┐          ┌─────────┐
  │   PM    │          │Architect│          │  Coder  │
  └────┬────┘          └────┬────┘          └────┬────┘
       │                    │                    │
       └────────────────────┴────────────────────┤
                                                 ▼
                                          ┌─────────┐
                                          │Reviewer │
                                          └────┬────┘
                                               │
                                     ┌─────────┴─────────┐
                                     │                   │
                                approved              revise
                                     │                   │
                                     ▼                   ▼
                                   END           Coder/Architect
                                                  │
                                                  ▼
                                             Supervisor

Supervisor 决策规则

条件→ 决策
task_breakdown 为空pm
有任务、architecture 为空architect
有架构、code 为空coder
有代码、未审查reviewer
revise + revision_count < 3coder 或 architect
approved 或 revision_count >= 3FINISH
为什么不用固定顺序流水线？
固定流水线（PM→Arch→Coder→Review→END）无法处理 Reviewer 打回修改的场景。
Supervisor 模式天然支持循环和条件跳转，这是 LangGraph 胜过 LangChain LCEL 的关键能力。

Multi-Agent 中的典型冲突

冲突场景解决机制
Reviwer ↔ Coder Reviewer 反复打回，Coder 反复修改 revision_count < 3 上限保护
Architect 越界 架构设计超出了 PM 任务范围 Reviewer 对照 task_breakdown 校验
Coder 质疑架构 Coder 发现架构问题但不能改 # [疑问] 注释 → Reviewer 判断是否退回 Architect
标准分歧 "好的代码"见仁见智 3 轮后自动通过 Stop-the-World 机制

三层冲突解决

第一层：预防
System Prompt 明确边界
90% 冲突在源头消除
↓
第二层：仲裁
Reviewer 统一标准裁决
9% 冲突有规则可依
↓
第三层：强制终止
revision_count >= 3 停止
1% 死锁自动解除

完整协作示例

用户输入: "开发一个用户管理系统，支持注册、登录、查询个人信息"

R1 Supervisor → PM 没有任务列表，先分析需求
PM 产出: P0 注册/登录/查询 | P1 密码重置 | P2 角色权限
R2 Supervisor → Architect 有任务、无架构
Architect 产出: FastAPI + SQLite + JWT | User(id,username,password_hash) | POST /register, /login, GET /users/me
R3 Supervisor → Coder 有架构、无代码
Coder 产出: 完整 Python 代码（FastAPI app + models + routers ~100行）
R4 Supervisor → Reviewer 有代码、未审查
Reviewer: 评分 6/10, revise — "密码未 hash，/users/me 缺少认证校验"
R5 Supervisor → Coder 修改意见 + revision_count=0
Coder 修改: 添加 passlib hash + JWT 依赖注入认证
R6 Supervisor → Reviewer 重新审查
Reviewer: 评分 9/10, approved ✓
R7 Supervisor → FINISH 审查通过，交付项目

Multi-Agent 框架对比

框架协调方式灵活度学习曲线适用场景
LangGraph 显式图 + State + Supervisor 最高 中 需要精细控制流程、循环依赖
CrewAI 预定义 Crew/Task 抽象 中 低 快速搭建多 Agent 原型
AutoGen 对话驱动、GroupChat 中 中 对话式协作、研究讨论
OpenAI Swarm 函数路由、handoff 低 低 简单任务分发、Demo

本项目为什么选 LangGraph

学习路径

009-agent-learning (单 Agent 基础)
         │
         ▼
007-langgraph-learning (StateGraph + Supervisor 模式)
         │
         ▼
010-multi-agent-learning (本模块: 4 Agent 协作)
         │
         ▼
    未来: 真实工具集成 (GitHub API, 文件系统, Docker)
         评估体系 (自动化测试, 性能基准)
         人机协作 (Human-in-the-Loop)