← 返回博客
AI · Agent · Tool Calling · 工程实践

从 Demo 到生产：Tool Calling 最容易踩的 7 个坑

·12 分钟阅读

Tool Calling 已经成为 AI 应用开发里的基础能力。

我们让模型调用天气 API、数据库查询、搜索服务、消息发送器，甚至多个工具串联起来完成一个任务。看起来，模型终于不只是“会说话”，而是开始“会做事”。

但很多团队都会经历同一个阶段：

  • Demo 跑得很好

  • 一接入真实业务，就开始出问题

  • 模型该调工具时不调

  • 调了工具却传错参数

  • 工具返回成功，模型却总结错了

  • 多工具链路一复杂，状态就开始混乱

  • 最危险的是，有副作用的工具真的被误调用了

所以，Tool Calling 真正难的，从来不是“怎么声明一个 tool”，而是：

怎么把它做成一个稳定、可控、可回溯的生产能力。

这篇文章不再重复入门概念，而是直接从工程落地出发，聊聊 Tool Calling 最常见的 7 个坑，以及对应的解法。

1. 该调工具的时候，模型直接瞎答

这是最常见的问题。

很多 Demo 的场景都很理想：

用户问：“北京明天天气怎么样？”

模型调用天气工具，再返回答案。

但真实用户不会这么配合。他们会说：

  • “我周五去北京出差，要不要带伞？”

  • “帮我看看这个客户今天有没有下单”

  • “查一下余额，不够就提醒我充值”

这时候，模型不一定会先调用工具。它很可能会先尝试“直接回答”。

原因很简单：语言模型的默认行为是生成一个看起来合理的答案，而不是主动承认“我需要外部数据”。

工程建议

不要只在 prompt 里写一句：

如果需要外部信息，请调用工具。

这不够。

更稳的做法是把规则显式化：

  • 涉及实时信息，必须调用工具

  • 涉及用户私有数据，必须调用工具

  • 涉及订单、余额、库存、状态，必须调用工具

  • 无法从上下文确定时，优先查证，不要猜

同时，你要在日志里记录：

  • 当前轮是否存在可用工具

  • 模型是否实际调用了工具

  • 最终回答是否基于工具结果

否则“模型没调工具但回答了”这种错误，你根本看不到。

2. 模型调了工具，但参数传错了

第二类高频问题，不是“不调用”，而是“乱调用”。

比如你定义了一个天气工具：

{
  "name": "get_weather",
  "parameters": {
    "type": "object",
    "properties": {
      "city": { "type": "string" },
      "date": { "type": "string" }
    },
    "required": ["city", "date"]
  }
}

你以为这已经够清楚了，但真实情况可能是：

  • city 被填成“北京出差”

  • date 被填成“这周五左右”

  • 明明要传标准日期，却传了自然语言

  • 明明工具要的是 user_id，模型传了用户名

Demo 阶段不容易暴露这个问题，因为测试输入通常都很规整。上线后，一旦输入变脏，参数问题会迅速放大。

工程建议

2.1 schema 要“机器友好”，不要只“人类友好”

字段名要明确、单义、边界清晰。

  • 好：city、date、user_id

  • 差：target、query、context

2.2 不要把复杂解析全丢给 tool arguments

像“下周一下午”“最近三天”“我上次那个订单”这种表达，本质上是解析任务，不一定适合直接塞进业务工具。

更稳的方式通常是：

  • 模型先产出结构化意图

  • 应用层做标准化解析

  • 最终再调用底层工具

2.3 永远校验参数

模型输出的参数，本质上就是不可信输入。

对 tool arguments 的态度，应该和对外部 API 请求一样严格：

  • 类型校验

  • 必填校验

  • 枚举校验

  • 格式校验

  • 权限校验

不要因为它是模型生成的，就默认“应该差不多对”。

3. 工具调用成功了，模型却把结果说错了

这是最隐蔽的一类问题。

例如工具返回：

{
  "status": "paid",
  "amount": 199,
  "currency": "CNY"
}

最后模型却说：

订单还未支付。

或者天气工具明明返回“小雨”，模型最后总结成“天气不错，适合出行”。

从系统日志上看：

  • 工具调成功了

  • 返回数据也对

  • 但用户看到的答案还是错的

这说明 Tool Calling 并没有消除生成风险，它只是把真实数据接入了系统。后面还有一步：模型要“读懂并转述”工具结果，而这一步一样可能出错。

工程建议

3.1 对关键结果，减少自由转述

不要让模型在高确定性场景里自由发挥。

例如：

  • 订单状态

  • 余额

  • 库存

  • 审批结果

  • 风险等级

这些结果更适合由程序模板化输出，模型只负责补充说明。

3.2 原始结果和最终回答一起记录

至少保留：

  • tool raw result

  • model final answer

否则你排查不了问题到底出在哪一层：

  • 没调工具

  • 调错工具

  • 参数错了

  • 工具挂了

  • 模型误读了结果

4. 多工具串联时，顺序没错，状态乱了

单工具调用只是开始。

真实业务里很快就会出现多步链路：

  • 先搜客户，再查订单，再生成回复

  • 先查天气，再判断条件，再创建提醒

  • 先查数据库，再调外部 API，再写回系统

这时候问题会从“会不会调”升级成“会不会串”。

常见故障包括：

  • 工具调用顺序不对

  • 上一步结果没正确传到下一步

  • 模型忘了之前拿到的实体

  • 工具 A 的输出格式，工具 B 吃不进去

  • 多轮之后状态描述越来越漂

工程建议

4.1 不要把状态只存成自然语言

如果所有中间状态都靠模型“记住”，系统迟早会乱。

更稳的做法是维护结构化执行状态，例如：

{
  "step": "query_order",
  "user_id": "u_123",
  "order_id": "o_456",
  "weather_checked": false,
  "last_tool_result": {...}
}

4.2 工具之间尽量走结构，不要走自由摘要

模型可以负责“决定做什么”，但状态传递最好由程序控制，而不是让模型自己改写一遍又一遍。

4.3 明确失败后的流程

你要提前定义：

  • 哪一步失败后终止

  • 哪一步允许重试

  • 哪一步可以降级

  • 哪一步必须人工接管

不然模型只会“继续生成点什么”，不会“正确收尾”。

5. 工具失败时，模型不会优雅失败

现实里的工具一定会失败：

  • 超时

  • 500

  • 空结果

  • 限流

  • 权限不足

  • 参数校验失败

而很多 Tool Calling Demo 根本没有认真设计失败路径。

结果通常是：

  • 工具挂了，模型继续编

  • 失败信息直接原样暴露给用户

  • 多步链路里前面失败了，后面还继续跑

工程建议

5.1 明确区分成功、可重试失败、不可重试失败

不要只把错误塞成一句文本。

系统层需要能区分：

  • success

  • retryable_error

  • non_retryable_error

  • validation_error

  • permission_error

5.2 模型看的错误信息，和系统日志里的错误信息分开

模型需要的是“下一步该怎么做”，系统需要的是“出了什么故障”。

这两个目标不一样，不应该用同一份错误文案。

5.3 设计失败体验，不要只设计成功体验

比起编个答案，诚实失败通常更好：

  • “我现在没查到实时天气，你要不要稍后重试？”

  • “订单系统暂时不可用，我可以先帮你整理问题。”

  • “我不能直接执行这个操作，但可以先给你生成执行计划。”

6. 有副作用的工具，不能和只读工具同级对待

这是生产里最危险的坑。

查询工具通常是只读的：

  • 查天气

  • 查数据库

  • 查知识库

  • 查工单

但真实业务里一定会出现写操作工具：

  • 发邮件

  • 发消息

  • 创建提醒

  • 修改订单

  • 写数据库

  • 调支付接口

  • 删除资源

如果这些工具和查询工具放在同一个自由调用层级里，风险会非常高。

因为模型不是天然理解“副作用成本”的。

工程建议

6.1 对工具做风险分级

至少分成：

  • 只读工具

  • 低风险写工具

  • 高风险写工具

6.2 高风险工具走二阶段执行

不要让模型一句话就能直接触发外部动作。

更稳的模式是：

  • 模型生成动作计划

  • 用户或系统确认

  • 再真正执行

6.3 幂等、权限、审计必须是系统责任

不要把安全寄托在 prompt 上。

生产系统里，高风险工具必须具备：

  • 权限检查

  • 参数校验

  • 幂等保护

  • 审计日志

  • 回滚或补偿机制

7. 你以为自己在调 prompt，其实你缺的是观测系统

很多团队一遇到 Tool Calling 问题，第一反应就是改 prompt。

但如果你没有足够好的观测，改 prompt 基本属于盲调。

你至少应该能看到：

  • 用户原始输入

  • 模型看到了哪些 tools

  • 模型选择了哪个 tool

  • 传了什么 arguments

  • tool raw result 是什么

  • final answer 是什么

  • 故障发生在哪一层

  • 延迟和 token 消耗如何

没有这些数据，你根本不知道问题出在：

  • 模型决策

  • 参数生成

  • 工具执行

  • 结果消费

  • 多步状态管理

工程建议

建议最少记录以下内容：

user_input
tool_candidates
tool_choice
tool_arguments
tool_raw_result
final_answer
error_type
latency_ms
token_usage

更进一步，可以把错误打成类型标签：

  • missed_tool_call

  • wrong_tool_call

  • invalid_arguments

  • tool_execution_failed

  • result_misread

  • unsafe_action

  • chain_state_error

当你能按这个维度看系统时，优化才真正开始变得可做。

一个更现实的结论：Tool Calling 的本质不是“会调工具”，而是“受控执行”

很多人第一次做 Tool Calling，目标是：

让模型学会调用工具。

但从工程角度看，真正的目标其实应该是：

让系统在模型、工具、网络、输入都不完全可靠的情况下，仍然可控地执行。

这两者差别非常大。

前者是 Demo 目标。

后者才是生产目标。

真正能上线的 Tool Calling 系统，通常都有这些共同点：

  • 工具 schema 足够克制

  • 参数校验严格

  • 工具分级清晰

  • 失败路径完整

  • 多步状态结构化

  • 关键结果不过度依赖模型自由总结

  • 日志可回放、可追责、可分析

换句话说：

生产级 Tool Calling 的关键，不是把模型放得更开，而是把系统收得更稳。

给 AI 应用开发者的一份 Checklist

如果你准备把 Tool Calling 用进真实业务，建议至少检查下面这些问题。

决策层

  • 哪些问题必须调工具？

  • 哪些问题可以直接回答？

  • 哪些问题必须人工确认后执行？

工具定义层

  • schema 是否清晰、单义、低歧义？

  • 参数是否可校验？

  • 是否把复杂解析过度丢给了模型？

执行层

  • 工具有没有超时、重试和错误分类？

  • 写操作工具是否分级？

  • 是否有幂等、防误触和审计机制？

结果层

  • 关键结果是否应该程序化渲染？

  • 模型是否可能误读 tool result？

  • 结构化结果是否被完整保存？

状态层

  • 多步任务是否有结构化状态？

  • 工具间数据传递是程序控制还是自然语言控制？

  • 失败后是否有明确中止或降级路径？

观测层

  • 能否完整看到 tool choice 和 tool arguments？

  • 能否看到 raw result 和 final answer？

  • 能否区分模型错误和工具错误？

  • 能否统计常见失败类型？

如果这些问题还没有答案，那你的系统大概率还处在“能演示”的阶段，而不是“能上线”的阶段。

结语

Tool Calling 是大模型应用真正走向实用的关键能力。

因为它让模型第一次不只是“生成内容”，而是“参与执行”。

但也正因为如此，它带来的不再只是提示词问题，而是一整套软件工程问题：

  • 决策是否可靠

  • 参数是否正确

  • 工具是否稳定

  • 结果是否被正确消费

  • 写操作是否安全

  • 系统是否可观测、可追责、可回退

所以，Tool Calling 真正难的，不是调用，而是落地。

如果你把它当成一个 prompt 技巧，它很快就会出问题。

如果你把它当成一个受控执行系统来设计，它才会真正变成产品能力。

查看全部文章 →