1. 排查起点：别再第一时间怀疑模型

做 Agent 开发最坑的一个思维定式，就是只要任务执行报错，第一反应永远是“模型能力不行”。我接手过不少这类问题，真正查下来，模型背锅的比例远没有想象中那么高。大部分失败其实发生在更外围的环节——工具调用的参数没对齐、上下文被上一轮污染、外部服务超时、甚至只是代码里一个全局变量在捣乱。

这次要复盘的问题就是一个典型：一个基于 Function Calling 的 Agent 在调用内部简历解析工具时，返回了一个粗错误码 422。看到这串数字的时候，我第一反应也是去检查是不是传给模型的函数参数格式不对。结果来回验证了好几轮，模型这边的输入输出一点毛病没有，报错却一如既往地稳定复现。

真正让我开始转变思路的，是把这个报错放进整条调用链路里重新看了一遍。Agent 执行一个任务走的路是：模型生成意图 → 框架解析出工具调用 → 工具执行 → 结果回填给模型 → 模型生成最终答案。这个链路里任何一环出问题，最后反映到业务层可能都只是一个 HTTP 状态码，而且这个状态码往往非常“粗”——只告诉你“失败了”，不告诉你“为什么失败”。

我那次排查最终花费了大半天时间，绕了不少弯路，但收获是实打实的：我把“看单个错误码”的思路，升级成了“追踪整条失败链”的方法。这篇就把完整过程、踩坑点、以及沉淀下来的排查套路一起写出来，给同样在 Agent 项目里被粗错误码折磨的人一个参考。

2. 错误码为什么“粗”：链路太长，错误被层层吞噬

先说清楚一个关键现象：Agent 框架里的错误码，天然就是粗粒度的。你直接对接 OpenAI 或 Claude API 的时候，模型层会返回比较明确的错误信息，比如上下文超长、格式校验失败、触发了安全策略等。但一旦外面套了 Agent 框架，再加了工具层、业务逻辑层，错误信息就会在每一层被“翻译”一遍，每次翻译都可能丢失细节。

我这次遇到的 422 就是一个绝佳的例子。HTTP 422 的语义是“请求格式正确，但语义上无法处理”，这个定义本身是清楚的，但在 Agent 链路里，框架层的 422 往往是笼统的“工具返回了异常结果”的代名词。也就是说，底层工具真正报的可能是 JSON 解析失败、可能是数组越界、可能是下游 HTTP 超时，但框架统一把它们打包成了 422 抛出来。

这就带来一个很实际的问题：排查的人只能看到最外层的“症状”，而病因深藏在链条内部。如果你只盯着模型输出和参数格式，就会像我一开始那样原地打转。

这里我整理了一个“错误解读矩阵”，能帮助你快速判断该往哪个方向追：

当你拿到一个错误码时，第一件事不是去猜，而是去确认这个错误码到底是在哪一层产生的。框架层产生的、模型层产生的、还是工具层产生的，排查路径完全不同。

2.1 一个实操技巧：把“错误信息”当作数据来对待

我后来给自己定了一条规矩：任何 Agent 项目的错误码，必须带三样附加信息——产生错误的阶段、关联的 trace ID、错误详情原始内容。没有这三样的错误码，本质上是无效信息。

举个例子，同样一个 422，如果附带的信息是“阶段：tool_execution；trace_id：a1b2c3；详情：JSONDecodeError at line 3”，那排查基本就是秒级的事。反之，如果只有一个 422，你就要从最外层一层层翻日志，效率至少差十倍。

这也解释了为什么很多 Agent 项目“看起来报错很多”。其实错误不少见，真正可怕的是错误信息被层层包装之后变得不可读，导致每次排查都像在盲人摸象。

所以排查的第一步，永远是把错误码还原成原始错误链。我这次的做法是直接跳过框架的错误提示，去翻工具层容器里的原始输出日志，很快就看到了真正的异常堆栈——一个 list index out of range。这个信息框架层根本没有传上来，如果只看 422，可能永远猜不到是这个问题。

3. 失败链追踪方法论：从症状到根因的四步定位

在排掉“模型背锅”的干扰项之后，我摸索出了一套比较通用的四步定位法，专门对付这种“一个粗错误码背后藏着一串失败链”的情况。这套方法不限于某一个框架，只要是 Agent + 工具链架构的项目都能用。

第一步是确定失败发生的边界。Agent 的执行边界可以切分为模型请求、工具调用、结果加工、状态更新四段。拿到错误码后，先根据错误语义和日志时间戳判断大致落在哪一段。这一步不用太精确，只需要排除掉绝对不可能的段，缩小范围。

第二步是拉取失败段的输入输出。比如怀疑工具调用段出问题，就把框架传入工具的参数、工具返回的原始响应、工具自身的日志三样东西全部拉齐。这一步的关键是“原始”二字——框架层可能已经对数据做过处理，只有原始日志才能还原真相。

第三步是沿着错误链向上回溯。找到工具层抛出的异常后，继续往它的依赖方向追。比如工具内部调了下游 API，下游返回的是什么？工具对下游返回做了什么处理？错误是在工具内部被捕获后重新抛出的，还是原始透传的？这一层一层翻下去，通常能找到真正的根因。

第四步是构造复现路径，验证修复效果。找到根因后，我会在测试环境重新触发一次完整调用链，确认同样的输入不再产生同样的问题，并且输出结果是正确且稳定的。这一步不能省，因为 Agent 任务本身有随机性，模型生成可能有波动，只有在构造的确定输入下验证通过，才算是真正修好了。

3.1 时空对位法：用 trace 串起散落的日志

上述四步听上去很顺，实际做的时候会遇到一个很现实的问题：Agent 异步链路里的日志是散落在各处的。模型请求走一个服务，工具调用走另一个服务，中间还可能有消息队列在转发。没有 trace 贯穿的话，你根本不知道某一条工具日志对应的是哪一次用户请求。

我在这次排查中采取的办法是“临时手工对位”——靠时间戳和内容特征把日志串起来。工具日志里会打印简历文件 ID，模型请求日志里会打印对话 ID，两个 ID 之间没有直接关联，但时间窗口重叠且内容上下文相符，基本可以确定是同一条链路。这个办法在小范围内可行，但说实话效率很低，而且容易漏。

如果项目还在早期，建议直接引入标准 trace 机制。给每个 Agent 任务生成一个 trace ID，在模型请求、工具调用、结果回填三个阶段都打印这个 ID。日志收集到统一的平台后，按 trace ID 过滤，整条失败链一目了然。早期不觉得有必要，等你被粗错误码折磨几次，就会明白 trace 是排查的命脉。

另外一个容易被忽略的点是日志级别。Agent 框架很多默认只打 WARNING 和 ERROR 级别的日志，但排查失败链的时候，恰恰是 INFO 级别的“参数传入”“结果返回”这类日志最有价值。建议排查阶段临时把框架日志级别调到 DEBUG，收集到足够的上下文后，再调回正常级别。

4. 真实案例复盘：从 422 到 list index out of range

下面把这次的实际排查过程完整复盘一遍，方便你看清楚错误链是怎么被逐层剥开的。

背景是这样的：我在做一个招聘助手 Agent，Agent 根据对话上下文调用一个简历解析工具，工具接收简历文件路径和解析配置两个参数，返回结构化文本。那天测试时，Agent 一调用工具就报 422，业务侧看到的就是“工具调用失败”，没有任何额外信息。

我刚开始排查时，走的是最直接的路线——检查模型生成的函数调用参数。用调试模式把模型返回的原生 JSON 打出来看，文件路径是字符串，解析配置是对象，枚举值也都符合要求。又连续测了好几轮，参数格式都是正确的。这基本上排除了模型参数格式问题。

接着我开始怀疑工具服务本身。工具是部署在独立容器里的，我进容器翻日志，发现每次 Agent 调用工具时，工具进程都会抛一个 list index out of range 的 Python 异常，位置在解析配置的处理逻辑里。这个时候错误链条已经比 422 清晰多了，但还差一环：为什么同样的参数，有时候能成功有时候就失败？我们之前单测工具时明明是好的。

我继续往工具内部看，发现它内部维护了一个历史解析任务的全局列表，每次新任务进来都会去读这个列表做一些去重判断。问题就出在这——这个列表在每次服务启动时初始化，但不会清理，随着测试轮次增加，列表越攒越长。当列表长度达到某个条件后，新任务读取时索引越界。

根因挖到这里，真相大白：不是模型的问题，不是参数格式的问题，是工具实现里一个低级的全局状态管理 bug。框架把工具进程的任何异常都统一包装成 422 抛给上层，导致表象和真实的根因之间隔着十万八千里。

4.1 为什么这次排查走了一大段弯路

复盘一下时间消耗，在这个 bug 上我前前后后花了大概半天，其中至少有三个小时是浪费在不必要的事情上。

第一段弯路是过度聚焦模型侧。因为错误码带了个 422，我本能地觉得是函数参数语义不对，反复调整了 description、严格模式、参数约束，还对比了不同模型的输出表现。其实一开始吃透 422 的来源语义，就该明白这是工具执行阶段的错误，而不是模型输出阶段的错误。

第二段弯路是忽略进程状态。工具在测试环境跑了一整天，我一直以“无状态服务”的方式理解它，没意识到内部有跨请求共享状态的存在。Python 模块级变量、类变量、全局缓存这些都可能是隐藏的状态源，排查时要多留一个心眼。

第三段弯路是没第一时间启用 DEBUG 日志。工具的 INFO 日志其实已经把执行过程打出来了，但默认配置下不显示。如果我更早调整日志级别，可能光看日志里的“当前任务列表长度”就能定位到问题，不需要反复尝试触发复现。

这次之后我把排查原则改成了：先看日志，再看代码，然后才怀疑模型。顺序反过来的话，浪费的只能是自己的时间。

5. 把补救变成预防：错误码规范化与失败链设计的四个落点

一次排查解决单个 bug 不算完事，真正的价值是把这次踩坑的经验转化成项目的基础设施改进。我事后做了四件事，每一件都直接针对这次暴露出来的薄弱环节。

第一件事是规范错误码。我给工具层定义了一套内部错误码体系，明确区分 JSON 解析错误、索引越界、参数校验失败、下游网络异常等类别。框架层不再统一包装成 422，而是把内部错误码和原始异常信息透传到上层日志。这样再出问题，至少不用靠猜。

第二件事是给整条 Agent 链路打 trace。从用户请求进入开始生成 trace ID，模型调用、工具调用、结果回填都记录同一 ID。工具日志里强制打印 trace ID 字段，日志平台支持一键按 trace ID 检索全部链路日志。这个改动对排查效率的提升是决定性的。

第三件事是引入了失败分类统计。每次线上 Agent 任务失败，自动打上失败阶段标签（模型侧、参数侧、工具侧、网络侧、超时侧）。每周看一眼分布数据，就能发现趋势性问题和最该优先修复的短板。这个看板最大的价值，是让“模型到底是不是罪魁祸首”这个问题从主观判断变成了数据说话。

第四件事是给工具层做状态管理审查。全局变量、缓存对象、进程内共享状态全部列出来，逐一确认是否需要跨请求保留。不需要的全部改成请求级作用域，需要保留的加上容量限制和清理机制。这个习惯是从根因 bug 里直接长出来的，没有那一次索引越界，大概率也不会重视这块。

5.1 更远一步：失败链感知的 Agent 架构

做完上面四件事之后，我还在想一个更深的问题：错误码规范化只是让“人”排查时更快，能不能让 Agent 自己也具备对失败的感知能力？

现在的 Agent 框架在工具调用失败后，通常只是把错误信息作为文本回填给模型，让模型决定下一步怎么做。但这里的错误信息往往是粗错误码，模型看到以后只能继续瞎猜或反复重试。更好的做法是，给模型提供结构化、阶段化的失败链摘要，比如“工具执行 JSON 解析失败，原因字段缺失，建议修正输入格式后重试”，模型就能基于真实原因做判断。

这个方向需要框架层做更多工作，比如失败分类、原因摘要生成、上下文裁剪之后再进入模型。目前成熟度还不高，但我觉得这是 Agent 工程化演进的一个重要方向。毕竟，如果连失败原因都无法透明传递，Agent 的自主性就始终隔着一层。

6. 常见排查误区与实用经验速查

最后把常见的误区和经验集中列一份参考，覆盖“排错之前、排错之中、修完以后”三个阶段。

还有一些经验值得单独拿出来强调。比如排查 Agent 问题时，尽量维持固定输入来复现，不要让模型每次都重新生成参数，否则你无法区分是随机问题还是稳定缺陷。再比如工具侧的异常处理，应该保留原始异常链，不要全部吞掉重新包装，一线工程师看代码和看错误日志时最恨的就是“只见包装不见原因”。

说到底，Agent 项目不是“模型一枝独秀”的事，而是模型、框架、工具、基础设施共同协作的系统工程。失败不可怕，可怕的是失败链断裂，让排查无从下手。

以我个人的体会，一次系统性排查带走的远不止一个 bug，它往往会重塑你对整个项目稳定性的认知。你开始意识到错误码要设计、链路要追踪、状态要管理、数据要看板，而这些认知最终会让你的 Agent 项目从“能跑”变成“能稳定地跑”。下次再碰到粗错误码，先别急着怪模型——沿着失败链往下挖，那里藏着真正的答案。