把 Agent 的失败全部算到模型头上这事我干过后来被打脸了。那阵子我们的 Agent 应用上线不到两周群里开始陆续有人反馈任务经常跑到一半就失败错误码清一色是那种特别粗的“模型调用超时”。于是所有人条件反射地开始查模型服务运维说模型侧监控一切正常研发说参数配置没问题前端说错误信息就那么一行。最后大家互相看一眼得出一个心照不宣的结论大模型不稳定呗等它自己恢复。这话听起来没毛病但问题在于你根本拿不出证据证明是模型的问题。后来我花了整整两天把一条粗错误码从用户请求入口一路拆到容器底层的网络栈才发现真正的根因跟模型半毛钱关系都没有。它藏在三件事的交叉点上JVM 内存暴涨引发的频繁 Full GC、内网 IP 冲突导致的连接抖动、Agent 编排层上下文失控引发的令牌超限。模型从头到尾都是清白的却差点背了口大锅。这篇就记录一下这次“从粗错误码到失败链”的完整排查过程。适合正在做 Agent 应用、AI 中间件或者被模型报错折磨得想摔键盘的同学参考。核心想法很简单Agent 失败不是单点故障而是一条链。光看最外层的错误码永远只能看到冰山一角。1. 症状与第一反应为什么“模型又挂了”最容易脱口而出1.1 那条笼统的错误码到底长什么样我先说下这次出问题的系统形态。我们做的是一款企业内部的 Agent 助手架构不算复杂用户在前端发起任务后端有一个 Agent 编排进程负责规划步骤、调用工具、组装上下文然后再统一走一个模型网关去请求大模型 API。整个链路里有若干个内部服务错误信息最终会聚合到一个统一的响应结构里返回给前端。这次线上暴露出来的错误码长这样{ code: ERR_AGENT_MODEL_TIMEOUT, message: model call timeout after 60000ms, trace_id: 7f3a9e2c, task_id: t-20250115-1024 }你只看这个结构会觉得信息量还挺大有错误码、有超时阈值、有 trace_id。但如果把这个响应往前端一抛用户看到的就是“模型调用超时”六个字。问题恰恰出在这。这个错误码确实记录了结果但它把整个链路压缩成了一个点。它告诉你“模型调用超时了”但没告诉你是从哪儿调用的模型Agent 编排进程还是其他服务超时发生在那一段是编排进程等网关超时还是网关等模型服务商超时在超时之前链路里已经发生了什么其他异常trace_id 到底能不能贯穿所有日志说白了这是一个“粗错误码”。它把多环节、多原因的长链路故障压缩成了一个面向用户的黑盒结论。1.2 归因误区看到“模型超时”你只是在看最终结果归因到模型几乎是一种条件反射。原因很现实模型是黑盒内部机制不透明服务状态波动也确实存在所以一旦报错大家下意识就觉得是它不行。再加上错误码本身就是这么设计的所有异常最终都被包装成了“模型调用超时”这一句话那你顺着错误码走必然走到模型门口。但这里有个底层逻辑上的坑在一个多跳链路里任何一环变慢最终都会表现为“下游超时”。我打个比方。你去餐厅点餐等了四十分钟服务员跟你说“后厨出餐太慢了”。这听起来是厨师的问题但可能是传菜员在走廊上磨蹭了半天也可能是收银台在排队阶段就卡住了菜根本还没下单到后厨。后厨只是整条链路里最后背锅的那一环。模型服务就是这样。Agent 编排进程里只要有一个环节拖时间比如工具调用迟迟不返回或者内存抖动导致线程卡顿最终到达模型网关的时机就会延后前端看到的仍然全是“模型超时”。这类错误码永远只会告诉你末端发生了什么不会告诉你是中间哪一截在拖。所以我把第一阶段的教训总结为一句话看到粗错误码先别急着下结论把它当成一次案发现场而不是最终的判决书。2. 第一刀先给模型侧“验明正身”2.1 5分钟看完模型侧监控先排除最大嫌疑排查的第一步不是去翻自己代码而是先看模型侧到底有没有问题。这一步其实是帮模型“验明正身”花不了多长时间五分钟足够。我们当时做的是这么几件事第一拉出模型网关的日志按 trace_id 找到这次失败请求对应的时间点。样本里那些报错集中在上午 10 点到 11 点之间记住这个时间窗口。第二统计模型服务商侧这段时间的响应时间分布。我们要的不只是平均值而是 P95 和 P99。如果模型服务商侧 P95 都在几秒以内P99 也没有明显尖刺说明模型侧基本排除了“服务端压力过大”的嫌疑。第三对比失败率曲线。把 Agent 任务失败的时刻点和模型侧的错误率曲线画在一起看有没有相关性。我们当时拉出来之后发现上午那个时间段模型侧的 5xx 几乎为零响应时间也相当平稳P95 稳定在 6 秒上下没有任何飙升。这几项合在一起的结论很明确模型侧服务端本身没有异常。既然模型服务商没毛病那问题大概率出在“我们怎么调用它”这件事上。2.2 超时是谁的视角拆开“调用超时”这层壳粗错误码里那句话是“model call timeout after 60000ms”。这里有个关键问题需要搞清楚这 60 秒是从哪里算到哪里的我当时去翻了编排进程的配置发现这条超时是编排进程到模型网关的 read timeout也就是编排进程发完请求之后等待网关返回响应最多等 60 秒。而网关到模型服务商的那一段是网关自己的超时配置单独设置为 30 秒。这就有意思了。假设网关到模型服务商正常只需要 6 秒但网关前面排了一堆请求编排进程请求排队等了 50 多秒才被网关处理那你最终看到的依然是“model call timeout after 60000ms”。超时这个词本身没骗人但它的归属完全取决于你测量的是哪一段。所以排查的第一步是把“超时”这个模糊概念拆清楚谁在等谁等待的计时起点在哪终点在哪。只有把这个拆开你才不会对着错误码里的 60000ms 一头雾水。为了验证到底卡在哪一段我们在编排进程代码里临时加了几个打点把模型请求的各个阶段耗时单独记录下来看是“请求发出前耗时”还是“等待响应耗时”占据了主要时间。这一步是后面所有排查的分水岭。2.3 把错误码升级成“失败日志上下文”当时源码里对错误处理写得非常草率就一行log.error(model call failed, code{}, e.getCode());然后什么上下文都没存。只有一个错误码和一条报错时间想凭这个定位根因等于手里只有一张写着“你生病了”的化验单具体什么病完全没有信息。排查的时候没办法只能走比较笨的路子把那个时间窗口内编排进程的所有 debug 日志全部捞出来用 trace_id 做过滤把这条失败请求的前后五分钟日志拼成一整条时间线。也是这样我才第一次看清这条请求里光是内部知识库工具的调用就花了 28 秒。这里要讲一个非常实用的经验错误码是入口日志才是地图。如果你系统里的错误处理只有一行 log.error 而没有 context总有一天你会被自己坑死。后面我会专门讲怎么把埋点做起来先继续顺着这条时间线往下挖。3. 失败链全景从请求入口到容器底层3.1 这条链上到底有哪些节点纠正一个常见的思维误区Agent 任务的“失败链路”不是从 Agent 编排进程到模型这样一跳就结束了。真实的路径要长得多我把这次实际链路展开一下用户在前端页面点击提交前端把任务请求发给后端 API 网关。网关鉴权通过后把请求路由给 Agent 编排进程。编排进程启动规划根据用户意图判断需要调用哪些工具。工具调用阶段编排进程请求内部知识库、搜索服务或业务 API。工具返回结果后编排进程把结果拼进上下文 messages组装成一次新的模型调用请求。请求到模型网关网关做鉴权、限流、负载均衡转发给模型服务商。模型服务商返回结果网关回传编排进程解析结果再决定是否进入下一轮工具调用。整个多轮调用全部完成编排进程把最终结果返回给前端。这还只是逻辑链路。往下看每一跳都跑在容器里容器又跑在节点上节点下面还有网络。任何一个基础设施层的问题都会以“请求变慢”“连接被重置”“进程卡死”的形式向上传导最后汇聚成一个粗错误码。3.2 链路每一环的“嫌疑点清单”我把每个环节可能出问题的地方列成一张表排查的时候逐项对照效率会高很多环节典型嫌疑排查手段用户端参数构造、任务重复提交前端日志、网关访问日志Agent 编排层上下文膨胀、工具调用死循环、重试风暴debug 日志、链路追踪模型网关限流排队、鉴权过期、超时阈值设定网关访问日志、监控面板模型服务商服务端负载、输入超限、输出异常厂商侧监控、错误码明细容器层内存占用高、Full GC、线程池打满jstat、jmap、jstack网络层IP 冲突、DNS 解析异常、连接被重置dmesg、arp、连接统计你发现没有这里面“模型服务商”只是七条嫌疑里的一条。如果一上来就把所有精力放在最后一条上前六条全都躲过了。而这次的实际根因恰恰出在最容易被忽略的后两条。3.3 关键拿到贯穿全程的 request_id失败链才有价值排查多跳系统最怕一种情况每层都有日志但每层各自为政没有同一个请求 ID 串起来。你如果靠时间去猜哪条日志对应哪次请求在低并发下还能凑合一旦并发一高多组日志混在一起根本没法拼。当时我们的编排进程是有 trace_id 的但问题在于 trace_id 没有透传到工具调用和网关层。工具调用日志里只有工具名和耗时没有关联字段网关日志里有自己的 request_id但跟编排进程的 trace_id 对不上。这导致我在第一轮排查时只能靠时间戳去对效率极低。后来我们做的第一个改造就是强制在网关层为每个请求生成 request_id并且在回传响应时把上游模型服务商返回的 request_id 一并透传回来。在工具调用环节把编排进程的 trace_id 放进自定义 header 里让所有下游服务都能记录这个字段。日志里有了贯穿的 ID失败链才算真正的链否则只是断成几截的碎片。所以在复盘这件事的时候我经常说排查 Agent 失败第一步不是看模型而是确认日志能不能支持你去看链。不支持的话先把链路打通再谈其他。4. 实操记录五个嫌疑点逐一排除4.1 嫌疑一Agent 编排层的上下文膨胀与工具调用拥堵拿到含 trace_id 的完整时间线之后第一个异常的轮廓浮现出来了。在一次失败任务里编排进程为了回答用户的问题连续调用了 7 次内部工具。每一次工具调用返回的结果都被完整地拼进了 messages 数组没有做任何截断或摘要。调用到第 4 次的时候messages 已经膨胀到了 2 万多 token到第 6 次的时候逼近 3 万。而模型网关那边配置的上下文长度上限是 32k一旦话题再拉扯一下很可能直接触发上限。更要命的是工具调用本身的耗时也异常。日志里显示某一次知识库搜索的耗时高达 28 秒而正常应该在 2 秒左右。虽然这个问题的根因在后面网络层才揭晓但在当时仅“工具调用耗时过长”这个事实就已经让下一次模型请求的启动时间大幅推迟。我看了一下线程池的状态发现大量线程阻塞在等待工具调用返回。这导致后续进来的新任务也只能排队形成了一个典型的拥堵循环工具调用越慢请求积压越多积压越多线程越不够用线程越不够用模型请求发出越晚最终表现为超时。这次排查看下来至少有一半的锅要分给编排层的设计缺陷没有对工具结果做上下文管理也没有限制单任务的工具调用轮数上限。我后来回忆时想到这其实是很多 Agent 项目通病框架本身不会主动帮你裁剪历史消息开发者不自已在代码里做限制早晚爆掉。4.2 嫌疑二网关层的 422 与限流排队把编排层的日志理清楚之后我又去翻了模型网关这一段的访问日志。然后发现一个之前被忽视的现象在失败窗口内有不小比例的请求直接返回了 HTTP 422。422 在模型网关这个语境下通常意味着“语义上无法处理”最常见的原因是输入超出了模型支持的最大上下文长度或者某些参数格式非法。翻看具体请求体之后确认就是 messages 太大触发了上下文超限校验网关直接把请求拒了根本没转发给模型服务商。这会产生一个连锁后果Agent 编排进程收到 422 之后第一反应是重试。而重试的时候如果代码把失败信息也追加进了 messages上下文又变大了一圈下一次 422 的概率更高。我当时在代码里看到异常处理逻辑确实把异常详情作为一条 system 消息塞回了 messages。这一步操作直接给“死循环重试”加了油门。另外模型网关还配置了限流阈值。虽然不是这次失败的主要诱因但在流量高峰时段限流会导致请求在网关排队。网关默认排队超时是 30 秒超时就直接断开——从编排进程的视角看这也是一次“模型调用超时”。我把网关的限制调高一些同时给编排层的重试策略加了退避参数这一层的影响就基本可控了。4.3 嫌疑三Java 容器内存暴涨与 Full GC 停顿把编排层和网关层的嫌疑排除掉一部分之后还有一个硬骨头没啃下来为什么工具调用会正常情况下的十几倍那么慢我开始怀疑编排进程所在的 Java 容器本身出了问题。查监控面板时看到这个容器的 RSS 内存居高不下已经接近 Pod 上限。JVM 堆内存使用率一直在高位徘徊GC 日志里 Full GC 频繁到我有点不敢相信几乎每隔几十秒就一次而且单次停顿时间达到数秒级别。为了确认我在现象复现期跑了一条命令jstat -gcutil pid 5000输出显示 Full GC 的次数在持续增长而且每次 Full GC 耗时要占掉 3 到 5 秒。GC 停顿期间整个进程的线程全部暂停模型中转、工具调用调度也跟着停摆。几秒的暂停穿插在 28 秒的工具调用耗时里完美解释了那种“卡但不彻底死”的诡异表现。用 jstack 抓线程栈进一步确认发现不少线程卡在向工具服务发送 HTTP 请求后的等待状态。而等待时间被 GC 停顿拉长了。我随后用 jmap 做了堆 dump分析后看到大量工具返回结果对象被缓存在内存里没有被清理它们都是那些超大 messages 和工具调用的产物。到这里内存问题的机理已经清晰上下文膨胀导致缓存对象大量存活缓存不设上限导致堆被填满堆满导致 Full GC 频繁GC 停顿导致工具调用和模型请求全线变慢。这跟“模型本身不稳定”没有半点关系。4.4 嫌疑四IP 冲突与连接重置内存问题虽然解释了“为什么慢”但还没解释“为什么工具服务本身会慢”。接下来我决定把视野放到编排进程之外的依赖服务上。工具调用的目标服务跑在另一个节点上按监控看它的负载很低不该出现 28 秒的超慢响应。于是我登录到目标服务所在节点去看网络状态翻 dmesg 时终于看到了那条关键日志Duplicate IP address detected for 10.0.13.57, received from 00:1a:2b:3c:4d:5e看到这条日志一切就说得通了。我们的内网环境里有两个容器节点因为网络配置问题拿到了同一个 IP 地址。冲突发生之后ARP 表会在两个 MAC 地址之间来回横跳导致访问该 IP 的请求在极端情况下会被发给错误的网卡连接要么超时要么直接 Connection reset。工具调用的 28 秒耗时一部分是被 GC 停顿放大的更底层的来源其实是网络层这个 IP 冲突。排查确认的方法很简单在冲突节点上执行arp-scan --interface eth0 --localnet扫描结果里果然出现了同一个 IP 对应两个 MAC 地址的记录。再结合节点上的网络插件配置发现是静态 IP 分配策略与 DHCP 范围重叠导致的冲突。修复起来不难调整地址分配策略重启相关节点的网络问题就消失了。这条线索不到半个小时就确认了但它藏得特别深。如果没有前面的链路日志支撑我根本不会把“Agent 任务失败”跟“内网 IP 冲突”联系起来。4.5 嫌疑五模型侧“正名”最后一个环节是给模型侧“正名”。我做了两组验证第一组把排查窗口内模型服务商侧的监控数据再度拉出来确认这段时间服务商侧 P95 响应时间始终在 6 秒上下无 5xx 错误也无明显的限流事件。第二组绕开编排进程直接用脚本请求模型网关随机发起 100 次真实业务请求全部成功平均耗时 5 秒多。这组实验结果说明一件事从模型网关到模型服务商这一段从头到尾都是健康的。真正拖垮模型调用的是前面的编排层、容器层和网络层。它们把一次原本只需 6 秒的模型请求硬生生拖成了 60 秒超时。这也是整篇最关键的一句话模型是清白的但错误码说它超时了。错误码没有故意冤枉它只是因为它站在链路末端前端的每一分延迟都由它来表现。排查这类问题的核心就是不要被末端结论带走而要往前翻链路的每一环。5. 从问题到机制把失败链埋点埋进代码里5.1 把粗错误码改造成“外粗内细”的两级结构这次排查结束后我们做的第一件事就是重构错误码体系。核心思路是“对外保持粗对内保持细”。对外前端用户和调用方仍然看到粗粒度的错误码比如 ERR_AGENT_MODEL_TIMEOUT这样 UI 层不用大改。但对内日志和监控里必须记录细粒度的内部错误码把真实失败环节标出来。当时我们设计了一批内部 detail_code外部错误码内部 detail_code触发条件ERR_AGENT_MODEL_TIMEOUTCONTEXT_OVERFLOW上下文 token 超限同上GATEWAY_429_LIMIT网关限流排队同上JVM_FULL_GC_LONGFull GC 停顿超过阈值同上NET_CONNECT_RESET底层依赖连接被重置同上MODEL_SIDE_ERROR模型服务商返回错误每次捕获异常时代码会把内部 detail_code、耗时、请求 ID、关键上下文摘要一并写进结构化日志。这样一来下次线上再出问题只要看日志里的 detail_code就能直接定位到具体环节不用再从头猜。5.2 链路追踪与告警维度改造另一个重点改造是链路追踪。当时我们还没上 OpenTelemetry 这类完整的可观测性框架只是利用 slf4j 的 MDC把 trace_id 自动注入到线程上下文里让同一个请求的所有日志自动带上这个标识。下游工具调用则通过自定义 header 把 trace_id 传递过去确保每一跳都有迹可循。这一步是纯代码层面的改动成本不高但对于后续排查的效率提升是翻倍的。以前拼一条时间线要手动翻十几分钟日志现在按 trace_id 一查所有环节的日志按时间排出来一目了然。告警维度我也顺手改了。以前我们只看“模型失败率”这个指标等于只看末端结果。后来改成按环节统计失败占比比如“工具调用阶段慢请求占比”“网关 422 占比”“GC 停顿超阈值千分比”。任何一个环节异常都能在告警里暴露出来而不是等它最终汇聚成一个粗错误码。5.3 排查顺序建议一套可复用的“先粗后细”流程经历过这次事件之后我总结了一套 Agent 类故障的排查顺序按照从执行成本最低到最高的排列先看模型侧监控确认服务端有没有问题这一步通常五分钟就能出结论。再翻网关访问日志看有没有 422、429 这类非超时类错误排除输入超限和限流。然后深度查编排层日志拼时间线定位请求发出前的等待时间。接着查容器指标和 JVM 状态确认 GC 和内存没有异常。最后查网络层重点看 dmesg 和 ARP 表排除 IP 冲突、路由异常等隐蔽问题。这个顺序的核心逻辑是先排除最容易验证的再把难度最高的网络层留在最后。很多人在第一步和第五步之间反复横跳结果查了半天还在原地打转。6. 常见问题与避坑6.1 几个高频问题的速查答案排查 Agent 故障时下面这几个问题几乎每次都会被问到我直接给结论为什么模型侧监控正常Agent 却总失败因为模型只是链路最后一跳。编排逻辑、工具调用、容器状态、网络质量任何一环变慢都会以模型超时的形式暴露。模型侧正常恰恰说明问题在它的上游。为什么重启容器之后能好一阵子大概率是内存或连接层面的问题。重启清空 JVM 堆内存重建网络连接相当于给系统强行止血但根因没消除过一段时间会复发。为什么测试环境一切正常线上量一上来就崩因为并发增加导致线程池排队、缓存膨胀、Full GC 加剧多个问题在压力下串联。测试环境没有流量根本触发不了这些临界条件。为什么错误码这么粗早不暴露晚不暴露因为之前配置的日志级别太高异常信息被吞了。出问题时只有一行粗错误码存留下来其余细节全被截断排查自然无从下手。6.2 我踩过的几个大坑希望你绕开第一个坑一看到“模型超时”就直接去问模型服务商。那个下午我们跟服务商来回对了好几轮工单对方反馈服务端无异常然后我们才回头查自己的链路。白白浪费了半天时间正确做法是先拉自己这边的监控数据确认是不是自己的锅再去对外求证。第二个坑排查时忘了看时间线把不同时段的事件当成因果关系。有一阵子我把凌晨的 GC 日志和白天的失败请求混在一起分析差点得出一个完全错误的结论。后来强迫自己把所有事件按时刻全部排列才理清真正的先后关系。第三个坑在内存高的时候直接重启容器。有个同事觉得重启一下就能继续观察结果堆内存释放了排障的一手证据也没了。如果你怀疑内存问题先跑 jstat、jmap dump保留堆现场再决定要不要重启。第四个坑只看平均值不看长尾。当时模型服务商侧平均耗时只有 4 秒让我一度以为完全没问题直到拉出 P99 曲线才发现高负载时段确实有尖刺。好在这个尖刺没有超过超时阈值否则这次排查的方向又要多绕一段路。6.3 一句话的排查心法把错误码当成起点别当成终点。你拿到任何一条粗错误码先问三个问题它是在哪儿产生的它描述的是哪一段链路它上游还有哪些环节会把它触发出来这三个问题都回答清楚了再开始动手查。否则就是拿着一张“病人发烧”的诊断单在不知道感染源的情况下乱开药。我个人在这次排查中最大的感受是Agent 这个领域真正难的不是写编排逻辑也不是调模型参数而是当失败发生的时候你能不能快速定位它到底死在链路哪一环。模型是黑盒天生容易背锅错误码是粗的天生容易误导。但只要你肯给自己留足观测的抓手——trace_id、结构化日志、按环节打点——大多数看起来很玄学的失败最后都会落到一个非常具体、甚至有点不起眼的根因上。我这次最后的根因是 IP 冲突加 JVM 内存膨胀加上下文失控三个问题叠在一起没有一个是模型本身引发的。希望这次从“粗错误码”到“失败链”的记录能让正被 Agent 失败折腾的同学少走几步弯路。总之一个原则先看链路别急着甩锅。
