Multi-Agent系统实战：任务拆解、上下文隔离与协作机制

1. 为什么单Agent不够用：从一次真实翻车说起

去年下半年我接手了一个内部工具链的改造项目，需求说起来不复杂：把散落在各个仓库里的技术文档做一次结构化整理，提取出接口定义、参数说明和调用示例，最后生成一份统一的API索引。我第一反应是写个Agent一把梭——给它一个系统提示词，挂上文件读写和搜索工具，让它自己遍历目录、逐个处理。

结果第一天就翻车了。处理到第17个文件的时候，Agent开始"失忆"，前面已经提取过的接口定义被它重新当成新内容处理，输出里出现了大量重复条目。更离谱的是，它在处理某个嵌套目录时，把上一轮对话里残留的路径信息当成了当前任务的输入，导致整个输出结构错乱。我盯着日志看了半天才反应过来：上下文窗口被塞满了，历史信息互相污染，Agent在长任务里彻底迷失了方向。

这不是个例。任何用过单Agent处理复杂任务的人，大概率都遇到过类似场景：任务一长就丢状态，工具一多就选错，步骤一深就绕圈。根本原因在于，单Agent把"理解任务、规划步骤、执行操作、维护状态"全部压在一个上下文里，而这个上下文是有限的、线性的、容易被污染的。

Multi-Agent要解决的就是这个问题。它的核心思路可以用一句话概括：把一个大任务拆成若干子任务，每个子任务交给独立的Agent处理，每个Agent拥有自己干净的上下文，Agent之间通过明确的协作机制传递结果。拆任务、隔离上下文、协作机制，这三件事构成了Multi-Agent系统的全部骨架。下面我按自己实际踩坑和落地的经验，把这三块逐一拆开讲。

2. 拆任务：不是切得越细越好

2.1 拆任务的本质是定义边界

很多人一上来就想把任务切成十来个步骤，觉得越细越专业。我试过，结果是灾难。切得太细，Agent之间的通信开销爆炸，每个Agent都要等上游输出，整体延迟比单Agent还高；而且细粒度切分容易把本来有强关联的操作硬生生拆开，导致下游Agent拿到的信息不完整，还得回头找上游要。

拆任务的核心不是"切多少刀"，而是定义清楚每个子任务的输入边界和输出边界。一个合格的子任务应该满足三个条件：输入明确（知道要什么）、输出明确（知道交付什么）、职责单一（不掺杂其他环节的判断）。举个我实际用过的例子，文档结构化整理这个任务，我最终拆成了四段：

这样切的好处是，每个Agent的上下文里只需要装自己那一段的信息，互不干扰。扫描Agent不需要知道接口长什么样，提取Agent不需要知道有多少个文件，去重Agent不需要关心文件从哪来。

2.2 拆任务的三种常见模式

根据我做过的一些项目，拆任务大致可以归为三种模式，选哪种取决于任务本身的形态。

流水线模式是最直观的，任务有明确的先后顺序，上游输出就是下游输入。适合数据处理、内容生成这类线性流程。优点是逻辑清晰、容易调试；缺点是串行执行，整体耗时是各段之和，而且一旦中间某段出错，后面全得重来。

并行扇出模式适合可以独立处理的子任务。比如批量处理100个文件，每个文件的处理互不依赖，就可以同时起多个Agent并行跑。这里的关键是结果汇总环节要设计好，否则并行跑完一堆结果，合并的时候又是一团乱麻。我一般会要求每个并行Agent输出统一格式，汇总Agent只做机械合并，不做二次判断。

层级委派模式适合任务本身有嵌套结构的情况。一个主控Agent负责整体规划，把子任务委派给下层Agent，下层Agent如果遇到更细的子任务，再往下委派。这种模式灵活但难控，我一般只在任务复杂度确实需要时才用，而且会严格限制委派层数，超过三层基本就失控了。

2.3 拆任务时最容易踩的坑

第一个坑是按步骤拆而不是按职责拆。比如"先读文件再提取再写入"，这是三个步骤，但如果拆成三个Agent，读文件的Agent和提取的Agent之间要传整个文件内容，上下文开销很大。更好的做法是按职责拆：一个Agent负责"从文件到结构化数据"，读和提取在它内部完成，对外只暴露结构化数据这个输出。

第二个坑是子任务之间隐含依赖没显式化。我遇到过提取Agent需要知道文件类型才能选对解析策略，但文件类型是扫描Agent产出的，如果不在输入里明确传过去，提取Agent就得自己再判断一遍，既浪费又容易判断错。解决办法是在拆任务阶段就把所有跨Agent的依赖列成一张表，确保每个依赖都有明确的传递路径。

第三个坑是拆完不验证。拆完任务后，我会做一次"空跑验证"：假设每个Agent都完美执行，把输出串起来，看最终结果是不是我想要的。如果串起来发现中间缺了环或者多了冗余，说明拆分有问题，得回去调整。

3. 隔离上下文：Multi-Agent的命门

3.1 上下文为什么会污染

要理解隔离上下文的重要性，得先搞清楚上下文是怎么被污染的。单Agent处理长任务时，上下文里会不断累积：系统提示词、历史对话、工具调用记录、工具返回结果、中间推理过程。这些东西混在一起，时间一长就出现几个问题。

信息过载：上下文里塞了太多无关信息，Agent抓不住重点。我见过一个Agent在处理第30个文件时，还在"回忆"第3个文件的内容，因为那些内容还在上下文里。

角色混淆：Agent分不清哪些信息是当前任务的，哪些是历史遗留的。前面提到的路径污染就是这个原因。

指令漂移：随着上下文变长，最初的系统指令被稀释，Agent的行为逐渐偏离预期。这个在长对话里特别明显。

隔离上下文的核心目的，就是让每个Agent只看到自己需要的信息，看不到不该看的。这不是简单的"少给点信息"，而是有意识地设计每个Agent的信息边界。

3.2 隔离的三个层次

我在实践中把上下文隔离分成三个层次，从粗到细依次是：进程级隔离、会话级隔离、字段级隔离。

进程级隔离是最彻底的，每个Agent跑在独立的进程或独立的会话里，彼此完全不共享内存。这种隔离最干净，但通信成本最高，适合子任务之间完全独立的场景。比如并行处理100个文件，每个文件一个独立Agent，互不干扰。

会话级隔离是每个Agent有独立的对话历史，但共享一些全局状态（比如任务配置、公共工具）。这种隔离在大多数场景下够用，也是我推荐默认采用的方案。实现上就是给每个Agent维护独立的message列表，全局状态通过一个只读的配置对象传入。

字段级隔离是最细的，在同一个上下文里，通过结构化字段来区分不同来源的信息。比如用<task_input>、<upstream_result>、<global_config>这样的标签把信息分区，Agent在推理时能明确知道每块信息的来源和用途。这种隔离成本最低，但对Agent的指令遵循能力要求高，适合子任务耦合较紧的场景。

实际项目里我一般是组合使用：Agent之间用会话级隔离，Agent内部用字段级隔离，需要完全独立的并行任务用进程级隔离。

3.3 上下文传递的设计原则

隔离不等于不传递。Agent之间还是要传数据的，关键是传什么、怎么传、传多少。

传什么：只传下游Agent必需的字段，不传原始上下文。比如提取Agent处理完一个文件后，传给去重Agent的应该是结构化的接口列表，而不是整个文件的原始内容加上提取过程的推理记录。

怎么传：用结构化格式（JSON最常用），不要用自然语言描述。自然语言传递信息量大但歧义多，结构化格式虽然死板但准确。我一般会定义一个Agent间通信的schema，所有Agent的输出都按这个schema来，下游Agent按schema解析。

传多少：这里有个反直觉的经验——宁可多传一点结构化字段，也不要少传导致下游要回头问。因为回头问的代价是双向通信，比一次性多传几个字段的成本高得多。我一般会把下游可能用到的元信息（来源、时间戳、版本号）都带上，反正结构化字段占的token不多。

3.4 一个具体的隔离实现示例

拿前面文档整理的项目来说，提取Agent的上下文结构大概是这样设计的：

# 提取Agent的上下文构造（伪代码） def build_extract_context(file_path, file_type, global_schema): return { "system": "你是一个文档提取Agent，只负责从给定文件中提取接口定义...", "task": { "file_path": file_path, "file_type": file_type, "output_schema": global_schema # 只读，来自全局配置 }, "history": [] # 每个文件处理时重置，不累积 }

关键点在于history每次处理新文件时都重置，global_schema是只读的全局配置，task里只放当前文件的信息。这样提取Agent的上下文永远是干净的，处理第100个文件和处理第1个文件的状态完全一样。

对比一下单Agent的做法：所有文件的信息都堆在一个上下文里，处理到后面上下文爆满，还得做截断，截断又可能丢掉关键信息。隔离上下文从根本上解决了这个问题。

4. 协作机制：Agent之间怎么配合

4.1 协作的四种基本形态

Agent拆开了、上下文隔离了，接下来就是它们怎么配合。我总结下来有四种基本形态，复杂度依次递增。

顺序传递是最简单的，A做完传给B，B做完传给C。适合流水线式的任务。实现上就是一个队列，每个Agent从队列取任务、处理后把结果放回队列。这种形态的难点在于错误处理——如果B失败了，A的结果怎么办？我的做法是每个环节都保留中间结果，失败时可以从任意环节重试，不用从头来。

广播订阅适合一个Agent的输出需要被多个Agent消费的场景。比如扫描Agent产出的文件清单，提取Agent和统计Agent都需要。实现上可以用一个简单的发布订阅模式，扫描Agent发布清单，其他Agent订阅。这种形态要注意的是订阅者的处理速度可能不一致，需要做背压控制，否则快的Agent会一直等慢的。

协商决策适合需要多个Agent共同决定一件事的场景。比如去重时，两个Agent对同一条记录是否重复有分歧，就需要协商。实现上一般用一个仲裁Agent，收集各方意见后做最终判断。这种形态最容易出问题的是死循环——两个Agent互相说服不了对方，一直来回。我的做法是设置最大协商轮数，超过就升级给人工或走默认策略。

竞争执行适合同一个任务有多个解法、想选最优的场景。比如同一个提取任务，用两种不同的提示词各跑一遍，选结果更好的那个。实现上就是并行跑多个Agent，然后用一个评估Agent打分选优。这种形态成本高，一般只在关键环节用。

4.2 通信协议的设计

Agent之间通信，最怕的是格式不统一。A输出的是自然语言，B期望的是JSON，中间就得加一层解析，解析又容易出错。我的经验是在项目开始就定死通信协议，所有Agent的输入输出都按协议来。

协议设计有几个要点。第一是字段命名要一致，不要一个Agent用file_path，另一个用filepath。第二是必填字段和可选字段要分清，必填字段缺失时直接报错，不要静默处理。第三是版本号要带上，协议升级时下游Agent能识别并做兼容处理。

我一般会用JSON Schema来定义协议，每个Agent的输出都做一次schema校验，校验不过的直接打回重做。这样虽然多了一步校验，但能避免大量下游的诡异错误。

4.3 状态管理：谁记得任务进度

Multi-Agent系统里，任务进度由谁维护是个关键设计决策。有三种常见做法。

中心化状态：有一个专门的状态管理Agent或状态存储，所有Agent的进度都往这里写，需要时从这里读。优点是全局视图清晰，缺点是状态存储容易成为瓶颈，而且一旦挂了整个系统就瘫了。

去中心化状态：每个Agent自己维护自己的状态，需要协作时通过消息传递同步。优点是鲁棒性好，缺点是全局进度不透明，调试困难。

混合模式：关键进度中心化存储，细节状态各Agent自己管。这是我在实际项目里用得最多的。比如整体任务进度（已完成多少文件、当前在哪个阶段）放在中心存储，每个文件的具体处理状态由处理它的Agent自己管。

状态管理还有一个容易忽略的点是幂等性。Agent重试时，同一个操作不能产生副作用。比如"写入结果"这个操作，重试时应该覆盖而不是追加。我一般会给每个操作带一个唯一ID，状态存储里记录已处理过的ID，重复的ID直接跳过。

4.4 错误处理与重试策略

Multi-Agent系统里错误是常态，关键是错误发生时系统怎么反应。我踩过的坑包括：一个Agent失败导致整个流水线卡死、重试时重复处理导致数据重复、错误信息在Agent之间传递时丢失上下文。

我的处理策略分三层。Agent内部：工具调用失败时先本地重试，重试次数用尽才向上报错。Agent之间：上游Agent失败时，下游Agent不应该傻等，而应该收到一个明确的失败信号，决定是跳过、用默认值还是终止。系统层面：有一个全局的监控，统计各Agent的失败率，失败率超过阈值时告警。

重试策略上，我一般用指数退避，第一次失败等1秒，第二次等2秒，第三次等4秒，避免短时间内大量重试打爆下游。同时设置最大重试次数，超过就标记为失败，不再重试，避免无限循环。

5. 一个完整的Multi-Agent落地案例

5.1 场景与目标

前面讲的都是拆开的知识点，这里用一个完整案例把它们串起来。场景是我做过的一个代码仓库文档生成项目：给定一个代码仓库，自动生成一份包含所有公开接口的文档，包括函数签名、参数说明、返回值、调用示例。

这个任务如果单Agent做，上下文根本装不下整个仓库的代码。所以必须用Multi-Agent。

5.2 任务拆解

我把它拆成了五个子任务：

1. 仓库扫描Agent：遍历仓库，识别出所有需要生成文档的源文件，输出文件清单和每个文件的类型。
2. 接口提取Agent：对单个文件，提取出所有公开接口的结构化信息。
3. 示例生成Agent：对单个接口，生成调用示例代码。
4. 文档组装Agent：把所有接口信息和示例组装成最终文档。
5. 质量校验Agent：检查文档的完整性和格式。

其中接口提取和示例生成是可以并行的，每个文件、每个接口独立处理。

5.3 上下文隔离设计

每个Agent的上下文都做了严格隔离。扫描Agent只看到目录结构，看不到文件内容。提取Agent只看到单个文件的内容和输出schema，看不到其他文件。示例生成Agent只看到单个接口的定义，看不到整个文档。组装Agent只看到结构化的接口列表，看不到原始代码。

这样设计的好处是，无论仓库多大，每个Agent的上下文都是可控的。扫描Agent的上下文大小和仓库文件数成正比，但只是路径字符串，占用很小。提取Agent的上下文大小和单个文件大小成正比，不会累积。

5.4 协作流程

整体流程是这样的：扫描Agent先跑，产出文件清单。然后对清单里的每个文件，起一个提取Agent并行处理。提取Agent产出接口列表后，对每个接口起一个示例生成Agent并行处理。所有示例生成完后，组装Agent把所有结果合并成文档。最后校验Agent检查一遍。

这里的关键是并行度的控制。我一开始没控制，100个文件同时起100个提取Agent，结果API限流了。后来加了一个信号量，最多同时跑10个，稳定多了。

5.5 实际效果与数据

这个系统跑下来，处理一个中等规模的仓库（约200个源文件、800个接口），总耗时大概15分钟。如果单Agent做，光是上下文就装不下，根本跑不完。而且因为每个Agent的上下文都干净，输出质量比单Agent稳定得多，重复和遗漏的情况基本没有了。

成本上，Multi-Agent的token消耗确实比单Agent高，因为每个Agent都有自己的系统提示词开销。但考虑到单Agent根本做不了这个任务，这个成本是值得的。我算过一笔账，如果换成人工写文档，800个接口至少需要一个人干一周，Multi-Agent 15分钟搞定，成本差距是数量级的。

6. 常见问题与排查技巧实录

6.1 Agent之间信息传递丢失

这是最常见的问题。表现是下游Agent报错说缺少某个字段，但上游Agent明明输出了。排查思路：先看上游Agent的实际输出，确认字段是否真的存在；再看通信协议，确认字段名是否一致；最后看下游Agent的解析逻辑，确认是否正确读取。

我遇到过一次，上游输出的是return_type，下游读的是returnType，就差一个下划线，排查了半天。后来我强制所有Agent的输入输出都过一遍schema校验，这类问题就再也没出现过。

6.2 并行Agent结果顺序错乱

并行处理时，结果回来的顺序是不确定的。如果下游Agent依赖顺序，就会出问题。解决办法是在每个结果里带上序号，下游按序号排序后再处理。不要依赖结果到达的顺序，那个是不可靠的。

6.3 某个Agent成为瓶颈

流水线里如果某个环节特别慢，整个流程就被拖住了。排查方法是统计每个Agent的平均处理时间和队列等待时间，找出瓶颈环节。解决办法要么是给瓶颈环节增加并行度，要么是优化它的处理逻辑。我遇到过一次瓶颈是示例生成Agent，因为它要调用外部API，后来加了缓存，同样的接口定义不重复生成，速度提升了好几倍。

6.4 上下文隔离不彻底导致串味

表现是Agent的输出里出现了不属于它职责范围的内容。比如提取Agent的输出里出现了示例代码。排查方法是检查Agent的上下文构造，看是否混入了不该有的信息。常见原因是全局状态没有做只读隔离，某个Agent修改了全局状态，影响了其他Agent。

6.5 常见问题速查表

6.6 几条独家避坑经验

第一条，先跑通再优化。我一开始就想把Multi-Agent设计得很完美，结果卡在架构设计上好几天。后来改成先用最简单的顺序传递跑通全流程，再逐步优化隔离和并行，效率高多了。

第二条，日志要打全。Multi-Agent系统出问题时，光看最终输出根本定位不到是哪一环出的错。我后来给每个Agent的输入输出都打了日志，还带上了trace_id，出问题时能顺着trace_id把整个链路串起来看。

第三条，不要过度隔离。隔离是为了避免污染，但隔离太狠会导致Agent之间信息不足，反而要来回通信。我的经验是，先按最小必要信息隔离，跑起来发现信息不够再补，比一开始就过度隔离要好调。

第四条，给每个Agent起个明确的名字。听起来是小事，但调试时"Agent3报错了"和"接口提取Agent报错了"，定位效率完全不一样。名字本身就是一种文档。

7. 我个人的一些体会

Multi-Agent这套东西，刚接触时容易被各种概念绕晕，什么编排、什么协作、什么通信协议。但真正落地下来，核心就三件事：把任务拆清楚、把上下文隔干净、把协作定明白。这三件事做好了，系统就稳；任何一件没做好，就会在各种奇怪的地方出问题。

我现在做新项目，习惯是先画一张图，把任务拆成几个方块，每个方块标上输入输出，方块之间画箭头标上传递的数据。这张图想清楚了，代码写起来就顺了。如果图画不清楚，说明任务本身还没想明白，这时候写代码就是浪费。

另外一点体会是，Multi-Agent不是银弹。有些任务单Agent就能做好，硬上Multi-Agent反而增加复杂度。判断标准很简单：如果单Agent的上下文装得下、不污染、不迷失，那就没必要拆。只有当任务复杂度确实超过了单Agent的处理能力时，Multi-Agent才是必要的。

最后分享一个小技巧：调试Multi-Agent时，我会先把所有Agent换成"假Agent"——输入什么就输出什么，或者输出预定义的mock数据。这样能先验证协作流程本身是否通，再逐个替换成真Agent。这个做法帮我省了大量调试时间，因为流程问题和Agent本身的问题可以分开排查，不会混在一起。