AI Agent 为什么总在＂工具调用＂上翻车?

上个月接触过一个团队，他们的情况很有代表性：Agent 的 Demo 演示效果惊艳无比，但一接入真实业务流程就开始翻车——查不到正确的文件、调用了错误的 API 参数、把搜索结果理解错了、甚至在循环里反复调用同一个工具直到触发限流。

这不是个例。我接触的大多数团队，在 Agent 落地初期都会在工具调用这个环节摔大跟头。

问题不在于 Agent 本身不够智能，而在于我们设计工具的方式、传递指令的方式、以及调试的方法，还没有跟上大模型调用工具的新范式。

心法一：先假设工具描述是错的

这是最重要、也是最反直觉的一条。大多数人在调试 Agent 工具调用时，第一反应是”Agent 理解错了”或者”提示词写得不够清楚”。但我见过的翻车案例里，有一大半问题出在工具描述本身就有歧义或者不完整。

举个例子：你的 Agent 需要调用一个”发送邮件”的工具。工具描述你可能随手写成：

“发送邮件，收件人为 email 参数”

看起来没问题对吧？但 Agent 调用的时候发现：收件人应该填字符串还是对象？邮件内容要不要指定编码？抄送怎么写？这些问题在人类工程师眼里是常识，但在模型眼里，如果你没有明确说，它就会瞎猜。

一个合格的工具描述，应该包含：

① 工具用途的一句话描述——让模型快速判断什么时候该用这个工具

② 每个参数的类型、格式、枚举值——模型需要知道它能填什么

③ 常见错误示例——直接告诉模型”不要这样做”

④ 返回值的具体结构——模型要根据返回内容做下一步决策

这不是过度设计，而是你在用规范化的文档去对齐模型的认知盲区。工具描述写得越细，Agent 的行为就越稳定。

心法二：用”意图猜测”来验证提示词

有时候工具描述没问题，但 Agent 还是调用错了工具——它把应该用”查询库存”的任务，理解成了”查询订单”。

更好的方法是：在提示词里加一层”意图校验”。每次 Agent 要调用工具之前，先让它输出一个”意图摘要”，格式大概是：

用户请求：”帮我查一下这件商品还有没有货”
我的理解：用户想查询某商品（通过商品ID）的实时库存数量
调用的工具：get_stock_by_sku
参数：{“sku_id”: “xxx”}

这样你可以在执行前就看到 Agent 的理解是否正确——如果错了，在这一步就打断它，而不是等调用完了才发现问题。意图摘要同时也是极佳的调试日志。

心法三：拥抱”有损调用”而非完美主义

什么叫有损调用？简单说就是：不要追求每次工具调用都返回最完整的信息，而是让工具在效率和精度之间做取舍。

举例：你要让 Agent 分析一封邮件的情绪。如果邮件正文很长，Agent 读完10页原始文本要花大量 token，处理效率极低且不稳定。

更好的做法：让”读取邮件”工具在返回内容里加一个固定格式的摘要字段：发件人身份 + 邮件主题 + 关键事件摘要 + 情绪判断。Agent 拿到结构化摘要就够了，不需要读全文。

核心思路：让工具的输出格式去适应模型的认知特点。大模型在处理结构化信息上很强，在处理长篇非结构化信息上就会不稳定。

心法四：建立工具调用的”熔断”机制

这是我自己踩过的一个大坑：做竞品监控 Agent 时，某个网站响应慢，Agent 连续重试了十几轮——最后把对方服务器打挂了，差点收到律师函。

后来我给所有工具调用都加上了熔断三件套：

① 超时限制
每个工具调用最多等待 X 秒，超时后记录错误并返回默认值，不无限等待或自动重试

② 重试上限
每个工具最多重试 N 次，全部失败后记录日志、跳过该步骤、继续执行后续流程，不卡死整个链路

③ 降级策略
某工具持续失败时自动切换备用方案，搜索竞品失败就改为搜索新闻源，不给出错留死胡同

有了熔断三件套，你的 Agent 不再是”一坏全坏”的脆皮系统，而是一个能在异常情况下保持基本运转的鲁棒工具。

心法五：录屏 + 结构化日志，调试效率翻倍

Agent 的执行过程涉及大量上下文、工具返回、中间推理步骤。一旦出错了，如果没有记录，几乎没法复现。

我的经验是加两个调试基础设施：

执行录屏
不只是给自己看，更重要的是给产品和业务方演示。当他们问”这个结果为什么错了”，你不用解释代码逻辑，直接播放录像，问题一目了然。

结构化日志
每次工具调用记录：时间戳、工具名、传入参数、返回摘要、执行耗时、状态。用固定格式，方便日志系统检索。

日志格式示例：

[TOOL_CALL] tool=search_web params={“query”:”竞品动态”} duration=1.2s status=success

[TOOL_CALL] tool=send_email params={“to”:”xxx”} duration=0.8s status=failed error=”smtp_timeout”

总结 · 5条心法

① 先假设工具描述是错的 — 规范化描述，减少歧义

② 用意图猜测来验证提示词 — 调用前加检查点

③ 拥抱有损调用 — 让工具输出适应模型认知

④ 建立熔断机制 — 超时、重试、降级三件套

⑤ 录屏 + 结构化日志 — 让调试有据可依、可复现

这 5 条不需要全部一次性上线，挑一条你现在最痛的开始改——从工具描述规范化开始就行，投入最小，收益最直接。