Agent失败排查实战：从粗错误码到失败链

最近排查一个基于 Agent智能体的文档问答服务测试环境跑得很欢一上生产就不断有任务失败。监控面板上清一色的“Agent execution terminated due to an error.”点开详情也只是“模型请求失败”这种粗错误码。更诡异的是手动拿同一段 prompt 去调模型一切正常模型服务商的状态页也显示全绿。那天上午我们几乎所有人都下了一个结论模型又“抽风”了。可问题并没有因为“甩锅给模型”消失。后来我从“粗错误码”转向“失败链”的视角把一次 Agent 运行拆成若干环节逐段验证最后定位到的根因却是一个再普通不过的问题工具返回内容过长把模型生成 function call 参数的余量挤爆了输出在接近截断位置处被掐断下游拿到的参数残缺于是整个任务被框架捕获并包装成了那行通用错误。这篇文章就还原这次排查全过程并给出一个可以复用的排查框架遇到 Agent 失败时怎么从粗错误码一步步摸到真正的根因。文章主要写给两类人一是正在做 Agent 应用开发、被各种泛化报错折腾的人二是刚接触 Agent 项目、还不太清楚函数调用和工具编排内部链路的新手。看完你会发现——Agent 排查和普通后端排查最大的区别不是步骤更玄而是中间多了一条由模型输出、工具调用、上下文记忆共同组成的“隐藏链路”。1. 先还原现场粗错误码是怎么把我带进坑里的1.1 现象只给一排“任务终止”和一句“模型失败”当时我们的 Agent 走的是比较典型的 ReAct 循环接收用户问题由模型决定调用哪些工具工具返回结果后再由模型整理成最终答案。任务失败后平台侧返回的错误信息有两层外层是“Agent execution terminated due to an error.”内层是“模型请求失败”。这几乎等于什么都没说。我把当天失败的 200 多条任务拉出来做了个简单统计表现高度一致失败点落在模型请求阶段而且都发生在工具调用比较多的会话里。此时如果按传统后端思路去排查第一步肯定是看模型服务的调用日志。但我把调用日志翻出来后发现每次模型请求其实都已经发出去了有些甚至拿回了完整响应只是 Agent 框架把后续某个步骤的异常吞掉了统一包装成了“模型失败”。这里就暴露出一个关键认知Agent 框架的错误码经常是“聚合错误”它是框架对整条失败链的简化抽象而不是对真实故障点的描述。我们太把它当回事反而被它带偏了节奏。1.2 为什么框架更愿意给一个模糊错误码而不是具体原因理解粗错误码为什么存在有助于我们冷静下来。常见原因有三个第一异常被多层包装后丢失了上下文。Agent 的编排层通常会有很多嵌套调用工具执行器 catch 住异常后转成内部错误内部错误又被记忆管理模块再包一层最后到了统一出口只剩下“模型请求失败”。每包一层原始的 exception class、堆栈、甚至具体是哪一次的 tool_call_id 触发的都可能被丢掉。第二跨服务边界本来就拿不到细节。Agent 服务调用模型服务、模型服务调用工具服务、工具服务又去调外部 API……很多服务在设计时只允许透出最低限度的错误信息比如“422”“500”“超时”。这不是某个框架的毛病而是分布式系统的一种默认保守姿态。第三日志和追踪没接好。只要我们把 Agent 的每一步 request_id 或 session_id 漂亮地串起来粗错误码就能快速定位到具体服务。可惜多数项目初期只做了业务日志没有做全链路追踪所以到了排查时才发现“链条断了”。不过也别急着否定粗错误码。它至少帮我们划出了边界“问题发生在 Agent 内部而不是任务根本没进入系统”。我们需要做的是把这条边界往里再推一层从“错误码”走向“失败链”。2. 从错误码到失败链把一次Agent运行拆成七段2.1 失败链七段法先给错误定位定边界我自己常用的做法是先不理会错误码本身把一次 Agent 运行的路径完整列出来。我会分成七段输入入口用户 query 的接收、会话状态的恢复、上下文初始化。编排决策Agent 的规划机制ReAct、plan-and-execute、多 Agent 协作决定下一步做什么。模型请求把系统提示词、历史消息、工具定义、当前任务拼装后发给模型服务。工具调用模型返回 function call 后框架解析参数执行工具 API拿回结果。记忆装配把长期记忆、短期记忆、检索到的知识塞回新的上下文供下一轮模型调用使用。输出解析模型回复转成 JSON 或结构化结果校验是否符合预期。基础设施容器网络、DNS、端口、超时策略、WSL2/Docker 环境等横切因素。这个七段并不一定是严格流水线很多 Agent 框架会把记忆装配和模型请求合并但用来做“失败链排查”已经够了。核心思路是不要把一次失败看成单个节点的事而是看成一条数据链在某处断掉。七段法的作用是帮我们一个个排除而不是在第一段或最后一段上原地打转。2.2 三段式边界划分先证明“模型”到底有没有问题“模型请求失败”这一句粗错误码最容易让人直接冲去找模型服务商。我的建议是先做三段式边界划分第一段模型能力。把完整 prompt、工具定义、历史上下文原封不动地拿出去直接通过模型服务的 API 或调试页面复现。如果复现成功说明模型自身没毛病问题在 Agent 框架或工具侧。第二段工具能力。把失败任务里最后调用的几个工具单独抽出来不看 Agent 框架直接构造参数去调工具 API。如果工具本身响应正常说明问题出在模型生成参数和工具入参之间的“翻译”。第三段编排逻辑。写一个最小脚本只包含“模型→工具→模型”三步把同样输入喂进去。如果最小链路也失败再逐步加回记忆、历史、多轮逻辑。理解这个分层法后前面“模型全绿但 Agent 还是失败”的矛盾就好解释了模型没问题工具没问题但它们在 Agent 这条链上组合在一起之后出了问题。所以排查要从“单独能力”回到“整条链路”。3. 实操一次完整的失败链排查实录3.1 第一步让日志重新变成一条可追溯的链那批失败任务发生在夜间日志量很大。第一件事当然是去把日志查出来但我没有只查“错误”关键字而是按 session_id 拉出整段链路。具体做法在 Agent 框架的入口处确认 session_id / task_id 是否贯通如果没有临时开启 DEBUG 日志把每个环节的进入、离开时间打出来。用时间窗过滤出失败任务所在时段的全部日志不要只看 error 级别。因为真正有用的线索工具返回内容的长度、模型输出的最后几十个 token往往在 INFO/DEBUG 里。如果日志是 JSON 结构用 jq 做字段提取。例如jq select(.session_idxxx) | {ts, stage, message}很快就能把同一任务在几十秒内的所有阶段排成一条时间线。当时我拉完日志发现失败前最后一个工具调用居然执行成功了工具也返回了一大堆 HTML 片段接下来模型回复了一个残缺的 JSON参数列表在数组中间被硬生生截断。这个现象如果只看最终错误是永远发现不了的。3.2 第二步顺着时间线复现并记录每一次工具调用新的问题变成了为什么工具返回内容后模型会在生成参数时被截断我把 Agent 的时间线打印出来得到几个量化数据一次任务平均循环 35 轮每轮模型输入里包含完整对话历史。工具返回的 HTML 片段最长超过 1 万 token但工具结果的配置项里我们当时设置的“截断阈值”是 2000 token。2000 token 的截断不是问题问题在于截断发生在工具结果返回给模型前这会导致 Agent 下一轮模型的输入上下文被大段 HTML 填满而模型需要输出的 function call 参数本身需要足够空间。这里我又核对了一个常识模型在生成时经常需要预留 max_tokens比如我们配的是 1024。如果上下文已经超过模型的上下文窗口上限框架会按“截断策略”裁掉较早的历史消息裁掉历史消息还好但有时会把非常关键的“上一轮工具结果摘要”也裁掉模型就看不到工具返回的实际内容了。最终模型为了“自救”会开始生成缺字段的参数请求落到工具 API 上自然就变成 422 或参数缺失。第三步我专门做了验证把同一份 prompt 和工具定义直接调用模型内容不经过 Agent 框架时模型完全能生成正确参数。这说明问题不在模型能力而在“上下文装配策略”——工具结果过长把模型思考空间挤没了。3.3 第三步把模型请求报文原样拉出来比对这一步很关键也是很多人会跳过的一步我们应该把“Agent 实际发给模型服务的请求体”原样保存下来而不是事后重新拼一个“差不多”的请求。我在排查时给所有模型请求加了一层报文记录记录内容包括请求时间、request_idsystem prompt 的完整内容消息列表每一条的 role、长度字符数和 token 数工具定义列表模型侧的 max_tokens、temperature 等参数实际响应内容尤其是最后一个 token 是否完整拿到这些之后再跟“直接调用模型”的输入做 diff差距立刻暴露Agent 发的请求里最后一轮 user 消息竟然是被拼接过的工具 HTML长度占满了上下文窗口模型根本没有余量生成完整的参数列表。于是它在接近输出上限的地方被强制截断了。这里还有个很容易踩的细节很多工具结果不是模型自己截断的而是框架的字符串截断逻辑导致的。比如我们存工具返回结果时按“字符”截断但模型上下文按“token”计费一个中文字符可能占多份 token最终 token 数比我们预估的大好多倍。字符截断和 token 截断之间必须做一次换算或者直接用模型的 tokenizer 去数。3.4 第四步排查工具所在的环境问题DNS、端口、容器网络当 Agent 链路里调用了外部工具时失败链上还有一个“基础设施”环节不能漏。我们的 Agent 服务是容器化部署的Docker/WSL2 环境排查模型报文之后我还顺手查了工具服务的网络连通性。当时有几个任务失败得很随机表现是工具调用超时触发重试后整体流程就会乱掉。我按下面的顺序检查先确认端口监听是否正常ss -tlnp | grep port看容器端口有没有映射到宿主机。再看 DNS 解析是否稳定getent hosts service-name重试几次看返回的 IP 是否稳定。容器网络里如果 DNS 解析偶尔失败外部工具调用就会超时。看容器网络情况docker network inspect network、docker logs container --since time。WSL2 网络模式偶尔也会出现瞬时丢包尤其在重启机器后残留旧 IP 缓存时。检查是否有 IP 冲突在局域网部署场景下用ip neigh查看 ARP 表避免工具服务的请求被错误路由。最后我们发现工具服务所在的容器发生过一次 IP 重新分配但 Agent 服务里还缓存着旧 IP导致部分机器访问失败表现成间歇性超时。把它改成服务名解析并清理了 DNS 缓存后超时明显减少。这里再次印证失败链里的任何一段都可能埋雷不能只看模型报文。3.5 第五步修复与验证修复动作分三层第一层上下文治理。工具结果不再直接全文塞给模型而是先做结构化摘要保留原始结果的哈希或索引模型需要细节时再按需检索。这样既保住了上下文空间又不至于丢失关键信息。第二层工具调用参数校验。模型返回的 function call 参数必须先做 schema 校验缺字段就触发“补全重启”机制而不是直接抛给工具 API。补全重启的成本远低于整条任务失败的代价。第三层错误码分级。我让框架在出口处不再简单输出“模型请求失败”而是按阶段输出结构化错误码比如 tool_timeout、tool_output_truncated、context_overflow、function_args_invalid、model_request_failed。每个码后面必须带 request_id 和阶段名。修复后我做了连续 50 轮的回归跑测成功率从 76% 提升到 98%剩下的 2% 大多是外部服务偶发 5xx而且现在能根据错误码直接定位到是哪个工具有问题不用再翻半天链路。这一步让我特别有感触把粗错误码变细不是为了好看而是为了让下一次失败可以被系统自动路由。4. 常见误区、速查表与工程化沉淀4.1 粗错误码 → 排查方向速查表我把常见的“粗错误码”和首选排查方向整理成一张表方便直接抄作业错误码/报错容易得出的错误结论建议优先排查方向422 Unprocessable Entity“模型收到了坏请求”模型生成的 function call 参数、工具输入 schema、上下文里被塞入了非预期字符500 Internal Server Error“模型服务挂了”Agent 服务自身未捕获异常、上游网关、工具服务崩溃502 Bad Gateway / 503“网络问题”Agent 到工具服务、Agent 到模型网关之间的负载均衡或网关状态服务限流504 Gateway Timeout“模型太慢/超时”工具执行时长、模型 max_tokens 过大、外部 API 响应慢、重试策略失效Agent execution terminated due to an error.“流程被终止原因不明”框架全局异常捕获重点查最后 23 步工具调用和输出解析模型请求失败泛化文案“模型不行”把请求报文原文存下来做 diff核查上下文长度、token 截断、参数生成截断间歇性失败“偶发不好查”DNS 解析、容器 IP 缓存、端口冲突、旧进程占用、限流配额这张表不是标准答案作用是快速收敛方向。真正常用的不是“查表”而是表背后的链路段位划分再加上“保留原始报文”的习惯。4.2 四个特别常见的误判场景第一个误判模型服务商状态页全绿就觉得模型没责任。状态页只是宏观情况不代表你的具体请求没问题。我自己就遇到过因为触发内容过滤而返回 4xx状态页永远是绿的。所以该做的是拿原始请求复现而不是看状态页。第二个误判只用最后一次报错信息不看失败链。Agent 失败往往不是瞬时发生而是一步步恶化的。比如第一轮工具返回内容就已经过大到第二轮模型才开始生成错误参数第三轮才正式报错。只看最终报错完全无法定位。第三个误判优先怀疑模型逻辑忽略基础设施。工具调用、记忆检索、模型请求之间的网络和环境问题经常被忽略尤其当项目跑在 WSL2/Docker 组合环境下。DNS 的瞬时失败、容器的 IP 重新分配、端口被占用这些都会悄悄爬上失败链。第四个误判用重试代替排查。偶发失败偶尔重试能恢复但重试次数太多会让整条 Agent 流程的状态变乱尤其是工具调用本身有副作用时比如已经扣了钱的任务重试造成重复扣款。重试必须是带了退避和幂等保护的而不是把同一份坏请求再发一遍。4.3 把这次教训固化成 Agent 工程规范从这次排查之后我给自己团队定了几条带强制性的工程规范第一所有 Agent 任务必须生成可关联的 trace_id从任务开始到结束经过的模型请求、工具调用、记忆读取、输出校验全部带上它。做不到全链路追踪至少也要把 trace_id 写进业务日志和模型网关日志。第二错误码必须带阶段前缀。内部代码里逐步重构返回格式tool_timeout:get_weather:request_idxxx。这样错误码本身就是一份“故障摘要”而不只是“又失败了”。第三工具结果要分层使用。粗结果、摘要结果、原始结果分别放不同位置模型默认只吃摘要必要时再加载原始内容。这个设计不仅解决上下文窗口问题也明显降低调用成本。第四失败样本要入库。把每次失败任务的 session_id、请求报文、上下文大盘、工具返回快照、模型响应结尾都存成回归集每次改版后跑一遍。这就是 Agent 项目的“故障演练场”。这些规范看起来会花一些开发成本但每一个都对应着真实踩过的坑。做 Agent 开发越久越会觉得与其让线上任务去暴露问题不如让工程规范把问题挡在发布之前。5. 最后分享三个能救命的排查小习惯最后说几个我自己实打实验证过的小习惯供参考。第一个习惯Agent 框架的错误日志只信三分原始报文信七分。现在我再看到“模型请求失败”会直接要求日志模块把真实发送的 prompt、上下文长度、响应末尾 20 个 token 一起打出来。正因为那次失败里模型响应是被硬生生截断的所以“末尾 20 个 token”往往比中间内容更能说明问题。第二个习惯做一个“最小 Agent 复现脚本”。它不用完整实现框架只要能完成“输入→模型→工具→模型→输出”五步闭环即可。遇到任何泛化报错先拿最小脚本跑一遍很多问题在完整框架里千头万绪在最小脚本里一眼就能看出来。第三个习惯给 Agent 加一条定时健康检查任务。我每天会让一个测试任务带着固定问题去跑故意制造轻微的工具超时或长文本输入看它能不能正确自愈。这不是无聊的监控而是用最低成本把失败链中最脆弱的几段暴露在白天。自从加了这条巡检我半夜被叫醒的次数确实少了很多。排查 Agent 失败最难的不是哪个环节的代码复杂而是我们太容易被一个粗错误码牵着走。把视角从“某个环节报错”切换到“整条失败链”把工具调用、上下文装配、基础设施这些平时不太起眼的环节都摆到桌面上大多数疑难杂症其实都能在半小时内锁死范围。希望这次从粗错误码到失败链的完整复盘能让你下次排查时少踩几个坑。