做 Agent 开发这两年我最大的感受是单体 Agent 像一把瑞士军刀拆快递、拧螺丝、开啤酒都能干可一旦让你用它在工地上盖出一栋楼你就会抓狂。最近一段时间我陆续把几个在跑的单体 Agent 应用改造成了 Multi-Agent 架构中间踩了不少坑也慢慢摸清了“什么时候该拆、什么时候不该拆”的判断标准。这篇内容不聊概念只聊我拆过的、见过的真实问题重点解释复杂任务为什么必然走向多智能体分工以及从单体迁到 Multi-Agent 的具体路径。适合正在做 Agent 开发、准备搭建 AI Agent 但还没想清楚架构的人阅读。1. 单体 Agent一把能干活但经不起折腾的瑞士军刀1.1 单体 Agent 的适用边界小任务不需要兴师动众很多人一听到 Multi-Agent 就觉得高级恨不得立刻把手头所有东西都拆成三五个角色。我劝你冷静。单体 Agent 的定义很简单一个 LLM 核心一套 System Prompt一串工具调用通过 ReAct 循环推理-行动-观察反复工作。它解决单点任务非常稳比如查天气、格式化代码、把一段自然语言转成 SQL、提取网页里的结构化信息。这类任务步骤少、反馈闭环短、目标清晰单体 Agent 是最优选。为什么因为单体 Agent 天然有“简单就是美”的优势。它不需要消息路由不需要角色协商不需要跨 Agent 传递上下文出问题直接打开一个对话窗口就能调试。成本也可控一次任务可能只有几千 token。这个阶段强行上多 Agent等于用集装箱卡车去送一封同城快递成本、延迟、运维复杂度全都上去了收益却接近零。所以我给这类 task 的第一条建议是别急着拆。先把系统 Prompt 打磨好把工具接口设计得干净一些把错误重试做扎实。你会发现 80% 的简单任务压根不需要“多角色”甚至不需要“Agent”一个稳定的函数调用流程就能解决。单体被诟病不是因为它没用而是因为它被用在了超出能力边界的地方。1.2 三个硬天花板上下文、状态与错误恢复单体 Agent 真正的天花板不在模型智商而在工程结构。我总结下来最硬的有三个。第一个是上下文窗口。目前的模型即便宣传支持 128K、200K 上下文实际跑业务时也别指望真能塞满。工具返回的内容会快速吃掉上下文——一个 API 返回 5KB 的 JSON一个网页抓取结果 10KB一个代码 diff 20KB几步下来就把窗口撑爆了。更长的问题还不只是爆掉而是长度一上来模型对早期指令的“注意力”明显下降经常出现“越到后面越无视最初约束”的飘移。也就是说即便窗口够大单体 Agent 也未必敢用。第二个是状态维护。复杂任务通常是长链条的比如“读 30 个文件、做分析、生成报告”。单体 Agent 要把“当前进度、已经完成的步骤、中间结论、待办事项”全部塞进同一个上下文。问题是这些状态里既有事实也有模型自己的推理混在一起很容易互相污染。我踩过最经典的坑是一个代码迁移 Agent 在处理第三个模块时突然把第二个模块的结论当成了当前模块的前提后面所有步骤全跑偏了。第三个是错误恢复。单体的纠错机制是“自己救自己”——当某一步工具调用失败它只能在自己的上下文里反复尝试。如果进入死胡同所有日志、报错、失败原因都会灌进上下文把原本有用的信息挤出去形成“越错越乱越乱越错”的循环。最后你看到的往往就是那句著名的agent execution terminated due to error.。单体不是没有容错能力而是它想把容错放在同一个容器里完成这本身就不现实。1.3 业务场景正在把单体逼向极限现在回到真实业务里看。我做企业级数据类 Agent 时发现数据的权限边界和血缘关系往往比模型能力更早成为瓶颈。一个单体数据 Agent 如果要同时访问销售数据库、用户画像库、财务报表它就必须持有多个数据源的凭据。而 Prompt 注入、工具误调用、越权查询这些问题在单体架构里没有任何隔离层——一个角色的手伸到了所有地方出事的爆炸半径就是全局的。代码类 Agent 更明显。一个单体 Agent 既要“理解项目结构”又要“执行重构”还要“检查测试是否通过”它得同时拥有读文件、写文件、执行命令的能力。看起来全能实际上每一项能力都在压缩其他能力的 Prompt 空间工具越多模型选错工具的概率越大。我见过某代码助手项目里Agent 在写文件时调用了搜索工具在下命令时调用了文件编辑工具步骤一多工具调用顺序完全错乱。不是模型笨是单体塞不下这么多互相约束的上下文。做研究类任务也一样要搜 20 个网页、读 10 篇文档、汇总一份报告。单体 Agent 串行跑完光上下文和等待时间就让人崩溃。所以每当我听到“我的 Agent 项目跑复杂任务总是出错”我的第一反应往往不是“换更强的模型”而是“你该拆了”。2. 复杂任务为什么必然走向 Multi-Agent2.1 规划与执行分离别让一个模型同时当项目经理和一线工人复杂任务最典型的特征是“要有全局规划也要有局部执行”。现实中任何组织都不会让一个人同时担任项目经理、架构师、程序员、测试员和运维。人的注意力有限多线程工作必然顾此失彼。模型也一样。一个全局规划 Agent 需要读完整份需求文档、拆解任务依赖、判断优先级。一个执行 Agent 只需要关心“眼前这个函数怎么改、这个数据表怎么查”。两者需要的上下文完全不同。把两种职责压到同一个 Prompt 里模型会在“全局视角”和“局部细节”之间反复横跳最后两头都做不好。我自己的实践是规划层负责“拆解和验收”执行层负责“完成单个交付”。规划层读长文档产生任务清单执行层只领自己的子任务和目标完成后交回结论。这样一来模型在每个节点上都只处理“当前这一层”的信息注意力不再被稀释。这也是 Multi-Agent 最本质的价值——它是把复杂度做了空间切分而不是时间堆叠。2.2 上下文隔离每个角色只看自己该看的部分Multi-Agent 很核心的一个收益是上下文隔离。五个子 Agent 各用 8K 上下文和用一个 40K 上下文的单体看起来总容量一样实际效果完全不同。为什么因为子 Agent 的每个 8K 窗口里都是“高密度、高相关”的信息——它只看到完成自己任务所必需的内容不会看到无关文件、其他角色的历史也不会被一堆中间日志干扰。举一个我最近做的代码审查项目开发者 Agent 改了 5 个文件审查 Agent 只需要拿到这 5 个文件的 diff 和项目的编码规范它不需要知道开发者 Agent 改文件之前的整个探索过程也不需要知道开发者试过哪几种方案。单体要做到这件事就得把探索过程全塞进去然后模型可能被“试错历史”误导对最终代码做出错误判断。拆开之后审查 Agent 的信息纯度提升了结论质量明显提高。上下文隔离带来的另一个好处是压缩。执行 Agent 处理完 40 个文件后只往上层传结论比如“文件 A 存在 3 个空指针风险文件 B 存在 1 个 SQL 注入点”而不是把 40 个文件原文一路带上。规划 Agent 看到的是干净的成果摘要而不是一坨原始材料。这个机制用一句大白话说就是把过程留给执行层把结论传给规划层。2.3 记忆分层working memory 和长期记忆不能混在一起很多人理解 Agent 的记忆就是“把历史聊天记录全存下来下次接着用”。这在小规模单体里勉强能跑一旦任务变复杂就出大问题。我倾向于把记忆分成两类working memory工作记忆和长期记忆。Working memory 是“当前这个任务正在处理的工作台”放的是目标、已完成清单、下一步动作、当前约束它必须短小精悍保持高信噪比。长期记忆是“档案柜”放的是跨任务复用的知识、规范、历史教训、用户偏好它通常放在向量数据库或者外部存储里需要时检索相关片段。单体的致命问题是所有记忆都挤在同一段上下文里工作台上堆满档案柜里的东西找什么都费劲。Multi-Agent 架构天然适合做记忆分层规划 Agent 只持有目标摘要和进度执行 Agent 只持有当前步骤的输入输出长期记忆由专门的记忆服务统一维护。每个角色都在自己的工作台上干精细活需要翻档案时再去检索用完就放回去。这套结构和人脑的工作机制是几乎一样的。2.4 工具边界与安全边界让副作用的爆炸半径可控复杂业务的另一个必然要求是权限分化。单体 Agent 一旦要通过命令行、数据库、邮件等多个敏感工具安全风险立刻变成架构问题。做agent安全相关评估时有一条很实际的标准如果某个角色的 Prompt 被污染最坏情况下能造成多大影响单体架构的答案是全局沦陷Multi-Agent 架构可以把影响圈在单个角色内。实际操作中我会给每个角色配最小工具集。数据 Agent 只能访问白名单内的表和参数化查询代码 Agent 只能改指定目录的文件汇报 Agent 只能读模板和写报告。工具层再加一道网关工具调用前检查参数合法性、频率、权限范围异常直接拦截。这样即使某一个子 Agent 被异常输入诱导它手里没有越权工具破坏力也就是局部的后续可以由 Supervisor Agent 重新调度和兜底。这种“角色即边界”的设计不只是为了安全也是为了让系统可维护。每一个 Agent 的工具列表变小之后Prompt 可以写得更细、更贴任务模型选择工具的准确率也会明显上升。工具越少选择越准这是单体 Agent 里无解的Prompt 空间挤压问题在架构层面的天然解法。2.5 成本与速度模型分层和并行化是现实驱动力很多人以为 Multi-Agent 一定更贵其实不完全对。拆开之后你能做模型分层规划类角色用推理能力强的贵模型执行类角色用便宜快速的小模型。比如重构任务里负责设计方案的 Agent 用旗舰模型负责批量替换字符串和格式化代码的 Agent 用轻量模型就够了。单体方案只能全程用同一个模型成本反而下不来。速度上同样如此。检索信息类任务天然适合并行 fan-out五个研究员 Agent 同时跑不同的资料源各自返回摘要后再汇总。单体 Agent 串行跑 20 个网页假设每步平均 5 秒就是 100 秒拆成四个并行角色差不多 25 秒就能跑完延迟降 75%。成本和延迟两个现实因素摆在这里复杂任务走向 Multi-Agent 已经不只是“能力问题”而是经济问题。3. 多 Agent 架构模式与主流框架选型3.1 主流框架各有性格怎么选目前市面上的 Agent 框架不少我按自己的使用感受和适用场景整理了一个表方便你选型时对照框架核心编排模型适合场景上手难度我的踩坑印象LangGraph图状态机流程复杂、状态依赖多、需要精细化编排中高节点和边设计灵活但也容易把自己绕进去AutoGen对话式协商多 Agent 对话、互相验证、迭代式任务中对话轮次多了容易发散需要强约束CrewAI角色协作业务角色分工清晰偏传统工作流低上手快但高度封装深水区调试麻烦MetaGPTSOP 流水线模拟软件公司流程、标准化产出中角色和模板很重适合特定领域Semantic Kernel企业级集成微软生态、与现有 C#/云服务集成中高适合正经企服不适合快速原型自己写编排完全自控需要定制协议、权限、审计视经验最可控但工作量不小我的选型标准很简单如果你的任务本质是“有依赖关系的多步流程”LangGraph 的图结构最匹配如果你想让 Agent 之间像同事一样讨论和互相校验AutoGen 更顺手如果你的核心诉求是让业务人员快速搭出角色分工CrewAI 最省心如果你要对接企业级基础设施语义内核之类的企业框架更有优势。框架只是编排层Agent 的智商和稳定性永远来自底层的模型、工具设计和上下文管理框架救不了烂架构。3.2 四种编排模式串行、并行、层级与协商Multi-Agent 编排不是只有一种“所有人一起聊天”的形式。我总结下来大多数项目跑的是四种模式。串行 PipelineA Agent 做完传给 B Agent再传给 C Agent。典型场景是数据流水线清洗 Agent - 特征提取 Agent - 报告生成 Agent。串行的好处是边界清晰、容易调试坏处是慢而且一步出错后面全停。并行 Fan-out/Fan-in一个分发 Agent 把任务拆成多路交给多个 Worker 同时跑最后汇总。典型场景是情报收集、批量文件分析。速度优势非常明显但对汇总 Agent 的信息压缩能力有要求它得能处理大量返回。层级 Supervisor-Worker主管 Agent 负责任务拆分、结果回收、质量把关Worker Agent 只做执行。这种模式最接近真实公司结构也最容易落地。我目前的主力架构就是这种规划层和监督层分离执行层并行。协商/辩论模式两个或多个 Agent 针对同一份产出互相对抗。比如写作 Agent 和审查 Agent 循环迭代直到双方都满意。这种模式适合创意类、复杂决策类任务但成本高而且容易陷入无限循环需要设定最大轮数。怎么判断用哪种我的经验是先看依赖关系。步骤之间有硬依赖就串行没有依赖就并行任务量太大就加层级结论存在分歧就协商。大部分项目是这四种模式的组合比如“串行主干 某些环节并行扇出”。3.3 不依赖框架手写一个最小 Multi-Agent 骨架把上面说的 Supervise-Worker 模式落到代码层面其实特别简单。这里给你一个极简的、不依赖任何框架的骨架理解它你就理解了 Multi-Agent 的编排本质# 一个极简的 supervisor-worker 骨架示意代码 async def supervisor(task): # 第一步用强模型规划产出子任务列表 plan await strong_model.plan(task) # 第二步按角色从注册表里取执行器逐个执行 for step in plan.steps: worker registry.get(step.role) result await worker.run(step.input) plan.record(step.id, result) # 第三步汇总所有子结果形成最终产出 return await strong_model.summarize(plan)这个骨架的核心就三个东西strong_model.plan负责规划registry是角色注册表worker.run是每个角色的独立执行函数。在此基础上你可以加路由选择根据任务类型分派给不同 Worker、加工具白名单限制每个 Worker 能用什么、加重试逻辑失败后重启该 Worker 而不是整个流程。把 ReAct 循环从“一个 Agent 内部循环”升级成“多个 Agent 之间通过消息循环”你就得到了一个能跑的 Multi-Agent 雏形。手写的好处是每一行代码你都清楚在干什么排查问题时不会陷入框架的“黑盒魔法”。坏处是要自己处理消息协议、权限、日志、并发这些底层细节。我的建议是项目初期先用这种手写骨架跑通流程等确认了架构真正有效再考虑引入成熟框架来补足工程化能力。很多团队一上来就上重型框架结果被框架的抽象层绑架问题定位无从下手。3.4 先泼盆冷水这些场景别急着拆写了这么多 Multi-Agent 的好处我必须反过来泼一盆冷水。至少有三类场景我强烈建议你别拆。第一步骤少于三个、单轮就能搞定的任务。比如简单问答、单个工具调用拆了纯粹是浪费延迟和 token。第二任务强依赖全局完整性。比如“根据整份文档生成摘要”你很难拆成多个 Agent 各读一段因为摘要需要全局理解强行分片反而丢失上下文。第三实时性要求极高、成本极度敏感的场景。每多一个 Agent 就多一轮网络往返、多一轮消息解析延迟必然上升模型调用次数多成本也水涨船高。判断要不要拆最简单的一个问题是当前单体失败的原因是否因为一个上下文里塞了太多互不相关的信息如果是拆如果不是先别拆。有一段时间我被“Multi-Agent 是趋势”冲昏了头硬把一个 PDF 解析任务拆成三个角色结果发现单人用更长的上下文一次跑完又快又准。所以记住Multi-Agent 是工具不是信仰。4. 从单体改造成 Multi-Agent 的实操路径4.1 第一步把任务拆成依赖图找出可并行环节从单体迁到 Multi-Agent第一步不是写代码而是拆任务。我通常拿一张白纸把整个任务分解成原子步骤然后给每个步骤标上依赖关系哪些步骤必须在前一步完成后才能做哪些步骤彼此无关可以同时做。比如“竞品迭代报告”这个任务可以拆成搜索资料、阅读文章、整理数据表格、分析竞品动向、写结论、排版输出。其中“搜索资料”可以按渠道并行“阅读文章”依赖“搜索资料”“写结论”依赖“分析竞品动向”和“整理数据表格”而“排版输出”永远在最后。标完依赖关系后可并行的步骤就是未来 Fan-out 的位置串行的主链就是未来 Pipeline 的主干。这一步做扎实后面一切角色定义和消息协议才有依据。最常见的问题就是跳过任务拆解直接搭角色最后角色之间边界重叠消息满天飞谁都不知道自己该干什么。我吃过亏所以现在每次改造都先花半小时画依赖图而不是急着写代码。4.2 第二步角色定义要按职责边界不按人设角色定义是整个 Multi-Agent 架构的灵魂。我见过很多项目给 Agent 起花哨的名字比如“创意总监”“灵感大师”但系统里没人说得清它的输入、输出和工具是什么这就是典型的人设式定义工程上基本没用。正确的角色定义应该围绕职责边界展开。我给每个角色建一张表至少包含四栏角色名、可访问工具、输入协议、输出协议。举一个数据报告系统的例子角色可访问工具输入输出研究员 Agent搜索引擎、网页抓取调研主题、资料源清单结构化调研笔记JSON数据分析 Agent数据库查询、图表生成数据表名、分析维度数据摘要和图表文件路径写作 Agent文档模板调研笔记、数据摘要报告初稿Markdown审查 Agent语法检查、规范检查报告初稿审查意见列表每个 Agent 的 Prompt 里都写清楚你是什么角色、你有哪些工具、你只能接收什么格式的输入、你必须返回什么格式的输出。这样模型没有自由发挥的空间行为边界就稳定了。经验之谈角色数量控制在 2 到 6 个最舒服超过 10 个角色消息协调的复杂度会指数级上升调试成本高到让人怀疑人生。4.3 第三步消息协议必须结构化别让 Agent 靠自然语言瞎猜多 Agent 之间的通信协议是决定系统稳定性的另一个关键。很多 Agent 框架默认让智能体之间用自然语言聊天这在原型阶段很愉悦但到了生产环境就是灾难——A Agent 说“帮我处理一下”B Agent 可能理解成完全不同的意思。自然语言天生有歧义不适合做跨角色协议。我建议所有 Agent 间消息统一走结构化 JSON 协议至少包含这些字段{ task_id: task_20260201_001, trace_id: trace_a1b2c3, from: supervisor, to: researcher, action: collect_materials, payload: { topic: 竞品迭代报告, keywords: [竞品A, 竞品B], max_sources: 10 }, status: pending }trace_id是我特别强调的一个字段。多 Agent 系统出了问题时最痛苦的就是不知道某个中间结果到底是从哪条链路传过来的。没有 trace_id你面对的是几十个 Agent 的日志一锅粥有了 trace_id你可以顺着一条链路把所有相关日志拉出来。我在做链路追踪时每次都会先把“trace_id 是否完整贯穿”作为第一检查项这比看模型输出内容重要得多。4.4 第四步状态管理与上下文压缩的落地手法拆完角色之后每个 Agent 内部依然要有自己的状态管理。我给每个子 Agent 维护一份显式的 working memory内容包括三块当前目标、已完成清单、下一步动作。这份状态不在对话上下文里裸奔而是被持久化到外部存储比如 Redis 或者一个简单的 JSON 文件每次执行前把最新状态写回 Prompt执行后更新状态。跨 Agent 传递信息时严格遵循“只传结论、不传过程”的原则。比如 数据分析Agent 跑完 40 个数据表它向上层传的不是 40 张表的原始数据而是一份统计摘要各表行数、异常比例、关键字段分布。这个过程就是上下文把高噪声低密度信息压缩成高密度低噪声信息的过程。长文档处理也同理。不要再把整篇 PDF 塞给 Agent提前用检索式记忆向量库加相似度检索把相关片段捞出来拼进上下文。这套机制其实不复杂但它能把每个 Agent 的上下文信噪比维持在高位模型输出质量会有肉眼可见的提升。4.5 第五步错误隔离、重试与幂等设计单体 Agent 的一个步骤失败整个任务跟着崩Multi-Agent 的价值就是让失败的影响被圈在局部。实操上我会做几件事每个子 Agent 单独设超时时间比如研究员 Agent 最长 60 秒超过直接判定失败每个子 Agent 设最大重试次数通常 2 次每次失败后把错误信息作为上下文传给 Supervisor Agent由它决定是重试、换 Worker 还是跳过。比单点错误处理更关键的是幂等设计。工具调用必须考虑“重复执行”的后果。比如“写文件”这个操作如果上次执行已经写了一半重试时是覆盖还是追加我的经验是所有写操作先生成临时文件成功后再改名替换所有不可逆操作发邮件、下订单设计成两阶段——先生成草稿人工或 Supervisor 确认后再真正执行。做到这几点至少能少踩一半agent execution terminated due to error.这种全线崩溃的坑。4.6 第六步部署试点与回归验证架构调整不动则已动则伤筋动骨。我强烈建议先用小流量试点再切换生产。第一步先保留单体主流程只把最耗时、最易失败的环节比如多路资料检索抽出来放到一个 Worker Agent 里跑。验证稳定后再逐步把其他环节拆出去。一次只拆一个角色出了问题能准确定位到新组件。部署环境上如果你在容器环境里跑比如在 Docker 里跑设备侧 Agent像 ROS2 相关项目要特别注意库版本和 API 兼容镜像里的 Python 包版本和本地不一致经常会冒出莫名其妙的连接错误。Windows 桌面环境跑 Agent 工具则是另一个坑环境变量、沙盒目录权限、缓存文件路径都能让一个看似正常的服务反复报错。我的建议是统一用容器编排来封装运行环境减少本机差异带来的“在我机器上能跑”问题。上线前跑一遍回归用例集把高频业务场景全过一遍确认没有引入新的回归错误再放量。5. 常见运行问题与排查技巧实录5.1 “agent execution terminated due to error” 是最常碰到的第一座大山这句话几乎是每个 Agent 开发者的老朋友。我最早跑单体的时候一看到它就头皮发麻因为整个任务都废了。后来拆成 Multi-Agent 才发现这句话远没有那么可怕——它只是某一个子 Agent 内部抛出了未捕获异常。排查思路按顺序走先看错误发生在哪个环节取出该子 Agent 的原始日志再分辨是工具调用失败API 超时、参数错误、网络不通还是模型输出解析失败模型返回了不合法 JSON。工具调用失败通常加重试和超时就能解决模型输出解析失败通常需要收紧输出协议强制模型按 JSON Schema 输出并加上解析容错。多 Agent 架构下遇到这个报错的第一反应不应该是“修复整个流程”而是“隔离这次失败”。Supervisor Agent 拿到失败信息后可以把它标记为“局部失败”重新调度另一个 Worker 或跳过该环节主流程继续走。把单体全局异常变成多 Agent 的局部事件心理压力和治疗成本都低得多。5.2 “工具已经执行但 Agent 说没干”副作用审计怎么做还有一类特别坑的报错提示信息大概是“agent couldnt generate a response. note: some tool actions may have already...”。翻译过来就是工具调用已经发生了但模型在生成最终回复时失败了系统无法确认现场状态。这种报错最危险因为它意味着副作用已经产生但系统没有正常“收尾”。比如 Agent 已经调用了删除文件的工具删除成功后网络连接断了模型没来得及生成确认回复。你看着日志不确定文件到底删没删。解决思路有两个第一把工具调用做成幂等且可审计的每一次调用都写入操作日志包含参数、时间、结果状态第二把不可逆操作做成两阶段第一阶段只生成指令草稿第二阶段由更高权限的 Supervisor 或人工确认后真正执行。我实际工作中对“审计日志”的重视程度不亚于模型质量。哪怕只用简单的文本日志也要把每个 Agent 的工具调用时间、参数、返回值完整记录下来。所谓没有记录就没有真相多 Agent 系统里尤其如此。5.3 模型“失忆”是上下文冲掉不是模型变笨用户投诉最多的问题之一就是“Agent 忘了自己刚干的事”。比如刚分析完一个文件下一步就忘记文件内容了。这不是模型变笨而是上下文被冲掉了后一个工具调用返回了超长文本把前面的关键信息挤出了窗口。解决办法不是“换更大窗口的模型”而是显式状态管理。把关键状态已完成步骤、关键结论、当前目标持久化到外部每一步执行前都把状态显著地放到 Prompt 的固定位置。这样即使上下文有波动模型也能从显式状态里恢复“记忆”。这里我想强调一个被很多人忽视的点模型是不可靠的记忆体别把记忆这件事全压在模型身上。凡是需要跨步骤保留的信息都用外部存储去管上下文只当“工作台”而不是“档案柜”。工作台上的东西可以随时清理档案柜里的东西才是真正安全持久的。5.4 多 Agent 排障利器链路追踪与结构化日志单体排障看一个上下文就够了Multi-Agent 排障则是面对一个分布式系统没有链路追踪根本无法定位问题。我建议从第一天就加 trace_id贯穿外层请求、规划结果、每个子任务、每个工具调用、最终响应。日志内容至少要包含时间戳、角色名、trace_id、输入消息摘要、输出消息摘要、消耗 token 数、工具调用明细。我见过很多团队日志只存“模型回复”没有上下文记录出了问题完全没法复盘。在 Multi-Agent 架构里日志已经是基础设施的一部分而不是事后补丁。排障时先按 trace_id 把所有相关日志拉出来看消息在哪一步断了。是规划 Agent 没产出任务Worker 没执行完还是汇总 Agent 没等到结果链路一清晰问题定位就从“猜”变成“看”。6. 记忆、安全与评测多 Agent 工程化的三块基石6.1 记忆工程working memory、长期记忆与防污染演进到多 Agent 阶段记忆工程就不再只是“存聊天记录”而是架构设计中不可绕过的基础设施。我把记忆至少分成三层working memory 是当次任务的短期状态episodic memory 是任务完成后的经验总结semantic memory 是可复用的知识库。三者存储位置不同读取方式也不同。实际项目里我常用向量数据库存语义记忆用 KV 存储 working memory用文件或专门的文档库存经验总结。每次新任务开始时先从长期记忆里检索相似任务的历史经验作为上下文的补充任务执行过程中只更新 working memory任务结束后把有价值的过程沉淀回长期记忆。但有个容易被忽略的安全问题记忆会被污染。如果某个子 Agent 在一次异常对话中接收了恶意指令并把“错误结论”写进了长期记忆后续所有任务都会被这份脏记忆带偏。这就是为什么要在记忆写入前做合法性校验——对写入内容做格式检查、敏感字段过滤、与当前任务的相关性评估。任何防御框架的核心思路都是一样的记忆不是来者不拒而是有门禁的。6.2 权限治理最小权限、工具网关和输入输出过滤多 Agent 系统的安全底线是“最小权限”。每个角色只拥有完成任务所需的最少工具、最少数据权限、最少文件路径。数据 Agent 不能访问财务库写报告 Agent 不能执行任意代码这是架构层面的一票否决项。工具网关是我在每个生产级系统里都会加的一层。所有 Agent 的工具调用请求必须经过网关网关负责检查调用方身份、参数合法性、频次限制、权限范围。如果研究员 Agent 试图调用“发送邮件”网关直接拒绝并记录告警。这一步能挡住绝大多数 Prompt 注入和误操作。输入输出过滤同样重要。输入侧过滤掉可疑的指令注入比如“忽略之前所有指令”这类模式输出侧过滤掉敏感数据手机号、密钥、内网地址。很多人把这些叫做agent安全标签下的工程实践其实就是“输入净化、调用授权、输出过滤”三件套。别嫌麻烦多 Agent 系统的攻击面比单体大了一个量级安全措施不是可选项。6.3 多 Agent 评测从单点正确率到端到端成功率多 Agent 比单体的评测难一个档次但再难也要做不然上线就是裸奔。我的评测体系分四层第一层是单次工具调用正确率比如“搜索 Agent 在 100 次调用中有多少次返回了相关结果”第二层是单角色任务完成率比如“数据分析 Agent 能在多少次任务中生成合法可用的 SQL”第三层是端到端任务成功率这是用户体感的最终标准第四层是副作用监控比如有没有误删文件、有没有越权访问。自动化评测优先挑“结果可验证”的任务来做。数据查询类的看结果集对不对代码重构类的看测试是否通过报告生成类的看模板是否合规。创意类任务的结果不好自动判定就做人工抽检抽样比例别设太低10 到 20 个点就足以暴露大部分问题。我最后想分享一个体会很多人一上来就搭四个 Agent但你会发现真正难的从来不是让四个 Agent 各说各话而是让他们把话传到对的人手里、把错留在对的地方。我迭代到现在反而把“少一个 Agent 就少一个故障点”当座右铭。如果你的任务还在可控范围先别急着堆一旦发现单体 Agent 在同一个上下文里反复救火、互相打架那就果断切 Multi-Agent。每次拆分都问自己三个问题这一步是谁在负责他要看什么上下文他失败了怎么兜底想清楚这三个问题Multi-Agent 才不会变成 Multi-乱。