在Gemini API中引入工具检索功能

模型更新 Google AI 原文语言:英文

Google推出Gemini API的工具检索预览,允许开发者在请求中仅按需加载工具参数模式,从而降低输入令牌消耗并提升延迟。通过在工具声明中设置defer_loading:true,模型仍能识别工具名称与描述,需时再请求完整模式,适用于Gemini 3.6及以上模型。

全文

Gemini API 现已推出工具检索(Tool Retrieval)功能

2026年11月19日

工具检索功能现已在 Gemini Interactions API 中提供预览版。按需加载工具参数架构,无需在每个提示词中发送完整的工具库,旨在减少输入 Token 并随着智能代理(Agent)规模的扩大保持工具选择的准确性。

Lucia Loher

Gemini API 产品经理

Nora Kassner

Google DeepMind 研究科学家

我们在 Gemini API 中推出了工具检索功能,以帮助您的智能代理更高效地管理大型工具库。通过仅在需要时加载参数架构,您可以减少复杂任务的延迟和输入 Token 成本。您今天就可以在 Interactions API 中尝试此功能,方法是添加一个 tool_search 工具并在请求中将 defer_loading 设置为 true。

我们在 Gemini API 中推出工具检索功能,以帮助您管理大型工具库。

该功能通过仅在需要时加载参数架构,减少了输入 Token 数量和延迟。

您可以通过添加工具搜索并将延迟加载(defer loading)设置为 true 来启用此功能。

工具检索功能适用于 Gemini 3.6 及更高版本模型,以支持您的复杂智能代理任务。

我们推出工具检索功能旨在帮助开发人员更高效地管理庞大的软件工具集。您的代理无需一次性加载所有工具,而是可以保持一个备用工具库,并仅调取任务所需的特定详细信息。这减少了数据使用量,提升了性能,并提高了准确性。您今天就可以结合我们最新的 Gemini 模型开始使用此功能,以构建功能更强大、响应更迅速的应用。

探索其他样式:

今天我们在 Gemini API 中推出工具检索功能,该功能在 Interactions API 中提供预览版。

当智能代理连接了数十个甚至数百个工具时,在每个请求中发送完整的参数架构会迅速累积。随着候选列表的增长,这会增加输入 Token 数量、增加延迟并降低工具选择的准确性。工具检索让您的代理保持其完整的工具库处于待命状态,并且仅在当前任务需要时才加载参数架构。

工作原理

要启用工具检索,请在请求中添加一个 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+ 个其他延迟加载的函数(使常用工具保持不延迟加载) ] 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 在服务器上运行搜索,因此对您的代码仅有的更改是新工具以及要在您想要延迟加载的工具上设置的标志。您可以让最常用的工具提前加载,并对长尾工具进行延迟加载。

工具检索还可以与前缀缓存(prefix caching)很好地配合使用。延迟加载的架构不会进入提示词的开头,模型加载的架构会在对话的后期添加,因此缓存的前缀在不同的轮次之间保持不变。

Tool Retrieval 还可以在 Gemini API 中与远程 MCP 服务器配合使用。在 mcp_server 工具上设置 defer_loading: true 后,该服务器公开的所有工具都将按需加载,因此你可以连接一个大型服务器,而无需逐个列出其工具。

客户端检索的工作原理

如果你维护自己的工具注册表、嵌入索引或按用户权限过滤器,请将 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,并且模型加载的每个 Schema 在接下来的对话中都将作为输入计费,这与预先声明的工具相同。当你从未加载的 Schema 数量超过加载的数量时,你就能节省 Token,这对于大型库来说通常是这样。请根据你自己的流量进行衡量。

Tool Retrieval 在 Interactions API 中适用于 Gemini 3.6 及更高版本的模型,包括所有 Gemini 4 模型。

如何开始

阅读文档 — 包含示例的完整设置指南

比较 Gemini 模型 — 为你的用例找到最佳模型

加入 Discord 上的讨论 — 与团队分享反馈

正文为 AI 译文。

参考来源

← 返回每日AI报告