AIsaAIsaStudio English 打开 AIsa Studio

Google 在 Gemini API 推出预览版 Tool Retrieval 功能

原标题:Introducing Tool Retrieval in the Gemini API

Google 在 Gemini API 预览版 Interactions API 中推出 Tool Retrieval。智能体通过添加 tool_search 工具并对工具设置 defer_loading: true,可按需加载参数 schema 而不必在每次请求中传入全部工具库,从而降低输入 token 消耗并提升大规模工具库下的工具选择准确性。该功能支持远程 MCP 服务器和自定义注册表的客户端检索,无单独收费,适用于 Gemini 3.6 及之后的所有 Gemini 4 模型。

为什么值得看

原文给出开启方式、定价逻辑和与 MCP、prefix caching 的兼容细节,开发者可据此评估大型工具库下的 token 优化方案。

阅读原文 ↗11月20日 AI 日报

本页的摘要、推荐理由与解读出自 AIsa Studio 的 AI 风向智能体,原文版权归原作者所有。

深度解读

发生了什么

Google 宣布在 Gemini API 中推出 Tool Retrieval(工具检索)功能,目前以预览版形式在 Interactions API 中提供。该功能允许 Agent 将完整的工具库置于待命状态,只在当前任务需要时才加载工具的参数 Schema,而不是在每次请求的提示词中发送全部 Schema。

Google 对其要解决的问题描述得很直接:当 Agent 连接数十甚至数百个工具时,每次请求都发送完整的参数 Schema 会「增加输入 token 数量、增加延迟,并随着候选列表增长降低工具选择准确率」。

关键细节

  • 服务端模式:在请求中添加一个 tool_search 工具,并对需要保留的工具设置 defer_loading: true。模型仍然能看到每个延迟加载工具的名称和描述,因此知道自己有哪些工具可用,但参数 Schema 不进入上下文。当模型需要某个工具时,按名称请求,API 加载完整 Schema,模型再调用该函数——全部发生在同一次请求内。搜索、加载、调用三步都会出现在 interaction.steps 中,便于调试工具名称或描述。
  • 无需自建索引:Gemini 在服务端运行搜索,代码改动只有新增的工具和对延迟工具的标志位。可以将最常用的工具保持前置加载,而把长尾工具延迟加载。
  • 与前缀缓存兼容:延迟加载的 Schema 不出现在提示词开头,模型加载的 Schema 会在对话靠后位置添加,因此缓存的前缀在各轮之间保持不变。
  • 支持远程 MCP 服务器:对 mcp_server 工具设置 defer_loading: true 后,该服务器暴露的所有工具都会按需加载,无需逐一列举即可接入大型服务器。
  • 客户端检索:如果你维护自己的工具注册表、嵌入索引或按用户的权限过滤,可以用 "execution": "client" 声明 tool_search 并定义搜索参数。这种方式每次搜索多一次往返,因为查找由应用执行;工具无需预先声明,因此可以在对话中途(例如用户接入新的集成时)暴露新工具。
  • 计费与模型支持:该功能不单独收费,token 按所调用模型的标准费率计费。开启 tool_search 会增加一小块固定的输入 token,模型每加载一个 Schema 则作为输入计费,与预先声明的工具相同。当从未加载的 Schema 多于实际加载的 Schema 时才会节省 token。Tool Retrieval 适用于 Gemini 3.6 及之后的所有模型,包括全部 Gemini 4 系列,在 Interactions API 中使用。

为什么重要

该功能瞄准了 Agent 开发中的一个实际扩展瓶颈:工具库越大,每次请求消耗的上下文越多,工具选择的准确性也越难保证。通过让 Schema 在需要前不占用上下文,Tool Retrieval 在减少输入 token 的同时——按照 Google 的设计目标——使 Agent 扩展时工具选择依然保持准确。

计费模式也值得在成本规划时注意:已加载的 Schema 与预先声明的工具计费相同,因此只有当工具库中大部分工具在某次对话中不会被使用时,该功能才带来净节省。Google 明确建议团队结合自身流量进行测算,而不是默认一定省。

对使用 MCP 的团队而言,整个服务器的工具按需加载后不再需要逐一列举,这改变了大型工具生态接入的方式。

对谁有影响

  • 在 Gemini API(Interactions API)上构建拥有大型工具库的 Agent 的开发者。
  • 目前需要逐一列出全部工具的远程 MCP 服务器接入方。
  • 拥有自建注册表、嵌入索引或权限过滤的团队,可使用客户端检索——但需接受每次搜索的额外往返。
  • 使用 Gemini 3.6 及之后版本(含全部 Gemini 4 系列模型)的用户。
全文翻译

2026年11月19日

| Gemini Interactions API 中的工具检索功能现已进入预览阶段。按需加载工具参数模式,而不是在每次提示中发送完整的工具库,旨在减少输入标记数量,并在智能体扩展时保持工具选择的准确性。


Lucia Loher

Gemini API 产品经理

Nora Kassner

Google DeepMind 研究科学家


Gemini spark on a space background

您的浏览器不支持音频元素。

收听文章

[[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


Gemini spark on a space background

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。