|

Gemini API 推出 Tool Retrieval:4 个模型支持按需加载,Agent 不再每次读取全部工具参数

Gemini API 推出 Tool Retrieval:4 个模型支持按需加载,Agent 不再每次读取全部工具参数

2026 年 11 月 19 日,Google 在 Gemini Interactions API 中以 Preview 形式推出 Tool Retrieval(工具检索)。Agent 可以先只看到工具的名称和简述,等真正需要调用时再把完整参数 Schema 载入上下文。它主要解决的是“工具越接越多、上下文被闲置工具定义占满”的问题。它最适合工具数量多、调用集中在少数高频工具、同时存在大量长尾工具的 Agent,并不是所有应用默认开启就能省钱。

您读完此文能了解到什么?

  • Tool Retrieval 改变的到底是什么,以及“开发者仍要提交完整工具声明”和“模型不必提前读完整 Schema”为何同时成立
  • 从工具注册到 function_call 的完整执行链,以及服务端检索与客户端检索的分工
  • 当前明确支持的 4 个模型 ID、标准价格,以及“没有单独功能费,但 Token 照常计费”的含义
  • 官方两组方向相反的示意算例:什么时候能省,什么时候反而更贵
  • 接入前需要注意的限制,以及如何判断自己的 Agent 是否值得采用

索引:后文先用一张概念表和影响速览帮你快速对齐背景。“客观事实”部分依次说明发布信息、工作机制、混合加载与远程 MCP、支持模型与成本、使用限制,全部以 Google 官方公告和开发文档为准。“分析判断”部分给出适用场景判断、迁移前的基线测量方法和几个常见疑问,其中带有判断或预测性质的内容会单独标明。

gemini-api-tool-retrieval-agent-on-demand-tool-schema-image-0


Gemini API Tool Retrieval 需要先知道的概念(To Know)

概念 简要解释
Tool Retrieval 先检索需要的工具,再把命中工具的完整参数定义加入模型上下文
Interactions API Gemini 面向 Agent 的接口,管理交互历史、工具执行步骤和模型输出,2026 年 6 月已正式可用
参数 Schema 描述函数接受哪些参数、类型是什么、哪些必填的结构,通常用 JSON Schema 表达
Function Calling 模型生成函数名和参数,由应用执行函数,再把结果交回模型
tool_search 声明工具检索机制的工具类型,模型通过它查找并载入工具定义
defer_loading 服务端模式下的配置,把工具完整参数定义延迟到检索命中时再加载
short_description 延迟工具的简短说明,供模型在初始目录中识别工具
远程 MCP 通过 Model Context Protocol 连接应用外部、由第三方服务提供的工具
隐式缓存 平台自动复用相同的上下文前缀,命中部分按缓存输入费率计费

Gemini API Tool Retrieval 影响速览

  • 正在给 Agent 接大量业务工具的开发者:可以不再自建工具检索器,就让模型按需读取几十甚至上百个工具的 Schema。不过仍需每次请求提交完整工具数组,并重新评估缓存与计费。迁移前建议先用现有 Function Calling 流程测出工具定义的实际占用,可借助 API易 apiyi.com 这类多模型统一接口快速跑出对照基线。
  • 产品与成本负责人:没有单独的功能费,但每次服务端搜索会触发额外的模型推理。省不省钱取决于工具规模、上下文长度和搜索频次,需要用账单字段验证,不能只看宣传方向。
  • 工具很少、调用稳定的应用:官方算例显示,小工具集叠加长上下文时,Token 总量反而会上升,继续直接加载是更稳的选择。
  • 使用 Agent 框架的团队:这是模型 API 层的新能力,框架不一定立即适配。在框架层面的渐进加载问题上,不能默认已经被解决。

客观事实:Gemini API Tool Retrieval 发布了什么

Gemini API Tool Retrieval 的发布信息与背景

Google 官方博客于 2026 年 11 月 19 日发布了《Introducing Tool Retrieval in the Gemini API》,作者是 Gemini API 产品经理 Lucia Loher 和 Google DeepMind 研究科学家 Nora Kassner。功能目前处于 Preview 阶段,只能在 Interactions API 中使用,需要 v1beta 版本。旧的 generateContent 方法不支持。

工程侧的准备早于公告。11 月 18 日,Google 官方 Python SDK 发布 v3.6.0,更新记录写明加入了 Tool Retrieval 与函数结果相关的公共 Schema。同日,Go SDK v1.79.0 也包含相应更新。从时间线看,这次是在已经 GA 的 Interactions API 上补齐工具发现与按需装载能力,并不是推出一个新的 API 产品。

开发者的需求也有记录可查。2026 年 3 月 18 日,有开发者在 Python SDK 仓库提交 Issue #2185,请求支持 defer_loading 和 tool_search,理由是 Agent 接入 30 个以上工具后,完整 Schema 会造成上下文膨胀。Google 维护人员在 3 月 20 日回应,将其登记为功能请求。这些是需求反馈,不是性能测试。

用一句话概括 Tool Retrieval:工具可以先被发现,具体参数等到需要调用时再读取。

Tool Retrieval 如何改变工具 Schema 的加载方式

在传统静态加载下,即使用户只想办一笔退款,订单、物流、库存、CRM 等几十个工具的参数声明也会随每次推理一起进入上下文。Google 文档提到,几十个函数声明就可能占用数万个 Token。这会挤占对话历史的空间,相似工具一多,还可能干扰模型选对工具。

Tool Retrieval 的关键在于区分三个层面:

  1. API 请求层:开发者照常提交完整工具定义,包括参数 Schema。
  2. 模型初始上下文:标记为 defer_loading: true 的工具只以名称加 short_description 的形式出现。如果没有配置简述,就取完整 description 的第一句。
  3. 工具调用阶段:工具被检索命中后,完整 Schema 才进入上下文,模型据此生成参数化的调用。

所以标题里“不再每次加载全部工具参数”,准确的含义是模型不再每轮提前读取所有完整参数,而不是开发者不用再发送完整声明。服务端模式下,官方要求每次请求都重新提交完整的 tools 数组,即使使用了 previous_interaction_id 也不例外。

gemini-api-tool-retrieval-agent-on-demand-tool-schema-image-1

Tool Retrieval 的执行链:以官方退款案例为例

Google 公告用了一个订单退款场景:订单 A-1042 的商品到货时已损坏,用户要求退款 40 美元,需要用到的工具是 issue_refund。服务端检索的完整过程如下:

  1. 请求中声明 {"type": "tool_search"},并对 issue_refund 等低频工具设置 defer_loading: true。
  2. 模型根据任务判断需要退款能力,发起 tool_search_call。
  3. API 返回 tool_search_result,其中包含 issue_refund 的完整参数 Schema。
  4. 模型读取参数定义,生成 function_call,参数为 order_id: "A-1042" 和 amount: 40。
  5. 应用执行函数并回传 function_result,模型据此继续完成任务。

搜索、载入和生成函数调用可以在同一次外部 API 请求内完成,所有步骤都能在 interaction.steps 中查看。但要注意,同一次请求不等于内部只推理一次,每次服务端搜索都会引发额外的、需要计费的模型调用。另外,这是演示案例,不代表任何退款成功率统计。

下面是依据官方文档整理的示意代码,直连 Google 端点,仅用于展示请求结构:

from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

tools = [
    {"type": "tool_search"},
    {
        "type": "function",
        "name": "issue_refund",
        "description": "Refund an order.",
        "short_description": "Refund a customer order.",
        "defer_loading": True,
        "parameters": {
            "type": "object",
            "properties": {
                "order_id": {"type": "string"},
                "amount": {"type": "number"}
            },
            "required": ["order_id", "amount"]
        }
    }
]

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Refund 40 USD for order A-1042.",
    tools=tools
)
for step in interaction.steps:
    print(step.type)  # tool_search_call / tool_search_result / function_call

Function Calling 原有的职责分工没有变化。对于自定义函数,API 只返回 function_call,执行退款、访问数据库、处理权限仍是应用的工作。只有连接远程 MCP 服务器时,API 才会代为发起远程调用,并返回 mcp_server_tool_call 和 mcp_server_tool_result。

Tool Retrieval 的混合加载、远程 MCP 与两种检索模式

Google 推荐混合使用:高频工具直接加载,低频、专业化的长尾工具延迟加载。这样简单任务不必先搜索一轮,长尾能力也不会长期占用上下文。远程 MCP 服务器也可以整体设置延迟加载,例如对一个 type: "mcp_server" 的配置加上 defer_loading: true,该服务器暴露的工具就会按需载入,不必逐个声明。

除了由 Gemini 完成检索的服务端模式,官方还提供客户端模式:开发者声明一个 execution: "client" 的 tool_search,由自己的应用查询工具注册表,再把匹配的完整工具声明放进 function_result.result 返回给模型。两者的区别如下:

比较维度 服务端检索 客户端检索
执行位置 Gemini API 服务端(默认 server) 开发者应用(client)
是否需要自建检索器 不需要 需要
是否需要提前声明工具库 需要 不需要,会话中可引入新工具
defer_loading 适用 不适用
额外网络往返 无需额外客户端往返 每次搜索多一次往返
权限控制 由请求声明的工具集决定 可结合自建的用户级权限过滤
典型场景 大型、相对固定的工具集合 动态工具库、多租户、企业私有注册表

客户端模式返回的函数声明应当是结构化对象,不能转成 JSON 字符串。同一请求内不能混用两种模式,且最多只能声明一个 tool_search。

Gemini API Tool Retrieval 支持哪些模型、价格如何

Google 公告的表述比较宽泛,称 Gemini 3.6 及更新的模型均支持,包括所有 Gemini 4 模型。但开发文档截至 11 月 20 日明确列出的只有 4 个模型 ID。落地时应以开发文档为准,对不支持的模型设置 defer_loading 会返回 HTTP 400。

模型 ID 标准输入价(美元/百万 Tokens) 标准输出价(含 Thinking) 备注
gemini-4-hydrogen $1.50 $7.50 标有 Free Tier
gemini-4-argon $2.00(12 月 1 日起 $4.00) $10.00(12 月 1 日起 $20.00) 无 Free Tier
gemini-3.8-flash $0.75(2027 年 1 月 1 日起 $1.50) $3.75(2027 年 1 月 1 日起 $7.50) 标有 Free Tier
gemini-3.6-flash $0.75(2027 年 1 月 1 日起 $1.50) $3.75(2027 年 1 月 1 日起 $7.50) 标有 Free Tier

价格来自 Google Gemini Developer API 定价页的 Standard 档。Free Tier 的实际额度和速率限制需要按项目确认。

计费上,Google 明确表示 Tool Retrieval 没有独立的功能费,但这不等于搜索免费。延迟工具的简述列表、开启 tool_search 后增加的固定搜索指令、每次服务端检索的额外推理、载入的完整 Schema 以及它在后续轮次中的保留,都会按所选模型的费率计 Token。观察成本时要特别关注 total_tool_use_tokens 字段,它记录了服务端搜索引发的额外模型调用输入。只看首次输入 Token 下降,很容易高估节省效果。

Tool Retrieval 的官方 Token 示意算例

官方早期测试显示,每个延迟工具在初始目录中平均约占 26 Tokens。这是近似值,不是固定开销。文档还给出了两组假设性算例,结论方向相反:

场景(官方假设) 静态加载全部工具 Tool Retrieval 变化
200 个工具,每个 400 Tokens,基础上下文 2,000,用到 2 个工具,共 2 次请求 164,000 约 23,650 减少约 85.6%(按算例推算)
10 个工具,每个 400 Tokens,基础上下文 30,000,用到 2 个工具,共 2 次请求 68,000 92,830 增加约 36.5%(按算例推算)

第二组算例变贵的原因是服务端搜索要额外推理一次,并重新处理已经很长的上下文,而 10 个工具本身占用不大,省下的 Schema 抵不过搜索开销。两组数字都是 Google 标明的假设性示例,没有计入输出 Token 和缓存收益,不是生产环境 Benchmark。截至资料核查日,Google 没有公布这项功能实测的 Token 节省比例、延迟改善或工具选择准确率提升。

gemini-api-tool-retrieval-agent-on-demand-tool-schema-image-2

缓存方面,Google 表示 Tool Retrieval 支持隐式缓存:完整 Schema 不出现在初始前缀中,系统指令和工具目录等前缀更容易保持稳定。但文档也提醒,延迟加载会让初始提示词变短,原本依赖大量 Schema 才能达到缓存最低门槛的请求,可能因此低于门槛。

Tool Retrieval 当前的使用限制

以下几点来自官方文档,在开发中最容易踩坑:

  • 已加载工具无法卸载:Schema 一旦被检索,就会在当前会话中一直保留。在很长的会话里不断检索新工具,上下文仍会持续增长。
  • 每次请求重新提交完整工具数组:包括 tool_search、全部延迟和非延迟工具、相关 MCP 配置。不能只交 name 和 short_description 而省略 parameters。
  • 系统指令直接点名的工具不要延迟:模型可能绕过搜索直接调用,导致缺少加载上下文而出错。
  • 无状态会话要完整保留检索步骤:使用 store=false 自行管理历史时,tool_search_call、tool_search_result 及其 signature 不能删改,否则可能返回 HTTP 400。
  • 调试要看 steps:即使 interaction.status 不是 requires_action,结果中也可能含有待执行的 function_call。
  • 未命中时可能返回文本:服务端搜索找不到匹配工具时,不一定返回结构化错误。

分析判断:Gemini API Tool Retrieval 对 Agent 开发意味着什么

Tool Retrieval 的适用场景判断

这次更新的实际价值,是把“维护一份完整工具清单”和“每轮推理都要读完这份清单”拆成两件事。工具库可以继续扩张,模型上下文里常驻的只是一份很薄的目录。对于持续接入新业务系统的团队,这能减轻预先裁剪工具集的负担,也减少为了控制 Token 而在应用侧每轮动态筛选工具、进而破坏缓存前缀的情况。

不过,官方算例已经说明收益是有条件的。结合官方工程建议,可以按下表初步判断(这是工程选择建议,不是硬性数量门槛):

Agent 类型 工具特征 建议
客服、业务流程助手 几十个工具,少数查询类高频,退款、审批、合同等低频 高频直接加载,长尾用服务端检索
多 MCP 服务器的研发/运维 Agent 每个服务器工具多,单次任务只用一小部分 对 MCP 服务器整体设置 defer_loading
多租户、按权限开放工具的平台 工具集合因用户和工作区而变 客户端检索,结合自建注册表和权限过滤
小型助手 少于约 20 个稳定工具,多数每轮都会用到 继续静态加载
长上下文 + 频繁搜索 对话很长,每轮常需多次检索 先测再决定,存在净成本上升风险

我们的判断是:工具调用分布越“长尾”,Tool Retrieval 越值得用。反过来,如果大部分工具每轮都要用,延迟加载只会多出一次搜索推理。

迁移到 Tool Retrieval 前,先测出工具 Schema 的真实占用

是否迁移,最可靠的依据是自己业务的数据。迁移前可以先用现有的 OpenAI 兼容 Function Calling 流程,测量“全量工具”和“只带实际用到的工具”两种请求的输入 Token 差,得到工具 Schema 的真实占用。下面的脚本做的是这种基线测量,并不是 Tool Retrieval 本身:

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # API易 OpenAI 兼容接口,用于测量静态加载基线
)

def make_tool(name, desc):
    return {"type": "function", "function": {
        "name": name, "description": desc,
        "parameters": {"type": "object",
                       "properties": {"order_id": {"type": "string"}},
                       "required": ["order_id"]}}}

all_tools = [make_tool(f"crm_tool_{i}", f"CRM operation {i}") for i in range(50)]
messages = [{"role": "user", "content": "查询订单 A-1042 的状态"}]

for label, tools in [("全量 50 个工具", all_tools), ("仅 1 个工具", all_tools[:1])]:
    resp = client.chat.completions.create(
        model="your-model-id", messages=messages, tools=tools)
    print(label, "prompt_tokens =", resp.usage.prompt_tokens)
查看完整的基线测量脚本(按工具数量批量对比)
import json
import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # 通过 API易 统一接口测量不同模型的工具 Schema 开销
)

def load_tools(path: str) -> list:
    """从业务工具注册表(JSON 文件)读取 OpenAI 格式的工具定义"""
    with open(path, "r", encoding="utf-8") as f:
        return json.load(f)

def measure(model: str, tools: list, prompt: str) -> int:
    resp = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": prompt}],
        tools=tools if tools else None,
        max_tokens=16,
    )
    return resp.usage.prompt_tokens

def baseline_report(model: str, tools: list, prompt: str, steps=(0, 10, 20, 50, 100)):
    base = measure(model, [], prompt)
    print(f"无工具基础输入: {base} tokens")
    for n in steps:
        if n == 0 or n > len(tools):
            continue
        used = measure(model, tools[:n], prompt)
        print(f"{n:>4} 个工具: {used} tokens, Schema 约占 {used - base} tokens")

if __name__ == "__main__":
    tools = load_tools("tool_registry.json")
    baseline_report("your-model-id", tools, "查询订单 A-1042 的状态")

🎯 技术建议:在评估 Tool Retrieval 之前,可以先通过 API易 apiyi.com 用一个 API Key 在多个主流模型上跑静态加载基线,看清工具 Schema 在你的请求里到底占了多少 Token。拿到基线后,再到 Gemini Interactions API 中开启 tool_search 做对照,比较 total_input_tokens 与 total_tool_use_tokens 之和。

需要说明的是,Tool Retrieval 依赖 Interactions API 的 v1beta 接口和专用字段,上面的 OpenAI 兼容调用只用于测量静态加载的开销。对照测试时,建议保持模型、工具库、任务集、上下文长度和缓存条件一致,再比较总计费成本、端到端耗时、正确工具选择率和平均搜索次数,这样才能把差异归因到检索策略上。如果想在同一套脚本里横向看不同模型的基线差异,API易 apiyi.com 的统一接口能省去逐家接入的工作。

值得关注的后续发展(预测性判断)

以下属于判断,不是已确认的事实。

第一,公告与开发文档在支持模型范围上存在差异,Gemini 4 Carbon、Gemini 4 Neon 等型号是否会进入兼容名单,需要关注文档更新。第二,“已加载 Schema 无法卸载”是长会话 Agent 的明显短板,正式版是否提供卸载或淘汰机制,会直接影响它在长任务里的表现。第三,Google ADK 的用户此前在 Issue #7241 中反馈过渐进式加载与缓存失效的问题,模型 API 支持了新能力,不代表框架会自动采用,框架层的适配节奏值得跟进。

按需加载工具定义的思路在业内此前已有先例,Google 这次属于把它补进 Gemini 的 Agent 接口。由于 Preview 阶段接口可能变动,生产系统接入时建议保留回退到静态加载的开关。

关于 Gemini API Tool Retrieval 的几个常见疑问

Q1:开了 Tool Retrieval,请求体会变小吗?

不会。服务端模式下每次请求仍要提交完整工具数组,变小的是模型初始上下文里的工具占用。如果想先算清现有请求中工具定义的体量,可以用上文脚本通过 API易 apiyi.com 测出基线。

Q2:Google 官方说能省 85% 吗?

没有这样的实测结论。85.6% 是按 200 工具的假设性算例推算出来的,同一份文档还给出了小工具集下 Token 增加约 36.5% 的反例。

Q3:Tool Retrieval 收费吗?

没有单独的功能费,但搜索指令、额外推理和载入的 Schema 都按模型费率计 Token。预算敏感的团队可以先通过 API易 apiyi.com 按量计费地小规模测试不同模型的 Function Calling 开销,再决定 Agent 的模型选型。

Q4:用了 Tool Retrieval,是不是不用自己执行函数了?

不是。自定义函数仍由应用执行并回传结果,Tool Retrieval 只负责找到并载入工具定义。只有远程 MCP 工具会由 API 代为调用。


工具库会越来越大,但每一轮真正需要的往往只是其中几件。Tool Retrieval 把“备齐工具”和“随时取用”分开处理,用得好能让大型 Agent 更轻,用得不对也可能多付一轮推理的代价。正如《论语·卫灵公》所言:“工欲善其事,必先利其器。”先量清手里每件“器”的分量,再决定怎么摆放。


📚 参考资料

  1. Google 官方公告:Introducing Tool Retrieval in the Gemini API(2026-11-19)

    • 链接: blog.google/innovation-and-ai/technology/developers-tools/gemini-api-tool-retrieval
    • 说明:发布信息、设计目标、两种检索模式与定价原则
  2. Google Tool Retrieval 开发文档:配置、限制、计费与示意算例

    • 链接: aistudio.google.com/docs/tool-retrieval
    • 说明:支持模型列表、Usage 字段、最佳实践与常见错误
  3. Gemini Developer API 定价:模型标准价格与缓存费率

    • 链接: aistudio.google.com/docs/pricing
    • 说明:各模型输入输出单价及生效日期
  4. Interactions API 文档:接口定位与执行步骤

    • 链接: aistudio.google.com/docs/interactions-overview
    • 说明:有状态对话、steps 结构及与 generateContent 的区别
  5. Google Python SDK v3.6.0 与 Issue #2185:工程佐证与开发者需求记录

    • 链接: github.com/googleapis/python-genai/releases/tag/v3.6.0
    • 链接: github.com/googleapis/python-genai/issues/2185
    • 说明:SDK 公共 Schema 更新与早期社区需求

作者:APIYI 技术团队
技术交流:欢迎在 API易 apiyi.com 首页联系我们,更多接入资料可访问 docs.apiyi.com 文档中心

延伸阅读

类似文章