Google AI Studio 在 Gemini Interactions API 推出 Tool Retrieval 预览:工具 schema 按需加载以省 input token
当地时间 11 月 19 日(北京时间 11 月 20 日凌晨),Google AI Studio 在官方博客与 X 平台官方账号 @GoogleAIStudio 同步宣布:Tool Retrieval 在 Gemini API 进入预览(preview)阶段,落地于 Interactions API。启用后,agent(智能体)不再在每次 prompt(提示词)里附带整个工具库的参数 schema(工具入参的结构定义),而是让全部工具保持待命,当前任务用到哪个才加载哪个;官方称此举旨在减少 input token(输入令牌)消耗,并在 agent 工具规模扩大到数十个甚至数百个时保持工具选择准确。
开启方式是在请求中加入一个 tool_search 工具,并对要暂缓加载(defer)的工具设 defer_loading: true:被 defer 的工具只向模型留下名称和描述,参数 schema 不进入上下文。搜索由 Gemini 在服务端运行,开发者不需要自建或托管任何索引。
按名称索取:搜索、加载、调用三步发生在同一次请求里
随帖附上的 X 长文先把问题摆明:把全部参数 schema 随每次请求发送,会推高 input token 计数、增加延迟,而且候选列表越长,工具选择的准确性越低。模型需要某个被 defer 的工具时,按名称索取;API 载入完整 schema,模型随即发出 function_call——搜索、加载、调用三步全部发生在同一次 API 请求内部。
官方示例用退款场景演示,示例代码使用的模型是 gemini-4-hydrogen:用户输入「Order A-1042 arrived damaged. Please refund 40 dollars.」(A-1042 订单到货破损,请退款 40 美元),工具列表里的 issue_refund 设了 defer_loading: true,注释提示另有 50 多个函数同样被 defer。这次调用里,模型搜索 issue_refund,API 载入其 schema,随后发出 function_call,参数为 order_id: A-1042、amount: 40。
tool_search_call、tool_search_result 和 function_call 三个步骤都会记录在 interaction.steps 里。官方称,开发者在排查工具命名或描述问题时,可以据此看到模型考虑过哪些工具。再往后就是常规流程:代码执行退款,回传一个 function_result。
启用只需两处代码改动,缓存前缀逐轮不变
按官方的描述,接入这套机制的代码改动只有两处:请求里加一个新工具,给要 defer 的工具加一个标志。常用的少数工具可以继续预先加载,长尾工具交给按需检索。
官方点名的另一个兼容点是 prefix caching(前缀缓存):被 defer 的 schema 不会出现在 prompt 开头,模型加载的 schema 插在对话靠后的位置,缓存前缀因此逐轮保持不变。
对远程 MCP(Model Context Protocol,模型上下文协议)服务器同样适用:对一个 mcp_server 工具设 defer_loading: true,该服务器暴露的所有工具都会按需加载。官方称,这样接入一个大型 MCP 服务器时不必逐一列出其中的工具;Gemini API 的 function calling 文档里有 MCP 接入的相关章节。
自建检索可切到 execution: "client",代价是每轮搜索多一次往返
如果团队维护着自己的检索机制、嵌入(embedding)索引或按用户划分的权限过滤,官方给的路径是把 tool_search 声明为 execution: "client",并自定义搜索参数(示例中该工具只带一个必填的 query 字符串参数)。这种模式下查找由应用自己执行,每次搜索多一轮往返(round trip)。
客户端模式还有一个差异:工具不必预先声明。官方示例中,模型对名为 search_tools 的检索工具发出 function_call,应用在自己的内部工具注册表里执行查找,再通过 previous_interaction_id 关联的后续请求,把匹配到的 function schema 以 function_result 送回。公告称,这意味着用户在对话中途接入一个新集成时,对应的新工具可以即时暴露给模型。
不单独收费:省多少取决于有多少 schema 从未被加载
官方写明 Tool Retrieval 不单独收费,输入与输出 token 按所调模型的标准费率计。开启 tool_search 会增加一小块固定的 input token;模型每加载一个 schema,从加载点起按普通输入计费,与预先声明的工具同等对待。
按官方的说法,只有当「从未被加载的 schema」在 token 量上盖过「实际加载的那部分」,这项功能才带来净节省,而大型工具声明通常正是这种情况。
适用范围是 Interactions API 中 Gemini 3.6 及更新模型,实测数字尚缺
公告写明的适用范围是:Interactions API 中 Gemini 3.6 及更新模型,包括全部 Gemini 4 模型。官方给出完整设置指南文档。
截至目前,上述细节均来自 Google AI Studio 的官方口径,公告没有提供 token 节省幅度或延迟变化的实测数字;官方建议开发者用自己的真实流量,找出预先加载与按需加载工具的合适配比。