AI Agent 工具调用失败的 5 种形态：一套可复用的定位顺序

给 Agent 接上 shell、浏览器、接口之后，最耗时间的不是写 prompt，而是它明明调了工具、也返回了，事情却没发生。下面五种形态是我这几个月踩出来的，每一种都给定位手法。

一、工具返回成功，业务没有变化

典型表现：命令 exit 0、接口 200，但数据库没写、文件没生成。先分清"工具成功"和"业务成功"。工具只能保证它自己那一步跑了，业务是否生效要看下一跳。定位方式是把返回值里所有疑似状态字段打出来，而不是只看 HTTP 状态码。很多后端在业务失败时仍返回 200，把错误塞在 body 的 code 字段里。

二、静默挂起：Promise 永不 settle

这是最难查的一种。请求发出去了，回调没来，进程就这么挂着，日志里什么都没有。根因通常是自己写的封装里 settled 标志位被提前置位——先 settled = true 再调 ok()，而 ok() 开头判断 if (settled) return，于是永远不会进成功分支。

排查手法：给每个异步封装加硬超时（8~21 秒随机），并且对 socket 的 close、error、end 三个事件都绑兜底回调，任何分支都能落地。再配一个退出钩子，保证脚本被杀之前把未完成的请求打出来。

三、URL 拼错但被 try 吞掉

new URL(字符串) 遇到空串、相对路径、小程序 scheme 会直接抛错。如果外层是 try/catch 且 catch 里只 return 空响应，你会看到"请求成功了，返回空"。定位方式：在 catch 里先把原始入参打印出来，再加一道正则守卫，只放行 ^https?:// 开头的地址，非法的直接跳过并记一条日志。

四、Session 看起来还在，其实已经降级

cookie 还在，页面能开，但接口返回 401 或 not login。原因是单点登录的 ticket 是一次性的，页面刷新后 cookie 域没同步。判断是否真登录，不要看首页能不能打开，要看一个必然需要鉴权的接口。例如查未读消息数、查个人资料这类，登录态失效立刻 401。

顺带一个坑：有些站的 token 不放在 cookie，而是 sessionStorage。抓 cookie 抓不到就别硬找，翻一下 localStorage 和 sessionStorage。

五、前端 handler 根本没发请求

按钮能点、有 hover 态、埋点也上报了，但网络面板里没有任何业务请求。这说明 handler 在第一行就 return 了。定位顺序：先看 network 有没有对应请求，没有就直接判定为前端逻辑问题，不用再怀疑账号、额度、权限。

这类问题最容易被误判成"我的账号没权限"。判据很简单：同一个账号在别的入口能正常用，那权限就没问题。

一个通用的排查顺序

1. 先确认请求有没有发出去（network / 抓包）

2. 发出去了，看响应体的业务 code，不要只看状态码

3. 业务 code 正常，看下一跳有没有落地（查数据库、查列表页）

4. 全都没问题，才回头查鉴权与参数

把上面四步写死成检查清单，比每次凭直觉猜要快得多。Agent 调工具也是同理：先验证工具侧，再验证业务侧，最后才怀疑模型。