接好一个能调工具的 agent,跑通一次不难,难的是后面某天它突然不调了、参数老是缺一格、或者绕着一件事转圈子。多数人第一反应是回去改提示词,改到第三版发现没用。这篇给一条从工具返回往回倒推的顺序,帮你定位到底卡在哪一层,以及每层该看什么、什么情况下这套顺序不适用。
接一个能调工具的 agent,跑通一次真不难。难的是后面某天它突然不调了、参数老是缺一格、或者绕着一件事转圈子。多数人第一反应是回去改提示词,改到第三版发现一点用没有,因为问题根本不在提示词那一层。
这篇给一条从工具返回往回倒推的顺序。核心思路就一句:先看工具到底返回了什么,再判断是哪一层断了。下面按四层拆开讲,每层说清看什么、怎么验证,最后补一段这套顺序什么时候不适用。
先分清是哪一层出的问题
把一次 agent 请求拆成四层:模型有没有选择调用、参数合不合法、工具本身成不成功、循环有没有收敛。你看到的报错现象基本能对上其中一层,先定位再动手,别一上来就重写系统提示。
关键是看原始返回,不是看你自己的业务日志。日志通常只记了你关心的字段,把最有诊断价值的东西过滤掉了。把上游响应体打出来,盯三个地方:tool_calls 字段出现了没有、arguments 是不是合法 JSON、工具返回里有没有 error 字段。这三处能砍掉大半猜测。
| 现象 | 大概率卡在 | 先看哪里 |
|---|---|---|
| 完全没返回 tool_calls | 模型选择层 | 系统提示里工具用途描述、tools 字段是否透传 |
| 有 tool_calls 但 arguments 解析失败 | 参数层 | schema 类型声明与模型输出格式是否一致 |
| arguments 合法但缺字段 | schema 描述层 | 必填/可选项划分、字段描述是否够具体 |
| 工具返回体带 error | 工具执行层 | 工具自身入参、权限、超时 |
| 反复调同一个工具 | 循环层 | 上轮返回是否给了它需要的数据、有没有步数上限 |
工具定义这关最容易埋雷
参数描述写得太省,模型只能猜。写「时间」两个字,和写「ISO 8601 格式的日期字符串,例如 2025-01-01」,对模型来说是两回事。前者它可能给你「明天下午」,后者才有机会填对。这不是提示词的功劳,是工具定义该干的活。
必填项和可选项要真的分开。把所有字段都标成必填,模型会硬凑一个空值塞进去,下游校验再报错,然后你回头怪模型不听话,其实是 schema 逼的。反过来,可选项也至少写清「不传时默认是什么」,否则模型不知道该不该填。
- 字段描述里带上格式和例子,别只写名词;
- 必填与可选分开标,可选项说明不传时的默认行为;
- 用途雷同的两个工具先合并或改名,再谈调优;
- 工具数量多时按场景分组,减少模型在相似选项间来回挑;
- 改完 schema 用同一批输入重跑,对比 tool_calls 的差异,别凭感觉判断有没有变好。
工具数量一多,名字和用途描述相近的两个工具会让模型反复挑错。实际用下来,合并或改名往往比加一段「请优先使用 X 工具」的提示更有效,因为后者是在跟 schema 打架。
调通了但停不下来,看循环和重试
模型重复调同一个工具、同一组参数,通常不是它笨,是上一次工具返回里没有它需要的信息。检查返回体是不是只给了状态码没给数据——它拿不到想要的结果,就只能再试一遍,然后一直试。
- 先看返回体确认工具成功时返回的数据里,是否包含模型下一步决策需要的信息,缺了就会原地打转。
- 设步数上限给单次请求一个最大工具调用轮数,到上限就停并返回当前结果,这不是优化项是必备项,否则一次跑飞就是持续计费。
- 加重复调用检测同一工具加同一组参数连续出现就中断,把情况回传出去,比让它自己绕出来更快。
- 重试要幂等工具超时后的重试,先判断这个工具是不是改状态。写操作类的重试前要带幂等键,否则一次写会被执行两遍。
判断标准很简单:这个工具不改状态,重试基本安全;它改状态,就没有「重试一下试试」这回事,必须先确认上一次到底成没成。
哪些情况这套顺序不管用
有一种情况最坑:模型本身不支持工具调用,或者中转层的兼容层把 tools 字段吃掉了。这时候你把提示词改出花来也没用,先确认字段有没有真正透传到上游。方法很直接,看上游原始响应里有没有 tools 相关的痕迹,没有就不是模型的问题。
工具是外部第三方维护、返回格式随版本变的时候,排查重点要挪到解析层,而不是模型侧。你这边解析没跟上对方的字段变化,表现出来很像模型乱调,其实是下游把数据读错了。
还有一种,用的是本地小模型,工具选择能力本身就不足。该换模型就换,别在参数和提示上反复磨,磨不出你想要的选择能力。至于换哪个、当时各家什么水平,去站内的模型资料库对一遍再定,别拍脑袋。
上面这些判断里涉及具体数字的地方,比如各家 API 的计费口径、当前在售模型清单,一律以站内页面为准,本文不写死,因为价格和模型都在变,写死了反而误导你。
下一步如果你正卡在「到底该换模型还是该改接入方式」,先去中转站导航页把候选列出来,再对照模型资料库确认工具调用支持情况,最后用同一批输入跑对比,比反复改提示词省事得多。→常见问题
模型一直不调工具,只回文字,先改哪里?
先确认请求里 tools 字段真的发到了上游,抓一次原始请求看。字段在的话,把工具描述改成一句话说清「什么时候该用它」,别写功能列表。还不行就换一个工具调用能力更稳的模型做对照实验。
参数老是缺一两个字段,是模型笨吗?
多数是 schema 里那几个字段的可选标记和描述不清。把必填项收窄到真正必需的,剩下的给默认值并在描述里写明默认行为,缺字段的情况会明显减少。
agent 跑到一半卡住不动,怎么判断是工具慢还是循环死了?
看日志里最后一次工具调用到下一次模型请求之间的间隔,以及同一个工具名加参数是否重复出现。重复出现就是循环没收敛,间隔很长则是工具超时,两件事的处理方式完全不同。