Google 在 Gemini API 中推出了 Tool Retrieval,目前已在 Interactions API 中预览。Gemini API Tool Retrieval 让 agent 可以维持一个大型工具库。它不会在每次提示中都发送每个参数 schema。只有当任务需要某个工具时,模型才会加载该 schema。对于接入了数十个函数或 MCP 服务器的 agent,它针对的是一项真实成本:工具定义。你可以通过我们的 GPULeaderboard.com chrome 扩展查看部署选项和规格。
TL;DR
- 工具:一项 API 功能,未说明工具数量上限。Google 建议在工具稳定且少于 20 个时使用静态加载。
- 运行于:Google 的服务器(服务端搜索)或你自己的注册表(客户端)。仅限 Interactions API,v1beta。
- 性能:在服务端模式下,搜索、schema 加载和函数调用在 1 次 API 请求中完成。
- 最佳:服务端检索无需额外往返,也无需托管索引。
什么是 Gemini API Tool Retrieval?
Tool Retrieval 是一项 Gemini API 功能,它会推迟工具参数 schema,直到模型请求时才提供。Google 的文档直白地说明了问题。几十个函数声明在每次请求中可能消耗数万个 token。
通过推迟,模型只能看到每个工具的名称和简短描述。在检索之前,它看不到参数 schema。
defer_loading 在 Gemini Interactions API 中如何工作?
你将 {"type": "tool_search"} 添加到 tools 数组中。然后对每个要推迟的函数设置 defer_loading: true。@googledevs 的发布帖展示了在 gemini-4-hydrogen 上一个被推迟的 issue_refund 函数。其代码注释提到另外 50+ 个被推迟的函数。
当模型需要一个被推迟的工具时,响应包含 3 个步骤:
- tool_search_call:模型按名称请求一个工具。
- tool_search_result:API 返回完整的 schema。
- function_call:模型发出由你的代码执行的调用。
API 自行解析前 2 个步骤。你的应用只运行 function_call 并返回 function_result。
被推迟的函数可以携带一个可选的 short_description。它在检索期间显示,且仅在 defer_loading 为 true 时有效。
服务端检索 vs 客户端检索
服务端是默认方式。Gemini 运行搜索,因此无需构建或托管索引。
客户端模式使用 "execution": "client"。你的应用运行自己的查找,例如嵌入索引、注册表或权限过滤器。它在 function_result.result 中返回匹配的声明。这些工具可以在对话中途加入,即使它们不在初始 tools 数组中。每次客户端搜索会多花 1 次往返。
这 2 种模式不能在同 1 次请求中组合使用。每次请求只允许 1 个 tool_search 条目。
它能与 MCP 服务器和前缀缓存一起使用吗?
两者都可以,但有注意事项。对 mcp_server 条目设置 defer_loading: true 会推迟该服务器暴露的所有工具。被推迟的 MCP 工具仍通过 Gemini API 的 MCP 支持远程执行。
关于缓存,被推迟的 schema 不会进入提示前缀。已加载的 schema 以内联方式追加,因此隐式缓存仍然适用。文档补充了一个注意点:推迟工具可能会使提示缩小到低于最小可缓存大小。
Tool Retrieval 的费用是多少?
没有单独的费用。Token 按模型的标准输入、缓存和输出费率计费。每次服务端搜索都会对完整上下文触发一次额外的模型调用。这些 token 出现在 total_tool_use_tokens 中,按输入费率计费。
之后每个已加载的 schema 会在对话剩余部分持续按输入计费。文档表示,对于小型工具库或逐轮搜索,静态加载可能成本更低。
它与 Claude 和 OpenAI 的工具搜索相比如何?
Anthropic 和 OpenAI 已经推出了类似的工具搜索功能,并公布了节省数据。
| 功能 | Gemini API Tool Retrieval | Anthropic Tool Search Tool | OpenAI tool search |
|---|---|---|---|
| 状态 | 预览版,v1beta | 文档页面未披露 | 文档页面未披露 |
| API 接口 | 仅 Interactions API | Messages API;Bedrock InvokeModel | Responses API |
| 模型 | Gemini 4 Carbon、Neon、Hydrogen、Argon;3.8 Flash;3.6 Flash | Claude 5 系列、Opus 4.5+、Sonnet 4.5+、Haiku 4.5 | gpt-5.4 及更高版本 |
| 搜索模式 | 服务端或客户端 | Regex、BM25 或自定义 | 托管或客户端执行 |
| 最大延迟工具数 | 未披露 | 10,000 | 未披露 |
| 每次搜索结果数 | 未披露 | 默认 5 | 未披露 |
| MCP 延迟 | 按 mcp_server 条目 | 按 mcp_toolset | 按 MCP 服务器工具 |
| 单独收费 | 否 | 否 | 未披露 |
| 公布的 token 节省 | 无 | 85%(77K 降至 8.7K tokens) | 250 个 MCP Atlas 任务上节省 47% |
| 公布的准确率 | 无 | Opus 4.5:79.5% 至 88.1% | 未披露 |
Anthropic 和 OpenAI 的数据来自其各自测试中的自报结果。它们与任何 Gemini 结果均不可比。
关键要点
- Gemini API Tool Retrieval 会延迟工具 schema,直到模型请求时才加载。
- 服务端模式在 1 次 API 请求中完成搜索、加载和调用。
- 客户端模式支持自定义注册表,每次搜索额外增加 1 次往返。
- 不额外收费,但已加载的 schema 会持续计费且无法卸载。
- Google 未公布节省数据;Anthropic 报告 85%,OpenAI 报告 47%。
查看 Google 博客文章、Tool Retrieval 文档和 MCP 函数调用文档。你可以通过我们的 GPULeaderboard.com Chrome 扩展在此查看部署选项和规格。
另外,欢迎在 Twitter 上关注我们,别忘了加入我们 150k+ 的 ML SubReddit 并订阅我们的 Newsletter。等等!你在 Telegram 上吗?现在你也可以在 Telegram 上加入我们。
需要与我们合作推广你的 GitHub Repo 或 Hugging Face Page 或产品发布或网络研讨会等?联系我们

Michal Sutter 是一名数据科学专业人士,拥有帕多瓦大学数据科学理学硕士学位。凭借在统计分析、机器学习和数据工程方面的扎实基础,Michal 擅长将复杂数据集转化为可执行的洞察。
- Michal Sutter来自哥伦比亚大学和 CertiK 的一组研究人员推出 TensorLean,用于 GPU 内核的形式化验证
- Michal SutterOpenAI 为语音代理发布 GPT-Live-1.1,将空闲成本降至 $0.02/分钟
- Michal SutterMeta FAIR 自改进记忆在持续学习基准上达到 56.0
- Michal SutterPerplexity 推出用于故障转移和模型路由的 Orchestrator API