多Agent协作实战：handoff机制与AGENTS.md设计

1. 多 Agent 协作到底在解决什么问题1.1 从单兵作战到团队配合的必然转变我最早接触 Agent 这个概念的时候想法很朴素给它一个任务描述它自己去规划、去执行、去交付我坐等结果就行。实际跑下来才发现单个 Agent 在面对复杂任务时翻车概率高得离谱。比如让它同时处理“读需求文档、写代码、跑测试、整理变更记录”这一整条链路它经常在第三步就忘了第一步的约束条件或者在长上下文里把关键信息丢了。这不是模型能力不行而是单 Agent 的上下文窗口和注意力分配天然有上限。你让一个人同时干产品经理、程序员、测试和文档工程师的活他也得疯。多 Agent 协作的核心思路就一句话把复杂任务拆成职责明确的角色让每个角色只关注自己那一亩三分地通过标准化的交接协议串起来。我目前用的这套协作模式核心角色一般控制在 3 到 5 个之间。太少了拆不干净太多了协调成本爆炸。常见的分工是这样的规划 Agent负责理解需求、拆解任务、定义验收标准输出一份结构化的任务清单执行 Agent按任务清单逐项落地可能是写代码、写文档、做数据分析审查 Agent对执行结果做质量检查挑毛病、提修改意见汇总 Agent把各环节产出整合成最终交付物处理格式统一和逻辑连贯这套模式跑通之后我最直观的感受是任务完成率从原来的六成左右拉到了九成以上而且返工次数明显减少。原因很简单每个 Agent 的上下文都变短了注意力更集中出错概率自然下降。1.2 为什么“handoff”机制是整个协作的命脉多 Agent 协作里最容易出问题的环节不是某个 Agent 本身能力不够而是交接的时候信息丢了或者传歪了。我踩过最典型的坑是规划 Agent 写了一份很详细的任务清单执行 Agent 拿到之后只看了第一条就开始干活后面的约束条件全忽略了。结果就是干到一半发现方向不对推倒重来。后来我引入了handoff 机制说白了就是标准化的交接协议。每次一个 Agent 把任务转给下一个 Agent 时必须附带一份结构化的交接文档包含以下字段字段名作用是否必填task_id任务唯一标识方便追溯是from_agent交出方标识是to_agent接收方标识是context_summary当前上下文摘要控制在 200 字以内是deliverables已完成的产出物清单是constraints必须遵守的约束条件是next_action明确下一步要做什么是deadline期望完成时间否这份交接文档看起来简单但它解决了一个致命问题接收方不需要重新理解整个任务背景只需要看这份交接单就能快速进入状态。我实测下来有了 handoff 机制之后Agent 之间的“理解偏差”导致的返工减少了大概七成。注意context_summary 这个字段千万不要写太长。我一开始觉得写得越详细越好结果接收方 Agent 被大量冗余信息干扰反而抓不住重点。后来强制压缩到 200 字以内效果立竿见影。1.3 AGENTS.md让协作有据可依的“团队公约”多 Agent 协作还有一个隐形成本每个 Agent 的行为风格不一致。有的 Agent 喜欢先问清楚再动手有的 Agent 上来就干干到一半发现理解错了。这种不一致性在单 Agent 场景下不明显但在多 Agent 协作里会被放大。我的解法是引入一份AGENTS.md 文件放在项目根目录下所有 Agent 在启动时都必须先读这份文件。它相当于团队的“公约”规定了以下内容每个角色的职责边界和权限范围交接文档的标准格式和必填字段遇到不确定情况时的处理流程是先问还是先做输出物的格式规范比如代码必须带注释、文档必须带目录禁止行为清单比如不允许跳过审查环节直接交付这份文件我改了大概七八版才稳定下来。早期版本写得太笼统Agent 看了等于没看后来改成每条规则都带具体示例执行效果才上来。比如“输出物必须带目录”这条我会附上一个标准目录的示例Agent 照着抄就行。2. 协作 Skill 的核心设计与实现细节2.1 Skill 到底是什么给 Agent 装的“操作手册”很多人第一次听到 Skill 这个词会懵觉得是不是又是什么新框架。其实你可以把它理解成给 Agent 装的一本操作手册。Agent 本身有通用能力但面对具体任务时它需要知道“在这个场景下应该怎么做”。Skill 就是把这个“怎么做”固化下来变成可复用、可组合的模块。我目前用的协作 Skill 结构是这样的skills/ handoff/ SKILL.md # 交接协议说明 template.md # 交接文档模板 validator.py # 交接文档格式校验脚本 review/ SKILL.md # 审查流程说明 checklist.md # 审查清单 summary/ SKILL.md # 汇总流程说明 format.md # 输出格式规范每个 Skill 目录下的 SKILL.md 是核心文件它用自然语言描述了这个 Skill 的用途、输入输出、执行步骤和注意事项。Agent 在执行任务前会先读对应的 SKILL.md然后按里面的步骤操作。这种设计的好处是解耦。我想调整交接流程只需要改 handoff/SKILL.md不需要动其他任何地方。想增加一个新的审查维度只需要在 review/checklist.md 里加一条所有 Agent 下次执行时自动生效。2.2 协作 Skill 的目录结构与关键文件让我把协作 Skill 的核心文件拆开讲。首先是handoff/SKILL.md它的内容大概长这样# Handoff Skill ## 用途 在 Agent 之间传递任务时生成标准化的交接文档。 ## 输入 - 当前 Agent 标识 - 目标 Agent 标识 - 已完成的工作摘要 - 待完成的工作清单 - 约束条件 ## 输出 一份符合 template.md 格式的交接文档保存为 handoff_{task_id}.md ## 执行步骤 1. 读取 template.md了解必填字段 2. 填写 from_agent、to_agent、task_id 3. 用不超过 200 字总结当前上下文 4. 列出已完成的产出物附上文件路径 5. 列出约束条件每条不超过 50 字 6. 明确下一步动作用动词开头 7. 运行 validator.py 校验格式 8. 校验通过后将文档传递给目标 Agent ## 注意事项 - context_summary 严禁超过 200 字 - 约束条件必须具体可执行禁止写“注意质量”这类模糊表述 - 如果校验不通过必须修正后重新提交然后是review/checklist.md这是审查 Agent 的武器库# 审查清单 ## 代码类产出 - [ ] 是否有未处理的异常分支 - [ ] 关键函数是否有注释说明输入输出 - [ ] 是否有硬编码的配置项 - [ ] 变量命名是否清晰可读 ## 文档类产出 - [ ] 是否有目录且层级正确 - [ ] 术语使用是否前后一致 - [ ] 是否有未完成的占位符如 TODO、TBD - [ ] 示例代码是否可运行 ## 数据类产出 - [ ] 数据来源是否标注 - [ ] 异常值是否处理 - [ ] 统计口径是否说明这份清单我根据实际踩坑经验持续补充。比如“是否有未完成的占位符”这一条就是因为有一次执行 Agent 交了一份带 TODO 的文档审查 Agent 没注意直接放行最后交付到用户手里才发现。2.3 上下文变量的传递与隔离策略多 Agent 协作里上下文管理是个技术活。我的原则是该共享的共享该隔离的隔离。共享的部分包括任务目标、验收标准、全局约束条件、AGENTS.md 里的团队公约。这些信息所有 Agent 都需要知道放在一个公共的 context 文件里每个 Agent 启动时加载。隔离的部分包括每个 Agent 自己的执行日志、中间产出、局部决策记录。这些信息只对当前 Agent 有用传给下一个 Agent 反而是噪音。我通常会在 handoff 文档里只保留经过提炼的上下文摘要而不是把原始日志一股脑传过去。具体实现上我用了一个简单的目录结构来管理workspace/ shared/ task_goal.md # 任务目标所有 Agent 可读 acceptance.md # 验收标准所有 Agent 可读 AGENTS.md # 团队公约所有 Agent 可读 agents/ planner/ local_context.md # 规划 Agent 的局部上下文 output.md # 规划 Agent 的产出 executor/ local_context.md # 执行 Agent 的局部上下文 output.md # 执行 Agent 的产出 reviewer/ local_context.md # 审查 Agent 的局部上下文 output.md # 审查 Agent 的产出 handoffs/ handoff_001.md # 规划到执行的交接文档 handoff_002.md # 执行到审查的交接文档 handoff_003.md # 审查到汇总的交接文档这种结构的好处是每个 Agent 的上下文边界非常清晰。规划 Agent 不需要知道执行 Agent 中间试错了多少次执行 Agent 也不需要知道审查 Agent 内部讨论了什么。大家通过 handoff 文档和 shared 目录里的公共信息来协作信息流干净利落。实操心得我一开始图省事让所有 Agent 共享一个大的 context 文件结果就是每个 Agent 都被大量无关信息干扰执行效率反而下降。后来改成“公共信息 交接摘要”的模式效果好了很多。上下文隔离不是不共享信息而是只共享必要的信息。3. 完整协作流程的实操拆解3.1 从零搭建一个多 Agent 协作项目的步骤假设我现在要做一个“竞品分析报告”的项目需要多个 Agent 协作完成。我会按以下步骤操作第一步初始化项目结构mkdir -p competitor-analysis/{shared,agents,handoffs,skills} cd competitor-analysis touch shared/task_goal.md shared/acceptance.md shared/AGENTS.md mkdir -p agents/{planner,executor,reviewer,summarizer} mkdir -p skills/{handoff,review,summary}第二步编写 AGENTS.md这是团队公约必须最先写。内容包括角色定义、交接规范、输出标准、禁止行为。我通常会花 20 分钟左右打磨这份文件因为它直接影响后续所有环节的执行质量。第三步编写各 Skill 的 SKILL.md把 handoff、review、summary 三个核心 Skill 的说明文件写好。每个文件控制在 500 字以内重点说清楚“什么时候用、怎么用、注意什么”。第四步定义任务目标和验收标准在 shared/task_goal.md 里写清楚我们要分析哪几个竞品、分析哪些维度、输出什么格式的报告。在 shared/acceptance.md 里写清楚什么样的报告算合格、必须包含哪些章节、数据来源有什么要求。第五步启动规划 Agent规划 Agent 读取 task_goal.md 和 acceptance.md输出一份任务清单包含每个子任务的责任人、输入、输出、截止时间。然后生成 handoff_001.md把任务清单交给执行 Agent。第六步执行 Agent 逐项落地执行 Agent 按任务清单逐项执行每完成一项就更新自己的 output.md。全部完成后生成 handoff_002.md把产出交给审查 Agent。第七步审查 Agent 质量检查审查 Agent 对照 review/checklist.md 逐项检查发现问题就记录在 output.md 里并生成 handoff_003.md 退回给执行 Agent 修改。如果全部通过则生成 handoff_004.md 交给汇总 Agent。第八步汇总 Agent 整合交付汇总 Agent 把所有产出整合成最终报告按 format.md 里的格式规范排版输出最终交付物。这套流程跑下来一个中等复杂度的竞品分析报告大概需要 15 到 25 分钟比我自己从头做快得多而且质量更稳定。3.2 交接文档的编写规范与校验方法交接文档写得好不好直接决定协作效率。我总结了一个**“三要三不要”原则**三要要具体约束条件必须可执行比如“代码必须通过 pylint 检查”而不是“代码质量要好”要简洁上下文摘要控制在 200 字以内只保留关键信息要可追溯每个产出物必须附文件路径方便接收方直接查看三不要不要模糊禁止使用“大概”“可能”“尽量”这类词不要冗余不要把原始日志、中间讨论过程塞进交接文档不要遗漏必填字段一个都不能少缺一个校验就不通过校验脚本 validator.py 的核心逻辑很简单import re import sys REQUIRED_FIELDS [task_id, from_agent, to_agent, context_summary, deliverables, constraints, next_action] def validate(filepath): with open(filepath, r, encodingutf-8) as f: content f.read() errors [] # 检查必填字段 for field in REQUIRED_FIELDS: if f{field}: not in content: errors.append(f缺少必填字段: {field}) # 检查 context_summary 长度 match re.search(rcontext_summary:\s*(.), content) if match and len(match.group(1)) 200: errors.append(fcontext_summary 超过 200 字当前 {len(match.group(1))} 字) # 检查是否包含模糊词汇 vague_words [大概, 可能, 尽量, 差不多] for word in vague_words: if word in content: errors.append(f包含模糊词汇: {word}) if errors: print(校验不通过:) for e in errors: print(f - {e}) return False print(校验通过) return True if __name__ __main__: validate(sys.argv[1])这个脚本我跑了上百次帮我拦住了大量格式不规范的交接文档。不要小看格式校验它是保证协作质量的第一道防线。3.3 审查环节的检查清单与退回机制审查 Agent 的工作不是“看一眼觉得还行就放行”而是对照清单逐项打勾。我要求审查 Agent 在 output.md 里明确记录每一项的检查结果格式如下## 审查记录 ### 代码类产出 - [x] 是否有未处理的异常分支已检查无问题 - [x] 关键函数是否有注释说明输入输出已检查3 个函数缺少注释已标记 - [ ] 是否有硬编码的配置项发现 2 处硬编码需修改 - [x] 变量命名是否清晰可读已检查无问题 ### 审查结论 不通过需修改后重新提交。 退回原因存在硬编码配置项且部分函数缺少注释。退回机制的关键是必须写明退回原因和修改要求。我见过太多协作流程里审查方只说“不行重做”执行方一脸懵不知道改哪里。我的做法是退回时必须附上具体的修改清单每条都指明位置和期望结果。执行 Agent 收到退回后按修改清单逐项处理处理完重新提交审查。这个循环一般不会超过两轮因为第一轮审查已经把大部分问题暴露出来了。注意审查 Agent 的权限要设好。我一开始让审查 Agent 可以直接修改执行 Agent 的产出结果出现了“审查者自己改代码改完自己放行”的情况质量完全失控。后来改成审查 Agent 只能标记问题不能直接修改必须退回给执行 Agent 处理质量才稳定下来。4. 常见问题与排查技巧实录4.1 Agent 之间“踢皮球”怎么办这是多 Agent 协作里最常见的问题之一。规划 Agent 觉得执行 Agent 应该自己判断某个细节执行 Agent 觉得规划 Agent 没写清楚所以不动手审查 Agent 觉得这是执行 Agent 的问题不归自己管。结果任务卡在某个环节谁都不推进。我的解法是在 AGENTS.md 里加一条**“不确定时必须向上游追问禁止自行猜测或搁置”**的规则。具体来说执行 Agent 如果发现任务描述有歧义必须在 5 分钟内生成一份“澄清请求”交接文档退回给规划 Agent规划 Agent 收到澄清请求后必须在 10 分钟内补充说明或调整任务如果规划 Agent 也无法确定则升级到人工介入这条规则加上之后“踢皮球”现象基本消失了。因为每个 Agent 都知道搁置不动的成本比追问的成本高得多。4.2 上下文膨胀导致 Agent “失忆”的解法多 Agent 协作跑久了上下文会越来越长。我遇到过最夸张的情况是一个执行 Agent 的 local_context.md 累积到了 8000 多字它开始忘记前面已经完成的任务重复执行同样的操作。解法是定期压缩上下文。我设定了一个规则每当 local_context.md 超过 2000 字就触发一次压缩。压缩的方式是保留最近 500 字内的操作记录把更早的记录提炼成 3 到 5 条关键结论删除所有中间过程的详细日志把压缩后的内容写回 local_context.md这个压缩动作由 Agent 自己执行不需要人工干预。我实测下来压缩之后 Agent 的执行准确率能恢复到正常水平。4.3 协作效率突然下降的排查思路有时候协作流程跑着跑着就变慢了但看不出明显问题。我总结了一套排查思路按顺序检查排查项检查方法常见问题交接文档质量随机抽 3 份 handoff 文档看字段是否完整context_summary 过长或约束条件模糊上下文长度检查各 Agent 的 local_context.md 字数超过 2000 字未压缩审查退回率统计最近 10 次审查的退回次数退回率超过 30% 说明执行质量下降Skill 版本检查各 Skill 的 SKILL.md 最后修改时间版本不一致导致行为冲突任务粒度看任务清单里单个任务的平均复杂度任务太大导致单个 Agent 处理不过来这套排查方法帮我定位过好几次“莫名其妙变慢”的问题。最典型的一次是审查退回率突然从 10% 涨到 40%查下来发现是执行 Agent 的上下文膨胀到了 5000 多字它开始忽略约束条件。压缩上下文之后退回率立刻降回正常水平。4.4 多 Agent 协作的避坑清单最后整理一份我踩过的坑和对应的解法供参考坑交接文档写得太详细接收方被噪音干扰。解法强制 context_summary 不超过 200 字。坑审查 Agent 既当裁判又当运动员。解法审查 Agent 只能标记问题不能直接修改产出。坑任务粒度太粗单个 Agent 处理不过来。解法任务清单里每个子任务的工作量控制在 15 分钟以内。坑Agent 之间互相等待谁也不推进。解法设定超时机制超时未推进则自动升级到人工介入。坑Skill 文件版本不一致行为冲突。解法每次修改 Skill 后在 AGENTS.md 里记录版本号和修改内容。坑上下文膨胀导致 Agent 失忆。解法设定 2000 字阈值超限自动压缩。坑规划 Agent 写的任务清单太抽象执行 Agent 无法落地。解法要求每个任务必须包含明确的输入、输出和验收标准。这套多 Agent 协作模式我跑了大概半年迭代了十几版目前稳定在 4 个核心角色加 3 个核心 Skill 的配置。最深的体会是协作的瓶颈从来不是单个 Agent 的能力而是 Agent 之间的信息传递效率。把 handoff 机制和 AGENTS.md 这两件事做好协作效率能提升一大截。至于 Skill 的设计核心原则是“一个 Skill 只干一件事”不要贪多求全越聚焦越好用。