Agent失败排查：从错误码到失败链，别再让模型背锅

1. 为什么“模型不行”往往是排查方向跑偏了做 Agent 开发的人大概都经历过这种场景线上告警突然炸了某个 Agent 任务批量失败日志里只有一行冷冰冰的agent execution terminated due to error或者一个422、一个model request failed。第一反应是什么大概率是“模型服务又抽风了”然后跑去模型服务商的错误信息里翻点开右侧箭头展开那一长串报错越看越懵最后在群里甩一句“模型不稳定等它恢复”。我踩过太多次这种坑了。真实情况是Agent 失败里真正由模型本身能力导致的占比远没有大家想象的高。大部分失败是链路问题工具调用参数拼错了、上下文超长被截断、某个中间步骤超时、状态机卡死、并发写冲突、容器内存打满被 OOM Kill、网络抖动导致的重试风暴。模型只是这条链路上最后那个“背锅侠”因为它是唯一一个会明确吐错误码的环节所以所有脏水都泼到它身上。这篇内容想聊的就是一件事别再把 Agent 失败都算给模型学会从粗错误码一路顺藤摸瓜还原出完整的失败链。所谓失败链就是一次 Agent 执行从入口到失败点之间所有参与环节按时间顺序串起来的那条因果链。你只有把这条链还原出来才知道到底是谁把这次执行搞挂的。适合谁看如果你正在做 Agent 开发、Agent 框架编排、多 Agent 协作或者你负责 Agent 项目的部署和测试天天跟错误码和日志打交道那这篇就是写给你的。哪怕你刚入门 Agent 学习路线只要你能看懂日志也能从里面拿到一套可复用的排查方法论。核心关键词就几个Agent、错误码、失败链、排查、terminalBlocker后面会反复围绕它们展开。先说结论性的判断一个成熟的 Agent 排查体系应该是“错误码 → 失败链 → 根因”三级递进而不是“错误码 → 模型 → 重试”。前者越查越清楚后者越查越糊涂。下面我把这套东西拆开讲透。2. 错误码到底在告诉你什么从粗到细的分层解读2.1 粗错误码的本质它只是“症状”不是“病因”很多人把错误码当成诊断结论这是最大的误区。错误码本质上是症状描述它告诉你“哪里疼”但不告诉你“为什么疼”。就像你去医院说肚子疼医生不会直接给你开止痛药而是要先做检查。Agent 的错误码也是同理。拿最常见的几类粗错误码举例错误码/信息表面含义可能的真实病因部分422请求语义无法处理工具参数 schema 不匹配、JSON 结构错误、必填字段缺失model request failed模型请求失败上下文超长、鉴权过期、限流、上游超时agent execution terminated due to error执行被终止未捕获异常、状态机死锁、子任务级联失败timeout超时工具响应慢、模型推理慢、网络抖动、死循环OOMKilled容器被杀内存泄漏、上下文无限增长、并发过高你看同一个422可能是参数问题也可能是编码问题还可能是上游传了个null进来。如果你只盯着“422 通信故障排查”这个关键词去搜很容易被带到网络层去结果发现根本不是网络的事。提示拿到粗错误码的第一件事不是去搜这个码的含义而是去定位这个码是在链路的哪一环产生的。产生位置比码本身重要得多。2.2 错误码的分层入口层、编排层、工具层、模型层我习惯把 Agent 执行链路分成四层每层都会产生自己的错误码排查时要先判断错误码属于哪一层入口层请求进来时的鉴权、限流、参数校验。这一层的错误码通常是 4xx比如 401、403、422、429。特点是“还没开始干活就挂了”。编排层Agent 框架负责的规划、状态流转、子任务调度、记忆读写。这一层错误码往往不标准很多是框架自定义的比如terminalBlocker、step_limit_exceeded、state_conflict。工具层Agent 调用的外部工具、API、数据库、文件系统。这一层错误码五花八门取决于工具本身比如 HTTP 状态码、SQL 错误码、文件系统 errno。模型层真正调用大模型的那一步。这一层错误码通常来自模型服务商比如context_length_exceeded、rate_limit_exceeded、invalid_request_error。判断错误码属于哪一层有个很实用的技巧看错误码出现的时间点和它前面的最后一条成功日志。如果最后一条成功日志是“开始调用工具 X”那错误大概率在工具层如果最后一条是“准备请求模型”那就在模型层。2.3 terminalBlocker一个容易被误读的“终止信号”terminalBlocker这个词在 Agent 排查里很关键但它经常被误读。很多人一看“terminal”就以为是终端或者终止直接判定“Agent 挂了”。其实terminalBlocker更准确的理解是一个阻止 Agent 继续推进的终止性阻塞条件。它不一定代表崩溃可能代表“Agent 主动决定停下来”比如达到了最大步数限制框架主动终止检测到重复循环防止无限调用工具某个前置条件不满足Agent 判定无法继续安全策略拦截比如检测到敏感操作。所以看到terminalBlocker不要急着当成 bug先问一句这是预期内的终止还是预期外的崩溃如果是预期内的那它其实是保护机制在起作用你要查的是“为什么触发了这个保护”而不是“怎么绕过这个保护”。这个区分特别重要我见过太多人把保护机制当成故障去修结果把安全阀给拆了。3. 失败链的构建方法把散落的日志串成一条因果线3.1 什么是失败链为什么它比单点错误码有用失败链的核心思想是一次 Agent 执行的失败从来不是单点事件而是一连串事件的结果。你看到的那个错误码只是这条链的最后一环。要真正解决问题必须把前面每一环都还原出来。举个我实际遇到的例子。某次批量任务失败错误码是model request failed。如果只看这个码你会去查模型服务。但把失败链还原出来是这样的入口层收到请求参数正常编排层开始规划读取长期记忆记忆读取返回了一个超大对象因为之前某次写入没做截断编排层把这个超大对象拼进了 promptprompt 总长度超过了模型的上下文窗口模型层返回context_length_exceeded被上层包装成了model request failed。你看根因在记忆写入没做截断跟模型一点关系都没有。如果只盯着模型层查永远查不到。3.2 构建失败链的三个关键字段trace_id、step_id、timestamp要把失败链串起来前提是日志里得有能串的“线”。我强烈建议在 Agent 项目里至少埋三个字段trace_id一次完整执行的唯一标识贯穿入口到结束。所有日志都带上它你就能把一次执行的所有日志捞出来。step_id编排层每一步的编号比如 step_1、step_2。有了它你能精确定位是哪一步出的问题。timestamp精确到毫秒的时间戳。多 Agent 协作场景下时间顺序是还原因果的关键。这三个字段缺一不可。只有 trace_id你知道是哪次执行但不知道哪一步只有 step_id你知道哪一步但不知道属于哪次执行没有 timestamp多 Agent 并发时你分不清谁先谁后。提示如果你的 Agent 框架还不支持这三个字段优先把 trace_id 加上这是投入产出比最高的一步。很多框架自带 tracing 能力别自己造轮子。3.3 从错误码反推失败链的实操路径有了字段接下来是反推路径。我的习惯是“从终点往回走”锁定终点找到那个粗错误码记下它的 timestamp 和 step_id往前捞日志用 trace_id 捞出这次执行的全部日志按 timestamp 排序找最后一个成功点从终点往前找最后一个“成功”的日志是什么定位断点成功点和失败点之间发生了什么那就是断点判断断点层级断点在入口层、编排层、工具层还是模型层深挖断点在断点层级里继续往前找直到找到最原始的触发条件。这套路径听起来简单但实操中最大的坑是日志不全。很多 Agent 项目只记了错误日志没记成功日志导致你根本找不到“最后一个成功点”。所以我在项目里会强制要求关键步骤的成功日志必须打哪怕只是一行“step X done”。4. 典型失败链拆解四类高频场景的排查实录4.1 场景一422 背后的参数 schema 漂移422是 Agent 工具调用里最常见也最容易被误判的错误码。很多人一看 422 就去查网络其实 422 在 HTTP 语义里是“请求格式正确但语义错误”放到 Agent 场景里绝大多数是工具参数 schema 不匹配。我遇到过一个典型案例某个工具定义里参数count是 integer但 Agent 在规划时把它填成了字符串5。模型觉得没问题因为模型输出的是文本但工具层做 schema 校验时直接 422。失败链是这样的编排层生成工具调用参数模型输出的参数是字符串形式的数字编排层没做类型转换直接透传工具层 schema 校验失败返回 422上层把 422 包装成通用错误丢失了细节。排查方法在工具调用前后各打一条日志记录原始参数和转换后参数。对比一下就知道是不是类型漂移。修复也简单在编排层加一层参数规范化把字符串数字转成数字把单值转成数组等。注意schema 漂移往往不是模型的问题而是编排层缺少“参数清洗”这一步。模型输出的是自然语言倾向的文本你不能指望它严格符合 JSON schema中间必须有一层转换。4.2 场景二模型请求失败背后的上下文超长model request failed这个错误码的迷惑性在于它把很多不同的底层错误都包装成了同一个。上下文超长是其中最高频的一种尤其在 Agent 记忆体系里短期、长期、永久记忆混用的时候。失败链通常长这样Agent 读取长期记忆拿到历史对话摘要摘要本身很长因为之前没做压缩编排层把摘要 当前任务 工具定义 系统提示全部拼起来总 token 数超过模型上下文窗口模型服务商返回context_length_exceeded框架包装成model request failed。排查的关键是在请求模型前打印 token 估算值。不用精确用个粗略的字符数除以 3 或 4 就能估个大概。如果发现某次请求的估算值突然飙升基本就是上下文膨胀了。修复思路有三条一是给记忆加压缩和截断二是给 prompt 各部分设 token 预算超了就裁剪三是换更大上下文的模型但这只是缓解不是根治。4.3 场景三容器内存飙高导致的执行中断这个场景在 Agent 部署测试里特别常见尤其是 Java 写的 Agent 服务跑在 Docker 里。热词里“java docker 容器占用内存特别高怎么排查”就是这个问题的典型。Agent 执行中断错误码可能只是agent execution terminated due to error但根因是容器被 OOM Kill 了。失败链Agent 执行过程中不断往内存里累积上下文某个工具返回了超大响应没做流式处理内存持续增长容器内存达到 limit被内核 OOM Killer 干掉上层只看到执行中断看不到 OOM 细节。排查方法先看容器退出码。如果是 137基本就是 OOM。然后看docker stats或监控里的内存曲线是不是在失败前有个陡增。再结合 Agent 日志看失败前最后调用的工具是不是返回了大对象。修复给工具响应加大小限制超限就截断或走流式给 Agent 上下文设内存预算JVM 参数调优比如-Xmx设合理值别让 JVM 无限制吃内存。4.4 场景四多 Agent 协作下的状态冲突多 Agent 协作是现在很热的方向但它带来的失败链最复杂。典型症状是单个 Agent 跑得好好的一协作就出问题错误码可能是state_conflict或者干脆没有明确错误码就是结果不对。失败链往往是并发写导致的Agent A 和 Agent B 同时读写共享状态A 读到旧状态基于旧状态做决策B 在 A 写回之前更新了状态A 写回覆盖了 B 的更新最终状态不一致后续步骤基于错误状态执行失败。排查方法给共享状态的每次读写打日志记录读到的版本号和写回的版本号。如果发现写回时版本号落后于当前版本就是并发冲突。修复用乐观锁或版本号校验写回时检查版本不一致就重试。场景粗错误码真实根因关键排查动作参数漂移422schema 不匹配对比调用前后参数上下文超长model request failed记忆未压缩打印 token 估算内存飙高execution terminatedOOM Kill看退出码 137状态冲突state_conflict并发写覆盖记录状态版本号5. 排查工具链与实操心得让失败链自己浮出来5.1 日志、追踪、指标三件套怎么配排查 Agent 失败光靠日志不够得日志、追踪、指标三件套配合。日志负责细节追踪负责链路指标负责趋势。日志结构化日志JSON 格式字段固定。关键是 trace_id、step_id、timestamp、level、message、extra。追踪用 OpenTelemetry 这类标准做 span每个 Agent 步骤一个 span工具调用一个 span模型调用一个 span。span 之间用 parent-child 关系串起来失败链一目了然。指标失败率、平均步数、平均 token 消耗、工具调用成功率、模型调用延迟。指标帮你发现“什么时候开始变坏的”日志和追踪帮你发现“为什么坏”。我自己的项目里这三样是标配。没有追踪的时候排查一次失败链要半小时有了追踪五分钟定位到具体 span。5.2 复现失败链的最小化方法排查最怕的是“偶发”。偶发的失败链最难还原因为你抓不到现场。我的做法是最小化复现从失败链里提取出关键输入用户请求、上下文、工具返回把这些输入固定下来写成一个测试用例在本地跑这个用例看能不能稳定复现如果能复现逐步删减输入找到触发失败的最小输入集用最小输入集去定位根因。这个方法的好处是把“偶发”变成了“必现”排查难度直接降一个数量级。很多看起来玄学的 Agent 失败最小化之后发现就是个简单的边界条件。5.3 几个我踩过的坑和对应技巧坑一只看错误日志不看成功日志。结果找不到“最后一个成功点”失败链断在半路。技巧强制要求关键步骤打成功日志。坑二错误码被层层包装丢失原始信息。比如底层是context_length_exceeded被包装成model request failed再被包装成agent execution terminated。技巧包装错误时保留cause字段别把原始错误吞掉。坑三多 Agent 场景下日志混在一起。分不清哪条日志属于哪个 Agent。技巧trace_id 之外再加 agent_id日志里带上。坑四重试掩盖了真实问题。框架自动重试失败被重试成功掩盖但根因还在迟早爆发。技巧重试要打日志记录重试次数和重试原因定期分析重试率。提示重试率高不代表系统稳定反而可能是失败链被掩盖的信号。我见过重试率 30% 还觉得“挺稳”的团队结果一次上游抖动就全线崩溃。5.4 从错误码到失败链的速查表最后给一张速查表方便你在实际排查时快速对照你看到的先别急着查应该先查422网络工具参数 schemamodel request failed模型服务状态上下文长度、鉴权、限流execution terminated模型容器退出码、OOM、未捕获异常terminalBlocker当成 bug是否预期内的保护性终止timeout网络工具响应时间、死循环、步数限制state_conflict单个 Agent多 Agent 并发写、版本号这张表不是万能的但它能帮你避免最常见的“查错方向”。排查的本质是先定位层级再定位环节最后定位根因而不是一上来就猜。6. 把失败链思维固化到 Agent 项目里聊了这么多其实核心就一句话Agent 失败排查的起点是错误码但终点必须是失败链。错误码是路标失败链是地图。你只有拿着地图走才不会在“模型不行”这个死胡同里打转。我在实际项目里推动这件事的时候发现最难的不是技术而是习惯。大家习惯了看到错误码就重试习惯了把锅甩给模型习惯了“重启大法”。要改变这个习惯得从两件事入手一是把可观测性做扎实让失败链能自动浮出来二是在团队里建立“先还原链路再下结论”的排查文化。具体落地的话我会建议从这几个动作开始给所有 Agent 执行加 trace_id给关键步骤加成功日志给错误包装保留 cause给重试加日志和指标给多 Agent 场景加 agent_id。这五件事做完你的排查效率会有肉眼可见的提升。至于后续扩展失败链这套思路其实可以往两个方向走一个是自动化用规则或模型去自动分析失败链给出根因建议另一个是预防把历史失败链沉淀成检查清单在 Agent 上线前做静态检查。这两个方向我都试过一部分效果不错但那是另一个话题了。如果你现在手上正好有个 Agent 失败案例别急着点重试先把 trace_id 捞出来按上面的路径走一遍。大概率你会发现那个被你骂了半天的模型其实是无辜的。