Gemini API Tool Retrieval 指南:tool_search、defer_loading 配置与计费

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

本文内容
Gemini API Tool Retrieval 指南:tool_search、defer_loading 配置与计费

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-hydrogen
  • gemini-4-argon
  • gemini-3.8-flash
  • gemini-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 仍须提供完整的 parameters schema。未被加载的 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 三项指标。

BetterToken · 企业采购
企业专属价
支持开发票对公转账 / 支付宝 / 微信支付全系列文本 / 编程、图像、视频模型
文本 / 编程
图像
视频
专属技术支持领取企业折扣价目表 →