1. 为什么“模型不行”往往是排查方向跑偏了做 Agent 开发这两年我参与过不少线上故障的复盘。一个特别高频的场景是Agent 任务失败日志里只留下一句agent execution terminated due to error或者一个语焉不详的错误码然后团队里立刻有人下结论——“模型能力不行”“换个更强的模型就好了”。结果换了模型问题照旧甚至因为换了模型失败形态变了排查难度反而更大。这个项目标题说的就是这件事别再把 Agent 失败都算给模型。真正要做的是从一个粗糙的错误码出发顺着执行链路一层层往下挖把“失败链”还原出来。所谓失败链指的是从任务下发到最终报错之间所有可能出问题的环节按顺序串起来的那条路径。Agent 和普通后端服务最大的区别在于它的执行链路特别长模型推理、工具调用、参数拼装、外部接口、沙盒环境、终端执行、结果回传、记忆写入任何一环出问题最终都可能表现为同一句模糊的报错。这篇文章适合三类人看。第一类是刚开始做 Agent 开发、被各种错误码搞得一头雾水的同学第二类是已经在维护线上 Agent 服务、需要一套系统排查方法的工程师第三类是做 Agent 平台或中台、需要设计错误码体系和可观测能力的同学。我会围绕“粗错误码到失败链”这条主线把排查思路、工具选型、实操步骤和踩坑经验都摊开讲尽量做到你看完就能照着复现。先给一个核心观点定调错误码是入口不是结论。一个terminalBlocker之类的标记或者一个9003这样的数字它只告诉你“这里断了”不告诉你“为什么断”。把错误码当结论就会把排查变成猜谜把错误码当入口才能顺着链路找到真正的断点。2. 失败链的整体拆解Agent 到底在哪几层会挂2.1 一条完整的 Agent 执行链路长什么样在动手排查之前得先在脑子里有一条完整的链路图。不同框架细节不同但主干大同小异。我把它拆成七层从外到内依次是接入层请求进来鉴权、限流、参数校验。这一层挂了通常是 4xx比较好认。编排层任务规划、子任务拆分、多 Agent 调度。这一层是 Agent 特有的也是最容易被忽略的。模型层推理调用、上下文组装、token 预算控制。模型超时、上下文超限、返回格式不合法都在这里。工具层工具选择、参数生成、schema 校验。模型“想调用工具”和“正确调用工具”是两回事。执行层真正去跑工具可能是 HTTP 请求、数据库操作、终端命令、沙盒执行。环境层沙盒、容器、虚拟化、网络、文件系统。terminalBlocker这类标记通常出现在这一层。回传层结果解析、记忆写入、状态更新、响应组装。这七层里模型层只是其中一层。而实际线上故障的分布我个人的经验是模型层大概占三成剩下七成散落在工具层、执行层和环境层。所以一上来就怀疑模型命中率其实不高。2.2 粗错误码为什么“粗”设计上的取舍很多人抱怨错误码太粗比如只有一个9003或者只有一句execution terminated。这里要理解一个设计现实错误码的粒度是成本和可维护性的权衡。Agent 的执行路径是动态的同一个任务每次走的工具链可能都不一样。如果要求每个可能的失败点都有独立错误码错误码表会爆炸维护成本极高而且很多失败是组合出来的没法预先枚举。所以平台方通常只暴露几个粗粒度的码把细节藏在日志和 trace 里。这就带来一个直接后果光看错误码永远不够必须结合 trace 和上下文日志。粗错误码的作用是缩小范围不是定位根因。理解这一点排查心态就对了——你不是在“解读错误码”你是在“用错误码圈定链路区间然后逐段验证”。2.3 失败链排查的核心方法论分段二分链路这么长怎么高效定位我常用的是分段二分法。具体做法是先在链路中间找一个可观测的锚点比如“工具是否被调用”“执行层是否收到请求”。如果锚点之前就断了问题在前半段如果锚点之后才断问题在后半段。然后在前半段或后半段里再找锚点继续二分。这个方法的好处是不依赖对每一层的深入理解先快速缩小范围再针对性深挖。下面几节我会把每一层的具体排查手段展开。3. 从错误码到失败链分层排查实操3.1 第一步把错误码归类别急着看细节拿到一个错误码先做归类而不是立刻去搜它的含义。归类维度我一般用三个归类维度判断依据典型指向失败阶段报错发生在任务开始、执行中还是收尾开始多为接入/编排执行中多为工具/执行/环境收尾多为回传失败性质超时、拒绝、格式错误、资源不足、权限问题决定后续排查方向可重试性重试是否可能成功区分偶发和稳定故障举个实际例子。之前遇到一个 Agent 批量任务错误码统一是execution terminated看起来毫无信息量。我先按阶段归类失败都发生在任务执行中段不是一开始就挂。再按性质归类日志里伴随大量超时。再按可重试性重试偶尔能成功。三个维度一交叉基本锁定在执行层或环境层的资源竞争而不是模型问题。后来查下来确实是沙盒并发太高终端命令排队超时。提示归类阶段不要陷入单个错误码的语义细节先建立“这批失败有什么共性”的整体判断共性比个案更有价值。3.2 第二步用 trace 还原真实执行路径归类之后下一步是拿到真实的执行 trace。注意是“真实”的不是你以为的。Agent 的执行路径经常和设计文档不一致因为模型会动态选择工具、动态调整参数。看 trace 我重点关注四件事工具调用序列实际调了哪些工具顺序是什么有没有重复调用、循环调用。每步耗时哪一步特别慢慢在模型推理还是工具执行。参数快照模型生成的参数长什么样有没有明显畸形。断点位置trace 在哪一步戛然而止那一步就是重点嫌疑。这里有个经验trace 断点不等于故障点。有时候 trace 断在工具调用但真正的原因是上一步模型返回了非法参数导致工具层直接抛异常trace 没来得及记录。所以看 trace 要往前多看一步。3.3 第三步模型层排查先排除“冤枉”虽然我说别把锅都甩给模型但模型层该查还是要查只是要放在合理的位置。模型层常见问题有这么几类上下文超限任务长了历史消息堆积超出窗口模型直接报错或返回空。返回格式不合法要求 JSON返回了带 markdown 包裹的 JSON解析失败。工具调用幻觉调用了不存在的工具或参数类型不对。推理超时模型响应慢触发上游超时。排查模型层我一般先看输入再看输出。输入侧检查上下文长度、消息角色是否正确、system prompt 有没有被污染。输出侧检查原始返回不是解析后的很多时候解析层报的错根因在原始返回格式。一个实用技巧把模型的原始返回单独落盘。很多框架默认只存解析后的结构化结果一旦解析失败原始返回就丢了排查时抓瞎。自己加一层原始日志成本很低收益很大。3.4 第四步工具层与执行层失败链的高发区这两层是失败的重灾区我合并讲。工具层的问题主要是“选错工具”和“参数不对”执行层的问题主要是“跑不起来”和“跑太久”。工具层排查要点schema 校验模型生成的参数是否符合工具定义的 schema。类型、必填项、枚举值都要看。工具可用性工具本身是否在线依赖的服务是否健康。参数语义参数格式对了但语义错了。比如路径写成了相对路径在沙盒里解析到了错误位置。执行层排查要点命令是否真的执行了有些框架在参数校验失败时直接跳过执行但错误信息看起来像执行失败。执行环境是否就绪容器没起来、依赖没装、工作目录不对。超时设置执行层超时和上游超时是否匹配经常出现上游 30 秒超时、执行层还在跑的情况。terminalBlocker这个标记我特别想提一下。它通常表示终端执行被阻断可能原因包括命令被安全策略拦截、沙盒资源不足、终端会话异常、或者命令本身触发了某种保护机制。看到这个标记第一反应应该是去查环境层而不是模型层。3.5 第五步环境层最容易被忽视的一环环境层包括沙盒、容器、虚拟化、网络、文件系统。这一层的问题往往表现为“莫名其妙”因为它的失败和业务逻辑无关。常见环境层问题资源竞争并发高了CPU、内存、文件句柄不够命令执行失败。网络问题工具需要访问外部服务网络不通或 DNS 解析失败。文件系统共享目录挂载失败、权限不对、路径不存在。虚拟化层容器运行时异常WSL2 之类的兼容层出问题。排查环境层我习惯先看系统级指标CPU、内存、磁盘、网络、进程数。再看容器/沙盒状态是否健康、日志有没有异常。最后看具体命令的执行环境工作目录、环境变量、权限。注意环境层问题经常是“间歇性”的单次复现不了不代表没问题。要结合时间窗口看指标找规律。4. 实操搭一套可复现的失败链排查流程4.1 准备最小可观测能力要排查失败链先得有观测能力。最小配置我建议包含结构化日志每条日志带 trace_id、span_id、阶段标记。原始返回落盘模型原始返回、工具原始返回都存。关键锚点埋点工具调用前后、执行前后、回传前后各埋一个点。指标采集耗时、成功率、资源使用率。这套东西搭起来不难但很多团队是出事了才补补的时候又没有历史数据很被动。我的建议是上线前就埋好成本远低于事后救火。4.2 复现把线上失败搬到本地排查最怕“线上有、本地没有”。复现的关键是还原现场包括输入还原把触发失败的原始请求完整保存包括上下文、历史消息。环境还原本地环境和线上环境的差异要清楚尤其是依赖版本、资源限制。并发还原如果是并发问题本地要模拟相同并发。时序还原有些问题是时序相关的要按相同顺序重放。复现不了的时候退而求其次做局部复现只复现失败链中的某一段比如单独测工具调用、单独测执行层。局部复现虽然不完整但往往足够定位根因。4.3 定位二分法实战假设一个 Agent 任务失败错误码是粗粒度的execution terminated。我的二分流程是锚点一工具是否被调用。查 trace如果工具没被调用问题在模型层或编排层如果调用了往下走。锚点二执行层是否收到请求。查执行层日志如果没收到问题在工具层到执行层的传递如果收到了往下走。锚点三执行是否完成。查执行结果如果没完成看是超时还是异常如果完成了问题在回传层。三步下来范围就缩得很小了。这个过程不需要你一开始就懂所有细节靠锚点逐步逼近。4.4 修复与验证别只修表象定位到根因后修复要注意两点修根因不修表象。比如超时问题不要简单调大超时时间要搞清楚为什么慢。加回归用例。把这次失败的场景做成测试用例防止回归。验证阶段除了验证修复还要验证没有引入新问题。Agent 系统耦合度高改一处可能影响另一处。5. 常见问题与排查速查表5.1 高频问题速查现象可能层级排查方向错误码模糊无细节全链路查 trace找断点工具调用失败工具层查 schema、参数、工具可用性终端执行被阻断环境层查沙盒资源、安全策略、会话状态模型返回空模型层查上下文长度、超时、格式间歇性失败环境层/执行层查资源竞争、并发、时序结果回传丢失回传层查解析逻辑、记忆写入5.2 独家避坑经验别信单一错误码错误码是入口trace 才是真相。原始数据一定要存解析后的数据会丢信息原始返回是排查的命根子。环境层问题占比被低估很多人只盯模型忽略了沙盒和容器。复现不了就局部复现不要死磕完整复现分段验证更高效。错误码体系要持续迭代每次排查完把新发现的失败模式补进错误码或标记里让下次排查更快。5.3 关于错误码设计的建议如果你在做 Agent 平台错误码设计我建议遵循几个原则分层编码用前缀区分层级比如M开头是模型层T是工具层E是环境层。保留扩展位不要把所有位都用满留出扩展空间。关联 trace每个错误码都要能关联到具体 trace方便下钻。文档化错误码含义、常见原因、排查步骤都要写清楚减少沟通成本。6. 我踩过的几个真实坑第一个坑是把超时当模型问题。有次 Agent 批量失败错误码指向模型超时团队准备换模型。我坚持先看 trace发现模型其实很快就返回了慢的是后面的工具执行只是上游超时设置太短把工具执行的耗时算到了模型头上。调大上游超时后问题消失。这个坑让我记住超时归属要看 trace 的时间分布不能看错误码的字面。第二个坑是忽略环境层的间歇性。有个任务偶尔失败错误码是terminalBlocker。本地怎么都复现不了。后来查线上指标发现失败都集中在整点附近那段时间有定时任务在跑抢占了沙盒资源。这种问题不看时间维度的指标根本发现不了。第三个坑是原始返回没存。早期框架只存解析后的结果有次解析失败原始返回丢了只能猜。后来加了原始日志排查效率提升非常明显。这个改动成本极低但价值极高强烈建议所有 Agent 项目都做。第四个坑是错误码不迭代。有段时间同一个错误码对应好几种根因排查时每次都要重新分析。后来我们把常见根因拆成了更细的标记虽然错误码表变长了但排查速度快了很多。错误码体系是要养的不是一次设计就完事。7. 后续可以怎么扩展这套方法这套“从粗错误码到失败链”的排查方法本身是可以产品化的。我目前在做的一个方向是自动失败链还原给定一个错误码和 trace自动把链路各段的状态标出来直接告诉排查者“断在哪一段”。这需要把前面说的锚点埋点标准化然后用规则或小模型做归因。另一个方向是失败模式库。把每次排查的根因、现象、修复方式沉淀下来形成可检索的库。下次遇到类似错误码先查库命中就直接给排查建议。这个库越用越值钱是团队的知识资产。还有一个方向是错误码的语义增强。粗错误码之所以粗是因为平台不知道细节。但如果执行层、工具层能主动上报更细的状态平台就能在错误码里带上更多信息。这需要各层配合但长期看收益很大。我个人在实际操作中的体会是Agent 排查这件事方法论比工具重要观测能力比技巧重要。工具会换框架会变但“分段二分、锚点定位、原始数据留存”这套思路是通用的。把观测能力建好把错误码体系养起来把失败模式沉淀下来排查就会从“玄学”变成“工程”。最后分享一个小技巧每次排查完花十分钟写一份简短的失败链记录包括错误码、断点、根因、修复。坚持几个月你会发现自己对 Agent 系统的理解深度完全不一样了。这份记录比任何文档都值钱。
1. 为什么“模型不行”往往是排查方向跑偏了做 Agent 开发这两年我参与过不少线上故障的复盘。一个特别高频的场景是Agent 任务失败日志里只留下一句agent execution terminated due to error或者一个语焉不详的错误码然后团队里立刻有人下结论——“模型能力不行”“换个更强的模型就好了”。结果换了模型问题照旧甚至因为换了模型失败形态变了排查难度反而更大。这个项目标题说的就是这件事别再把 Agent 失败都算给模型。真正要做的是从一个粗糙的错误码出发顺着执行链路一层层往下挖把“失败链”还原出来。所谓失败链指的是从任务下发到最终报错之间所有可能出问题的环节按顺序串起来的那条路径。Agent 和普通后端服务最大的区别在于它的执行链路特别长模型推理、工具调用、参数拼装、外部接口、沙盒环境、终端执行、结果回传、记忆写入任何一环出问题最终都可能表现为同一句模糊的报错。这篇文章适合三类人看。第一类是刚开始做 Agent 开发、被各种错误码搞得一头雾水的同学第二类是已经在维护线上 Agent 服务、需要一套系统排查方法的工程师第三类是做 Agent 平台或中台、需要设计错误码体系和可观测能力的同学。我会围绕“粗错误码到失败链”这条主线把排查思路、工具选型、实操步骤和踩坑经验都摊开讲尽量做到你看完就能照着复现。先给一个核心观点定调错误码是入口不是结论。一个terminalBlocker之类的标记或者一个9003这样的数字它只告诉你“这里断了”不告诉你“为什么断”。把错误码当结论就会把排查变成猜谜把错误码当入口才能顺着链路找到真正的断点。2. 失败链的整体拆解Agent 到底在哪几层会挂2.1 一条完整的 Agent 执行链路长什么样在动手排查之前得先在脑子里有一条完整的链路图。不同框架细节不同但主干大同小异。我把它拆成七层从外到内依次是接入层请求进来鉴权、限流、参数校验。这一层挂了通常是 4xx比较好认。编排层任务规划、子任务拆分、多 Agent 调度。这一层是 Agent 特有的也是最容易被忽略的。模型层推理调用、上下文组装、token 预算控制。模型超时、上下文超限、返回格式不合法都在这里。工具层工具选择、参数生成、schema 校验。模型“想调用工具”和“正确调用工具”是两回事。执行层真正去跑工具可能是 HTTP 请求、数据库操作、终端命令、沙盒执行。环境层沙盒、容器、虚拟化、网络、文件系统。terminalBlocker这类标记通常出现在这一层。回传层结果解析、记忆写入、状态更新、响应组装。这七层里模型层只是其中一层。而实际线上故障的分布我个人的经验是模型层大概占三成剩下七成散落在工具层、执行层和环境层。所以一上来就怀疑模型命中率其实不高。2.2 粗错误码为什么“粗”设计上的取舍很多人抱怨错误码太粗比如只有一个9003或者只有一句execution terminated。这里要理解一个设计现实错误码的粒度是成本和可维护性的权衡。Agent 的执行路径是动态的同一个任务每次走的工具链可能都不一样。如果要求每个可能的失败点都有独立错误码错误码表会爆炸维护成本极高而且很多失败是组合出来的没法预先枚举。所以平台方通常只暴露几个粗粒度的码把细节藏在日志和 trace 里。这就带来一个直接后果光看错误码永远不够必须结合 trace 和上下文日志。粗错误码的作用是缩小范围不是定位根因。理解这一点排查心态就对了——你不是在“解读错误码”你是在“用错误码圈定链路区间然后逐段验证”。2.3 失败链排查的核心方法论分段二分链路这么长怎么高效定位我常用的是分段二分法。具体做法是先在链路中间找一个可观测的锚点比如“工具是否被调用”“执行层是否收到请求”。如果锚点之前就断了问题在前半段如果锚点之后才断问题在后半段。然后在前半段或后半段里再找锚点继续二分。这个方法的好处是不依赖对每一层的深入理解先快速缩小范围再针对性深挖。下面几节我会把每一层的具体排查手段展开。3. 从错误码到失败链分层排查实操3.1 第一步把错误码归类别急着看细节拿到一个错误码先做归类而不是立刻去搜它的含义。归类维度我一般用三个归类维度判断依据典型指向失败阶段报错发生在任务开始、执行中还是收尾开始多为接入/编排执行中多为工具/执行/环境收尾多为回传失败性质超时、拒绝、格式错误、资源不足、权限问题决定后续排查方向可重试性重试是否可能成功区分偶发和稳定故障举个实际例子。之前遇到一个 Agent 批量任务错误码统一是execution terminated看起来毫无信息量。我先按阶段归类失败都发生在任务执行中段不是一开始就挂。再按性质归类日志里伴随大量超时。再按可重试性重试偶尔能成功。三个维度一交叉基本锁定在执行层或环境层的资源竞争而不是模型问题。后来查下来确实是沙盒并发太高终端命令排队超时。提示归类阶段不要陷入单个错误码的语义细节先建立“这批失败有什么共性”的整体判断共性比个案更有价值。3.2 第二步用 trace 还原真实执行路径归类之后下一步是拿到真实的执行 trace。注意是“真实”的不是你以为的。Agent 的执行路径经常和设计文档不一致因为模型会动态选择工具、动态调整参数。看 trace 我重点关注四件事工具调用序列实际调了哪些工具顺序是什么有没有重复调用、循环调用。每步耗时哪一步特别慢慢在模型推理还是工具执行。参数快照模型生成的参数长什么样有没有明显畸形。断点位置trace 在哪一步戛然而止那一步就是重点嫌疑。这里有个经验trace 断点不等于故障点。有时候 trace 断在工具调用但真正的原因是上一步模型返回了非法参数导致工具层直接抛异常trace 没来得及记录。所以看 trace 要往前多看一步。3.3 第三步模型层排查先排除“冤枉”虽然我说别把锅都甩给模型但模型层该查还是要查只是要放在合理的位置。模型层常见问题有这么几类上下文超限任务长了历史消息堆积超出窗口模型直接报错或返回空。返回格式不合法要求 JSON返回了带 markdown 包裹的 JSON解析失败。工具调用幻觉调用了不存在的工具或参数类型不对。推理超时模型响应慢触发上游超时。排查模型层我一般先看输入再看输出。输入侧检查上下文长度、消息角色是否正确、system prompt 有没有被污染。输出侧检查原始返回不是解析后的很多时候解析层报的错根因在原始返回格式。一个实用技巧把模型的原始返回单独落盘。很多框架默认只存解析后的结构化结果一旦解析失败原始返回就丢了排查时抓瞎。自己加一层原始日志成本很低收益很大。3.4 第四步工具层与执行层失败链的高发区这两层是失败的重灾区我合并讲。工具层的问题主要是“选错工具”和“参数不对”执行层的问题主要是“跑不起来”和“跑太久”。工具层排查要点schema 校验模型生成的参数是否符合工具定义的 schema。类型、必填项、枚举值都要看。工具可用性工具本身是否在线依赖的服务是否健康。参数语义参数格式对了但语义错了。比如路径写成了相对路径在沙盒里解析到了错误位置。执行层排查要点命令是否真的执行了有些框架在参数校验失败时直接跳过执行但错误信息看起来像执行失败。执行环境是否就绪容器没起来、依赖没装、工作目录不对。超时设置执行层超时和上游超时是否匹配经常出现上游 30 秒超时、执行层还在跑的情况。terminalBlocker这个标记我特别想提一下。它通常表示终端执行被阻断可能原因包括命令被安全策略拦截、沙盒资源不足、终端会话异常、或者命令本身触发了某种保护机制。看到这个标记第一反应应该是去查环境层而不是模型层。3.5 第五步环境层最容易被忽视的一环环境层包括沙盒、容器、虚拟化、网络、文件系统。这一层的问题往往表现为“莫名其妙”因为它的失败和业务逻辑无关。常见环境层问题资源竞争并发高了CPU、内存、文件句柄不够命令执行失败。网络问题工具需要访问外部服务网络不通或 DNS 解析失败。文件系统共享目录挂载失败、权限不对、路径不存在。虚拟化层容器运行时异常WSL2 之类的兼容层出问题。排查环境层我习惯先看系统级指标CPU、内存、磁盘、网络、进程数。再看容器/沙盒状态是否健康、日志有没有异常。最后看具体命令的执行环境工作目录、环境变量、权限。注意环境层问题经常是“间歇性”的单次复现不了不代表没问题。要结合时间窗口看指标找规律。4. 实操搭一套可复现的失败链排查流程4.1 准备最小可观测能力要排查失败链先得有观测能力。最小配置我建议包含结构化日志每条日志带 trace_id、span_id、阶段标记。原始返回落盘模型原始返回、工具原始返回都存。关键锚点埋点工具调用前后、执行前后、回传前后各埋一个点。指标采集耗时、成功率、资源使用率。这套东西搭起来不难但很多团队是出事了才补补的时候又没有历史数据很被动。我的建议是上线前就埋好成本远低于事后救火。4.2 复现把线上失败搬到本地排查最怕“线上有、本地没有”。复现的关键是还原现场包括输入还原把触发失败的原始请求完整保存包括上下文、历史消息。环境还原本地环境和线上环境的差异要清楚尤其是依赖版本、资源限制。并发还原如果是并发问题本地要模拟相同并发。时序还原有些问题是时序相关的要按相同顺序重放。复现不了的时候退而求其次做局部复现只复现失败链中的某一段比如单独测工具调用、单独测执行层。局部复现虽然不完整但往往足够定位根因。4.3 定位二分法实战假设一个 Agent 任务失败错误码是粗粒度的execution terminated。我的二分流程是锚点一工具是否被调用。查 trace如果工具没被调用问题在模型层或编排层如果调用了往下走。锚点二执行层是否收到请求。查执行层日志如果没收到问题在工具层到执行层的传递如果收到了往下走。锚点三执行是否完成。查执行结果如果没完成看是超时还是异常如果完成了问题在回传层。三步下来范围就缩得很小了。这个过程不需要你一开始就懂所有细节靠锚点逐步逼近。4.4 修复与验证别只修表象定位到根因后修复要注意两点修根因不修表象。比如超时问题不要简单调大超时时间要搞清楚为什么慢。加回归用例。把这次失败的场景做成测试用例防止回归。验证阶段除了验证修复还要验证没有引入新问题。Agent 系统耦合度高改一处可能影响另一处。5. 常见问题与排查速查表5.1 高频问题速查现象可能层级排查方向错误码模糊无细节全链路查 trace找断点工具调用失败工具层查 schema、参数、工具可用性终端执行被阻断环境层查沙盒资源、安全策略、会话状态模型返回空模型层查上下文长度、超时、格式间歇性失败环境层/执行层查资源竞争、并发、时序结果回传丢失回传层查解析逻辑、记忆写入5.2 独家避坑经验别信单一错误码错误码是入口trace 才是真相。原始数据一定要存解析后的数据会丢信息原始返回是排查的命根子。环境层问题占比被低估很多人只盯模型忽略了沙盒和容器。复现不了就局部复现不要死磕完整复现分段验证更高效。错误码体系要持续迭代每次排查完把新发现的失败模式补进错误码或标记里让下次排查更快。5.3 关于错误码设计的建议如果你在做 Agent 平台错误码设计我建议遵循几个原则分层编码用前缀区分层级比如M开头是模型层T是工具层E是环境层。保留扩展位不要把所有位都用满留出扩展空间。关联 trace每个错误码都要能关联到具体 trace方便下钻。文档化错误码含义、常见原因、排查步骤都要写清楚减少沟通成本。6. 我踩过的几个真实坑第一个坑是把超时当模型问题。有次 Agent 批量失败错误码指向模型超时团队准备换模型。我坚持先看 trace发现模型其实很快就返回了慢的是后面的工具执行只是上游超时设置太短把工具执行的耗时算到了模型头上。调大上游超时后问题消失。这个坑让我记住超时归属要看 trace 的时间分布不能看错误码的字面。第二个坑是忽略环境层的间歇性。有个任务偶尔失败错误码是terminalBlocker。本地怎么都复现不了。后来查线上指标发现失败都集中在整点附近那段时间有定时任务在跑抢占了沙盒资源。这种问题不看时间维度的指标根本发现不了。第三个坑是原始返回没存。早期框架只存解析后的结果有次解析失败原始返回丢了只能猜。后来加了原始日志排查效率提升非常明显。这个改动成本极低但价值极高强烈建议所有 Agent 项目都做。第四个坑是错误码不迭代。有段时间同一个错误码对应好几种根因排查时每次都要重新分析。后来我们把常见根因拆成了更细的标记虽然错误码表变长了但排查速度快了很多。错误码体系是要养的不是一次设计就完事。7. 后续可以怎么扩展这套方法这套“从粗错误码到失败链”的排查方法本身是可以产品化的。我目前在做的一个方向是自动失败链还原给定一个错误码和 trace自动把链路各段的状态标出来直接告诉排查者“断在哪一段”。这需要把前面说的锚点埋点标准化然后用规则或小模型做归因。另一个方向是失败模式库。把每次排查的根因、现象、修复方式沉淀下来形成可检索的库。下次遇到类似错误码先查库命中就直接给排查建议。这个库越用越值钱是团队的知识资产。还有一个方向是错误码的语义增强。粗错误码之所以粗是因为平台不知道细节。但如果执行层、工具层能主动上报更细的状态平台就能在错误码里带上更多信息。这需要各层配合但长期看收益很大。我个人在实际操作中的体会是Agent 排查这件事方法论比工具重要观测能力比技巧重要。工具会换框架会变但“分段二分、锚点定位、原始数据留存”这套思路是通用的。把观测能力建好把错误码体系养起来把失败模式沉淀下来排查就会从“玄学”变成“工程”。最后分享一个小技巧每次排查完花十分钟写一份简短的失败链记录包括错误码、断点、根因、修复。坚持几个月你会发现自己对 Agent 系统的理解深度完全不一样了。这份记录比任何文档都值钱。
