Gemini API 推出 Tool Retrieval

2026年11月19日

|

Tool Retrieval 现已在 Gemini Interactions API 中开放预览。它可以按需加载工具参数模式,无需在每个提示中发送完整的工具库,旨在减少输入 token,并在智能体规模扩大时保持工具选择的准确性。


Lucia Loher

Gemini API 产品经理

Nora Kassner

Google DeepMind 研究科学家

分享
Gemini spark on a space background

我们正在 Gemini API 中推出 Tool Retrieval,帮助你的智能体更高效地管理大型工具库。通过仅在需要时加载参数模式,你可以降低复杂任务的延迟和输入 token 成本。现在,你可以在 Interactions API 中试用此功能:添加一个 tool_search 工具,并在请求中将 defer_loading 设置为 true。

摘要由 Google AI 生成。生成式 AI 尚处于实验阶段。
  • 我们正在 Gemini API 中推出 Tool Retrieval,帮助你管理大型工具库。
  • 此功能仅在需要时加载参数模式,从而减少输入 token 数量并降低延迟。
  • 你可以通过添加工具搜索并将延迟加载设置为 true 来启用此功能。
  • Tool Retrieval 支持 Gemini 3.6 及后续模型,可用于处理复杂的智能体任务。
摘要由 Google AI 生成。生成式 AI 尚处于实验阶段。

我们正在推出 Tool Retrieval,帮助开发者更高效地管理大量软件工具。智能体无需一次性加载所有工具,而是可以让工具库保持待命,仅调取当前任务所需的具体信息。这可以减少数据用量、提升运行速度并提高准确性。现在,你可以搭配我们最新的 Gemini 模型使用此功能,构建能力更强、响应更迅速的应用。

摘要由 Google AI 生成。生成式 AI 尚处于实验阶段。

探索其他风格:

今天,我们在 Gemini API 中推出 Tool Retrieval,目前已在以下产品中开放预览: Interactions API.

当智能体连接数十种乃至数百种工具时,每次请求都发送所有工具的完整参数模式,很快就会带来沉重负担。这会增加输入 token 数量和延迟,而且随着候选工具越来越多,工具选择的准确性也会下降。Tool Retrieval 可以让智能体的完整工具库保持待命,仅在当前任务需要时加载参数模式。

工作原理

要开启 Tool Retrieval,请在请求中添加一个 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 会在服务器端执行搜索,因此你只需在代码中添加新工具,并为希望延迟加载的工具设置一个标志。你可以预先加载最常用的工具,把其余长尾工具设为延迟加载。

Tool Retrieval 还可以很好地配合前缀缓存使用。延迟加载的模式不会出现在提示的开头,模型加载的模式则会在对话后续阶段加入,因此缓存的前缀在各轮对话中保持不变。

Tool Retrieval 也支持 Gemini API 中的远程 MCP 服务器。设置 defer_loading: true 于一个 mcp_server 工具上,该服务器公开的所有工具都会按需加载,因此你可以连接大型服务器,而不必逐一列出其中的工具。

客户端检索的工作原理

如果你维护自己的工具注册表、嵌入索引或按用户配置的权限过滤器,请声明 tool_search 并搭配 "execution": "client" ,然后定义搜索参数。客户端检索会为每次搜索增加一次往返通信,因为查找操作由你的应用执行。工具无需预先声明,因此当用户在对话过程中连接某个集成时,你也可以随时开放新工具:

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 Retrieval 不单独收费。输入和输出 token 按所调用模型的标准费率计费。开启 tool_search 会增加一小段固定的输入 token;模型加载的每个模式都会在对话剩余过程中按输入计费,与预先声明的工具相同。当从未加载的模式所节省的 token 多于实际加载模式所消耗的 token 时,你就能节省费用,而这通常适用于大型工具库。请根据自己的实际流量进行评估。

Tool Retrieval 支持 Gemini 3.6 及后续模型,包括 所有 Gemini 4 模型,并可在 Interactions API 中使用。

如何开始使用

在收件箱中获取 Google 的最新消息

订阅我们的新闻简报,获取产品更新、活动信息、特别优惠等内容。

完成了。只差最后一步。

请查看收件箱并确认订阅。

你也可以通过 . 订阅。

我们将依据 Google 隐私权政策 使用你的信息。你可以随时选择退出。

发布于: