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 计费外也没有额外费用。

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 模型。
原始资料
工具信息
工具信息有变化? 帮助我们更新
Gemini API Tool Retrieval 的评价
正在加载评价…