一个内部发票助手开始只有两个只读功能:查一张发票的状态,列出未结发票。后来,它要服务多个工作区,还得区分客服、财务和只看汇总的人。工具清单里的名字越来越像,参数说明越来越长,但一次查询仍常常只用到一个功能。如果直接给模型同一份庞大清单,输入被无关契约填满;如果为了节省输入把所有功能统一藏起来,模型遇到简单查询也要先搜索。更重要的是,模型搜到了功能,并不意味着这次会话有权用它。
Google 在 2026 年 11 月 19 日发布公告,把 Tool Retrieval 带到 Gemini Interactions API 预览。它解决的是何时把工具的参数契约纳入模型上下文,而不是如何替应用做访问授权。判断这项能力值不值得用,不能只问一次提示词少了多少,也要问在真正的对话里,权限在哪儿生效、搜索失败如何收场、一次任务要来回几次。下面用合成账单说明,不涉及真实客户资料。
三种加载方式解决的不是同一个问题
静态清单是最简单的起点:应用先按当前身份挑出可用工具,然后把完整声明直接放进请求。模型看得到它们的参数,匹配后返回调用,应用再决定能否执行。对于两个长期稳定、几乎每次都用的工具,这种方式很实用。应用能清楚知道每轮提供过什么,少了一种搜索失败,也少了一段必须处理的中间交互。只要可用清单很短,就没有必要为了接入新特性而先建一个检索层。对于上线团队,这也适合作为对照组,之后才能判断改动来自目录变化,还是来自加载机制。
服务端检索适合较稳定、规模较大但每次只用少数工具的目录。依据 Gemini 开发指南,应用仍向接口提交完整声明,长尾功能标记为 defer_loading,并放入服务端 tool_search。模型开始处理问题时,延迟工具的名称与短描述仍可见,参数契约按需加进同一请求的工作上下文。这里的「没有全加载」不是说请求体没有发送声明,也不是说供应商从未收到 schema。试图只发名称、删掉参数来缩短请求,反而让工具被找到后缺少可调用的契约。
应用自管检索则让应用选择如何搜、从哪儿搜、返回什么。模型发出搜索需求,应用以当前会话绑定的工作区和角色过滤目录,再返回候选声明;每次这样的搜索都比服务端检索多一个应用往返。它适合不同组织的目录本来就不同,或授权变化很频繁、目录数据不能预先批量交给推理服务的情况。自管不是把整个目录搬到另一处就结束了:要给零匹配、搜索超时和索引延迟设定退路,处理一轮多次搜索,也不能把本该只供内部路由使用的目录标识暴露给模型。
三种方式可以并存。比如常用的发票状态查询静态加载,低频且共用的帮助类只读工具交给服务端延迟加载,各组织自己的账单功能留在应用检索中。不要把这理解为在同一请求里任意叠加所有协议变体。实现时应按 官方指南 选择相应的工具搜索形态;尤其不能把服务端 defer_loading 生硬地套到只配置了客户端搜索的请求中。先做流量层面的分组,或按产品页面分别测试,比设计一个把所有模式都塞进去的调用封装更容易归因。
查得到与做得到,中间还有一道门
设想账单助理从工作区甲开始对话,模型得到函数名与类似「读取发票状态」的描述。工作区甲的员工问另一个工作区的票号,模型可能把工作区当成查询参数补进去。这个值属于用户输入,并不是访问凭证。应用应该从已认证会话取当前工作区,不接受模型自行指定的身份,再根据当前权限和已知参数形状检查调用。即便前一秒检索允许,同一个用户也可能刚刚换了角色;检索结果不能当作一个长期有效的通行证。若检索是远程服务、执行来自应用,这个边界尤其容易写成两个团队各自假定对方已经检查。
授权应发生两次,目标不同。给模型看候选功能之前过滤,是为了不外泄组织功能名称、描述和目录结构,也避免模型被无关选项干扰。调用发生前再次检查,是为了保护实际记录,防止会话间复用目录、延迟结果或者权限撤销落在两次请求之间。发票号只能识别记录,不能确定归属;实际查询应在数据层一并限定工作区与记录标识。对不存在和无权读取的对象,产品不一定要给出可区分的信息,否则只读工具本身也可能被用来探测记录归属。检索日志同样应以少量状态和计数为主,不用保存用户的原始票号去证明模型搜得对。
普通函数与远程 MCP 还要分开。普通函数由应用收到调用后执行,正好有机会在派发处做校验。官方指南描述的延迟远程 MCP 工具可由 Gemini 在服务端执行,并在响应中给出远程调用与结果。此时看到调用步骤已经太晚,不能把它当成一个待本地批准的请求,也不要以为切成客户端检索就多了一层远程执行拦截。若组织必须逐次检查实际工具和参数,就选择可由应用控制派发的路径,或者让远程端本身以每个请求的有效授权限制操作;仅凭检索结果或一个过宽的共享凭证不能提供这个保障。下例刻意不接远程工具,不会触发写操作。
用一个只读例子把边界跑清楚
以下 JavaScript 是一个本地策略模型。把它保存成 policy-demo.js 后可用现代 Node.js 运行。搜索仅返回名称,以便看清过滤过程;实际客户端搜索还要按协议返回选定的函数声明对象,而不是把名称列表当作 Gemini 响应。账单是硬编码合成数据,真实实现需替换为认证后的访问控制及带工作区约束的读取。这个例子不需要连接模型或外部服务。
function buildTools(workspace, getRights) {
const names = ["billing_get_status", "billing_list_open"];
const allowed = name => names.includes(name) && getRights(workspace).has(name);
return {
search(query) {
const q = String(query).trim().toLowerCase();
if (!q || q.length > 64) return [];
return names.filter(n => allowed(n) && n.includes(q)).slice(0, 3);
},
dispatch({name, args}) {
if (!allowed(name)) return {error:"denied"};
if (!args || Object.keys(args).length !== 1) return {error:"bad_args"};
if (name === "billing_get_status" && typeof args.id === "string" &&
/^INV-[0-9]{3}$/.test(args.id)) {
return {status: workspace === "work-a" && args.id === "INV-001"
? "open" : null};
}
if (name === "billing_list_open" && args.status === "open")
return {count: workspace === "work-a" ? 1 : 0};
return {error:"bad_args"};
}
};
}
const rights = new Set(["billing_get_status"]);
const api = buildTools("work-a", w => w === "work-a" ? rights : new Set());
const check = condition => { if (!condition) throw Error("assertion failed"); };
check(api.search("billing").length === 1);
check(api.search(" ").length === 0);
check(api.dispatch({name:"billing_get_status",args:{id:"INV-001"}}).status === "open");
check(api.dispatch({name:"billing_get_status",args:{id:"INV-001",workspace:"work-b"}}).error === "bad_args");
check(api.dispatch({name:"billing_list_open",args:{status:"open"}}).error === "denied");
rights.clear();
check(api.dispatch({name:"billing_get_status",args:{id:"INV-001"}}).error === "denied");
console.log("six checks passed");
六项本地 JavaScript 检查通过:目录只给出已授权功能,空查询不列出目录,合法请求返回合成状态,额外工作区参数被拒,直接调用未授权工具失败,检索后撤权同样使执行失败。这里展示的是策略分层,不是把每种 JavaScript 对象都验证完毕,也不证明生产系统在撤权和并行请求的竞态下有同样保证。真正的实现还应使用严格的 schema 校验、数据层权限、请求大小限制及带归属的权限上下文;把决定工具资格的状态延续到实际数据读取,比在模型请求开始时先做一次快照可靠。
还有两个实际失败值得演练。一个是查询词不落在预期命名空间:比如用户问的是付款渠道,而这套目录只有发票读取能力。空匹配时返回有限的可用类别或请用户具体说明,而不是把检索范围自动扩大到公司全局。另一个是权限变动之后用户恰好发来下一句话。对用户来说,合理回复是说明目前无法完成查询,而不是用旧结果假装刚查过。模型搜索准确率的统计也应保留这类失败:一次不该执行的任务被正确拒绝,是策略的成功,不应被简单归入「工具没有找到」。反过来,超时后回答一句「已经查到」也不应因为成功生成文字就计为完成。
多轮请求常见的两种断点
该能力目前针对支持模型的 Interactions API v1beta 预览,不宜照搬到其他 Gemini 接口。使用服务端保存的交互时,即便下一次携带 previous_interaction_id,每次请求也应重新提交当前适用的 tools 数组,回传函数结果的那轮也不例外。把交互标识当作永久保存并继承当前工具清单的句柄,容易出现第一轮能搜、第二轮不能继续的问题。在应用端把可用目录的构建从首轮代码中抽出来,让每次请求走相同的授权与目录生成入口,更便于定位问题。
使用无状态历史时,回传的内容也不能只保留最后的自然语言和函数参数。官方指南要求把 tool_search_call、tool_search_result 等需要回放的步骤按顺序保留,签名字段不可丢。日志脱敏与协议回放最好分两条路径:面向排障的简表只保存事件类别、数量和追踪标识,而用于继续请求的内部存储按协议原样持有必要步骤,并接受访问控制和保留策略。不要用一段人工摘要代替带签名步骤后再交回接口;摘要能帮助人理解之前发生过什么,不是供应商认可的交互证据。
应用还应逐次看返回中的 function_call 步骤,而不是只通过一个顶层状态判断是否需要处理。对一次复合问题,请区分发现候选工具、模型实际给出调用、应用授权、执行得到结果、结果被用户看到这几个检查点。这样才知道一轮失败究竟来自检索没找到、声明漏了参数、权限不再允许,还是执行成功但回传链断了。对于有限时间内的重复调用,应用可以按交互和调用标识防止同个返回被派发两次,但这个机制也不能替代权限复核。
看整次交互,不要只看第一轮的输入
官方计费说明 表明,延迟工具的名称和短描述仍会计入输入;服务端搜索还会触发额外模型运算,其输入相关用量记录在 total_tool_use_tokens,按输入费率计。缓存也会改变结论:按需加载让前缀缩短,可能反而低于该模型的缓存门槛;另一方面,如果短目录本就小,每次还多一次搜索,自管方案的网络耗时或服务端多出的模型用量都可能比节省的 schema 更显眼。不能只从一个总数把各字段相加,计量前先查适用模型的字段定义与账单口径,防止把包含关系算成两份成本。
可以把验证拆成三组固定任务:第一组只查一个常用工具,第二组一轮依次要用不同领域的几个工具,第三组故意让角色只看到汇总。对三种加载方式使用同样的模型、约束和工具返回,把冷启动与重复前缀分别记下来。每条记录观察整次处理需要多少请求、多少搜索、发现的候选是否合理、是否尝试了越权调用、最终得到的答复是否来自这轮结果,以及首次可用答案的耗时。比较时也要把正确拒绝、无匹配降级、重试带来的消耗计进去。如果只留下速度最快的成功样本,最重要的上线成本会藏在失败里。
模型供应商的实际选工具、用量、延迟以及远程执行行为没有在本文中实测,不能把本地策略的通过数代替线上数据。我的选择是先用静态授权清单做可靠基线;确实出现大量命名稳定且低频的工具时,再挑长尾做服务端延迟加载;目录的可见性跨工作区差别大,或工具调用必须逐条走应用控制时,再评估自管检索。无论最后采用哪一种,要把权限复核留在真正能阻止执行的位置。这比让模型更快记住工具名字重要得多。
相关文章
Digital.ai Release 26.3:让 AI 代理读懂发布,而不是替人批准
Antigravity /teamwork 新进展:多代理何时值得并行
模型路由何时省钱:成本、质量与缓存的取舍
Finch 调用 MCP 实战:从零开始制作一个 MCP 小程序

评论
暂无评论。