Gemini API 支持按需加载工具参数
Gemini 的 Interactions API 预览版加入 Tool Retrieval。请求可注册 `tool_search` 并为工具设置 `defer_loading: true`,让模型先看到工具名称和简介,需要调用时再加载参数定义。
AI 深度解读
给 AI 助手接上邮箱、搜索和发布系统后,一次只想查封邮件,也可能要把所有工具的参数说明塞进请求。Google 在 Gemini API 里预览的 Tool Retrieval 改了这个流程:先给模型看工具目录,选中哪个,再加载哪个的完整参数定义。
这套做法适合工具多、单次任务只用其中几个的 Agent。它能省多少输入 token,要看工具的调用频率和对话长度。对开发者来说,工具描述也从文档变成了模型选工具的依据。
一次请求里,模型怎么拿到工具参数?
Google 在 2026 年 11 月 19 日公布 Tool Retrieval,通过 Interactions API 提供预览,支持 Gemini 3.6 及之后的模型,包括 Gemini 4 系列。接入时,在请求里加一个 tool_search,再给想延迟加载的工具设置 defer_loading: true。
模型一开始能看到这些工具的名称和简短描述。参数名、类型、必填项等完整定义暂时留在请求的初始上下文之外。模型决定用某个工具时,会按名称请求它的定义,API 加载完整 schema,模型再按这个定义填参数并调用工具。检索、返回 schema、发起调用都在同一次请求里完成。
这三步分别以 tool_search_call、tool_search_result 和 function_call 记在 interaction.steps 里。排查问题时,可以先看模型找了哪个工具、拿到了什么定义,再看它最终传了哪些参数。一次调用出错,可能早在选工具时就走偏了。
低频工具适合延迟加载,高频工具适合预载
tool_search 会增加一小段固定的输入 token,检索本身也多一步。功能没有单独收费,每份被加载的 schema 从加载时起,在这轮对话的余下部分都按输入计费,规则和预先声明的工具一样。一个工具如果几乎每轮都用,放在开头更直接。那些整段会话可能一次都用不到的工具,才有更大的节省空间。
延迟加载的 schema 不占据提示词开头,因此前缀缓存(prefix caching)可以继续跨轮工作。远程 MCP server 也能设置 defer_loading: true,让服务端的工具按需加载,省去逐个配置。Google 没有公布节省比例或基准测试,实际账单得结合自己的工具库和会话来看。
工具描述太泛,参数写得再细也帮不上选型
作者在 RiceStudioLab 的运行环境里已经用过类似设计:先看简短介绍,任务需要时再加载对应工具命名空间的完整 schema。这个例子说明,按需加载可以用在同时接入邮件、日历、发布、搜索等数十项服务的工作流里。作者也指出,一旦完整定义被延后,模型就要凭名称和短描述决定先找谁。
比如站点同时有「搜索已发布文章」和「搜索待审稿件」两个工具,如果两条描述都写成「搜索内容」,模型在检索时就缺少区分依据。第一句直接写清搜索范围,比把区别埋在参数定义里更管用。
我的判断
这篇最适合借鉴的是高频工具预载、低频工具按需加载的分法,以及出错后沿 interaction.steps 回查的思路。作者的团队确实在用相似机制,但原文给出的实测数字是站点运营记录。比如 11 月 20 日 IT Post 累计发布 875 篇,当天发了 12 篇,低于 15 篇的目标。这些数字交代了工作场景。原文没有提供两种加载方式在 token、延迟或工具选错率上的对照,所以结尾关于能从 100 个工具中一次只加载 1 份 schema 的 Agent 会更快,仍是经验判断。
如果你的 Node 服务在调用模型前就知道当前操作属于哪个业务域,比如「编辑稿件」页面只需要草稿工具,直接按入口传工具子集也能缩小上下文,并省掉模型检索这一步。如果用户能在同一段对话里从查新闻跳到找稿件、查邮件,模型按需检索才更有发挥空间。
能拿来做什么
- 从已有调用日志里挑出几乎每轮都用的工具,保留预载。先对低频工具试用
defer_loading: true,并用同一批真实任务比较输入 token、端到端耗时和任务完成率。 - 检查名称相近的工具,把操作对象、数据范围和关键边界写进描述第一句。例如,把「查询文章」写成「按关键词搜索已发布文章」,让模型在看到参数前就能区分它和草稿查询。
- 遇到工具调用失败时,先在
interaction.steps里确认模型选了谁,再核对拿到的 schema 和最终参数。选错工具就回查名称和描述,选对却填错参数就检查参数定义。