推荐:MeloLab– 使用 AI 创作歌曲和背景音乐。

Gemini API Tool Retrieval

打开官方网站

Gemini Interactions API 的 Tool Retrieval 通过 tool_search 与 defer_loading 按需加载工具 Schema,减少输入 token 并在智能体扩展时保持工具选择准确。

类型:
AI 工具
Gemini API Tool Retrieval 产品预览
本页目录

Gemini API Tool Retrieval 是什么?

Gemini Interactions API 的 Tool Retrieval 通过 tool_search 与 defer_loading 按需加载工具 Schema,减少输入 token 并在智能体扩展时保持工具选择准确。

最近更新 ·

Gemini API Tool Retrieval:Interactions API 中的按需工具 Schema 加载

资料对应公告日期:

Tool Retrieval 是 Gemini Interactions API 中的预览功能,它按需加载工具参数 Schema,而不是在每次提示中发送完整的工具库。启用方式是向请求添加 tool_search 工具,并对希望暂缓加载的工具设置 defer_loading 为 true。模型仍能看到每个被暂缓工具的名称和描述,因此知道有哪些工具可用,但完整 Schema 不会进入上下文,直到模型按名称请求某个工具。搜索由 Gemini 在服务端执行,因此无需构建或托管索引,除标准 token 计费外也没有额外费用。

宣布 Gemini API 推出 Tool Retrieval 的宣传图
产品方发布配图,非产品界面截图。

Tool Retrieval 是什么,解决什么问题

随着智能体规模扩大,工具库也会随之增长。在每次提示中发送每个工具的完整参数 Schema 会推高输入 token,并可能降低工具选择的可靠性。Tool Retrieval 旨在同时应对这两个问题:它按需加载工具参数 Schema,而不是每次都发送整个工具库,目标是减少输入 token,并在智能体扩展时保持工具选择准确。

该功能目前以预览形式在 Gemini Interactions API 中提供。它是服务端能力:搜索由 Gemini 执行,因此你无需构建或托管索引。

  • 按需加载工具参数 Schema,而非在每次提示中发送完整工具库
  • 旨在减少输入 token,并在智能体扩展时保持工具选择准确
  • 以预览形式在 Gemini Interactions API 中提供
  • 服务端搜索意味着无需构建或托管索引

如何通过 tool_search 和 defer_loading 启用 Tool Retrieval

启用 Tool Retrieval 需要对请求做两处改动。第一,向请求添加 tool_search 工具。第二,对每个希望暂缓加载 Schema 的工具设置 defer_loading 为 true。由于搜索由 Gemini 在服务端执行,这就是所需的全部代码改动。

暂缓加载并不会隐藏工具。模型仍能看到每个被暂缓工具的名称和描述,因此知道有哪些工具可用,但参数 Schema 不会进入上下文。当模型需要某个工具时,它会按名称请求,API 加载完整 Schema,模型随即调用该函数,整个过程都在同一个请求内完成。

  • 向请求添加 tool_search 工具
  • 对希望暂缓加载的工具设置 defer_loading: true
  • 被暂缓工具的名称和描述对模型仍然可见
  • Schema 按需加载,函数调用在同一请求内完成

在远程 MCP 服务器上使用 Tool Retrieval

Tool Retrieval 支持远程 MCP 服务器。你无需逐个列出服务器上的工具,只需对 mcp_server 工具设置 defer_loading 为 true,该服务器暴露的所有工具都会按需加载。这样就能在不预先枚举全部工具的情况下连接大型 MCP 服务器。

  • 对 mcp_server 工具设置 defer_loading: true
  • 该服务器暴露的所有工具都会按需加载
  • 适合连接大型服务器而无需逐个列出其工具

服务端检索与客户端检索的区别

默认情况下检索在 Gemini 一侧执行,因此无需构建或托管索引。客户端检索通过将 execution 设置为 client 来声明,在这种模式下由你的应用执行查找。代价是延迟:客户端检索每次搜索都会增加一次往返,因为查找由你的应用完成。

  • 服务端检索:由 Gemini 执行搜索,无需托管索引
  • 客户端检索:通过 execution 设置为 client 声明,由你的应用执行查找
  • 客户端检索每次搜索增加一次往返

计费与模型支持

Tool Retrieval 没有单独费用。输入和输出 token 按你所调用模型的标准费率计费。启用 tool_search 会增加一小段固定的输入 token,模型加载的每个 Schema 会在对话剩余部分作为输入计费,与预先声明的工具相同。

在 Interactions API 中,Tool Retrieval 适用于 Gemini 3.6 及更高版本模型,包括所有 Gemini 4 模型。

  • Tool Retrieval 无单独费用
  • 按标准输入和输出 token 费率计费
  • tool_search 增加一小段固定输入 token
  • 已加载的 Schema 在对话剩余部分作为输入计费
  • 在 Interactions API 中支持 Gemini 3.6 及更高版本,包括所有 Gemini 4 模型

如何开始使用

由于该功能处于预览阶段,实际的起点是在 Interactions API 中针对受支持的模型发起请求。添加 tool_search 工具,对希望暂缓加载的工具设置 defer_loading: true,其余工具声明保持不变。如果你依赖远程 MCP 服务器,请暂缓 mcp_server 工具,而不是逐个暂缓其中的工具。

估算成本时请记住,被暂缓的 Schema 并非免费:一旦加载,该 Schema 会在对话剩余部分作为输入计费。暂缓不常使用的工具正是该功能的设计思路,但具体节省取决于你的工具库和对话长度,因此应针对自身工作负载进行测量,而不是假定固定的降幅。

  • 从 Interactions API 中受支持的模型开始
  • 添加 tool_search,并对希望暂缓的工具设置 defer_loading: true
  • 暂缓 mcp_server 工具,而非逐个暂缓 MCP 工具
  • 考虑已加载 Schema 会在对话剩余部分作为输入计费

常见问题

Tool Retrieval 是否支持远程 MCP 服务器?

支持。对 mcp_server 工具设置 defer_loading 为 true,该服务器暴露的所有工具都会按需加载,因此可以连接大型服务器而无需逐个列出其工具。

Tool Retrieval 如何计费?

没有单独费用。输入和输出 token 按你所调用模型的标准费率计费。tool_search 会增加一小段固定输入 token,模型加载的每个 Schema 会在对话剩余部分作为输入计费,与预先声明的工具相同。

哪些 Gemini 模型支持 Tool Retrieval?

在 Interactions API 中,Tool Retrieval 适用于 Gemini 3.6 及更高版本模型,包括所有 Gemini 4 模型。

原始资料

  1. blog.google — 原始资料 1 ↗

工具信息

工具信息有变化? 帮助我们更新

相关工具与指南

加载评价…

Gemini API Tool Retrieval 的评价

暂无评分0 条真实用户评价

你推荐 Gemini API Tool Retrieval 吗?在下面分享使用体验!

评分
0 / 2000

正在加载评价…

所属分类

为产品创造者

做了一个好产品?让更多人发现它。

从官网开始,整理 Logo、截图和产品介绍,建立可持续维护的工具页面。

免费收录需核验官网 Badge