Gemini Tool Retrieval 拆解:Agent 有上百个工具时,怎么少发 schema 还不选错?
先说结论
Google 在 2026 年 11 月 19 日把 Tool Retrieval 放进 Gemini Interactions API 预览。它解决的不是“模型不会调用工具”,而是另一个随着 Agent 规模增长才会暴露的问题:当工具从十几个变成上百个时,每次请求都把全部参数 schema 塞进上下文,会同时增加输入 token、延迟和选错工具的机会。
官方方案是把工具拆成两层:模型始终看到每个工具的名称和描述,但把较长的参数 schema 标记为 defer_loading: true;请求里增加一个 tool_search,模型需要某个工具时先搜索,API 在同一次交互里加载匹配工具的完整 schema,再继续生成工具调用。
我的判断是:这是一项很适合 Agent 平台直接采用的“上下文控制面”能力,但不要把它误读成免费的向量数据库或自动可靠性证明。它能减少未使用工具的重复传输;它不能替你修复含糊的工具名、重叠的描述、危险的权限边界,也不能保证模型永远挑中正确工具。工程上应该保留高频工具常驻,把长尾工具延迟加载,并用真实任务统计每次搜索带来的 token、延迟和误选变化。
发生了什么
主来源是 Google 官方博客《Introducing Tool Retrieval in the Gemini API》,发布日期为 2026 年 11 月 19 日:
- 原始 URL:https://blog.google/innovation-and-ai/technology/developers-tools/gemini-api-tool-retrieval/
- 官方页面给出的功能状态:Gemini Interactions API 预览
官方事实是:Tool Retrieval 适用于 Gemini 3.6 及更新模型,并支持全部 Gemini 4 模型;不另收 Tool Retrieval 服务费,仍按所调用模型的标准输入与输出 token 计费。启用 tool_search 会增加一小段固定输入 token;模型实际加载的每个 schema,会像预先声明的工具一样计入后续对话输入。我的判断是:成本是否下降取决于“从未被调用的 schema”是否明显多于“实际被加载的 schema”,不能只看产品名称就假设每个请求都会更便宜。
技术细节
1. 工具描述可见,参数结构延迟加载
传统的工具调用请求通常把工具数组完整放进去:名称、用途描述、参数类型、必填字段、枚举值和嵌套对象全部随请求发送。当 Agent 有 50 个甚至更多函数时,真正与当前任务相关的可能只有一两个,但其余 schema 仍然占据上下文。
Tool Retrieval 的切分很实用。调用方在工具列表中加入一个 tool_search,对长尾函数设置 defer_loading: true。模型仍然能看到这些函数的名称和 description,因此知道“工具库里有哪些能力”;完整参数定义暂时不进入上下文。模型判断需要退款工具时,可以先按名称请求搜索,平台返回 issue_refund 的完整参数结构,随后模型在同一交互中发出普通的 function call。
官方示例使用一个退款函数:工具名是 issue_refund,参数包括订单标识和退款金额;另外还有 50 多个延迟加载函数。该示例表达的不是“所有工具都必须延迟”,而是一个混合策略:经常使用的工具保持常驻,长尾工具才放到检索路径。
2. 一次交互里的三步可观测
这个设计的关键不只是少传内容,还把选择过程变成了可检查的步骤。官方示例的 interaction.steps 依次包含:模型发起 tool_search_call,API 返回 tool_search_result,模型再产生 function_call。
这为排障提供了比“最后调用失败”更好的证据链。平台可以记录模型搜索了哪些函数、返回了哪些候选、最终调用了哪一个;开发者可以区分三种问题:模型根本没搜到工具,搜索结果里有正确工具但模型选错,还是选对以后参数校验或执行失败。对于生产 Agent,这三类问题的处理方式完全不同,不能都归因成“模型能力不够”。
Google 还说明,搜索发生在同一次 API 调用中,不需要调用方另建索引或托管检索服务。平台会在服务器侧完成工具搜索;应用代码主要变化是增加 tool_search,再给目标函数加延迟加载标记。
3. 和前缀缓存的关系
官方特别提到 Tool Retrieval 可以配合 prefix caching。延迟加载的 schema 不会出现在提示词开头;模型真正加载的 schema 会在对话后段加入。这样,稳定的系统提示、工具名称和描述仍有机会复用缓存,而当前任务才需要的参数细节在后面补进来。
不过,这不是无条件的性能承诺。缓存命中率取决于请求前缀是否稳定,搜索结果取决于工具命名和描述质量,最终账单还取决于实际加载了多少 schema。部署前至少要测三组流量:少量工具、几十个工具、长尾工具很多的工具库,并分别记录输入 token、首 token 延迟、完整响应延迟、搜索命中率和工具误选率。
对 Agent / 工程的影响
1. 工具注册表应该分层,而不是一股脑塞给模型
以前很多 Agent 框架的工具注册方式是启动时收集全部函数,然后每轮请求原样发送。这种方式在 Demo 阶段简单,但工具规模一大,schema 会成为隐形的固定税。Tool Retrieval 给出的启发是把注册表分成三层:安全且高频的核心工具常驻;低频但描述清晰的工具延迟加载;需要额外授权的高风险工具甚至不要直接暴露给模型,而是先经过确定性的策略检查。
这里的“延迟加载”不是权限控制。一个被检索出来的删除、转账或发布工具,仍然需要服务端做身份、参数、审批和幂等校验。不要因为 schema 没在初始 prompt 里,就把它当成安全隔离。
2. 工具描述要像检索索引,不只是给人看的注释
当模型先依据名称和描述选择候选时,描述质量直接影响召回。工具名应该稳定、具体、可区分;描述要说明什么时候用、什么时候不要用、输入的关键限制是什么。两个工具都写成“处理订单”,即使参数 schema 设计得很严谨,前面的搜索也可能把它们混在一起。
建议为每个工具补充离线评测集:给定用户目标,检查正确工具是否出现在检索结果中;再检查模型是否能根据完整 schema 生成合法参数。把“检索召回”和“调用成功”分成两个指标,才能知道优化应该落在描述、搜索还是模型推理。
3. 观测系统要把搜索步骤纳入 trace
传统 Agent trace 只记录最终 function call,Tool Retrieval 之后至少要增加三类事件:候选工具数量、搜索请求与返回结果、最终工具及参数校验结果。成本指标也要拆开:初始工具描述 token、搜索固定开销、实际加载 schema token、工具结果 token。
对线上故障来说,这些字段比一条“工具调用失败”有用得多。比如某次延迟升高,可能不是函数执行变慢,而是工具库描述过长;某次误调用,可能不是模型突然退化,而是新工具和旧工具的描述发生语义重叠。把搜索步骤单独记录,才能做回归比较。
4. 跨 Provider 的抽象要谨慎
这项能力目前是 Gemini Interactions API 的预览接口,字段和行为不能直接假定与其他模型平台一致。如果 Agent 框架要同时支持多个 Provider,建议在内部抽象一个“工具目录与加载策略”层,而不是把 defer_loading 写死在业务工具定义中:Provider 支持时映射到原生 Tool Retrieval,不支持时可以退化为本地候选筛选或静态分组。
但退化路径必须明确标记为不同实现。不同 Provider 的检索算法、计费方式、上下文位置和 trace 语义可能不同,不能对外声称“同一套工具路由行为”。
我的判断
第一,工具数量超过几十个、且每轮只会用到少数工具的 Agent,值得优先试 Tool Retrieval;只有几个高频工具的应用,复杂化收益很小。第二,默认采用“核心工具常驻、长尾工具延迟加载、高风险工具确定性审批”的三层策略,不要把所有函数一刀切延迟。第三,把它当成上下文与成本优化,不要当成安全边界或正确率保证;上线门槛应是自己的检索召回、误选率、延迟和账单数据,而不是官方功能名。
Q&A
Q1:来源和发布日期是什么?
A:Google 官方博客《Introducing Tool Retrieval in the Gemini API》,发布日期为 2026-11-19,原始 URL 是 https://blog.google/innovation-and-ai/technology/developers-tools/gemini-api-tool-retrieval/。本文涉及的功能状态、模型范围、计费说明和示例均以该官方页面为准。
Q2:最小接入需要改什么?
A:在 Interactions API 的工具列表中增加 tool_search,把希望按需加载的函数标记 defer_loading: true,保留名称、描述和完整参数定义。先用一个低风险工具做小流量验证,再逐步扩展到长尾工具。
Q3:它是否一定省钱?
A:不一定。Tool Retrieval 本身没有单独服务费,但固定搜索开销和实际加载的 schema 都会计入输入 token。只有未使用的 schema 足够多,节省才会超过新增开销;必须用真实流量测量。
Q4:能否替代权限系统?
A:不能。延迟加载只改变工具 schema 何时进入上下文,不改变工具是否有权执行。删除、付款、发布等操作仍需服务端鉴权、参数验证、审批和幂等控制。
Q5:哪些场景暂时不适合?
A:工具很少、每轮几乎都会调用全部工具,或者 Provider 适配层还没有稳定 trace 的场景,暂时不必引入。先把工具描述、错误处理和执行验证做好,收益通常比增加一层检索更确定。
字数自检:正文超过 1500 个中文字符;来源、发布日期和原始 URL 已列出。
隐私自检:未包含内部网络地址、真实机器名、凭据或用户相关信息。
文件名:2026-11-22-gemini-tool-retrieval-agent-schemas.md
封面尺寸:1600 / 900;categories:ai_tech