AI Agent 工具调用失败排查:不触发、参数错、死循环六原因

先给结论:Agent「不动手」几乎都出在六个地方——工具清单没传、工具描述写不清、参数 JSON 解析失败、tool_call_id 对不上、没有最大步数导致死循环、工具返回太大爆 token。其中「清单没传」和「死循环」最多。按下面的对照表逐项查,再用第六节的调试代码把每轮消息打出来,基本一次定位。

一、先确认「模型到底有没有要求调工具」

排错第一步别猜,直接看模型返回的 message 里有没有 tool_calls:

  • 没有 tool_calls:模型压根没打算调工具 → 查第一、二类原因(清单 / 描述)。
  • 有 tool_calls 但你执行崩了 → 查第三、四类(参数 / id)。
  • 能调但停不下来或越来越慢 → 查第五、六类(死循环 / 返回过大)。

把现象归到这三类之一,排查范围立刻缩小一半。

二、六个原因对照表

现象原因处理
模型只回文字,不调工具请求里没带 tools,或 tool_choice 被设成 none确认 tools 字段随请求发出;用 auto
选错工具 / 参数乱填description 太笼统,模型不知道何时用写清「何时用、每个参数是啥」,宁可啰嗦(D12)
arguments 解析报错模型返回的参数不是合法 JSONjson.loads 包 try/except,失败让模型重出
接口报 tool_call_id 错误回灌结果时 id 与原调用对不上 / 顺序错位逐条按原 id 组装 role=tool 消息
一直调工具不停没设最大步数与终止条件循环加上限,超限强制收尾(D8)
几轮后变慢 / 超长报错每轮把整段历史和巨大工具结果全带上工具层裁剪、长结果摘要(D15)

三、原因 1~2:工具清单与描述

D8 的最小 Agent 骨架里,TOOLS 是随每次请求一起发的。最容易漏的是把它写在初始化里却忘了放进 POST 的 json 体,或某个网关不转发该字段。tool_choice 保持 auto,别误设成 none。

描述写「查天气」三个字,模型就分不清它和别的查询工具该用哪个。按 D12 的思路,把「何时用、入参含义、返回什么」写进 description,选错工具的概率会明显下降。

四、原因 3~4:参数与 tool_call_id

模型返回的 arguments 是字符串,不是对象,必须 json.loads 一次;偶尔会产出不合法 JSON,别让整个循环崩掉,包一层 try/except 并把错误回灌让模型重出。

更隐蔽的是 id 问题:一次可能有多个 tool_calls,每条都要严格用它自己的 id 组装一条 role=tool 消息,顺序别打乱、id 别复用。多工具并行时这里最容易错。

五、原因 5~6:死循环与 token 膨胀

  • 死循环:循环必须有最大步数(D8 用 range(5))和超时,超限返回「未得出结论 / 转人工」,别指望模型自己懂事。
  • token 膨胀:工具一次查回几 MB 直接塞进对话,几轮就撞上下文上限(D15)。工具层先分页、只回关键字段,长文本先摘要。

六、逐轮调试代码(把过程打出来)

def run_agent_debug(question):
    messages = [{"role": "user", "content": question}]
    for step in range(5):
        resp = requests.post(API_URL, json={
            "model": "your-model",
            "messages": messages,
            "tools": TOOLS, "tool_choice": "auto"    # 确认 tools 真的发出去了
        }, timeout=60).json()
        msg = resp["choices"][0]["message"]
        print("第", step, "轮 tool_calls:", msg.get("tool_calls"))  # 关键:先看有没有
        if not msg.get("tool_calls"):
            return msg["content"]
        messages.append(msg)
        for call in msg["tool_calls"]:
            try:
                args = json.loads(call["function"]["arguments"])
            except json.JSONDecodeError:
                args = {}                            # 参数不合法,别让循环崩
            result = dispatch(call["function"]["name"], args)
            messages.append({"role": "tool",
                             "tool_call_id": call["id"],   # 严格用原 id
                             "content": str(result)[:2000]})  # 先裁剪再回灌
    return "超过最大步数,转人工"

这段代码把三个关键观察点都摆出来了:每轮有没有 tool_calls、参数能不能解析、回灌的 id 对不对。跑一遍,六类原因里命中哪一类通常一眼可见。

七、FAQ

Q:工具换成 MCP(D9)后还会犯这些错吗? 会,前四类一模一样。MCP 只是把工具标准化成服务,模型侧的 tools 描述、参数 JSON 和 tool_call_id 规则没变,排错思路可直接照搬。

Q:模型偶尔调、偶尔不调,怎么查? 多半是 description 边界模糊或提示词太松(D12)。把「什么情况必须调工具」写进 system 提示,并给一两个样例,稳定性会好很多。

Q:多步编排(D10)里怎么防死循环? 除了总步数上限,给每个步骤单独设重试次数,且只对可恢复错误重试(D15),避免某一步卡住把整条流程拖死。

小结

Agent 工具调用失败,按现象先分三类:没 tool_calls 查清单和描述、有但执行崩查参数与 id、停不下来查步数上限和返回体积。六类原因里「tools 没随请求发出」和「没设最大步数」最常见,也最好修。用第六节的逐轮调试代码把消息打出来,比逐行猜快得多。具体 tools 字段、tool_choice 取值与错误码以你所用模型厂商当天官方文档为准。

相关推荐

相关推荐

评论(0)
发表评论