Gemini Tool Retrieval:工具越来越多,Agent 如何按需读取参数说明?

本文根据截至 2026 年 11 月 20 日的 Google 公告和开发文档整理。该功能仍处于预览阶段,接口与支持范围可能调整。

1. 概要

给 Agent 接入工具时,开发者通常需要提供工具名称、用途和参数结构。

只有几个工具时,这些说明并不显眼。扩展到几十、上百个工具后,参数结构、字段解释和枚举值会占用越来越多上下文;用户这次只想查订单,却可能连报表、库存和工单工具的参数都一起读了。

2026 年 11 月 19 日,Google 发布 Tool Retrieval,在 Gemini Interactions API 中预览。开发者可以让部分工具延迟加载,等模型需要时再读取完整参数结构。

2. 主要内容

2.1 延迟加载的重点是参数结构

一个函数工具通常包含:

json 复制代码
{
  "name": "get_order_status",
  "description": "根据订单编号查询订单状态",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string"
      }
    },
    "required": ["order_id"]
  }
}

其中,parameters 就是参数 Schema。真实业务中的 Schema 往往更复杂,可能包含多个嵌套对象、分页条件和大量可选字段。

服务端 Tool Retrieval 的基本方式是:

  • 模型先看到延迟工具的名称与描述。
  • 完整参数结构暂时不进入初始上下文。
  • 模型按名称请求需要的工具定义。
  • API 加载定义后,模型再生成函数调用。

这意味着工具命名和描述仍然重要。模型需要先知道有哪些能力,才能决定读取哪份参数说明。

2.2 "查找工具"与"执行业务"是两个步骤

用查询订单举例:

text 复制代码
用户:查一下订单 A-1042 到哪了
    ↓
模型发现 get_order_status 可能有用
    ↓
请求加载它的参数结构
    ↓
API 返回参数定义
    ↓
模型生成 order_id = A-1042 的函数调用
    ↓
业务后端执行查询
    ↓
返回结果,由模型回答

官方服务端模式可以在同一次 API 请求内部完成工具定义的查找与加载,但业务函数仍需要应用执行,并回传执行结果。

这里容易误解的是"同一次 API 请求":

它不表示整个过程只有一次内部模型处理,也不表示数据库查询、退款或工单操作会自动由 Google 完成。

2.3 如何开启服务端延迟加载

基本配置包含两个部分:

json 复制代码
{
  "tools": [
    {
      "type": "tool_search"
    },
    {
      "type": "function",
      "name": "get_order_status",
      "description": "根据订单编号查询订单状态",
      "defer_loading": true,
      "parameters": {
        "type": "object",
        "properties": {
          "order_id": {
            "type": "string"
          }
        },
        "required": ["order_id"]
      }
    }
  ]
}

这个示例只展示工具配置片段。

按照当前开发文档,功能使用 Interactions API 的 v1beta 版本,不能直接把同样的配置当作 generateContent 功能使用。

另外,延迟加载并不意味着客户端不再提交完整工具定义 。当前服务端模式仍要求每次请求发送完整的 tools 数组;延迟的是参数结构进入模型上下文的时机。

2.4 企业也可以自己决定返回哪些工具

如果工具目录需要结合用户权限动态生成,可以考虑客户端检索模式:

json 复制代码
{
  "type": "tool_search",
  "execution": "client",
  "name": "search_tool_registry",
  "description": "查找当前用户可使用的业务工具",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string"
      }
    },
    "required": ["query"]
  }
}

在这种模式下,模型调用搜索函数,应用查询自己的工具目录,再返回匹配的函数定义。检索逻辑可以采用名称匹配、规则或语义检索,但这些需要应用自己实现。

客户端模式会增加往返请求,且配置方式与服务端的 defer_loading 模式不同,不应直接混用。

2.5 能省多少成本,要看整项任务

可以用一个简化假设理解收益:

  • 有 100 个工具。
  • 每个完整参数结构平均占 300 token。
  • 某次任务只需要其中 3 个。

全部加载对应约 30,000 token 的参数结构;按需加载则可能只需要其中约 900 token。

但这只比较了 Schema 大小。实际账单还要计算工具目录、检索步骤、历史上下文和额外模型处理的 token。

官方没有为 Tool Retrieval 单独收费,但相关 token 仍按模型费率计算。**一次 API 请求中发生的内部工具搜索,也可能增加输入侧用量。**因此应对比整项任务的总用量和成本,而不只看首个请求的输入 token。

3. 对于生产项目的参考

3.1 先判断工具定义是否真的是主要负担

不是所有 Agent 都值得增加这一层。

如果系统只有几个参数简单、经常共同使用的工具,直接加载通常更容易维护。工具数量多、Schema 复杂,而且多数工具低频使用时,按需加载更值得评估。

可以先统计:

指标 用途
工具定义占总输入的比例 判断优化空间
每次任务实际使用的工具数量 判断闲置定义有多少
工具选择错误率 判断是否存在能力混淆
完成任务需要的请求次数 判断额外检索开销
整项任务成本和耗时 判断最终收益

高频工具可以保持直接加载,低频工具再尝试延迟加载,不必一次性全部迁移。

3.2 工具描述要写清业务边界

比较下面两个描述:

text 复制代码
处理订单。
text 复制代码
根据订单编号查询物流进度和履约状态,不修改订单。

第二种描述更容易帮助模型判断何时该用这个工具。

对于名称相近的工具,还应明确区别:

工具 描述中需要说明的内容
查询订单 返回哪些状态,是否只读
查询物流 需要订单号还是运单号
取消订单 哪些订单可以取消
申请退款 只是提交申请,还是立即退款

这些边界既能帮助选择工具,也便于人审查工具设计。

3.3 返回工具定义前过滤权限,执行时再次检查

以企业业务助手为例,用户要求"修改客户合同"。

工具目录不能只因为语义相关,就把所有合同管理工具都返回。应先确认当前用户可访问哪些客户、哪些合同,以及是否有修改权限。

工具实际执行时,后端还需要再次校验。工具被模型发现,只说明它进入了候选能力范围,不表示业务已经获得授权。

对于客户端检索模式,应用可以在返回定义前执行权限过滤;无论采用哪种检索方式,最终执行入口都应负责身份、参数与操作权限检查。

3.4 将"工具没找到"和"工具执行失败"分开记录

两者需要不同的处理方式。

text 复制代码
工具没找到
→ 检查目录、描述、权限范围和检索策略

工具找到了,但参数错误
→ 检查 Schema、参数生成和输入校验

工具调用成功,但业务失败
→ 检查业务状态、依赖系统与错误返回

如果日志里只有"Agent 任务失败",很难判断应该优化提示词,还是修复工具接入。

建议串联记录工具发现、定义加载、函数调用与执行结果,并对敏感参数做脱敏。这样既能排查错误,也能统计"额外搜索是否换来了更高成功率"。

3.5 用同一批任务比较迁移前后的表现

可以选择三组任务:

  1. 只需一个常用工具。
  2. 需要几个不同业务工具协作。
  3. 容易混淆相近工具,或涉及权限边界。

对照直接加载与按需加载两种方案,保持任务、工具实现和模型设置尽量一致,比较完成率、错误调用次数、总 token、耗时和总成本。

如果 Schema 占用下降,但模型反复搜索、选错工具或增加了大量往返,仍然需要调整。生产接入的目标应是让任务更稳定、更划算地完成。

相关推荐
用户19172912708318 分钟前
Agent 工具面裁剪:动态暴露与渐进披露(附 Python 代码)
人工智能
AI前端工程狮19 分钟前
我给 MCP 长任务加进度条,五步只显示了一步
javascript·人工智能·程序员
TsingtaoAI21 分钟前
VeyForge:构建具身智能的AI 3D资产与Sim-to-Real数据引擎
人工智能·机器学习
螺丝钉tina43 分钟前
[Playwright] [21][AI] 千问生成测试的完整 mini demo
人工智能
高洁011 小时前
世界模型的因果内核:从预测表象到理解机制
人工智能·python·深度学习·transformer·迁移学习
Forget the Dream1 小时前
Spring AI 2.0 系列(三):ChatClient 与 ChatModel:Spring AI 2.0 的两层职责
java·人工智能·spring·springai
syso_稻草人1 小时前
qwen-image-2.1 姿态控制拆解:SDPose 提骨架 + Fun-ControlNet-Union 锁姿势,换人换景不换姿势
人工智能·stable diffusion·prompt·提示词优化·qwen-image
Baihai_IDP1 小时前
大模型 API 真的在赔本赚吆喝吗?聊聊 Token 背后的真实成本
人工智能·llm·aigc
数字融合1 小时前
透明化视频动态三维重建空间数据零核心技术
人工智能·python·virtualenv