从"Agent 又失败了"到真正定位到根因，中间隔着多少层？去年有段时间，我们团队的 Agent 服务频繁报警，错误码清一色是AGENT_EXECUTION_FAILED，一眼看去全是模型接口报错。当时所有人的第一反应都是"模型又抽风了"，甚至有人开始准备甩锅文档。但当我真正顺着链路往下挖，才发现事情远没有那么简单——粗错误码背后的真实原因五花八门：有上游服务超时参数配置不合理，有上下文窗口被日志撑爆，甚至有一次纯粹是 JSON 解析时对转义字符处理不一致。这篇文章就完整还原一下我是怎么一步步从粗错误码排查到失败链的，整个过程对于所有做 Agent 开发、模型应用集成的人都有参考价值。比起"模型垃圾"这种结论，真正值得花时间的是把失败链路理顺，让 Agent 系统出问题时能快速定位到是人、是配置、是依赖，还是模型本身。
1. 粗错误码是怎么一步步把排查带偏的
1.1 一个最典型的翻车现场
那次线上报警发生在周三下午，告警群里的消息很简单：agent execution terminated due to error.，附带一个 request_id。我进到监控后台，看到错误分布统计，几乎全部集中在几个固定的模型调用节点上。配套的错误信息是model request failed，连 HTTP 状态码都没有细分。
按照常规思路，我先测了模型接口的连通性，发现外网调用完全正常，一番折腾后仍然没有结论。后来去看模型网关的日志，才发现一个尴尬的事实：网关给业务侧返回的统一错误码把真正的异常信息全部吞掉了。业务侧只能看到"模型调用失败"，但究竟是超时、限流、上下文溢出还是负载均衡探活失败，完全看不出来。
这个问题的根源其实很典型。Agent 框架在向上层抛错的时候，往往只保留了"最终状态"，而把内部的失败原因降级成了一个粗粒度枚举值。更麻烦的是，某些中间层还会二次封装，比如在捕获异常时直接拼一句"model error"就抛出去了，原始错误信息被丢得干干净净。
1.2 粗错误码的隐性成本
粗错误码最大的问题不是"信息少"，而是会诱导团队往错误的方向排查。一旦所有人默认"失败等于模型问题"，就会出现几个连锁反应：
第一，模型提供方的真实瓶颈长期被掩盖。比如某个模型服务商在高峰期有挺高的限流概率，但因为统一错误码看起来像普通失败，我们根本不会去统计限流占比。
第二，Agent 编排层的缺陷被错误归因。我们后来发现，有好几次失败真正原因是编排逻辑在重试时拿错了消息 id，导致同一个用户请求被并发了多次，模型网关触发并发保护。这属于应用层 bug，被粗错误码一包装，反而让模型背了锅。
第三，排查成本指数级上升。没有中间过程的快照，每一次失败都要重新构造现场，运气不好得复现好几次才能抓到关键信息。说白了，粗错误码省的是开发时的一行日志，花掉的是排查时的几个小时。
这里有个很实用的判断标准：如果一个错误码对应了三种以上的真实根因，那它就是不合格的。真正好用的错误码至少要能区分"客户端问题"和"服务端问题"，在这个基础上再细分到具体阶段。
2. 一次从错误码反查失败链的完整还原
2.1 时间线和现场信息整理
既然粗错误码靠不住，我决定从现场信息入手，把链路彻底走一遍。当时拿到的线索只有三样：request_id、时间戳、模型服务商的响应体片段。
按照时间线去日志平台里拉取了整个请求的轨迹，核心节点包括：用户输入进入 Agent 编排引擎、意图识别调用、检索增强模块的召回、上下文拼装、模型服务商网关调用、结果解析与回传。我重点比对的是每个节点的时间戳差值。
拉出来的数据让我很意外。在模型网关调用这个环节，耗时高达 800 多毫秒，但这个时间消耗并不是花在模型推理上，而是花在了连接等待上。网关侧日志显示，TCP 连接建立后迟迟没有收到模型的第一个字节响应，客户端在等待超时边缘反复试探。
2.2 顺着依赖关系逐层定位
我整理了一份依赖关系，并按"入口 -> 编排 -> 记忆 -> 检索 -> 模型网关 -> 模型服务商 -> 回调解析"的顺序逐层排查。
先看入口层，用户请求本身没有问题，没有极端长度，也没有异常参数。再看编排层，任务状态机的流转记录是正常的，没有出现死循环或状态跳变。看到这里，本来想放一放，但直觉告诉我别轻易下结论。
进入模型网关层之后，发现了一个配置细节：网关的超时阈值设的是 1000 毫秒，而模型服务商侧的排队时间在某些时段会达到 2000 毫秒。上游还没开始推理，网关这边就已经掐断连接了。这个时间差就是导致"看起来是模型失败、实际上是网关配置不合理"的核心原因。
2.3 模拟验证和结论修正
为了确认这个判断，我在沙箱环境里搭了一个最小复现链路：直接用同样的模型服务商 API，在网关超时阈值分别设为 500 毫秒、1000 毫秒、3000 毫秒的情况下压测相同特征的请求。结果很清晰，把阈值调到 3000 毫秒之后，同样的请求成功率从 71% 提升到 96%，剩余失败大部分是模型服务商自带的限流。
到这里，根因已经定位：粗错误码掩盖了"网关超时配置"和"模型服务商排队时间"之间的冲突。把这一层的结论回写之后，团队把错误码规范补了一版，模型网关开始透传具体的拒因、限流类型、排队耗时和上游状态码。
这个案例给我一个很深的体会：很多 Agent 失败不是模型不行，而是系统的超时配置、重试策略、并发控制和上下文管理之间存在隐性冲突。错误的映射关系一天不修，排查人员就会一直在同一堆错误码里打转。
3. 失败链的概念拆解：从单点错误到全链路可观测
3.1 为什么单点错误视角根本不够用
很多人把 Agent 排查理解为"看错误码，定位出错的那一行"，但实际上 Agent 请求是一条链：从用户输入到工具调用中间会有多轮上下文、多步规划的叠加。单点错误视角只能告诉你"哪一步崩了"，但无法解释"为什么是这一步崩"。
失败链强调的是整条链路上每个环节的状态、输入、输出、耗时、依赖服务反馈。它回答的问题不是"模型报错了吗"，而是"这个错误是在什么前置条件下出现的"。有了失败链，我们才能区分：是模型在上下文污染的前提下裁断失误，还是工具返回结构异常导致模型无法解析，还是外部依赖在高延迟下触发了调用超时。
举个例子，我们有一次排查一个连续对话场景下的 Agent 崩溃，表面上是模型对同一指令反复返回同样的输出。单看模型调用错误码根本看不出端倪，但拉出失败链之后才发现上一轮工具返回的 JSON 就是一个空对象，这个空对象被塞进了上下文，模型在后续轮次里一直基于"什么也没检索到"的状态做决策。这就是典型的失败链问题，而不是模型质量问题。
3.2 失败链的核心组成和层次划分
结合那次的排查经验，我觉得一个合格的失败链至少要包含几个组成要素：
- 触发条件：这次请求的特征，比如用户输入、会话轮次、上下文 token 数、重试次数。
- 各节点快照：编排引擎在每个关键节点记录的输入输出摘要和当时的状态。
- 依赖服务明细：模型服务商的响应体、网关耗时、HTTP 状态码、排队指标、限流信息。
- 决策记录：Agent 在每一步选择了哪个工具、切换了哪个意图，以及对应打分或排序结果。
- 错误归一化：把不同来源的错误映射到统一分类体系，比如超时类、限流类、内容类、解析类。
在实现上，失败链和一般日志的区别在于它更强调"上下文对齐"。所有节点记录的数据必须围绕同一个 request_id 聚合，并且按时间顺序串联。如果缺少某个环节的记录，那整个链就是断的，排查时又得靠猜。
3.3 和传统 tracing 的区别
可能会有人说，这不就是分布式链路追踪吗？确实有交集，但侧重点不太一样。传统 tracing 更多地关注服务节点之间的调用关系和耗时情况，而失败链还需要额外的"内容快照"。
比如一个工具调用环节，tracing 可能只知道"调用了某个服务，耗时 200 毫秒，返回 500"，但失败链要记录的是"发送的工具参数是什么、返回内容是什么、Agent 基于这个返回值做了什么样的下一步决策"。没有这些内容级信息，就很难判断问题出在"模型理解错了"还是"工具返回的数据本身就是残缺的"。
所以做失败链的时候，不要只把它当做一个技术埋点来搞，它同时也是一个数据模型设计问题。链条上的每个节点都需要定义清楚：哪些字段是结构化字段，哪些是便于排查的自然语言摘要。越是关键的工具调用，越要有内容快照。
4. 搭建失败链埋点体系的实践记录
4.1 先定义统一事件模型
我们踩过很多次坑之后，决定从零设计一套适合 Agent 场景的失败链埋点规范。第一个核心工作是定义统一事件模型。
这个模型没有沿用传统的"span 套 span"结构，而是把一次 Agent 执行定义成一个执行单元，内部的每个步骤定义成step。每个 step 有固定的字段：step_id、step_type（意图识别/工具调用/模型调用/上下文拼装等）、输入摘要、输出摘要、状态、耗时、错误分类、关联的外部依赖信息。
在这个基础上，嵌入一个轻量级的快照存储，主要记录输入输出的关键片段，不做全量留存。全量数据太占空间，而且很多中间输出对排查并没有帮助，真正有价值的往往是"摘要级别的信息"加上"异常时的完整快照"。
4.2 错误分类体系的思考
粗错误码靠不住，很大程度是错误分类粒度太粗。我们参考了模型服务商的一些错误定义，再结合自己的编排场景，把错误分成几大类：
- 超时类：包括连接超时、读取超时、排队超时。
- 限流类：包括并发限流、配额不足、服务商主动限流。
- 内容类：包括安全审核拒绝、上下文长度超限、内容格式异常。
- 解析类：包括输出无法按预期 JSON 解析、字段缺失、类型不匹配。
- 编排类：包括工具不存在、规划循环、状态机非法跳转。
- 依赖类：包括上游服务崩溃、DNS 解析失败、网络分区。
每类错误在失败链里都需要带上一个额外字段，用来存放该类别下的具体原因。比如超时类要记录连接建立耗时、等待首字节耗时、总体预算耗时，这样后续统计和排查才有实质性的数据支撑。
4.3 埋点采集的具体实现细节
实现埋点的时候我们走了不少弯路，最开始是直接在业务代码里到处加日志，结果日志爆炸不说，字段格式还不统一，后续聚合非常痛苦。后来改成在 Agent 编排器的关键接口处做统一拦截，在每个 step 的入口和出口分别采集上下文。
采集的时机很关键：入口处采集的是步骤接收到的输入和前置状态，出口处采集的是步骤产生的输出和后置状态。如果步骤内部出现异常，需要额外记录当时的运行时上下文，比如工具参数原始内容、模型返回原文、重试次数等。
存储层我们用了分桶策略：正常执行只记录摘要字段和一些必须的关联 id，异常执行才触发完整快照。这样既保留了失败链的连续性，又控制了存储成本。查询侧通过 request_id 直接聚合链路，不需要跨系统 join，效率很高。
4.4 从埋点到可用的排查台
埋点数据只有变成可查询的界面才有价值。我们做了一套排查台，入口就是 request_id 搜索框。输入之后直接展示这次 Agent 执行的完整 step 链条，每个 step 可以展开查看输入输出摘要和异常快照。
排查台上还有个很有用的功能：对同类型失败做模式归并。把最近一小时所有标记为"超时类"的 step 按特征聚类，方便看出是某一类模型的通病，还是特定工具调用独有的问题。这个功能在跨字段关联分析时省了很多事，不再需要手动导日志到 Excle 里折腾。
我还建议在排查台里保留一个"时间线预览"模式，按实际执行顺序直观展示每个 step 什么时候开始、什么时候结束、哪一段耗时超标。这些信息靠代码 review 很难发现，但可视化时间线一摆出来，基本几秒就能看出端倪。
5. 借助失败链重构排查流程的方法论
5.1 按失败链分类选择不同的排查路径
有了失败链体系之后，我们的排查思路完全变了。不再用单一错误码触发排查，而是先看失败链属于哪种模式，再走对应的排查路径。
如果是超时类失败链，优先检查网络链路和依赖服务排队情况，同时确认 Agent 编排层的超时预算分配是否合理。很多时候超时是"上游慢+下游又没配够等待时间"共同造成的，不是一句模型慢可以打发的。
如果是内容类失败链，重点检查输入上下文是否存在污染。比如历史轮次带入了无关工具返回、角色系统提示被覆盖、用户指令被截断等。内容问题靠摘要快照往往一眼就能看出，比猜测模型行为可靠得多。
如果是解析类失败链，就要去检查模型输出和解析器的匹配程度。模型的输出格式偏好、结构化输出开关、以及解析器对特殊转义字符的处理策略都会影响。为了避免这类问题，我们还专门维护了一份不同模型服务商的输出差异对照表。
5.2 重试策略必须依赖失败链分层设计
重试是 Agent 系统里绕不开的机制，但无脑重试会放大故障。我们按失败链分类设计了一套分层的重试策略：超时类可以尝试一次，但需要放宽单次超时阈值；限流类的重试必须带退避，并且要参考限流头中给出的等待时间；解析类失败不建议直接重试，而是应该触发输出校正流程；内容类失败通常不能重试，需要让模型重新理解输入或者降低上下文复杂度。
这套策略落地的关键是：重试决策不能只依赖最终错误码，而要读取失败链中的节点状态。我们给每个 step 增加了一个重试预算计数器，任何一环超预算都会终止整个链路，避免形成请求风暴。
5.3 从多次失败链中提炼模式
当失败链积累到一定量级后，它就不再仅仅是一个排查工具，还能用来做模式分析。比如我们通过失败链发现某个特定提示词模板在长上下文场景下特别容易触发内容审核，于是直接改了模板措辞，效果立竿见影。
类似的提炼工作是很有价值的：定期跑一遍过去一周的失败链，按分类聚合出 Top 问题，再把这些问题回写到代码规范或配置规范里。这样每一次排查的成果，都能变成下一次的预防手段。
我个人的经验是，失败链数据的质量直接决定这套方法论的上限。如果每个 step 都记录了可靠且完整的快照，那后续的分析、重试、模式提取都会非常顺手。如果埋点偷工减料，那这套东西和以前的粗错误码也没什么本质区别。
6. 未知错误与外部依赖的边界处理
6.1 外部依赖返回未知错误时的兜底逻辑
模型服务商偶尔会返回一些文档里没有出现过的错误。最简单省事的处理方式是当作"未知错误"直接抛出来，但这样做的问题在于：模型网关会把它映射成粗错误码，后续又要重新排查。
我们的做法是在网关层做了一层兜底翻译：把未知错误连同原始响应体、请求头、耗时数据全部记进失败链的依赖明细里，同时打上一层"未分类"的标记。排查的时候遇到这种"未分类"标记，第一步先去和上游服务商核对错误语义，而不是猜。
这也引出另一个关键点：外部依赖的错误语义必须主动维护。我们每个月会整理一次实际生产返回的错误清单，和服务商提供的错误文档做差异对比。文档没覆盖但实际高频出现的错误，直接升级成标准分类，避免一直以"未知错误"的形式存在。
6.2 上下文信息丢失是最隐蔽的敌人
排查中还有一种很隐蔽的情况：错误本身消失了，但上下文已经悄悄被截断或覆盖。比如 Agent 在长对话场景里，历史消息过多导致上下文压缩算法把关键指令给精简掉了，后续模型虽然"没有报错"，但行为明显偏移预期。
这种问题用传统错误码根本发现不了，只能靠失败链里的上下文快照回溯。所以我们在上下文拼装节点专门记录了压缩前后的 token 数和关键指令是否存在。一旦发现模型行为异常，就能快速确认是不是上下文丢失引起的。
顺便说一句，这类问题在排查时容易误判成"模型能力下降"。如果没有失败链，真的很难想到是压缩逻辑在捣鬼。现在我们在每次上下文压缩前都会跑一遍完整性检测，强制保留系统指令和最近聊天的核心内容，避免压缩策略对 Agent 行为产生隐性影响。
6.3 边界预算：别让失败链本身成为性能瓶颈
做失败链埋点时要控制好它自身的开销。我们最开始把每个 step 的完整输入输出都存了下来，结果存储开销涨得很快，而且高并发下会影响主链路延迟。
后面优化成"双阈值"策略：小于某个长度的输入输出直接完整记录，大于阈值的先生成摘要再存储，异常场景才触发完整快照。这样一来，失败链的信息密度没有明显下降，但存储和性能开销都回到了可接受的范围。
超时方面也做了严格限制，埋点逻辑绝不阻塞主流程，全部采用异步上报。即使链路数据写入失败，也不能影响 Agent 的正常执行，这是底线。
7. 经验沉淀与团队协作的踩坑复盘
7.1 失败链建设需要组织配合
我一个人能做的只有技术埋点和排查工具，真正让这套体系跑起来，需要多个角色的配合。后端要把每个 step 的上下文快照规范化，算法团队要协助定义哪些模型输出需要额外记录，测试要构造各种失败场景来验证失败链的完整性。
所以我的建议是：不要把失败链当成纯后端工程，而是当成一种研发效能设施来建设。从第一次复盘会议开始，就要明确谁负责定义节点规范、谁负责采集实现、谁负责数据分析，否则很容易出现"采集了一堆日志但没人分析"的尴尬状态。
团队里还需要有一名固定的"失败链接口人"，发现新的失败模式时，由他统一维护错误分类映射和排查兜底策略。否则每个人按自己的理解记录错误，过两个月数据就是一锅粥。
7.2 我用过之后觉得值得上手的实践清单
总结一下实际操作中的体会，有几点是立刻就能落地的。
先把自己系统里的错误码全部列出来，检查是否存在"一个错误码对应三种以上根因"的情况，有的话优先拆分。
然后给每个外部依赖加上透传明细，至少包括原始状态码、错误子码、耗时和限流信息。依赖服务的错误不透明，排查很容易卡壳。
再给 Agent 编排引擎的每个关键节点增加输出摘要快照，摘要控制在 200 字左右，不需要很长，重点是保留决策依据。
最后设置一个固定的复盘节奏，比如每周抽取 30 条失败链做聚类分析，把高频错误映射到标准分类库里。三个月下来，大部分问题都能在发生前被预判到。
7.3 从这次排查中学到的最重要一课
回到标题的问题：Agent 失败到底该不该算到模型头上？我的答案是先别急着算账。模型的输出质量当然会影响成功率，但"模型调用失败"和"模型能力不足"是性质完全不同的两类问题。前者可能是网关配置、超时预算、限流策略、上下文污染或者工具返回异常；后者才真正指向模型本身的选择。
定了错误分类，再把失败链建好，哪怕一开始简陋点也没关系。信息先记录起来，再逐步优化汇总维度。你会发现，很多以前觉得"无法解释"的 Agent 诡异行为，其实都有清晰的因果链条。与其天天怀疑模型，不如把失败链搭好，让数据告诉你答案。
提示：建议团队里所有 Agent 相关项目都尽早引入失败链概念。越早开始积累，越能避免日后在排查中反复交学费。
