你的 agent 接上百个工具,Gemini 改成要用哪个才调哪个
Google 在 Gemini API 的 Interactions API 里推出了 Tool Retrieval,目前是预览形式。它解决的是规模问题:一个 agent 接上几十甚至上百个工具,每次请求都发送全部参数 schema,开销累加得很快。
开销不只是钱。输入 token 被撑大,延迟跟着上去;候选列表越长,模型选错工具的概率也越高。工具少的时候这套做法还成立,工具一多就不好说了。
Tool Retrieval 换了思路:不给模型看全部说明书,只给它看工具的名字和简介。模型因此知道有哪些工具可用,但参数 schema 不进上下文。真需要某个工具时,它按名称请求,API 把完整 schema 加载进来,模型随即调用函数。搜索、加载、调用三步都在同一个请求内完成,不需要外部再发起一轮。
开启方式很轻。请求里加一个 tool_search 工具,再对要延迟加载的工具标记 defer_loading: true。模型搜索、加载 schema、发出 function_call 这三个步骤都会出现在 interaction.steps 里,排查工具名称或描述写得对不对时可以直接看。之后就是普通的函数调用:你的代码执行实际操作,把 function_result 送回。
不需要自建索引,也不用托管检索服务,搜索在 Gemini 服务端跑。代码层面的改动只有两项:新增那个工具,加上延迟加载的标志。
部署可以分开处理。最常用的工具保持预先加载,长尾工具延迟加载。这个比例没有统一答案,建议在自己的真实流量上测,找到适合自己场景的平衡点。
它和前缀缓存也配合得上。延迟的 schema 不在提示开头,被加载的 schema 是对话进行到中途才加进去的,所以缓存前缀在各轮之间保持不变。多轮对话里,这一点会直接影响响应速度和成本。
远程 MCP 服务器是同一套逻辑的延伸:给 mcp_server 工具设置 defer_loading: true,该服务器暴露的所有工具就全部按需加载,不必一个一个列出来。接一个工具很多的大型服务器,配置成本不会跟着线性增长。
如果开发者已经有自己的检索机制、向量索引或按用户做的权限过滤,可以走客户端检索:声明 tool_search 时设 "execution": "client" 并定义搜索参数,查找由你的应用执行。代价是每次搜索多一次往返。换来的是工具不需要预先声明,因此可以在对话中途、用户刚连上某个集成的时候,把新工具暴露出来。
计费没有单独的项目。输入和输出 token 按所调用模型的标准费率算。开启 tool_search 会增加一小块固定的输入 token;模型每加载一个 schema,该 schema 在对话剩余部分按输入计费,和一开始就声明好的工具算法相同。省钱的条件很直白:没被加载过的 schema 要多于被加载的,工具声明规模大时通常就是这个情况。
适用版本是 Gemini 3.6 及更高,包括所有 Gemini 4 模型,且限于 Interactions API。
有几处材料没有回答。预览阶段的配额和使用限制没有说明;客户端检索多出的那一次往返到底增加多少延迟,也没有给出数字。工具调用本身的权限控制会不会受检索机制影响,同样不清楚——在需要按用户区隔工具权限的场景里,这一点值得留意,因为客户端检索的一大卖点正是能自己做权限过滤。3.6 以下版本的用户,也没看到向后兼容的安排。
关键事实
- Tool Retrieval 在 Gemini API 的 Interactions API 中以预览形式推出。
- Tool Retrieval 的设计目标是减少输入 token 并保持工具选择准确,适用于 agent 规模扩展的场景。
- 当 agent 连接几十甚至上百个工具时,每次请求都发送完整参数 schema 会快速累积开销。
- 发送所有工具 schema 会膨胀输入 token 数、增加延迟,并随着候选列表增长降低工具选择准确率。
- 启用 Tool Retrieval 的方式是在请求中添加 tool_search 工具,并对要延迟加载的工具设置 defer_loading: true。
- 模型仍能看到每个延迟工具的 name 和 description,因此知道有哪些工具可用,但参数 schema 不进入上下文。
- 当模型需要某个工具时,它按名称请求,API 加载完整 schema,模型调用函数,全部在同一个请求内完成。
- 搜索、加载 schema、发出 function_call 三个步骤都出现在 interaction.steps 中,便于调试工具名称或描述。