Gemini API 推出工具检索功能

查看产品与平台全部内容
查看创新与 AI 全部内容
查看产品与平台全部内容
在 Gemini API 中引入工具检索
在 Gemini API 中引入工具检索
工具检索现已在 Gemini Interactions API 中开启预览。按需加载工具参数 schema,无需在每次提示中发送完整的工具库,旨在减少输入 Token,并在你的智能体规模扩展时保持工具选择的准确性。
Gemini API 产品经理
Google DeepMind 研究科学家
您的浏览器不支持音频元素。
我们在 Gemini API 中推出工具检索(Tool Retrieval),帮助你的智能体更高效地管理大型工具库。通过仅在需要时加载参数架构,你可以降低复杂任务中的延迟和输入 Token 成本。你今天就可以在 Interactions API 中试用该功能,只需添加一个 tool_search 工具,并在请求中将 defer_loading 设为 true。
摘要由 Google AI 生成。生成式 AI 仍处于实验阶段。
我们在 Gemini API 中推出工具检索(Tool Retrieval),帮助你管理大型工具库。
该功能仅在需要时加载参数架构,从而减少输入 Token 数量和延迟。
你只需添加一个工具搜索,并将 defer loading 设为 true,即可启用该功能。
工具检索可与 Gemini 3.6 及更高版本的模型配合使用,为你的复杂智能体任务提供支持。
摘要由 Google AI 生成。生成式 AI 仍处于实验阶段。
我们推出 Tool Retrieval,帮助开发者更高效地管理庞大的软件工具集合。智能体不再一次性加载所有工具,而是将一个工具库保持在待命状态,只拉取当前任务所需的特定细节。这减少了数据用量、加快了性能表现,并提升了准确性。从今天起,你就可以配合我们最新的 Gemini 模型使用这一功能,构建能力更强、响应更快的应用。
摘要由 Google AI 生成。生成式 AI 仍处于实验阶段。
今天我们在 Gemini API 中推出 Tool Retrieval,现已在 Interactions API 中提供预览版。
当智能体连接数十甚至数百个工具时,每次请求都发送完整的参数 schema 会迅速累积开销。它会推高输入 Token 数量、增加延迟,并随着候选列表扩大而降低工具选择的准确率。Tool Retrieval 让智能体将完整工具库保持在待命状态,仅当当前任务需要时才加载参数 schema。
要开启 Tool Retrieval,请在请求中添加一个 tool_search 工具,并对你希望暂缓加载的工具设置 defer_loading: true。模型仍能看到每个被延迟加载工具的名称和描述,因此知道有哪些工具可用,但参数 schema 不会进入上下文。当模型需要某个工具时,它会按名称请求该工具,API 加载完整 schema,模型随即调用该函数——全部都在同一个请求内完成。
from google import genai client = genai.Client() tools = [ {"type": "tool_search"}, { "type": "function", "name": "issue_refund", "description": "将订单退款至原支付方式。", "defer_loading": True, "parameters": { "type": "object", "properties": { "order_id": {"type": "string"}, "amount": {"type": "number"}, }, "required": ["order_id", "amount"], }, }, # ... 另有 50+ 个延迟加载函数(将高频工具保持非延迟加载) ] interaction = client.interactions.create( model="gemini-4-hydrogen", input="订单 A-1042 到货时已损坏。请退款 40 美元。", tools=tools, )
在这单个 API 调用内部,模型会搜索 issue_refund,API 加载其 schema,然后模型发出 function_call。这三个步骤都会出现在 interaction.steps 中,因此在调试工具名称或描述时,很容易检查模型考虑了哪些工具:
"steps": [ { "type": "tool_search_call", "id": "tsc_7f2a", "arguments": {"function_names": ["issue_refund"]}, "signature": "..." }, { "type": "tool_search_result", "call_id": "tsc_7f2a", "result": [{"type": "function", "name": "issue_refund", "parameters": {...}}], "signature": "..." }, { "type": "function_call", "id": "fc_91c3", "name": "issue_refund", "arguments": {"order_id": "A-1042", "amount": 40} } ]
从这里开始就是常规的函数调用:你的代码执行退款,并回传一个 function_result。
无需构建或托管索引。Gemini 在服务器端运行搜索,因此你的代码唯一的变化就是新增的工具,以及在想要延迟加载的工具上加一个标志。你可以将最常用的工具保持预先加载,而将长尾工具延迟加载。
Tool Retrieval 与前缀缓存也能很好地配合。被延迟的 schema 不会出现在 prompt 的开头,而模型加载的 schema 是在对话较后位置加入的,因此缓存的前缀在每一轮之间保持不变。
Tool Retrieval 同样适用于 Gemini API 中的远程 MCP 服务器。在 mcp_server 工具上设置 defer_loading: true,该服务器暴露的每个工具都会按需加载,这样你就能连接一个大型服务器,而无需逐个列出其工具。
客户端检索的工作方式
如果你维护自己的工具注册表、嵌入索引或按用户划分的权限过滤器,就用 "execution": "client" 声明 tool_search,并定义你的搜索参数。客户端检索每次搜索会增加一次往返,因为查询是由你的应用执行的。工具无需预先声明,因此当用户接入某个集成时,你也可以在对话中途暴露新工具:
tools = [{ "type": "tool_search", "execution": "client", "name": "search_tools", "description": "Search the internal tool registry for functions.", "parameters": { "type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"], }, }] # 当模型为 "search_tools" 发出 function_call 时, # 在 function_result 中返回匹配的 {"type": "function", ...} schema: followup = client.interactions.create( model="gemini-4-hydrogen", previous_interaction_id=interaction.id, tools=tools, input=[{ "type": "function_result", "name": "search_tools", "call_id": step.id, "result": my_registry.search(**step.arguments), }], )
定价与支持的模型如何运作
Tool Retrieval 不单独收费。输入和输出 Token 按你所调用模型的标准费率计费。开启 tool_search 会增加一小段固定的输入 Token,而模型加载的每个 schema,在之后的对话中都会作为输入计费,与一开始就声明的工具相同。当从未加载的 schema 多于实际加载的 schema 时,你就能省下 Token——对于大型工具库而言这通常是常态。请结合你自己的实际流量来评估。
Tool Retrieval 适用于 Gemini 3.6 及更高版本的模型,包括所有 Gemini 4 模型,在 Interactions API 中使用。
阅读文档——包含示例的完整设置指南
对比 Gemini 模型——为你的使用场景找到最合适的模型
加入 Discord 讨论——与团队分享反馈
译文由英文原文机器翻译,术语按行业惯例统一,可在文末展开原文核对。
查看英文原文(Introducing Tool Retrieval in the Gemini API)
See all in Products & platforms
See all in Innovation & AI
See all in Products & platforms
Introducing Tool Retrieval in the Gemini API
Introducing Tool Retrieval in the Gemini API
Tool Retrieval is now in preview in the Gemini Interactions API. Load tool parameter schemas on demand instead of sending your full tool library in every prompt,designed to reduce input tokens and keep tool selection accurate as your agent scales.
Product Manager, Gemini API
Research Scientist, Google DeepMind

Your browser does not support the audio element.
We are launching Tool Retrieval in the Gemini API to help your agents manage large tool libraries more efficiently. By loading parameter schemas only when needed, you reduce latency and input token costs for complex tasks. You can try this feature today in the Interactions API by adding a tool_search tool and setting defer_loading to true in your requests.
Summaries were generated by Google AI. Generative AI is experimental.
We are launching Tool Retrieval in the Gemini API to help you manage large tool libraries.
This feature reduces input token counts and latency by loading parameter schemas only when needed.
You can enable this by adding a tool search and setting defer loading to true.
Tool Retrieval works with Gemini 3.6 and later models to support your complex agent tasks.
Summaries were generated by Google AI. Generative AI is experimental.
We are introducing Tool Retrieval to help developers manage large collections of software tools more efficiently. Instead of loading every tool at once, your agent now keeps a library on standby and only pulls in the specific details it needs for a task. This reduces data usage, speeds up performance, and improves accuracy. You can start using this feature today with our latest Gemini models to build more capable and responsive applications.
Summaries were generated by Google AI. Generative AI is experimental.
Today we're launching Tool Retrieval in the Gemini API, available in preview in the Interactions API.
When an agent connects to dozens or even hundreds of tools, sending every full parameter schema on every request adds up fast. It inflates input token counts, adds latency, and lowers tool-selection accuracy as the candidate list grows. Tool Retrieval lets your agent keep its full tool library on standby and load parameter schemas only when the current task needs them.
To turn on Tool Retrieval, add a tool_search tool to your request and set defer_loading: true on the tools you want to hold back. The model still sees the name and description of every deferred tool, so it knows what's available, but the parameter schemas stay out of context. When the model needs a tool, it asks for it by name, the API loads the full schema, and the model calls the function, all inside the same request.
from google import genai
client = genai.Client()
tools = [
{"type": "tool_search"},
{
"type": "function",
"name": "issue_refund",
"description": "Refund an order to the original payment method.",
"defer_loading": True,
"parameters": {
"type": "object",
"properties": {
"order_id": {"type": "string"},
"amount": {"type": "number"},
},
"required": ["order_id", "amount"],
},
},
# ... 50+ other deferred functions (leave frequent tools undeferred)
]
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="Order A-1042 arrived damaged. Please refund 40 dollars.",
tools=tools,
)
Inside that single API call, the model searches for issue_refund, the API loads its schema, and the model emits the function_call. All three steps appear in interaction.steps, making it easy to inspect which tools the model considered when debugging tool names or descriptions:
"steps": [
{
"type": "tool_search_call",
"id": "tsc_7f2a",
"arguments": {"function_names": ["issue_refund"]},
"signature": "..."
},
{
"type": "tool_search_result",
"call_id": "tsc_7f2a",
"result": [{"type": "function", "name": "issue_refund", "parameters": {...}}],
"signature": "..."
},
{
"type": "function_call",
"id": "fc_91c3",
"name": "issue_refund",
"arguments": {"order_id": "A-1042", "amount": 40}
}
]
From here it's normal function calling: your code runs the refund and sends back a function_result.
There's no index to build or host. Gemini runs the search on the server, so the only changes to your code are the new tool and a flag on the tools you want to defer. You can keep your most-used tools loaded up front and defer the long tail.
Tool Retrieval also plays well with prefix caching. Deferred schemas stay out of the start of the prompt, and the schemas the model loads are added later in the conversation, so the cached prefix stays the same from turn to turn.
Tool Retrieval also works with remote MCP servers in the Gemini API. Set defer_loading: true on an mcp_server tool and every tool that server exposes is loaded on demand, so you can connect a large server without listing its tools one by one.
How client-side retrieval works
If you maintain your own tool registry, embedding index, or per-user permission filter, declare the tool_search with "execution": "client" and define your search parameters. Client-side retrieval adds one round trip per search, because your app runs the lookup. Tools do not need to be declared upfront, so you can also expose new tools mid-conversation when a user connects an integration:
tools = [{
"type": "tool_search",
"execution": "client",
"name": "search_tools",
"description": "Search the internal tool registry for functions.",
"parameters": {
"type": "object",
"properties": {"query": {"type": "string"}},
"required": ["query"],
},
}]
# When the model emits a function_call for "search_tools",
# return matching {"type": "function", ...} schemas in function_result:
followup = client.interactions.create(
model="gemini-4-hydrogen",
previous_interaction_id=interaction.id,
tools=tools,
input=[{
"type": "function_result",
"name": "search_tools",
"call_id": step.id,
"result": my_registry.search(**step.arguments),
}],
)
How pricing and supported models work
Tool Retrieval has no separate charge. Input and output tokens are billed at the standard rates for the model you call. Turning on tool_search adds a small, fixed block of input tokens, and each schema the model loads is billed as input for the rest of the conversation, the same as a tool declared up front. You save tokens when the schemas you never load outweigh the ones you do, which is the usual case for large libraries. Measure it against your own traffic.
Tool Retrieval works with Gemini 3.6 and later models, including all Gemini 4 models, in the Interactions API.
Read the documentation — Full setup guide with examples
Compare Gemini models — Find the best model for your use case
Join the discussion on Discord — Share feedback with the team
原文为英文,正文由自动抓取并保留原文。
原文发布于 Google Blog(Introducing Tool Retrieval in the Gemini API),标题、摘要与正文由机器翻译,术语按行业惯例统一,未经人工逐句校订。