03 · Tool Calling：让模型能做事，也让调用可控

1. 工具层在Agent里处于什么位置？

Prompt表达任务要求，模型据此提出下一步；工具层把这些请求接到真实业务能力上。它处在Harness与订单、商品、文件等系统之间，负责描述能力、检查请求、组织执行，再把结果或错误交回模型。

提示词可以要求“分析昨晚直播的成交额”，却不能让模型凭空知道店铺数据。查询订单、计算指标、读取文件或发送通知，都需要应用提供实际能力。

Tool就是开放给模型使用的能力。Tool Calling指模型提出工具名和参数、程序检查执行、结果回传的过程。工具层同时要控制权限、返回规模与调用消耗，避免模型选错、填错或不断重试。

2. Tool、Function Calling和API是什么关系？

传统后端分析直播数据，由业务代码决定先调订单接口，再调流量接口。Agent可以让模型提出下一步，实际执行仍可复用这些接口。

不同平台命名有所交叉；工具还可以包括平台内置搜索、代码执行等能力。这里重点讲我们自己封装的业务工具。

不要机械地把每个API都变成一个工具。查两场直播、统一口径、计算差额，可以组合成一个“对比直播成交额”的能力；但也不宜做一个把查询、分析、发通知全部绑在一起的万能工具，否则权限、失败与重试都难拆开处理。

3. 一次工具调用，实际经过哪些地方？

应用先把可用工具的定义交给模型。模型返回工具请求后，Harness找到对应实现，检查参数、权限和预算，再调用业务服务。

结果要按模型接口协议与对应调用关联后，进入后续模型请求。并行调用时尤其不能把订单查询结果误配给流量查询；调用标识用于关联一次请求与反馈，不等于后面讲的业务幂等键。

工具执行不了，也要返回明确的错误或任务状态。只打印服务器日志，模型并不知道发生了什么；但堆栈、密钥和完整内部响应，也不该原样交给它。

4. 工具定义和Schema，要解决什么问题？

工具名、描述和参数说明，会影响模型能否选对能力。叫“查询数据”，模型很难知道该用它查什么；叫“对比直播成交额”，还要说明比较口径、适用条件和不支持的范围。

Schema是一份参数结构约定，描述字段、类型、必填项和允许值。以这个工具为例：

Schema能约束结构，不能证明业务合法。两个场次标识都是字符串，也可能属于别人的店铺。店铺归属与权限应由程序根据认证身份校验，不能相信模型自己填写的用户或租户身份。

还要检查时间先后、查询跨度、条数上限等业务条件。支持严格参数约束的模型接口可以帮助减少格式错误，服务端校验仍要保留；流式参数还没接收完整时，不应抢先执行。

超出范围就明确拒绝或要求调整；如果产品允许缩小查询范围，也要返回实际范围，不能悄悄缩小后仍声称查了全部。

5. 工具返回得越多，模型就越懂吗？

直播分析可能涉及商品、订单、流量记录和海量历史数据。把这些原始明细全返回，模型未必能抓住关键证据，后续请求还要继续携带这些内容。

结果过大，可能导致输入费用与延迟上升、重点被忽略，甚至挤掉其他必要信息。触发摘要或压缩后，如果口径和来源没保留，还可能引发重复查询。第02篇的前缀缓存也不能替你解决信息冗余。

对成交额这种精确指标，应由数据服务按口径计算，返回必要金额和差额，不让模型从大量订单行里自己累加。比如下面是虚构教学结果：

这里的来源标识需要有对应记录或读取能力，不能只是给模型一个无法核对的编号。

工具层要控制字段、行数和响应大小。需要明细时按页读取，告诉模型是否还有下一页；别让模型把第一页当全部。完整聚合结果和明细分页是两种情况，应分别说明覆盖范围。

也不要用截字符串的方式硬切JSON。先限制查询与返回结构，再检查大小；无法完整返回时，给出明确的分页、缩小范围或单独读取方案。

6. 模型反复调用，怎样避免无意义查询？

模型看到的信息不足、错误含糊，或者忘记前面查过什么，都可能再次提出相同请求。先记录工具名、规范化参数、结果和实际数据范围，才能判断是在补查，还是在重复查。

对已成功的只读查询，在权限、指标口径、数据版本和时效要求一致的前提下，可以复用结果。直播实时流量不断变化，不能因为参数相同就永远返回旧值；改了时间范围或筛选条件，也不能误用旧结果。

重复请求仍要消耗逻辑调用额度。并行请求也要受任务、用户及下游服务的并发限制；两个查询都依赖同一数据库，并不意味着可以无限并行。

工具定义本身也会占用输入。先给当前任务需要的能力，描述清楚，避免大量含义重叠的工具一起出现。筛选和加载工具时，同时考虑第02篇提到的前缀稳定性，但不能为了缓存保留不该开放的能力。

7. 错误要让程序和模型都知道下一步怎么办

只返回“失败了”，很难判断该改参数、等待，还是结束。可以用稳定错误类别和简短说明区分：

错误中可以表达是否具备重试条件，最终还得由程序结合剩余预算、权限和任务状态决定。不能仅凭模型说“再试一次”，就开始下一次访问。

8. 重试、超时、熔断，要控制到哪一层？

常见的放大来自两层：接口客户端或SDK（服务方提供的调用库）自动重试，模型收到失败后又发起同一工具请求。

假设模型连续提出3次相同查询，每次客户端最多尝试3次，包含首次调用，没有共同预算时，下游最多收到9次请求。这是示意配置，不是推荐次数。

需要同时控制：单次调用超时、单次工具内的最大尝试数、整个任务的调用与实际尝试额度，以及总截止时间。不要每收到一个新的工具请求，就把额度重新算满。并发执行时，额度检查与占用要原子化，避免多个请求同时通过检查后超额。

选择一个明确的层负责下游重试，计入SDK已有行为。只对适合重试的错误退避等待，并加入随机抖动，避免同时冲击依赖；剩余时间不够，就不要启动下一次尝试。

限流控制访问速率和并发；熔断在依赖持续故障时暂时阻止访问，按策略探测恢复。任务预算则防止一个分析任务不断请求。三者作用不同，不能只在提示词里写“少查几次”。

超时或取消也不一定让远端操作立即停止。调用方应尽力传播取消、停止启动新操作；无法中断的远端执行，要保留结果未知等状态。跨执行者恢复放在长任务稳定性专题展开。

9. 查询重试和动作重试，有什么区别？

重新查成交额通常不会产生业务写入，但仍会增加负载；重新发送报告通知，则可能通知两次。

写操作要使用业务幂等机制：给同一个获准动作分配稳定标识，重试继续使用它，由执行服务核对并避免重复生效。不能每次重试重新生成一个键，也不能简单按参数相同，把用户两次独立授权的动作合并。

远端成功、响应丢失时，要按该标识查询结果或对账。模型这次生成的工具调用标识，只用于关联这次请求，未必能标识跨重试的同一个业务动作。授权与动作生命周期在输出校验和动作执行篇细讲。

10. 做一个工具，怎样检查有没有做好？

先用固定样例检查实现，再通过模型看它能否选对、填对和理解反馈。例如：正常查询、错误参数、越权请求、超大结果、下游超时、模型重复请求、写操作结果未知。

记录任务标识、工具调用标识、工具版本、耗时、返回大小、错误类别、重试次数和预算消耗。业务事实进入模型需要的结果中；执行元数据进入观测记录，敏感信息按需脱敏。完整原始响应不等于应该记录或交给模型的内容。

这一篇的重点，是能解释工具怎样把模型与实际能力连接起来，以及参数、结果和调用治理分别管什么。工具能调用成功，只是起点；返回是否足够、失败能否收住、重试会不会重复生效，都要检查。

下一篇进入Context Engineering：工具结果、历史消息和任务要求一起增长时，每一轮该让模型看到哪些信息。