function call 与 agent怎么排查:先看工具返回,别急着改提示词

接入与开发

讲清 function call 与 agent 出问题时的分层排查顺序:先判断是模型没选工具、参数填错、工具本身失败,还是循环没停下来,附判断标准和可执行动作。

接好一个能调工具的 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 打架。

调通了但停不下来,看循环和重试

模型重复调同一个工具、同一组参数,通常不是它笨,是上一次工具返回里没有它需要的信息。检查返回体是不是只给了状态码没给数据——它拿不到想要的结果,就只能再试一遍,然后一直试。

  1. 先看返回体确认工具成功时返回的数据里,是否包含模型下一步决策需要的信息,缺了就会原地打转。
  2. 设步数上限给单次请求一个最大工具调用轮数,到上限就停并返回当前结果,这不是优化项是必备项,否则一次跑飞就是持续计费。
  3. 加重复调用检测同一工具加同一组参数连续出现就中断,把情况回传出去,比让它自己绕出来更快。
  4. 重试要幂等工具超时后的重试,先判断这个工具是不是改状态。写操作类的重试前要带幂等键,否则一次写会被执行两遍。

判断标准很简单:这个工具不改状态,重试基本安全;它改状态,就没有「重试一下试试」这回事,必须先确认上一次到底成没成。

哪些情况这套顺序不管用

有一种情况最坑:模型本身不支持工具调用,或者中转层的兼容层把 tools 字段吃掉了。这时候你把提示词改出花来也没用,先确认字段有没有真正透传到上游。方法很直接,看上游原始响应里有没有 tools 相关的痕迹,没有就不是模型的问题。

工具是外部第三方维护、返回格式随版本变的时候,排查重点要挪到解析层,而不是模型侧。你这边解析没跟上对方的字段变化,表现出来很像模型乱调,其实是下游把数据读错了。

还有一种,用的是本地小模型,工具选择能力本身就不足。该换模型就换,别在参数和提示上反复磨,磨不出你想要的选择能力。至于换哪个、当时各家什么水平,去站内的模型资料库对一遍再定,别拍脑袋。

上面这些判断里涉及具体数字的地方,比如各家 API 的计费口径、当前在售模型清单,一律以站内页面为准,本文不写死,因为价格和模型都在变,写死了反而误导你。

下一步如果你正卡在「到底该换模型还是该改接入方式」,先去中转站导航页把候选列出来,再对照模型资料库确认工具调用支持情况,最后用同一批输入跑对比,比反复改提示词省事得多。

常见问题

模型一直不调工具,只回文字,先改哪里?

先确认请求里 tools 字段真的发到了上游,抓一次原始请求看。字段在的话,把工具描述改成一句话说清「什么时候该用它」,别写功能列表。还不行就换一个工具调用能力更稳的模型做对照实验。

参数老是缺一两个字段,是模型笨吗?

多数是 schema 里那几个字段的可选标记和描述不清。把必填项收窄到真正必需的,剩下的给默认值并在描述里写明默认行为,缺字段的情况会明显减少。

agent 跑到一半卡住不动,怎么判断是工具慢还是循环死了?

看日志里最后一次工具调用到下一次模型请求之间的间隔,以及同一个工具名加参数是否重复出现。重复出现就是循环没收敛,间隔很长则是工具超时,两件事的处理方式完全不同。

本文依据各平台公开文档与官方公告整理,只做中文归纳;具体做法、参数与限制以官方文档为准。