Gemini API Tool Retrieval 指南:tool_search、defer_loading 配置与计费
介绍如何在 Gemini Interactions API(v1beta)预览版中使用 tool_search 与 defer_loading 启用 Tool Retrieval。对比服务端与客户端两种检索模式,核对官方文档列出的 4 个支持模型与 Google 博客表述差异,提供远程 MCP 配置、无状态重放规则、常见 400 报错排查,以及 token 计费与隐式前缀缓存评估方法。
本文内容

Tool Retrieval(工具检索)现已在 Gemini Interactions API(v1beta)中上线预览,支持智能体通过 tool_search 和 defer_loading 按需加载工具参数 schema。这项能力面向需要将数十个自定义函数或远程 MCP 服务器接入 Gemini 的开发者,并且仅限 Interactions API 使用(generateContent 不支持)。截至 2026-11-20,你可以调用 v1beta/interactions,选用文档明确列出的四个模型之一(gemini-4-hydrogen、gemini-4-argon、gemini-3.8-flash 或 gemini-3.6-flash),加入 {"type": "tool_search"},并对核心工具集之外的工具设置 defer_loading: true 来开始试用。
先选对 API 接入路线
Google 于 2026 年 11 月 19 日在 Google 官方博客 发布了 Tool Retrieval,并在 AI Studio Tool retrieval 文档 中提供了配置说明。由于该功能目前限定在 Interactions API 预览版(v1beta),你当前使用的接口直接决定了能否立即启用。
| 路线 | 账号与地区要求 | 计费单位 | Tool Retrieval 支持情况 | 适用场景 |
|---|---|---|---|---|
官方 Gemini Interactions API(v1beta) | 开发者须位于 Google AI Studio 支持的地区,并持有 Google AI Studio API 密钥;gemini-4-argon 仅限 Paid Tier(付费层级) | 按每 1M 输入、缓存和输出 token 计费(gemini-4-hydrogen、gemini-3.8-flash、gemini-3.6-flash 提供 Standard Free Tier 标准免费层级) | 预览版支持(tool_search、defer_loading、远程 mcp_server) | 工具库规模大,且可以直接调用 v1beta/interactions |
官方 Gemini generateContent API | 同上,开发者须位于支持的地区并拥有 Google AI Studio 账号 | 按每 1M 输入、缓存和输出 token 计费 | 不支持 | 稳定工具数量少于 ~20 个、需要在支持的 Gemini 3 或 2.5 模型上使用显式缓存,或暂时无法迁移接口 |
| 按量付费 API 网关(如 BetterToken) | 需先注册 BetterToken 账号,再进入控制台创建 API 密钥 | 按各模型当前计费单位从按量付费余额扣费 | 未记录对 Interactions API 的支持;Tool Retrieval 支持情况未经核验 | 继续在多模型场景下使用已文档化的原生 Gemini generateContent 或 OpenAI 兼容 Chat Completions 接口(各模型工具调用支持情况以 BetterToken 文档为准) |
如果你暂时不迁移到 Interactions API,而是继续使用标准的 Gemini generateContent 或 OpenAI 兼容 Chat Completions 接口,可以查看 BetterToken 的 Gemini API 参考文档,核对已支持的端点、模型 ID 及各模型的工具调用能力。
支持的模型清单与 Gemini 4 的 400 报错
Google 在 2026 年 11 月 19 日的发布博客中表示,Tool Retrieval 适用于 Gemini 3.6 及更新模型(包括所有 Gemini 4 模型),并链接至最新 Gemini 模型页面。该页面共列出了四款 Gemini 4 模型:gemini-4-carbon、gemini-4-neon、gemini-4-hydrogen 和 gemini-4-argon。
但截至 2026-11-20,官方 Tool retrieval 支持模型清单 实际上只列出了四个模型 ID:
gemini-4-hydrogengemini-4-argongemini-3.8-flashgemini-3.6-flash
截至 2026-11-20,gemini-4-carbon 和 gemini-4-neon 并未出现在 Tool Retrieval 文档的支持列表中。向不支持的模型发送 defer_loading 会返回 HTTP 400 错误,报错信息为 deferred loading is not supported for this model。
建议先用 gemini-4-hydrogen 跑通集成,这也是 Google 在 Tool Retrieval 文档示例里统一使用的模型;如果你正从 Flash 系列迁移过来,可以参考我们的 Gemini 4 Hydrogen 定价与迁移指南。如果你的业务依赖 gemini-4-carbon,启用 defer_loading 前务必先在 v1beta 实际验证可用性,或暂时保留静态加载工具,同时查看 Gemini 4 Carbon API 定价与迁移指南。
服务端检索与客户端检索对比
Interactions API 提供两种互斥的检索模式:服务端检索(默认模式)和客户端检索(execution: "client")。两种模式都能避免在初始提示词里塞入完整参数 schema,但在延迟、开发工作量和工具注册方式上差异明显。
| 对比维度 | 静态工具加载 | 服务端检索 | 客户端检索 |
|---|---|---|---|
| schema 如何提供给模型 | 全部提前随请求发送 | Gemini 按需加载延迟工具的 schema | 由你的应用在 function_result 中返回 schema |
| 需要编写的检索代码 | 无 | 无 | 需自行实现搜索、排序和过滤逻辑 |
| 工具是否需提前声明 | 是 | 是 | 否 |
| 远程 MCP 支持 | 是 | 是(在 mcp_server 上设置 defer_loading: true) | 不适用 |
| 额外网络往返 | 无 | 无(在单次 API 请求内完成) | 每次检索增加一次网络往返 |
| 最适合的场景 | 少于 ~20 个稳定工具 | 大规模固定工具库或多个远程 MCP 服务器 | 私有工具注册表、按用户隔离的权限控制、会话中途动态接入的工具 |
每次请求只能声明一个 tool_search 项。如果在同一请求中同时包含服务端和客户端 tool_search,接口会返回报错 Cannot specify both client-side and server-side tool_search tools.。
配置服务端检索与远程 MCP
服务端检索必须使用 v1beta API 版本。虽然 Google 博客中的代码片段省略了 api_version,但官方 Tool retrieval 指南 明确指出预览版 Tool Retrieval 必须指定 v1beta:在 Python 中需初始化为 genai.Client(http_options={"api_version": "v1beta"});在 JavaScript 中需初始化为 new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } })。
在 Bash 终端中,先以不回显的方式读入你的 Gemini API 密钥,再向 https://generativelanguage.googleapis.com/v1beta/interactions 发送 POST 请求。下面的示例将一个延迟加载的本地函数(convert_currency)与 Google 文档提供的天气演示远程 MCP 服务器(https://gemini-api-demos.uc.r.appspot.com/mcp)组合在同一次调用中:
read -rs GEMINI_API_KEY && export GEMINI_API_KEY
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-4-hydrogen",
"input": "Check the temperature in London and convert 100 USD to EUR.",
"tools": [
{"type": "tool_search"},
{
"type": "function",
"name": "convert_currency",
"description": "Convert an amount from one currency to another using live mid-market rates.",
"short_description": "Convert an amount between currencies.",
"defer_loading": true,
"parameters": {
"type": "object",
"properties": {
"amount": {"type": "number"},
"from": {"type": "string"},
"to": {"type": "string"}
},
"required": ["amount", "from", "to"]
}
},
{
"type": "mcp_server",
"name": "weather_service",
"url": "https://gemini-api-demos.uc.r.appspot.com/mcp",
"defer_loading": true
}
]
}'
构造 tools 数组时必须遵守以下四条规则:
- 服务端
tool_search对象不要设置name、description或parameters。 - 每个延迟加载的
function仍须提供完整的parametersschema。未被加载的 schema 不会计费;如果发送工具时不带参数定义,检索后返回的 schema 将为空,模型将无法调用该函数。 - 可选字段
short_description只能与defer_loading: true一起使用,用于在精简的延迟工具列表中替代冗长的description。 - 接入远程 MCP 服务器时,仅支持 Streamable HTTP 端点(不支持 SSE 服务器),且服务器名称需使用
snake_case命名,不能包含-,具体规范见 Remote MCP 文档。如果远程服务器在握手或 schema 校验阶段报错,可以查看我们的 MCP 服务器接入排障指南。
验证服务端检索响应
服务端检索成功后,同一次 API 响应的 steps 数组中会依次出现 tool_search_call 和 tool_search_result 步骤,随后是实际的工具调用。对于演示服务器上的 get_weather 等远程 MCP 工具,API 还会在同一次响应里直接完成远程调用,并返回 mcp_server_tool_call 与 mcp_server_tool_result 步骤。
对于你自己定义的本地函数,请直接检查 steps 中的 function_call 项。不要只依赖 status == "requires_action" 做判断,因为 Google 指出存在 function_call 步骤时,status 并不总是 requires_action。在本地执行函数后,于下一轮请求中提交 function_result 即可。
配置客户端检索
当工具目录取决于用户权限、内部命名空间,或在会话开始后才动态挂载新集成时,应改用 execution: "client" 模式。客户端 tool_search 定义必须同时填写 name 和 description(缺少任意一项都会返回 400 错误),并且请求中的任何工具都不能设置 defer_loading。
下面的 Python 代码是一个最小协议示例,直接返回固定的函数声明而非查询真实注册表。如果脚本从 followup.steps 中打印出针对 get_billing_history 且参数为 {"user_id": 123} 的 function_call 步骤,就说明整套客户端检索往返已经跑通:
from google import genai
client = genai.Client(http_options={"api_version": "v1beta"})
tools = [
{
"type": "tool_search",
"execution": "client",
"name": "search_tool_registry",
"description": "Search internal tool namespaces such as billing and support when needed.",
"parameters": {
"type": "object",
"properties": {
"query": {"type": "string"},
"namespace": {"type": "string"},
},
"required": ["query"],
},
}
]
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="Look up the billing history for user 123.",
tools=tools,
)
for step in interaction.steps:
if step.type == "function_call" and step.name == "search_tool_registry":
# Minimal protocol example: replace with your own registry or permission filter.
matches = [
{
"type": "function",
"name": "get_billing_history",
"description": "Retrieve billing history for a given user.",
"parameters": {
"type": "object",
"properties": {"user_id": {"type": "integer"}},
"required": ["user_id"],
},
}
]
followup = client.interactions.create(
model="gemini-4-hydrogen",
previous_interaction_id=interaction.id,
tools=tools,
input=[
{
"type": "function_result",
"name": step.name,
"call_id": step.id,
"result": matches,
}
],
)
for next_step in followup.steps:
if next_step.type == "function_call":
print(next_step.name, next_step.arguments)
在 function_result.result 数组中必须返回完整的 JSON 对象形式的函数声明,不要将其序列化为 JSON 字符串,同时要带上对应检索 function_call 的 name 和 call_id。如果客户端检索没有匹配结果,可以返回一段简短文本,说明未找到匹配项并列出模型可搜索的范围,方便它调整查询词。
多轮状态、无状态重放与常见报错
首轮调用跑通之后,大多数集成故障都源于预览版的三项约束:
- 每轮请求都必须重新发送完整的
tools数组。 传入previous_interaction_id时,Interactions API 会保存对话步骤历史,但不会在请求之间保留工具声明。后续轮次若漏传工具数组,模型会找不到未声明的工具,或在服务端模式下输出内部的retriever:调用。 - 已加载的工具无法卸载,服务端未命中时返回纯文本。 工具一旦被模型加载,其 schema 就会在剩余对话中一直留在上下文里。如果服务端检索未能匹配任何延迟工具,API 只会返回普通文本回复,而不会抛出结构化的检索错误,因此不要依赖
tool_search_result来检测未命中。 - 开启
store=false时必须原样回传步骤与签名。 在每次无状态后续请求中,都需要在input里传入完整步骤历史并重新发送完整tools数组。将收到的每一个响应步骤(tool_search_call、tool_search_result、thought和function_call)按原始顺序、保留完整signature字段原样追加,再在末尾附上新的function_result。如果只发送function_result,会丢失检索上下文并触发400报错。请使用能够识别tool_search_call与tool_search_result的新版 SDK,旧版本会把它们解析为未知步骤并丢弃关键字段。此外,系统提示词或工具输出里点名提到的任何工具都不要设为延迟加载,否则模型可能跳过检索直接调用,导致提交function_result时报错。
Google 针对不支持的模型、设置 defer_loading 却缺少服务端 tool_search、未设 defer_loading: true 却使用 short_description、客户端检索漏填 name 或 description、无状态请求遗漏回传步骤以及丢失 signature 等情况,均记录了对应的 HTTP 400 报错。对照下表可快速定位报错原因与修复方式:
| 文档记录的报错信息 | 触发原因 | 修复方式 |
|---|---|---|
deferred loading is not supported for this model | 向不在支持清单中的模型发送了 defer_loading | 改用 gemini-4-hydrogen、gemini-4-argon、gemini-3.8-flash 或 gemini-3.6-flash |
tool_search tool must be specified when using defer_loading. | 某个 function 或 mcp_server 设置了 defer_loading: true,但请求中没有任何 tool_search 工具 | 添加 {"type": "tool_search"},或移除 defer_loading |
When defer_loading is set on a FunctionDeclaration, a Tool with tool_search must also be provided in the request. | 函数设置了 defer_loading: true,但请求缺少服务端 tool_search(例如仅声明了 execution: "client",或后续轮次漏传 tool_search) | 客户端模式下移除 defer_loading,或在后续请求中重新发送包含 {"type": "tool_search"} 的完整 tools 数组 |
Cannot specify both client-side and server-side tool_search tools. | 同一请求中同时声明了服务端与客户端 tool_search | 每次请求只保留一个 tool_search 声明 |
ToolSearch name must not be specified when execution mode is SERVER_SIDE. | 服务端 tool_search 设置了 name(设置 description 或 parameters 也会返回同类错误) | 删除对应字段;若要切换为 execution: "client",需同时提供 name 和 description,并移除所有工具上的 defer_loading |
short_description can only be set if defer_loading is true | 函数设置了 short_description,但未设置 defer_loading: true | 补充 defer_loading: true,或删除 short_description |
Server side tool call context must be circulated when using deferred loading functions. | 无状态请求的历史记录中包含延迟工具的 function_result,但缺少加载该工具的 tool_search_call 和 tool_search_result 步骤 | 原样回传所有 tool_search_call 和 tool_search_result 步骤,并保留 signature |
Server side tool call context must be circulated ... Missing circulated context for functions: FUNCTION_NAME(即便已回传全部步骤) | 模型调用了未经 tool_search 加载的延迟函数,通常是因为该函数名出现在系统提示词或其他工具的输出里 | 不要将按名称提及的工具设为延迟加载 |
Tool call part is missing thought_signature. / Tool response part is missing thought_signature. | 无状态请求中回传的 tool_search_call(call part)或 tool_search_result(response part)步骤缺少 signature 字段 | 保留原始 signature 值,原样回传这两类检索步骤 |
计费字段、前缀缓存与盈亏平衡测算
Tool Retrieval 本身不收取额外功能费,所有 token 均按 Gemini API 定价 页面公布的标准输入、缓存和输出费率计费。截至 2026-11-20,gemini-4-hydrogen 在 Paid Tier 的费率为每 1M 输入 token $1.50、每 1M 缓存输入 token $0.075、每 1M 输出 token $7.50(含思考 token)。gemini-4-hydrogen、gemini-3.8-flash 和 gemini-3.6-flash 均提供 Standard Free Tier 访问;而 gemini-4-argon 仅限 Paid Tier,每 1M token 输入 $2.00、缓存 $0.10、输出 $10.00 的旧费率适用至 2026 年 11 月 30 日(含当天),新费率自 2026 年 12 月 1 日起生效,上调至 $4.00 / $0.20 / $20.00。
每次交互响应可通过 usage 中的五个字段追踪 token 消耗:
total_input_tokens:请求内首次模型调用的提示词总计,包含你的输入、对话历史、系统提示词、未延迟工具的 schema、一小段固定的tool_search指令块,以及延迟工具的单行索引(由name加short_description或description首句组成,Google 早期测试中每个延迟工具约占 26 个 token)。total_tool_use_tokens:服务端工具执行后,API 在同一次请求内追加发起的模型调用所产生的提示词总计,每次服务端工具检索都会计入其中。每次追加调用都会把完整上下文连同新加载的 schema 重新发送一遍,按输入费率计费;单轮内触发多次检索会产生多轮额外开销。total_cached_tokens:由隐式缓存命中的提示词部分,按缓存费率而非标准输入费率计费。total_output_tokens:生成的回复 token,按输出费率计费。total_thought_tokens:生成的思考 token,同样按输出费率计费。
前缀缓存的最小门槛限制
根据上下文缓存文档,Interactions API 仅支持隐式缓存;无论是 Interactions API 还是 Gemini 4 系列模型,均不支持显式缓存。由于检索到的 schema 会追加在模型加载它的对话位置,而不是插入提示词开头,你的系统提示词、工具列表和早期对话轮次在多轮之间能保持稳定的前缀。一旦该前缀超过模型的最小可缓存长度,后续请求(包括每次服务端检索触发的额外模型调用)都可以命中隐式缓存,并在 total_cached_tokens 中体现。
不过,截至 2026-11-20,支持 Tool Retrieval 的全部四个模型对隐式缓存的最小输入门槛均为 4,096 个输入 token。如果你的提示词原本是靠包含完整工具 schema 才超过 4,096 个输入 token,启用延迟加载后,模型提示词的输入 token 数可能降至 4,096 以下,从而低于最小可缓存门槛。此外,在 Gemini 4 模型的多轮对话和智能体循环中,新请求必须至少新增 2,050 个 token(模型输出、思考内容和函数结果均计入该增量),Gemini 才会缓存完整的上一轮请求;若新增量不足,Gemini 会按标准输入费率重新处理上一轮请求末尾的 2,050 个 token。
什么情况下省 token,什么情况下反而更贵
Google 文档给出了一组示意性的两轮请求估算(采用取整数字,未计入输出 token 与缓存):假设模型在请求 1 中加载两个各占 400 token 的工具并返回 function_call,请求 2 传回 function_result。
| 示意场景(Google 文档估算) | 静态加载(输入 token) | 工具检索(输入 + 工具调用 token) | 净变化 |
|---|---|---|---|
| 200 个工具(每个 400 token),2,000 token 上下文 | 2 × (2,000 + 80,000) = 164,000 | 请求 1:7,350 + 检索轮次 8,150;请求 2:8,150 = ~23,650 | 节省 ~86% 输入侧 token |
| 10 个工具(每个 400 token),30,000 token 上下文 | 2 × (30,000 + 4,000) = 68,000 | 请求 1:30,410 + 检索轮次 31,210;请求 2:31,210 = ~92,830 | 增加 ~37% 输入侧 token |
当工具库庞大且单轮通常只用到少数几个工具时,延迟加载带来的收益最明显。相反,如果工具集本身很小,或者长对话几乎每轮都要触发检索,服务端检索带来的额外模型调用(total_tool_use_tokens)就可能抵消甚至超过节省下来的输入 token。建议保留最高频的核心工具提前加载,仅将长尾工具设为延迟加载,并在全面上线前基于真实业务流量,结合实际账单成本观测 total_input_tokens、total_tool_use_tokens 和 total_cached_tokens 三项指标。