1. 为什么“Agent 失败”这件事九成人都归因错了做 Agent 开发的人大概都经历过这种场景任务跑着跑着挂了日志里蹦出一行agent execution terminated due to error或者干脆只给你一个code: 1、code: 422、ssl_get_error 返回 1这种没头没尾的错误码。第一反应是什么绝大多数人脱口而出“模型不行”“模型又抽风了”“换个更强的模型试试”。我一开始也这么想。直到有一次同一个模型、同一套 prompt我在本地跑十次成功八次部署到容器里跑十次挂九次。那一刻我才意识到问题根本不在模型身上而在从请求发起到结果返回这条链路上有太多环节会悄悄失败而它们最终都被压缩成了一个粗粒度的错误码。这就是我今天想聊的核心别再把 Agent 失败都算给模型要学会从粗错误码反推到失败链。所谓失败链指的是一个 Agent 任务从触发到结束中间经过的每一个环节——任务编排、工具调用、网络请求、沙盒执行、终端交互、结果回传——任何一环出问题最终都会以“Agent 失败”的面目呈现。而错误码只是这条链最末端的一个信号它告诉你“出事了”但几乎不告诉你“谁出的事”。这篇文章适合谁看如果你正在做 Agent 开发、Agent 框架搭建、多 Agent 协作或者你被terminalBlocker、agent execution terminated due to error、模型请求失败这类报错折磨过那这篇就是写给你的。我会把“从错误码定位失败链”的方法论拆开讲配上我实际踩过的坑、排查指令、参数判断逻辑让你下次看到错误码时能像老中医一样顺着经络找到病灶而不是对着模型一顿输出。先给一个我总结的判断原则错误码是症状失败链是病因模型只是众多嫌疑人之一而且往往不是主犯。记住这句话后面的排查思路就顺了。2. 错误码到底在说什么从粗粒度信号到失败链的映射逻辑2.1 为什么错误码天生“粗”很多人抱怨错误码太笼统其实这不是设计缺陷而是分层系统的必然结果。一个 Agent 请求要穿过编排层、网络层、模型服务层、工具执行层、沙盒层每一层都有自己的异常类型。如果每一层的异常都原样往上抛调用方会被几十种错误类型淹没。所以工程上通常做异常收敛把底层五花八门的错误归并成几个顶层错误码。代价就是信息丢失。code: 1可能是网络超时也可能是沙盒启动失败还可能是模型返回了非法 JSON。422在通信语境里常指请求格式或参数校验不通过但在 Agent 场景里它可能来自工具调用的参数 schema 校验失败也可能来自模型服务商对请求体的拒绝。ssl_get_error 返回 1更典型它本质是 TLS 握手或读写过程中的一个底层信号返回 1 通常意味着“需要重试”或“底层 I/O 未就绪”但被上层包装后就变成了一个让人摸不着头脑的失败。所以第一步认知要转变不要试图从错误码本身读出全部真相而要把它当成一个“入口”顺着它去还原失败链。2.2 失败链的五个典型环节我把 Agent 任务的失败链拆成五个环节这是我排查时脑子里的一张地图环节典型表现常见错误码/信号任务编排层任务状态机卡死、重试逻辑异常自定义 code、超时网络与通信层请求发不出、响应收不全422、ssl_get_error、连接超时模型服务层模型拒绝、返回格式错误模型请求失败、code 1工具与沙盒层工具调用失败、沙盒起不来terminalBlocker、执行终止结果回传层结果丢失、序列化失败空响应、解析异常这张表不是让你背而是让你在拿到错误码时按顺序过一遍这五个环节逐个排除。很多人一上来就盯着模型层结果绕了一大圈才发现是沙盒层的问题。2.3 一个真实的反推案例我遇到过一次典型的“冤枉模型”事件。任务报错agent execution terminated due to error错误码是 1。团队第一反应是模型服务不稳定准备换供应商。我拦了一下做了三件事第一看时间分布。发现失败集中在每天固定时段而不是随机分布。随机失败才更像模型问题规律性失败往往指向环境或资源。第二看并发量。那个时段正好是并发高峰。Agent 扛并发时如果沙盒或工具执行是串行资源就会排队、超时、被 kill。第三看底层日志。果然terminalBlocker在高峰期频繁出现说明终端交互环节被阻塞任务超时后被上层统一报成 code 1。最后定位到不是模型的问题是沙盒终端资源池太小高并发下阻塞。把资源池扩容后失败率从 30% 降到 2%。这个案例我后面还会展开讲排查细节。3. 从错误码定位路径的实操方法论3.1 先分层再定位三步锁定法拿到一个错误码我习惯走三步第一步确认失败的可复现性。是必现、偶现还是特定条件下现必现通常是配置或代码问题偶现多半是并发、网络或资源问题特定条件现则要找到那个“条件”。这一步决定了你后面排查的方向。第二步确认失败的边界。同一个任务换模型还挂吗换环境还挂吗换并发量还挂吗通过变量控制把失败范围一步步缩小。我常用的一张对照表变量保持不变改变结论方向模型换模型仍失败换模型成功模型层问题环境本地成功、容器失败容器成功环境/沙盒问题并发低并发成功高并发失败资源/并发问题网络内网成功、外网失败外网成功通信层问题第三步抓底层日志。顶层错误码是收敛后的结果底层日志才有原始异常。这一步最关键也最容易被忽略。很多人只看应用层日志不看沙盒、不看网络、不看系统层自然找不到根因。3.2 网络与通信层的排查要点通信层是 Agent 失败的高发区尤其是跨服务、跨容器调用时。422和ssl_get_error是我见得最多的两个信号。422在 Agent 场景里我总结出三个常见来源一是工具调用的参数不符合 schema比如该传数组传了字符串二是模型服务商对请求体做了额外校验比如 token 超限、字段缺失三是网关层做了请求改写把合法请求改成了非法请求。排查时把原始请求体完整打印出来和 schema 逐字段比对基本能定位。ssl_get_error 返回 1这个信号本质是 TLS 层的 I/O 状态。返回 1 通常对应底层需要重试的情况可能是连接被中途断开、证书链校验卡住、或者对端在握手阶段就关闭了连接。我的处理经验是先确认是不是偶发偶发就加重试如果必现检查证书有效期、TLS 版本协商、以及中间是否有代理层做了拦截。这里要提醒一句不要一看到 SSL 错误就怀疑加密配置很多时候是连接被提前掐断导致的。排查通信层我常用的指令组合是# 看连接状态和重传 ss -s netstat -s | grep -i retrans # 看 DNS 解析是否稳定 dig short your-service-host # 看端口连通性 nc -zv host port # 抓包看握手过程需要权限 tcpdump -i any -w agent.pcap port 443抓包这步很多人嫌麻烦但它能直接告诉你握手卡在哪一步比猜快得多。3.3 沙盒与终端交互层的排查要点terminalBlocker这个词做 Agent 沙盒的人应该不陌生。它描述的是终端交互被阻塞的状态——Agent 想执行一条命令但终端没有及时返回或者返回了但 Agent 没读到导致任务挂起直到超时。这类问题的根因通常有三类一是资源竞争多个 Agent 抢同一个终端会话二是读写不同步命令发出去了但没等 prompt 回来就发下一条三是超时设置不合理命令本身执行时间长但超时设得太短。我的排查顺序是先看是不是并发抢资源再看读写时序最后调超时。这里有个经验终端交互的超时不要设成固定值要按命令类型分级。查询类命令给短超时编译、安装类命令给长超时。一刀切的超时要么误杀正常任务要么让真卡住的任务拖死整个队列。3.4 模型服务层的排查要点终于说到模型层了。我不是说模型不会出问题而是说模型层的问题往往有更明确的信号不像底层那么隐蔽。模型请求失败常见原因有token 超限、内容被安全策略拦截、返回格式不符合预期、服务端限流。这些在日志里通常有更具体的描述比如context length exceeded、content filtered、rate limit。如果你看到的只有一句笼统的“模型请求失败”那大概率是上层把细节吞了要去翻模型服务商返回的原始响应。我处理模型层问题的原则是先确认是不是模型的问题再确认是模型的什么问题。前者靠变量控制后者靠原始响应。很多团队跳过第一步直接开始调 prompt、换模型结果在一个根本不是模型问题的坑里越陷越深。4. 完整排查流程一次从报错到根因的实战复盘4.1 现场还原那个被冤枉的模型回到开头那个案例。任务报错agent execution terminated due to error错误码 1团队准备换模型。我介入后按上面的方法论走了一遍。第一步可复现性。本地手动跑十次成功八次容器里跑十次成功一次。失败率差异巨大说明和环境强相关不是模型随机抽风。第二步边界确认。换模型容器里照样挂降并发容器里成功率明显上升。到这里基本可以排除模型锁定并发和资源。第三步抓底层日志。在沙盒层日志里terminalBlocker高频出现时间点和任务失败时间点吻合。进一步看终端会话池只有 5 个而并发任务是 20 个大量任务在等终端等到超时被 kill。根因清楚了终端资源池容量不足高并发下阻塞任务超时后被统一报成 code 1。模型全程无辜。4.2 修复方案与参数计算定位到根因后修复分两步。第一步扩容终端会话池。这里有个参数计算假设单任务平均占用终端时长 T峰值并发 N那么池大小至少要满足池大小 N * T / 任务总时长。我们实测单任务平均占用终端 8 秒峰值并发 20任务总时长约 30 秒算下来20 * 8 / 30 ≈ 5.3但这是平均值考虑到长尾我直接扩到 20留足余量。第二步优化超时策略。把固定超时改成分级超时TIMEOUT_CONFIG { query: 5, # 查询类 compile: 120, # 编译类 install: 300, # 安装类 default: 30, }同时给终端交互加了读写同步锁确保命令发出后等到 prompt 再发下一条避免时序错乱。修复后失败率从 30% 降到 2%剩下的 2% 是真正的模型层偶发问题属于正常范围。4.3 这次复盘给我的三个教训第一错误码的粒度决定了排查的起点但不决定终点。code 1 很粗但顺着失败链走照样能找到根因。第二规律性失败优先怀疑环境和资源随机性失败优先怀疑模型和网络。这个直觉帮我省了大量时间。第三并发是 Agent 失败的最大放大器。单机能跑通不代表生产能跑通Agent 扛并发的能力取决于最窄的那个环节而不是模型。5. 常见问题速查与避坑经验5.1 高频问题速查表现象可能环节排查动作code 1 且规律出现资源/并发看并发量、资源池、时间分布422 通信故障通信/参数打印原始请求体比对 schemassl_get_error 返回 1通信/TLS查证书、TLS 版本、连接是否被掐断terminalBlocker沙盒/终端查会话池、读写时序、超时设置模型请求失败模型/网关看原始响应确认是否限流或拦截任务卡死不报错编排/状态机看状态流转、重试逻辑、死锁这张表我贴在工位上出问题先扫一眼能快速缩小范围。5.2 避坑经验那些文档不会告诉你的坑一只看应用层日志。应用层日志是收敛后的结果底层日志才有真相。沙盒日志、网络日志、系统日志一个都不能少。我现在的习惯是排查 Agent 问题必开四层日志。坑二超时一刀切。前面说过固定超时要么误杀要么拖死。分级超时是必须的而且要根据实际命令耗时动态调整。坑三忽略并发下的资源竞争。单机测试永远发现不了资源池不足的问题。上线前一定要做并发压测找到最窄环节。坑四把重试当万能药。重试能解决偶发问题但会放大必现问题。如果失败是必现的重试只会让日志更乱让问题更难定位。先定位再重试。坑五错误码不记录上下文。只记 code 1 没用要记录当时的并发量、资源占用、请求参数、时间戳。上下文越全反推越快。5.3 一个提升排查效率的小技巧我给团队定了个规矩任何 Agent 失败必须能回答三个问题——失败发生在哪个环节、当时的并发和资源状态是什么、底层原始异常是什么。回答不了这三个问题就不许说“模型不行”。这个规矩执行三个月后团队里“甩锅模型”的情况少了八成大部分问题在半小时内能定位到具体环节。排查效率的提升本质上来自把模糊的失败拆解成可验证的环节。6. 把失败链思维固化到开发流程里排查能力再强也不如让失败一开始就更容易被定位。所以我现在做 Agent 项目会把失败链思维前置到开发阶段。第一错误码分级设计。顶层保留粗粒度错误码给调用方但内部日志必须记录细粒度异常并且带上环节标识。比如SANDBOX_TERMINAL_BLOCKED、NET_TLS_RETRY、MODEL_RATE_LIMITED一看就知道去哪查。第二关键环节埋点。任务编排、网络请求、沙盒执行、模型调用每个环节的进入、退出、耗时、结果都打点。出问题时一眼能看出卡在哪个环节。第三并发压测常态化。不要等上线才发现资源池不够。每次改动涉及资源相关的逻辑都跑一遍并发压测。第四失败链文档化。把常见错误码和对应环节、排查动作整理成文档新人也能照着查。这比口口相传靠谱得多。我个人在实际操作中的体会是Agent 开发里模型只是众多变量之一而且往往是最后才需要怀疑的那个。真正让 Agent 失败的是那些藏在错误码背后的、跨环节的、并发下才暴露的问题。把失败链摸清楚你会发现很多所谓的“模型问题”其实是你自己的系统在某个角落悄悄掉了链子。下次再看到 code 1别急着换模型先顺着链子走一遍答案大概率就在那里。