2026年11月19日
| Gemini Interactions API 中的工具检索功能现已进入预览阶段。按需加载工具参数模式,而不是在每次提示中发送完整的工具库,旨在减少输入标记数量,并在智能体扩展时保持工具选择的准确性。
Lucia Loher
Gemini API 产品经理
Nora Kassner
Google DeepMind 研究科学家

您的浏览器不支持音频元素。
收听文章
[[duration]] 分钟
此内容由 Google AI 生成。生成式 AI 处于实验阶段
今天,我们在 Gemini API 中推出了工具检索功能,该功能可在 Interactions API 中以预览形式使用。
当智能体连接到数十甚至数百个工具时,在每次请求中发送每个工具的完整参数模式会迅速累积。这会膨胀输入标记数量,增加延迟,并随着候选列表的增长而降低工具选择的准确性。工具检索允许您的智能体将完整的工具库保持在待命状态,并仅在当前任务需要时才加载参数模式。
工作原理
要启用工具检索,请在请求中添加一个 tool_search 工具,并将您希望保留的工具设置为 defer_loading: true。模型仍然可以看到每个延迟加载工具的名称和描述,因此它知道有哪些可用工具,但参数模式不会出现在上下文中。当模型需要某个工具时,它会按名称请求该工具,API 加载完整的模式,然后模型调用函数,所有这些都在同一个请求中完成。
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,
)
在该单个 API 调用内部,模型搜索 issue_refund,API 加载其模式,然后模型发出 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 在服务器上运行搜索,因此对代码的唯一更改是新增的工具以及您希望延迟加载的工具上的标志。您可以让最常用的工具预先加载,并延迟加载长尾工具。
工具检索还与前缀缓存兼容。延迟的模式位于提示的开头之外,而模型加载的模式是在对话后期添加的,因此从一轮到下一轮,缓存的前缀保持不变。
工具检索还与 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"],
},
}]
# 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),
}],
)
定价和支持的模型如何工作
工具检索没有单独的费用。输入和输出标记按照您调用的模型的标准费率计费。开启 tool_search 会增加一小块固定的输入标记,并且模型加载的每个模式都将作为其余对话的输入进行计费,这与提前声明的工具相同。当您从未加载的模式多于已加载的模式时,您就会节省标记,这通常是大型库的常见情况。根据您的流量进行衡量。
工具检索适用于 Gemini 3.6 及更高版本的模型,包括 所有 Gemini 4 模型,均在 Interactions API 中提供。
如何开始
在您的收件箱中获取来自 Google 的最新新闻
订阅我们的通讯,获取产品更新、活动信息、特别优惠等。
您的信息将按照 Google 的隐私政策 使用。您可以随时选择退出。
查看原文
Nov 19, 2026
|
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.
Lucia Loher
Product Manager, Gemini API
Nora Kassner
Research Scientist, Google DeepMind

Your browser does not support the audio element.
Listen to article
[[duration]] minutes
This content is 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.
How it works
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.
How to get started
Get the latest news from Google in your inbox
Sign up for our newsletters with product updates, event information, special offers, and more.
Your information will be used in accordance with Google's privacy policy. You may opt out at any time.
原文版权归 Google · AI 及原作者所有,本站转载仅供阅读。如需删除,请联系 support@aisa.one。