Google 在 11 月 19 日的官方博客上宣布,Gemini API 推出 Tool Retrieval(工具检索),目前在 Interactions API 里以预览版提供。这个功能解决的是 Agent 规模化之后一个很实际的问题:当一个 Agent 要接几十甚至上百个工具时,每次请求都把所有工具的完整参数 schema 塞进 prompt,token 花得多、延迟高,模型还容易选错工具。Tool Retrieval 的思路很简单:工具库继续待命,但参数 schema 只在真正用到的那一刻才加载。
对正在做 Agent 的算法工程师来说,这不是一个新模型,而是一次接口层面的减负。它不改变你的工具定义方式,只改变 schema 进入上下文的时机。
以前的问题:工具越多,prompt 越臃肿
Function calling 的标准做法,是每次调用模型都把全部工具的名字、描述和参数 schema 一次性发过去。工具只有三五个时,这点开销可以忽略;但一个客服 Agent 可能挂着退款、改地址、查物流等几十个工具,一个企业内部 Agent 甚至要接上百个。
全量 schema 会带来三个麻烦。第一是 token 膨胀:每个工具的参数定义少则几十 token,多则几百,几十个叠加,一次请求还没开始干活就先烧掉几千 token,而且每轮对话都重复烧。第二是延迟:输入越长,首 token 越慢。第三是准确率:候选工具越多,模型越容易在相似工具之间挑错,比如把“退款到原支付方式”和“退款到账户余额”搞混。
业内常见的 workaround 是自己做一层检索,先筛出可能相关的几个工具再发 schema。但这要自己建索引、维护注册表,还要处理检索失败的兜底。Google 这次是把这层检索做进了 API 内部。
怎么用:加一个工具,改一个 flag
开启 Tool Retrieval 只需要两处改动:在请求里加一个 tool_search 工具,并把想延迟加载的工具标上 defer_loading: true。
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 随即把该工具的完整 schema 加载进来,模型再发出真正的 function_call。检索、加载、调用这三步都记录在返回结果的 interaction.steps 里,调试时能清楚看到模型考虑过哪些工具、最终选了哪一个。

服务端不需要你建索引、也不用你托管检索服务,Gemini 在服务端完成搜索。你可以把最常用的几个工具留在请求里直接加载,把长尾工具全部延迟加载,冷热搭配着用。
客户端检索和 MCP 整库延迟
Tool Retrieval 提供了两种检索方式。默认是服务端检索,上面说的就是这种。另一种是客户端检索:把 tool_search 声明为 "execution": "client",检索逻辑跑在你自己的应用里。适合已经有工具注册表、向量索引,或者要按用户权限过滤工具的场景——比如某个工具只对管理员开放,检索时直接不返回它。
客户端模式多一次往返:模型发出检索调用后,你的应用执行查找,再把匹配到的 schema 通过 function_result 传回去。好处是工具不需要提前声明,你可以在对话中途让用户新接一个集成,动态暴露新工具。
另一个值得注意的点是 MCP。Tool Retrieval 同样支持 Gemini API 里的远程 MCP 服务器:只要在 mcp_server 工具上设置 defer_loading: true,这个服务器暴露的所有工具都会按需加载,不用一个一个列出来。这对接了大型 MCP 服务的 Agent 很有用——以前光是把几十个工具声明一遍就很啰嗦,现在一行配置就能连上整个服务。
计费和支持范围
先说最关心的计费:Tool Retrieval 本身不单独收费,输入和输出 token 都按所用模型的标准价目结算。开启 tool_search 会增加一小块固定的输入 token;模型加载过的 schema 会按输入 token 计费,直到对话结束——和一开始就声明这个工具的计费方式一样。所以能不能省钱,取决于一个不等式:你没加载的 schema 比加载了的多不多。对工具库大、每次只用其中一两个的 Agent,这个账很容易算赢;如果每次都要用掉大半工具,省下的可能还抵不过 tool_search 本身的固定开销。Google 在博客里也提醒,要按自己的实际流量实测。
支持范围方面,Tool Retrieval 适用于 Gemini 3.6 及更新的模型,包括全部 Gemini 4 模型,并且只在 Interactions API 里提供。Interactions API 是 Google 在 2026 年年中正式推出的新一代接口,定位是 Agent 应用的推荐入口,老的 generateContent 方法不支持这个功能。
还有两个细节值得留意。第一,Tool Retrieval 和前缀缓存是配合的:被延迟的 schema 不会出现在 prompt 开头,加载进来的 schema 追加在后面,所以缓存的前缀在多轮对话里保持不变。第二,这仍然是预览版,接口和行为在正式发布前可能调整;按文档说明,在不支持的模型上设置 defer_loading 会返回 400 错误,已加载的工具在对话中也不能再卸载。生产环境接入前,最好把模型版本钉死,并对工具选择做回归测试。
另外要说明一点:Google 这次的公告没有给出任何实测数字——没有说能省百分之多少 token、延迟降多少、选工具准确率提升多少。这些都要等社区实测,或者你自己跑 A/B 对比。公告里给的是机制,不是成绩单。
小杜点评
这个功能真正有意思的地方,不在于它多新,而在于它承认了一个现实:Agent 的工具数量只会越来越多,靠“每次全量发送”迟早会撞墙。Google 的解法是把检索内化成 API 的一部分,开发者几乎不用改代码就能用上,这比让每个人自己搭一套检索要务实得多。
但也要看到它的边界。名字和描述仍然是全部进上下文的,所以工具的命名和描述质量直接决定检索效果——描述写得含糊,模型一样会点错名。真正省 token 的前提是“工具库大、每次只用少数几个”,对工具本来就不多的 Agent,收益有限。
我的建议是:先把高频工具留在请求里、长尾工具标记延迟加载,跑一周对比 token 账单和选错率,再决定全量推广。这是一个典型的“先量后质”的优化,收益可以用数字验证,没必要凭感觉下结论。
参考来源
- Google 官方博客:Gemini API tool retrieval for efficient agent scaling(2026 年 11 月 19 日)
- Unite.AI:Google Previews On-Demand Tool Retrieval for Gemini API Agents
- AlphaSignal:Google's Gemini API Drops Schema Overhead for Agents With Hundreds of Tools



