1. 为什么“模型背锅”是 Agent 排查里最常见的误判做 Agent 开发这几年我见过太多团队在故障复盘会上把问题一股脑推给模型效果不好说是模型能力不行任务中断说是模型幻觉工具调用失败说是模型没理解意图。结果换了一轮又一轮模型问题依旧。真正的原因往往藏在模型之外——一个被吞掉的错误码、一次超时后没有回收的会话、一个在沙盒里悄悄退出的子进程。Agent 和传统后端服务最大的区别在于它是一条多跳的执行链。用户一句话进来中间要经过意图解析、规划、工具选择、参数拼装、外部调用、结果回填、再规划最后才输出。这条链上任何一环出问题最终表现都可能是“Agent 答错了”或者“Agent 卡住了”。如果你只盯着最后一环的模型输出等于在错误的楼层找钥匙。我印象很深的一次排查某个 Agent 在调用终端工具时频繁失败日志里只有一句agent execution terminated due to error.。团队第一反应是模型规划能力弱准备换更大的模型。我坚持先把错误码打全结果发现底层返回的是ssl_get_error返回 1也就是 SSL 层在握手阶段就被中断了。这跟模型一点关系都没有是出口网络策略变更导致的。如果当时真换了模型钱花了问题还在。所以这篇内容我想聊的核心就一件事把 Agent 的失败从“一个粗错误码”还原成“一条失败链”。适合正在做 Agent 开发、Agent 部署测试、或者被线上 Agent 稳定性折磨的工程师。不管你是刚入门 Agent 学习路线的新手还是已经在搭 Agent 框架的老手这套排查思路都能直接抄。2. 从粗错误码到失败链Agent 排查的底层思路拆解2.1 粗错误码为什么必然存在又为什么必然不够用先说清楚一个事实粗错误码不是谁偷懒它是分层架构的必然产物。Agent 通常跑在应用层下面压着框架层、运行时层、操作系统层、网络层。每一层出错向上传递时都会做一次“语义压缩”。底层可能是ECONNRESET到了框架层变成tool_call_failed到了应用层就只剩agent execution terminated due to error.。这种压缩对用户友好对排查是灾难。因为它把“哪一层、哪个组件、什么原因”三个关键信息全丢了。你要做的第一件事就是在每一层边界上把原始错误码截留下来而不是让它一路被覆盖到顶层。我通常会在 Agent 的执行器里加一个错误上下文对象结构大概是这样class AgentErrorContext: def __init__(self): self.trace_id None # 全链路追踪 ID self.step None # 当前处于哪一跳 self.tool_name None # 调用的工具名 self.raw_error_code None # 底层原始错误码 self.raw_message None # 底层原始消息 self.retry_count 0 # 已重试次数 self.elapsed_ms 0 # 本跳耗时关键在于raw_error_code和raw_message这两个字段它们必须在最靠近故障点的地方被写入之后无论上层怎么包装都不允许被清空。这样你拿到的就不再是一个孤零零的粗错误码而是一个带上下文的失败节点。2.2 失败链的三个维度时间、调用、状态一条完整的失败链我习惯从三个维度去还原。时间维度这一跳从发起到失败花了多久是秒级失败还是超时失败秒级失败通常是连接被拒、参数错误、权限不足超时失败则要看是网络慢、下游卡、还是自己死锁。这两个方向的排查路径完全不同。调用维度失败发生在第几跳是第一次工具调用就挂还是跑到第五跳才挂如果是后者要重点看前几跳有没有留下脏状态比如没关闭的文件句柄、没释放的锁、没清理的临时目录。状态维度失败时 Agent 的内部状态是什么规划队列里还有没有待执行的任务记忆里有没有写入半截的数据沙盒进程是活着还是已经退出这三个维度交叉起来基本能定位到具体组件。2.3 为什么必须区分“模型失败”和“链路失败”这是整篇内容最想强调的一点。模型失败的特征是错误发生在推理阶段输入输出都在模型边界内重试同样的输入大概率得到同样或类似的输出。链路失败的特征是错误发生在模型边界之外重试可能成功也可能失败取决于外部环境。区分方法很简单把模型调用单独隔离出来做对照实验。同样的 prompt、同样的上下文直接调模型 API如果稳定成功那问题就不在模型。我见过太多案例隔离之后发现模型侧成功率 99%而整条 Agent 链成功率只有 60%那 39% 的差距全在链路上。提示不要用“换个模型试试”作为第一排查手段。它成本高、周期长而且会掩盖真正的链路问题。先隔离再定位最后才考虑模型替换。3. 核心细节解析错误码、失败链与 terminalBlocker 的实操要点3.1 常见错误码的语义分层与快速定位错误码不是拿来背的是拿来分层的。我把 Agent 场景里高频出现的错误码按层归了个类方便你看到码就知道往哪查。错误码/现象所属层典型原因排查方向ssl_get_error返回 1网络/安全层握手被中断、证书或策略问题检查出口策略、证书有效期ECONNRESET网络层对端强制关闭连接下游服务健康、连接池配置ETIMEDOUT网络层连接或读写超时超时阈值、下游响应时间EACCES/ 权限拒绝系统层文件或端口权限不足运行用户、目录权限ENOENT系统层路径或可执行文件不存在沙盒挂载、工作目录422应用层参数校验不通过工具入参 schematool_call_failed框架层工具执行异常看被包装的原始码agent execution terminated应用层顶层兜底回溯完整失败链这张表我建议你贴在自己项目的排查文档里。看到ssl_get_error就别去查模型看到422就别去查网络方向对了效率差十倍。3.2 失败链的埋点设计让每一跳都留下证据埋点不是越多越好是要在关键边界上留。Agent 执行链上我一般埋五个点任务入队、规划完成、工具调用前、工具调用后、结果回填。每个点记录 trace_id、step、时间戳、状态。工具调用前后这两个点尤其重要因为它们夹住了最容易出问题的那一段。调用前记录入参和工具名调用后记录返回码、耗时、返回体大小。如果调用后这个点没打出来说明进程在调用中途就没了那问题大概率在沙盒或运行时。def call_tool(tool_name, params, ctx): ctx.step 1 log_point(tool_call_before, ctx, extra{tool: tool_name, params: params}) try: result executor.run(tool_name, params) log_point(tool_call_after, ctx, extra{code: result.code, size: len(result.body)}) return result except Exception as e: ctx.raw_error_code getattr(e, errno, None) ctx.raw_message str(e) log_point(tool_call_error, ctx) raise这段代码的价值在于无论上层怎么包装异常raw_error_code和raw_message已经被固定下来了。事后你拿 trace_id 一查整条链清清楚楚。3.3 terminalBlocker被忽视的“静默杀手”terminalBlocker这个词在热词里出现我觉得很贴切。它指的是那种不报错、不退出、但也不干活的阻塞状态。Agent 卡住的时候日志里往往什么都没有因为进程还活着只是卡在某个等待上。常见的 terminalBlocker 有几类等待一个永远不会返回的 stdin、等待一个已经死掉的子进程、等待一个被占用的锁、等待一个已经断开的 socket 的读事件。它们的共同点是没有错误码只有沉默。排查 terminalBlocker 的核心手段是主动探测而不是被动等日志。我通常会在 Agent 执行器里加一个看门狗每隔固定时间检查当前 step 的耗时超过阈值就 dump 一次调用栈。# 快速查看某个进程当前卡在哪个系统调用 cat /proc/pid/stack # 或者用 strace 跟踪注意只在测试环境用 strace -p pid -f -e tracenetwork,read,write注意strace对性能有影响线上慎用。生产环境优先用看门狗加调用栈 dump或者用gdb的 batch 模式抓一次现场。3.4 沙盒与运行时Agent 特有的故障高发区Agent 和普通服务不一样的地方在于它经常要在沙盒里跑代码、跑命令、跑子进程。沙盒带来隔离性的同时也带来了一堆特有的坑。比如 Docker 容器里的 ROS2 环境micro-ROS agent 和容器网络配置稍有不对就会出现“容器活着但 agent 连不上”的情况。再比如 Windows 上装 Docker Desktop虚拟化和 WSL2 配置不对容器起不来报的错还特别含糊。这些都不是模型问题是运行时问题。我的经验是把沙盒的健康检查做成 Agent 启动的前置条件。启动 Agent 之前先跑一遍沙盒自检——能不能创建进程、能不能读写工作目录、能不能访问需要的端口、子进程退出码能不能正确回收。自检不过直接拒绝启动别让它带着病跑。4. 实操过程一次完整的失败链还原4.1 现场Agent 批量任务成功率骤降说个我实际处理过的案例。某天下午一个批量处理任务的 Agent 成功率从 95% 掉到 40% 左右。日志里大量出现agent execution terminated due to error.偶尔夹杂几条tool_call_failed。团队第一反应是模型服务不稳定准备切备用模型。我先拦住了。理由很简单如果是模型问题失败应该集中在推理阶段而且错误分布会比较均匀。但这次失败是成簇出现的集中在某些时间段这更像是外部依赖的间歇性故障。4.2 第一步把粗错误码打回原形我做的第一件事是临时提高日志级别把tool_call_error这个点的raw_error_code和raw_message全量打出来。跑了一批样本后发现底层错误码集中在两类ssl_get_error返回 1以及ETIMEDOUT。这两个码指向很明确网络层。ssl_get_error返回 1 意味着 SSL 握手阶段就失败了ETIMEDOUT意味着连接或读写超时。跟模型推理没有半点关系。4.3 第二步按时间维度对齐失败分布我把失败时间戳和几个外部依赖的监控曲线对齐。发现失败高峰和某个下游服务的响应时间尖峰高度重合。那个下游服务在高峰期响应时间从 200ms 涨到 3s 以上而 Agent 侧的工具调用超时阈值设的是 2s。超时之后连接被强制关闭SSL 层就报出了那个ssl_get_error。到这里失败链已经清晰了下游变慢 → 工具调用超时 → 连接被强制关闭 → SSL 层报错 → 框架层包装成tool_call_failed→ 应用层兜底成agent execution terminated。模型全程无辜。4.4 第三步验证与修复验证方法很直接把工具调用超时阈值临时调到 5s重跑同一批任务。成功率立刻回到 90% 以上。这就坐实了根因是超时阈值不合理而不是模型或框架的问题。修复分两步。短期把超时阈值按下游 P99 响应时间重新设定并加上指数退避重试。长期给工具调用加上熔断和降级下游持续慢的时候不再无脑重试而是快速失败并记录避免拖垮整条链。# 超时阈值按下游 P99 设定留 50% 余量 DOWNSTREAM_P99_MS 800 TOOL_TIMEOUT_MS int(DOWNSTREAM_P99_MS * 1.5) # 指数退避重试最多 3 次 def call_with_retry(tool, params, max_retry3): for i in range(max_retry): try: return tool.run(params, timeoutTOOL_TIMEOUT_MS) except TimeoutError: if i max_retry - 1: raise time.sleep(2 ** i * 0.1)4.5 第四步把这次排查沉淀成规则一次排查的价值不在于修好这一个问题而在于让同类问题下次能更快定位。我把这次的经验沉淀成了三条规则第一所有工具调用必须记录原始错误码第二超时阈值必须基于下游实测 P99 设定不能拍脑袋第三失败率异常时先看时间分布成簇失败优先怀疑外部依赖。5. 常见问题与排查技巧实录5.1 Agent 排查高频问题速查表现象可能原因快速验证方法处理建议日志只有顶层兜底错误错误码被层层覆盖提高底层日志级别在边界处固定原始错误码失败成簇出现外部依赖间歇故障对齐失败时间与依赖监控加熔断、降级、退避Agent 卡住无日志terminalBlocker看门狗 dump 调用栈加超时、加主动探测沙盒内命令不执行权限或挂载问题手动进沙盒跑同命令检查运行用户与挂载点工具调用 422入参 schema 不匹配打印实际入参与 schema 对比校验层前置别等调用才报换模型后问题依旧根因在链路不在模型隔离模型调用做对照先查链路再谈模型5.2 几个我踩过的坑坑一只看应用层日志。早期我排查 Agent 问题只看应用层日志结果永远只能看到agent execution terminated。后来强制自己在框架层和运行时层都加日志才发现大量问题在更底层就已经发生了。坑二把重试当万能药。有一段时间我给所有工具调用都加了重试结果下游本来就慢重试反而加剧了拥塞失败率更高。重试必须配合熔断和退避否则就是火上浇油。坑三忽视沙盒的生命周期。Agent 跑批量任务时沙盒进程可能因为资源限制被系统回收但 Agent 侧不知道还在往一个已经死掉的沙盒里发指令。后来我加了沙盒心跳检测问题才稳定下来。坑四错误码语义想当然。比如ssl_get_error返回 1我一开始以为是证书问题查了半天证书最后发现是连接被对端提前关闭。错误码的语义要结合上下文看不能望文生义。5.3 一套可复用的排查动作清单遇到 Agent 失败我现在的标准动作是这五步第一拿到 trace_id拉出完整失败链第二看原始错误码按层归类第三看失败的时间分布判断是持续还是成簇第四隔离模型调用做对照第五检查沙盒和运行时健康状态。这五步走完八成问题能定位。提示排查动作要固化成清单而不是靠记忆。人在紧张的时候容易漏步骤清单能保证你不跳过关键环节。6. 把失败链思维变成 Agent 工程的默认习惯做 Agent 开发模型能力固然重要但真正决定线上稳定性的是你对失败链的掌控能力。一个只会调模型的人遇到问题只能换模型一个懂失败链的人遇到问题能精准定位到某一跳、某一层、某一个错误码。我现在带团队新人入职第一件事不是学框架 API而是学怎么读失败链。我会让他们拿一个故意注入故障的 Agent 去排查从粗错误码一路还原到根因。这个过程比看十篇教程都管用。最后分享一个我一直在用的小习惯每次线上出问题修完之后我都会问自己一句——如果明天同样的问题再出现我能不能在五分钟内定位如果不能说明埋点或工具还不够那就继续补。Agent 的稳定性不是一次修出来的是一次次排查沉淀出来的。