AI Agent 最常见的卡死，不是模型回答错了，而是卡在工具调用上。你让它查个数据库，它超时了；让它调个接口，参数填错了一半；让它读个表格，返回的 JSON 结构变了，它就开始胡编。这些问题看起来五花八门，其实就三类：模型决策错、工具执行错、返回解析错。
排查工具调用失败，最忌讳的是上来就改 prompt。prompt 改了，可能把原来对的场景也改坏。正确做法是先还原调用链，搞清楚到底断在哪一层，再对症下药。这个思路和 证据包、回放对照 是一条线——先留痕，再定位。
先分清失败在哪一层
一次工具调用可以拆成三步：模型决定调用哪个工具、传什么参数；工具实际执行；模型解析返回结果。失败在哪一步，处理方式完全不同。
如果是模型决策错——比如该调 A 工具却调了 B，或者参数选错了——那是 prompt 和工具描述的问题，要改的是工具的名称、描述和参数说明，让它更清楚。如果是工具执行错——超时、报错、权限拒绝——那是工具本身和环境的问题。如果是返回解析错——返回结构变了、字段缺失、模型读不懂——那是工具契约和校验的问题。
判断属于哪一层，靠的是日志。每次调用都该记录：模型发出的工具名和参数、工具返回的原始结果、模型拿到结果后的下一步动作。这套字段怎么设计，可以看 审计查询字段 里的思路。
五类高频失败怎么查
第一类，超时。原因通常是工具本身慢，或者并发太高把它打满了。处理上，先加超时阈值，超时后走重试或降级，别让 Agent 无限等。第二类，参数错误。工具返回 400 之类，多半是模型理解错了参数语义，去查工具描述写没写清楚必填项、类型和示例。
第三类，返回解析失败。最常见的是上游接口改了返回结构，Agent 还按旧格式读，读不到就开始编。这种情况要在工具层做一层契约校验，结构不对直接报「返回异常」，而不是把脏数据塞给模型。第四类，权限拒绝。Agent 拿到的凭证过期了，或者没权限调这个接口。第五类，死循环。模型反复调用同一个工具，越调越错。这五类里，死循环最伤成本，因为它在持续烧 token。
重试要有上限，还要幂等
重试不是越多越好。没有上限的重试，遇到一个稳定的错误，能把 token 烧到天上去。建议按错误类型分级：网络抖动这种瞬时的可以重试两三次，参数错误这种确定性的就别重试了，直接失败。这和 失败升级规则 的分层思路一致——拿不准的重试，确定错的转人工。
另一个容易被忽略的点是幂等。如果工具会写数据，重试前要保证同一操作执行两次结果不变，否则一次失败重试就可能写入两条重复数据。
查不出就转人工，别硬撑
连续失败或者命中敏感操作时，最好的处理不是继续猜，而是转人工。给失败任务配上明确的 转人工队列，附上已经还原的调用链和原始返回，人一看就知道卡在哪。这个兜底机制，比任何 prompt 微调都更能保证业务不中断。
总结
AI Agent 工具调用失败，先别急着改 prompt，先分清是模型决策错、工具执行错还是返回解析错。靠日志还原调用链，按超时、参数、解析、权限、死循环五类对症处理，重试设上限并保证幂等，查不出就转人工。这样排查，Agent 卡死和重复烧 token 的概率都会明显下降。
