工具调用是智能体最容易出问题的环节。报错形式五花八门,但根因通常集中在少数几类。按顺序排查,比乱试有效得多。

参数不对怎么判断?

表现是接口返回参数校验失败,或者模型传了一个不存在的字段。根因通常是工具描述写得含糊,模型靠猜。

排查动作:把工具的 schema 打印出来,逐字段检查类型、必填、枚举范围是否说清楚。特别检查日期格式、金额单位、ID 类型这些容易出错的字段。

修法是把描述写具体。不要写查询订单,要写按订单号查询订单,订单号为字符串,长度为十六位。

模型选错工具怎么发现?

表现是明明该调 A 却调了 B,或者该调工具却直接回答。根因是工具之间的边界不清楚。

排查动作:把全部工具的名字和一句话描述列出来,看看有没有两个工具的描述高度重叠。有重叠,模型就会混。

修法是合并或改名。功能相近的工具合并成一个带参数的,名字里带上区分词。

返回值解析失败怎么处理?

表现是工具返回了结果,但模型没用上,或者用错了。根因是返回结构太复杂,模型抓不住关键字段。

排查动作:看原始返回值,检查是不是嵌套太深、字段名太抽象、或者返回了模型不认识的格式。

修法是在工具层做一次扁平化,只把模型需要的字段返回,多余的去掉了再给。不要让模型做数据清洗。

多步调用状态错乱怎么排查?

表现是连续调几个工具之后,参数串了或者顺序错了。根因是没有显式的状态管理。

排查动作:把每一步的输入输出打日志,看是哪一步开始偏的。多数情况是第二步用了第一步的旧参数。

修法是把中间结果显式写进上下文,并且每步调用前校验前置条件是否满足。

超时与重试该怎么设?

表现是偶发失败,重试后成功。根因是接口慢或者网络抖动。

排查动作:统计失败率与调用时长的关系。如果失败集中在长尾耗时,就是超时设置问题。

修法是把超时按工具分别设置,慢接口给长超时,快接口给短超时。重试要加退避,并且保证幂等。

排查的通用顺序是什么?

先看日志,确认是模型的问题还是接口的问题。再看 schema,确认描述是否清楚。然后单独测工具,绕开模型直接调。最后才考虑改提示词。

跳过前三步直接改提示词,是浪费时间。大部分工具调用问题不在提示词,在接口设计和描述质量。

有什么预防性做法?

给每个工具写一个最小测试用例,在接入时跑一遍。后续每次改工具都重跑。这能挡住大部分回归问题,成本很低。

去论坛讨论

前往 ziyuanagi.com 论坛 参与讨论