Agent跑失败了日志里只有一句干巴巴的报错或者更糟——连报错都没有任务就是没完成。这种时候大部分人的第一反应是去翻prompt改两句话再跑一遍运气好碰对了运气不好就是无限循环地试。但真正做过一段时间Agent开发的人会意识到靠直觉调prompt的效率极低因为你根本不知道失败发生在哪一环是规划阶段就偏了是工具调用参数错了还是多步推理中间某一步的上下文被污染了这篇内容围绕五篇论文拼出的一条完整诊断链路展开核心是回答一个问题Agent失败了怎么系统性地定位原因而不是靠猜。涉及的关键词包括Agent、LLM、ReAG、DuoTrace、EDGE适合已经上手做过Agent项目、但被失败排查折磨过的开发者也适合刚开始接触Agent架构、想提前建立正确调试思维的人。我不会逐篇翻译论文而是把它们串成一条从“发现失败”到“归因到具体环节”的实操路径中间穿插我在实际项目中踩过的坑和验证过的做法。1. 为什么Agent的失败排查比传统程序难得多传统程序报错堆栈信息直接告诉你哪一行出了问题。Agent不一样它是一连串LLM调用的组合每一步的输出都是自然语言或者结构化但语义模糊的内容。一个任务失败了可能是第一步规划就错了也可能是规划对了但某个工具调用返回了意外结果还可能是中间某步的推理被前序上下文带偏了。更麻烦的是这些环节之间没有硬性的类型检查或断言错误会静默传播直到最后一步才暴露出来。1.1 失败信号的三种典型形态我在实际项目中遇到的Agent失败大致可以归为三类。第一类是显式失败工具调用返回了错误码或者LLM接口直接报超时、限流。这类最好排查因为至少有明确的错误信息。第二类是隐式失败Agent完成了所有步骤输出了一个看起来像模像样的结果但实际上是错的。比如让它查某个数据并汇总它编了一个数字出来。第三类是部分失败多步任务中某一步没完成但Agent自己没意识到继续往下走最终结果缺了一块。这三类的排查难度是递增的。显式失败只需要看日志隐式失败需要你有一套验证机制部分失败最麻烦因为你需要重建整个执行链路才能定位到是哪一步断的。1.2 为什么“重跑一遍”是最差的调试策略很多人遇到Agent失败第一反应是重跑。如果重跑成功了就觉得是偶发问题不管了。但LLM的输出本身有随机性重跑成功不代表问题解决了只是这次随机到了正确的路径。我见过一个案例某个Agent在调用搜索工具时有大约30%的概率会生成一个格式不对的查询参数导致搜索返回空结果然后Agent基于空结果继续推理最终输出一个完全虚构的答案。重跑三次可能有一次成功但另外两次的失败被忽略了。正确的做法是把这个失败模式记录下来定位到参数生成这一步加一个格式校验或者few-shot示例来修复。注意如果你的Agent失败率在10%到40%之间波动不要把它当成“偶发”这通常意味着某个环节存在系统性的脆弱点只是触发条件不是每次都满足。1.3 诊断链路的核心思路从终点反推五篇论文拼出的这条链路核心思路是一致的不要从头开始猜而是从失败的结果反推逐步缩小范围。具体来说先判断失败发生在哪个阶段规划、执行、汇总再判断这个阶段的失败是输入问题、模型能力问题还是上下文问题。这个反推过程需要你有一套结构化的记录机制否则连反推的素材都没有。2. ReAG把Agent的执行过程变成可追溯的证据链ReAGReasoning-Augmented Generation在这条链路里扮演的角色是让Agent的每一步推理都有据可查。它的核心思想不复杂要求Agent在每一步输出时不仅给出结论还要给出支撑这个结论的证据或推理依据。这样当最终结果出错时你可以沿着证据链往回查看是哪一步的证据出了问题。2.1 ReAG在实际项目中的落地方式我在一个信息提取类的Agent项目里用过类似ReAG的思路。具体做法是在system prompt里加一段约束每次调用工具后必须用一句话总结“我从这次调用中得到了什么信息这个信息支持我下一步做什么”。这看起来只是多了一句输出但排查效率提升非常明显。有一次Agent最终输出的汇总数据少了一个字段我沿着它的步骤总结往回看发现它在第三步调用数据库查询时返回的结果里那个字段是空的但Agent没有意识到直接跳过了。如果没有这步总结我可能要花半小时去重建整个调用链。实现上你可以把每步的总结存到一个结构化的日志里格式大概是{ step: 3, action: query_database, input: {table: orders, filter: date 2024-01-01}, output_summary: 查询返回了120条订单记录但customer_id字段为空, next_plan: 基于订单记录计算总金额 }这个日志不需要多复杂关键是让每一步的输入、输出和Agent的解读都可查。2.2 ReAG的边界它不能解决什么ReAG能让过程可追溯但它不直接告诉你哪一步错了。它只是提供了排查的素材。另外ReAG会增加token消耗因为每步都要多输出一段总结。在成本敏感的场景下你需要权衡是每步都记录还是只在关键步骤记录。我的经验是工具调用步骤必须记录纯推理步骤可以简化。还有一个容易忽略的点ReAG的总结本身也可能出错。Agent可能总结了一个错误的理解然后基于这个错误理解继续走。所以看ReAG日志时不能只看总结要对照原始的工具返回结果。3. DuoTrace双通道追踪如何定位规划与执行的偏差DuoTrace的思路是同时追踪两条线一条是Agent的规划路径它打算怎么做另一条是实际执行路径它实际做了什么。这两条线之间的偏差往往就是失败的根源。3.1 规划与执行偏差的三种模式我在项目中观察到的偏差主要有三种。第一种是规划漂移Agent一开始计划先查A再查B但执行到一半变成了先查B再查A导致依赖关系错乱。第二种是步骤遗漏规划里有五步实际只执行了四步漏掉的那步可能是关键的数据校验。第三种是额外步骤Agent在执行过程中自作主张加了一些规划里没有的步骤这些步骤可能引入噪声。DuoTrace的价值在于它让这些偏差变得可见。实现方式可以是在Agent的规划阶段输出一个步骤列表然后在执行阶段每完成一步就标记一下最后对比两个列表。3.2 一个具体的偏差定位案例之前有个项目Agent的任务是“从三个数据源分别获取信息然后合并输出”。最终输出总是缺一个数据源的信息。用DuoTrace的思路一对比发现规划阶段列出了三个数据源但执行阶段只调用了两次工具。往回查发现Agent在第二次调用后认为“已经获取了足够的信息”自动跳过了第三个数据源。这不是工具报错而是Agent的决策逻辑出了问题。修复方式是在prompt里明确要求“必须对每个数据源都执行一次查询不得跳过”。这个案例说明DuoTrace不仅能定位执行错误还能暴露Agent决策逻辑中的隐含假设。3.3 DuoTrace的实现成本与简化方案完整的DuoTrace需要你在Agent架构里加一层规划记录和执行记录的对齐机制。如果不想大改架构一个简化方案是在Agent的system prompt里要求它先输出一个编号的步骤计划然后在每步执行后输出“已完成步骤X”。这样你至少有一个粗略的对照。成本更低的方式是在代码层面拦截每次工具调用记录调用顺序和参数然后和规划做人工对比。4. EDGE用执行图来可视化失败传播路径EDGE的核心是把Agent的执行过程建模成一个图节点是每一步的操作边是步骤之间的依赖关系。当最终结果出错时你可以沿着图往回追看错误是从哪个节点开始传播的。4.1 执行图相比线性日志的优势线性日志只能告诉你“发生了什么”执行图能告诉你“什么导致了什么”。举个例子Agent最终输出了一个错误的汇总数字。线性日志显示最后一步是“汇总计算”输入是前几步的结果。但前几步有多个工具调用你无法一眼看出是哪个调用的结果导致了汇总错误。执行图则可以直接标出汇总节点的输入来自查询节点A和计算节点B而计算节点B的输入又来自查询节点C。如果查询节点C返回了错误数据整条链路的问题就一目了然。4.2 构建执行图的实操要点构建执行图不需要复杂的图数据库用简单的邻接表就能起步。关键是在每次工具调用或推理步骤时记录它的输入来源依赖哪些前序步骤和输出去向被哪些后续步骤使用。我在一个项目里用Python的字典实现了这个记录execution_graph { step_1: {action: search, depends_on: [], output_used_by: [step_2, step_3]}, step_2: {action: extract, depends_on: [step_1], output_used_by: [step_4]}, step_3: {action: validate, depends_on: [step_1], output_used_by: []}, step_4: {action: summarize, depends_on: [step_2], output_used_by: []} }当step_4出错时沿着depends_on往回查就能快速定位到是step_2的问题还是step_1的问题。4.3 EDGE在复杂多Agent场景下的价值单Agent的执行图还比较简单多Agent协作时执行图会变成跨Agent的依赖网络。比如Agent A的输出是Agent B的输入Agent B又调用了Agent C。这种情况下没有执行图几乎无法排查。我参与过一个多Agent的客服工单处理项目最终工单分类错误排查发现是Agent A在提取工单关键词时漏了一个关键实体导致Agent B的分类依据不完整。如果没有跨Agent的执行图这个链路要花很长时间才能理清。5. 把五篇论文的方法拼成一条可操作的诊断流程单独看每篇论文方法各有侧重但实际排查时你需要把它们串起来用。我总结的流程是先做失败分类再建执行记录然后定位偏差最后归因到具体环节。5.1 第一步失败分类与优先级判断拿到一个失败案例先判断它属于显式失败、隐式失败还是部分失败。显式失败直接看错误信息通常不需要完整链路。隐式失败和部分失败才需要启动完整的诊断流程。判断标准很简单如果Agent输出了一个结果但结果是错的就是隐式失败如果结果不完整就是部分失败。5.2 第二步用ReAG思路建立最小可追溯记录不要一上来就搞复杂的执行图。先在Agent的prompt里加一步总结要求把每步的输入、输出和Agent的解读记下来。这个记录不需要很规范关键是能让你在失败后快速重建执行过程。我通常会在项目初期就用这个方式因为它的改造成本最低但排查收益很高。5.3 第三步用DuoTrace对比规划与执行有了记录之后对比Agent的规划步骤和实际执行步骤。如果发现偏差先看偏差是否合理。有些偏差是Agent的合理调整有些则是错误。判断标准是偏差是否导致了最终结果与预期不符。如果是就定位到偏差发生的那一步。5.4 第四步用EDGE追溯错误传播路径如果偏差不明显或者失败是隐式的就需要用执行图来追溯。从最终错误的输出节点往回走检查每个输入节点的输出是否合理。通常走两到三层就能找到问题源头。5.5 第五步归因到具体原因并修复定位到具体步骤后归因通常落在以下几类prompt指令不清晰、工具返回格式不符合预期、上下文过长导致信息丢失、模型能力不足。针对不同原因修复方式不同。prompt问题就改prompt工具问题就加校验或改工具描述上下文问题就做摘要或分片模型能力问题就换模型或加few-shot示例。失败类型典型原因修复方向规划漂移prompt中步骤约束不明确增加步骤编号和顺序约束步骤遗漏Agent自行判断“信息足够”明确要求每步必须执行工具参数错误工具描述不清晰或缺少示例补充参数格式示例和校验上下文丢失对话过长导致早期信息被截断做上下文摘要或关键信息前置隐式错误缺少输出验证机制增加结果校验步骤6. 实操中容易踩的坑和我的应对经验这套诊断链路听起来逻辑清晰但实际用起来有几个坑我踩过不止一次。6.1 记录太多导致排查反而变慢一开始我恨不得把Agent的每个token都记下来结果日志文件巨大排查时要在海量信息里找关键线索效率反而低。后来我改成只记录工具调用的输入输出、每步的总结、以及规划与执行的对比。纯推理的中间过程不记除非怀疑是推理出了问题。6.2 把Agent的自我总结当成事实ReAG的总结是Agent自己写的它可能总结错。我有一次看到一个总结说“查询返回了有效数据”但实际返回的是空列表。Agent把空列表理解成了“没有匹配结果”然后继续往下走。所以看总结时一定要对照原始的工具返回。6.3 忽略上下文长度对诊断的影响当对话轮次很多时早期的规划信息可能已经被挤出上下文窗口了。这时候Agent的执行偏差可能不是因为它“不想按规划走”而是它“已经忘了规划是什么”。这种情况下DuoTrace的对比会显示规划为空或缺失。解决办法是在每轮关键步骤前把规划摘要重新注入上下文。6.4 在多Agent场景下只追踪单个Agent多Agent协作时失败往往发生在Agent之间的交接处。如果只追踪单个Agent的执行图你会看到每个Agent都“正常完成了自己的任务”但整体结果是错的。必须建立跨Agent的依赖记录至少记录每个Agent的输入来自哪个Agent的哪个输出。6.5 修复后不做回归验证定位到问题并修复后一定要用同样的失败案例重跑确认修复有效。更严谨的做法是把失败案例存成一个测试集每次修改Agent逻辑后都跑一遍防止修复了一个问题又引入新的问题。我在项目里维护了一个“失败案例库”大概有二十多个典型失败场景每次迭代都跑一遍虽然费时间但能避免很多回归问题。这套从ReAG到DuoTrace再到EDGE的链路本质上是在给Agent加上“可观测性”。传统软件的可观测性靠日志、指标、追踪三件套Agent的可观测性目前还没有标准方案但这五篇论文拼出的思路已经足够指导实践了。我的体会是不要等失败了才想起来加记录在项目初期就把最小可追溯机制建起来后面排查会轻松很多。另外Agent的失败排查不是一次性的工作它是一个持续积累的过程每解决一个失败案例就把它变成一条规则或一个测试用例慢慢你的Agent会越来越稳。