multi-agent-patterns

Claude Code 的多 Agent 架构模式

多 Agent 架构将工作分配给多个 Agent 调用，每个调用都有专注于特定任务的上下文。设计得当时，这种分配能实现超越单 Agent 能力上限的功能；设计不当时，则会带来协调开销，抵消这些优势。关键在于，子 Agent 的主要作用是隔离上下文，而不是将角色分工拟人化。

核心概念

多 Agent 系统通过分散工作来应对单 Agent 的上下文限制。主要有三种模式：用于集中控制的监督者／编排者模式、用于灵活交接的点对点／蜂群模式，以及用于分层抽象的层级模式。关键设计原则是上下文隔离——子 Agent 的主要作用是划分上下文，而不是模拟组织角色。

有效的多 Agent 系统需要明确的协调协议、避免谄媚行为的共识机制，并仔细关注瓶颈、分歧和错误传播等故障模式。

为什么采用多 Agent 架构

上下文瓶颈

单 Agent 在推理能力、上下文管理和工具协调方面存在固有上限。随着任务日益复杂，上下文窗口会被累积的历史记录、检索到的文档和工具输出填满。性能会按照可预见的规律下降：中间信息遗失效应、注意力稀缺和上下文污染。

多 Agent 架构通过将工作划分到多个上下文窗口中来应对这些限制。每个 Agent 都在干净的上下文中运行，专注于自己的子任务。结果会在协调层汇总，而无需由任何单一上下文承担全部负担。

并行化论据

许多任务包含可并行处理的子任务，而单 Agent 必须按顺序执行这些任务。研究任务可能需要搜索多个互不相关的来源、分析不同文档或比较相互竞争的方法。单 Agent 会依次处理这些任务，并在每一步累积上下文。

多 Agent 架构会将每个子任务分配给一个专用 Agent，并为其提供全新的上下文。所有 Agent 同时工作，然后将结果返回给协调者。实际总耗时接近耗时最长的子任务，而不是所有子任务耗时之和。

专业化论据

不同任务适合不同的 Agent 配置：不同的系统提示词、不同的工具集、不同的上下文结构。通用 Agent 必须在上下文中携带所有可能的配置；专业化 Agent 则只携带所需内容。

多 Agent 架构能够实现专业化，同时避免组合爆炸。协调者将任务路由给专业化 Agent；每个 Agent 都使用针对其领域优化的精简上下文运行。

架构模式

模式 1：主管／编排器

主管模式由一个中央 Agent 负责控制，将任务委派给专业 Agent 并综合结果。主管维护全局状态和执行轨迹，将用户目标分解为子任务，并将任务分配给合适的执行 Agent。

User Request -> Supervisor -> [Specialist A, Specialist B, Specialist C] -> Aggregation -> Final Output

适用场景： 可明确分解的复杂任务、需要跨领域协调的任务，以及重视人工监督的任务。

优点： 严格控制工作流，更容易实施人在回路中的干预，并确保遵循预定义计划。

缺点： 主管的上下文会成为瓶颈；主管故障会波及所有执行 Agent；还可能出现“传话游戏”问题，即主管错误地转述子 Agent 的响应。

Claude Code 实现： 创建一个主命令，通过调用专用子 Agent 的 Task 工具来编排工作。主管命令包含协调逻辑，并调用子 Agent 执行专门的工作。

1. Analyze the user request and decompose into subtasks
2. For each subtask, dispatch to appropriate specialist:
   - Use Task tool to spawn subagent with focused context
   - Pass only relevant context to each subagent
3. Collect and synthesize results from all subagents
4. Return unified response to user

传话游戏问题： 如果主管错误地转述子 Agent 的响应，导致信息失真，主管架构的表现可能会变差。解决方法：如果综合响应会丢失重要细节，就允许子 Agent 直接传递响应。在 Claude Code 中，这意味着让子 Agent 直接写入共享文件，或原样返回输出，而不是让主管重写所有内容。

模式 2：点对点／群集

点对点模式取消了中央控制，允许 Agent 根据预定义协议直接通信。任何 Agent 都可以通过明确的交接机制将控制权转交给其他 Agent。

适用场景： 需要灵活探索的任务、僵化规划会适得其反的任务，以及需求会自然涌现、难以预先分解的任务。

优点： 不存在单点故障；适合扩展广度优先探索；能够产生涌现式的问题解决行为。

缺点： Agent 数量增加会提升协调复杂度；缺少中央状态管理者时存在偏离风险；需要健全的收敛约束。

Claude Code 实现： 创建可根据发现的需求调用其他命令的命令。使用共享文件（如任务列表或状态文件）作为协调机制。

1. Analyze current state from shared context file
2. Determine if this agent can complete the task
3. If specialized help needed:
   - Write current findings to shared state
   - Invoke appropriate peer command/skill
4. Continue until task complete or hand off

模式 3：分层

分层结构将 Agent 组织为不同抽象层：战略层、规划层和执行层。战略层 Agent 制定目标和约束；规划层 Agent 将目标分解为可执行计划；执行层 Agent 执行原子任务。

Strategy Layer (Goal Definition) -> Planning Layer (Task Decomposition) -> Execution Layer (Atomic Tasks)

适用场景： 结构清晰的大型项目、具有管理层级的企业工作流，以及同时需要高层规划和详细执行的任务。

优点： 与组织结构相似；职责分工明确；能够在不同层级采用不同的上下文结构。

缺点： 层级之间的协调开销；战略与执行之间可能出现偏差；错误传播过程复杂。

Claude Code 实现： 将插件中的命令按不同抽象层级组织起来。高层命令专注于战略，并调用中层规划命令；中层规划命令再调用原子执行命令。

将上下文隔离作为设计原则

多 Agent 架构的主要目的是隔离上下文。每个子 Agent 都在干净的上下文窗口中专注于自己的子任务，不会携带其他子任务累积的上下文。

隔离机制

指令传递： 对于简单、定义明确的子任务，协调器会创建有针对性的指令。子 Agent 只会收到完成其特定任务所需的指令。在 Claude Code 中，这意味着通过 Task 工具向子 Agent 传递精简且有针对性的提示词。

文件系统记忆： 对于需要共享状态的复杂任务，Agent 会读取并写入持久化存储。文件系统充当协调机制，避免因传递共享状态而导致上下文膨胀。这是 Claude Code 中最自然的模式——Agent 通过 Markdown 文件、JSON 状态文件或结构化文档进行通信。

完整上下文委派： 对于需要子 Agent 全面理解的复杂任务，协调器会共享其完整上下文。子 Agent 拥有自己的工具和指令，但会收到完整上下文，以便做出决策。请谨慎使用这种方式，因为它会违背上下文隔离的目的。

隔离权衡

完整上下文委派能提供最大的能力，但会违背使用子 Agent 的目的。指令传递能够维持隔离，但会限制子 Agent 的灵活性。文件系统记忆可以在不传递上下文的情况下实现状态共享，但会带来一致性方面的挑战。

合适的选择取决于任务复杂度、协调需求和工作性质。

共识与协调

投票问题

简单多数投票会将薄弱推理产生的幻觉与可靠推理等同看待。如果不加干预，多 Agent 讨论可能会因固有的从众倾向而逐渐形成对错误前提的共识。

加权贡献

根据置信度或专业知识为 Agent 的贡献赋予权重。在最终决策中，置信度更高或具备相关领域专业知识的 Agent 权重更大。

辩论协议

辩论协议要求 Agent 在多轮讨论中相互评议输出。对于复杂推理，对抗性评议通常比协作式共识能带来更高的准确性。

Claude Code 实现： 创建一个评审阶段，由一个 Agent 评议另一个 Agent 的输出。将其设计为独立的命令：一个用于初始工作，一个用于评议，还可以选择添加一个基于评议结果进行修订的命令。

基于触发条件的干预

监控多 Agent 交互，识别特定的行为标志：

• 停滞触发条件： 在讨论没有进展时触发
• 谄媚触发条件： 检测 Agent 是否在没有独立推理的情况下模仿彼此的答案
• 偏离触发条件： 检测 Agent 是否偏离了原始目标

失败模式与缓解措施

失败：监督者瓶颈

监督者会累积所有工作 Agent 的上下文，容易导致容量饱和和性能下降。

缓解措施： 限制输出，要求工作 Agent 只返回提炼后的摘要。使用基于文件的检查点机制持久化状态，避免在上下文中携带完整历史记录。

失败：协调开销

Agent 通信会消耗 token 并增加延迟。复杂的协调可能抵消并行化带来的收益。

缓解措施： 通过明确的交接协议尽量减少通信。使用结构化文件格式进行 Agent 间通信。在可能的情况下，批量汇总结果。

失败：偏离

在缺乏中央协调的情况下，Agent 追求不同目标可能会偏离预期目标。

缓解措施： 为每个 Agent 明确目标边界。实施收敛检查，确认是否正朝共同目标推进。为 Agent 的执行设置迭代次数上限。

失败：错误传播

一个 Agent 输出中的错误会传播到使用该输出的下游 Agent。

缓解措施： 在将 Agent 的输出传递给使用方之前进行验证。实施重试逻辑。设计组件故障时的平稳降级机制。

在 Claude Code 中应用模式

作为主管的命令

创建一个主命令，用于：

1. 分析任务并制定计划
2. 通过 Task 工具派遣子 Agent 执行专业工作
3. 收集结果（通过返回值或共享文件）
4. 综合生成最终输出

作为专家的子 Agent

针对专业领域定义子 Agent：

• 每个子 Agent 专注于一个专业领域
• 子 Agent 仅接收与其专业领域相关的精简上下文
• 子 Agent 返回结构化输出，供协调者汇总

将文件用作共享记忆

使用文件系统进行 Agent 间协调：

• 状态文件跟踪各 Agent 的进度
• 输出文件收集并行工作的结果
• 任务列表协调待完成的工作

示例：多 Agent 代码审查

Supervisor Command: review-code
├── Subagent: security-review (security specialist)
├── Subagent: performance-review (performance specialist)
├── Subagent: style-review (style/conventions specialist)
└── Aggregation: combine findings, deduplicate, prioritize

每个子 Agent 只会收到要审查的代码以及其专业领域说明。主管会汇总所有发现，形成统一的审查结果。

指南

1. 将上下文隔离作为多 Agent 系统的首要优势来设计
2. 根据协调需求而非组织结构比喻选择架构模式
3. 将基于文件的通信作为 Claude Code 多 Agent 模式的默认方案
4. 实施明确的交接协议，并清晰传递状态
5. 通过批评／辩论模式达成共识，而非简单认同
6. 监控主管是否成为瓶颈，并通过文件设置检查点
7. 在 Agent 之间传递输出前先进行验证
8. 设置迭代次数上限，防止无限循环
9. 明确测试故障场景
10. 从简单方案开始——仅在单 Agent 方案无法满足需求时，才增加多 Agent 的复杂性

记忆与状态管理

对于跨多个会话的任务，或需要持久化状态的任务，请使用基于文件的记忆：

工作记忆

即上下文窗口本身。它能提供即时访问，但会在会话结束时消失。仅保留当前活跃信息，并对已完成的工作进行总结。

会话记忆

在会话期间创建、用于跟踪进度的文件：

• 任务列表（已完成事项和剩余事项）
• 中间结果
• 决策日志

长期记忆

可跨会话保留的持久化文件：

• 用于项目级上下文的 CLAUDE.md
• 指定目录中的记忆文件
• 以 Markdown 或 JSON 格式保存的结构化知识库

多 Agent 的记忆模式

• 交接文件： Agent A 写入状态，Agent B 读取并继续
• 结果汇总： 多个 Agent 分别将结果写入不同文件，主管读取所有文件
• 进度跟踪： 所有 Agent 都会更新的共享任务列表
• 知识积累： Agent 将发现追加到共享知识文件中

选择能满足需求的最简单记忆机制。基于文件的记忆具有透明、易于调试且无需基础设施的优点。

记忆系统设计

记忆提供持久化层，使 Agent 能够在多个会话之间保持连续性，并基于积累的知识进行推理。简单的 Agent 完全依赖上下文作为记忆，会在会话结束时丢失所有状态。复杂的 Agent 会实现分层记忆架构，在满足即时上下文需求与保留长期知识之间取得平衡。从向量存储到知识图谱，再到时序知识图谱的演进，体现了为改进检索和推理而不断增加对结构化记忆的投入。

核心概念

记忆的范围从即时上下文延伸到永久存储。一端是上下文窗口中的工作记忆，它能提供零延迟访问，但会在会话结束时消失；另一端是永久存储，它能无限期保留，但需要检索才能进入上下文。

简单的向量存储缺乏关系和时间结构。知识图谱保留关系以支持推理。时序知识图谱则增加有效期，以支持感知时间的查询。具体的实现选择取决于查询复杂度、基础设施限制和准确性要求。

详细主题

记忆架构基础

上下文-记忆谱系 记忆存在于从即时上下文到永久存储的谱系上。在一个极端，上下文窗口中的工作记忆提供零延迟访问，但会在会话结束时消失。在另一个极端，永久存储无限期持久存在，但需要检索才能进入上下文。有效的架构会沿着这一谱系使用多个层级。

该谱系包括工作记忆（上下文窗口、零延迟、易失）、短期记忆（会话内持久、可搜索、易失）、长期记忆（跨会话持久、结构化、半永久）和永久记忆（归档、可查询、永久）。每个层级都有不同的延迟、容量和持久性特征。

为什么简单的向量存储不够用 向量 RAG 通过将查询和文档嵌入共享的嵌入空间来提供语义检索。相似性搜索会检索语义上最相似的文档。这对文档检索很有效，但缺乏用于 Agent 记忆的结构。

向量存储会丢失关系信息。如果 Agent 得知“客户 X 在日期 Z 购买了产品 Y”，当被直接询问时，向量存储可以检索出这一事实。但它无法回答“购买产品 Y 的客户还购买了哪些产品？”，因为关系结构没有被保留。

向量存储也难以处理时间有效性。事实会随时间变化，但向量存储除了通过显式元数据和过滤之外，没有机制区分“当前事实”和“过时事实”。

转向基于图的记忆 知识图谱保留实体之间的关系。图不是孤立的文档块，而是编码实体 A 与实体 B 之间存在关系 R。这使得查询可以遍历关系，而不仅仅是依赖相似性。

时间知识图谱为事实添加了有效期间。每个事实都有一个“valid from”以及可选的“valid until”时间戳。这使得时间旅行查询成为可能，可以重建特定时间点的知识。

基准性能比较 Deep Memory Retrieval（DMR）基准提供了跨记忆架构的具体性能数据：

记忆系统	DMR 准确率	检索延迟	说明
Zep（时间 KG）	94.8%	2.58s	最佳准确率，检索快速
MemGPT	93.4%	可变	总体性能良好
GraphRAG	~75-85%	可变	相比基线 RAG 提升 20-35%
向量 RAG	~60-70%	快速	丢失关系结构
递归摘要	35.3%	低	严重信息丢失

与完整上下文基线相比，Zep 展示出检索延迟降低 90%（GPT-5.2 为 2.58s 对 28.9s）。这种效率来自只检索相关子图，而不是整个上下文历史。

在复杂推理任务中，GraphRAG 相比基线 RAG 实现了约 20-35% 的准确率提升，并通过基于社区的摘要将幻觉降低最多 30%。

记忆层架构

第 1 层：工作记忆 工作记忆就是上下文窗口本身。它提供对当前正在处理的信息的即时访问，但容量有限，并且会在会话结束时消失。

工作记忆的使用模式包括：Agent 用来跟踪中间结果的暂存区计算、为当前任务保留对话内容的对话历史、跟踪活跃目标进展的当前任务状态，以及保存当前正在使用信息的活跃检索文档。

通过只保留活跃信息、在已完成工作从注意力中淡出之前对其进行总结，以及将关键信息放在注意力偏好的位置，来优化工作记忆。

第 2 层：短期记忆 短期记忆会在当前会话中持续存在，但不会跨会话保留。它提供搜索和检索能力，同时没有永久存储的延迟。

常见实现包括：持续到会话结束的会话级数据库、存储在指定会话目录中的文件系统存储，以及按会话 ID 作为键的内存缓存。

短期记忆的使用场景包括：跨轮次跟踪对话状态而无需塞满上下文、存储工具调用产生的之后可能需要的中间结果、维护任务清单和进度跟踪，以及在会话内缓存已检索的信息。

第 3 层：长期记忆 长期记忆会跨会话无限期地持续存在。它使 Agent 能够从过去的交互中学习，并随时间积累知识。

长期记忆的实现范围从简单的键值存储到复杂的图数据库。选择取决于要建模的关系复杂度、所需的查询模式，以及可接受的基础设施复杂度。

长期记忆的使用场景包括：跨会话学习用户偏好、构建随时间增长的领域知识库、维护带关系历史的实体注册表，以及存储可复用的成功模式。

第 4 层：实体记忆 实体记忆专门跟踪关于实体（人物、地点、概念、对象）的信息，以保持一致。这会创建一个初步的知识图谱，使实体能够在多次交互中被识别出来。

实体记忆通过跟踪一次对话中提到的 “John Doe” 与另一次对话中的是同一个人，来维护实体身份。它通过存储随时间发现的关于实体的事实，来维护实体属性。它通过跟踪实体之间被发现的关系，来维护实体关系。

第 5 层：时间知识图谱 时间知识图谱通过明确的有效期扩展了实体记忆。事实不再只是真或假，而是在特定时间范围内为真。

这使诸如 “用户在日期 X 时的地址是什么？” 这样的查询成为可能，方法是检索在该日期范围内有效的事实。当过时信息与新数据冲突时，它可以防止上下文冲突。它支持关于实体如何随时间变化的时间推理。

记忆实现模式

模式 1：将文件系统用作记忆 文件系统本身可以充当记忆层。此模式简单易用，无需额外基础设施，还能实现按需加载，这也是基于文件系统的上下文管理如此有效的原因。

实现时使用文件系统层次结构进行组织，并采用具有明确含义的命名约定。以结构化格式（JSON、YAML）存储事实。使用文件名或元数据中的时间戳进行时间追踪。

优点：简单、透明、可移植。 缺点：无法进行语义搜索、无法追踪关系、需要手动整理。

模式 2：带元数据的向量 RAG 通过丰富的元数据增强向量存储，可实现带筛选功能的语义搜索。

实现时对事实或文档进行嵌入，并与元数据一同存储。元数据包括实体标签、时间有效性、来源归属和置信度分数。查询时，除语义搜索外，还包含元数据筛选条件。

模式 3：知识图谱 知识图谱对实体和关系进行显式建模。实现时定义实体类型和关系类型，使用图数据库或属性图存储，并针对常见查询模式维护索引。

模式 4：时态知识图谱 时态知识图谱为事实添加有效期，从而支持时间回溯查询，并避免过时信息造成上下文冲突。

记忆检索模式

语义检索 使用嵌入相似度搜索，检索与当前查询在语义上相似的记忆。

基于实体的检索 通过遍历图关系，检索与特定实体相关的所有记忆。

时态检索 使用有效期筛选条件，检索在特定时间或时间范围内有效的记忆。

记忆整合

记忆会随着时间不断累积，需要进行整合，以防止无限增长并移除过时信息。

整合触发条件 在记忆显著累积后、检索返回过多过时结果时、按计划定期执行，或收到明确的整合请求时，触发整合。

整合流程 识别过时事实、合并相关事实、更新有效期、归档或删除已失效的事实，并重建索引。