Gemini 支持按需加载工具参数定义
Gemini Interactions API 预览推出 Tool Retrieval,模型可先看到工具名称和描述,再在同一次请求中按需加载参数定义。接入时添加 tool_search,并为需要延迟加载的工具设置 defer_loading。
AI 深度解读
给 AI Agent 接了几十个工具,用户只问了一句「能退款吗」,请求却可能带上整套工具的参数定义。按原文所述,Google 在 2026 年 11 月 19 日为 Gemini Interactions API 推出了 Tool Retrieval 预览版。它让模型先看工具名和描述,需要调用时再加载参数 schema。
这套做法适合工具多、单轮只用少数几个的 Agent。对接入方来说,有两件事尤其值得看懂。一是按需加载省下的是哪部分 token,二是工具描述写得含糊时,怎么从调用轨迹里找出问题。
同一次 API 请求里,模型怎么找到退款工具?
接入服务端检索只需要改两处。在请求中加入 tool_search,再为想延迟加载的工具设置 defer_loading: true。模型仍能看到这些工具的名称和描述,只是暂时看不到参数 schema,也就是有哪些参数、各是什么类型、哪些必填。检索由 Gemini 在服务端完成,应用侧省去了建索引和托管索引的工作。
Google 的例子是一名用户收到破损的订单 A-1042,要求退款 40 美元。模型先检索 issue_refund,API 再加载这个工具的 schema,模型随后生成函数调用。三步都发生在同一次 API 请求内,并分别以 tool_search_call、tool_search_result 和 function_call 出现在 interaction.steps 里。
这条轨迹能帮你区分两类问题。如果搜索结果里就缺了退款工具,先看名称和描述有没有写清适用场景。如果搜到了,最后却没选对,就接着看实际发出的函数调用。过去靠看最终输出来猜的环节,现在有了中间记录。
工具按需加载,到底省的是哪笔账?
Tool Retrieval 没有单独收费,输入和输出仍按所用模型的标准 token 费率计价。加入 tool_search 会增加一小段固定输入开销。某个 schema 一旦被加载,在余下对话中就会像一开始声明的工具一样计入输入。只有始终没加载的 schema 所省下的 token 超过检索开销,按需加载才划算。
Google 建议把高频工具直接放在请求里,把偶尔才用的工具延迟加载。原文用 20 个各自每天只调用一次的工具说明这种长尾分布,它是算账示例。这个设计也能配合前缀缓存(prefix caching)。按需加载的 schema 后续才进入对话,请求开头的前缀更容易保持一致。
接了远程 MCP,还要自己做工具检索吗?
给远程 MCP 的 mcp_server 设置 defer_loading: true,该服务器暴露的工具就会按需加载。接入方可以在服务器这一层配置,无须逐个把工具列进请求。
如果团队已有自己的工具注册表、向量索引,或者不同用户能用的工具不同,可以给 tool_search 设置 "execution": "client",并定义自己的检索参数。查询由应用执行,每次搜索多一次往返。对应的好处是应用能自己做排序和权限过滤,也可以在用户对话中途接入新集成时,提供此前没有声明过的工具。
我的判断
按工具调用频率决定哪些 schema 要常驻,这个思路成立。全量声明便于检查每轮提供了哪些工具,适合工具少、使用频率高的场景。服务端检索更适合有大量低频工具、希望少维护一套检索逻辑的团队。客户端检索只有在动态注册、权限过滤或自定义排序确实有需求时,才值得承担额外往返。
原文展示了调用流程,但公告没有给出实测的 token 节省量、延迟数据或工具选择准确率的对照结果。前缀更稳定可以从加载机制解释,实际缓存命中率能提升多少仍要测。工具越多就越容易选错,也是缺少对照数据的经验判断。
按原文列出的范围,Tool Retrieval 支持 Gemini Interactions API 中的 Gemini 3.6 及后续模型,包括所有 Gemini 4 模型。功能还在预览期,接入时可以固定模型版本,并留意 interaction.steps 的结构变化,尤其是已经用它做日志解析和监控的项目。
能拿来做什么
- 在 Node 服务里先统计各工具的调用频次,再挑一批低频工具开启延迟加载。用同一批代表性请求对比全量声明和按需加载的输入 token、端到端延迟及工具选对率。
- 用
interaction.steps复盘一次工具误选,从检索请求、返回结果到最终函数调用逐步看。遇到用途相近的工具,在描述里写清各自的适用条件,让模型在看到参数之前就能区分。 - 如果用户能在会话中途连接新集成,或工具权限因人而异,把客户端检索接到现有的工具注册表,按当前用户权限筛选候选,并单独记录每次搜索增加的往返耗时。