|

Gemini Tool Retrieval 怎么接入?3 步用 Python、tool_search 和 defer_loading 实现工具按需加载

Gemini Tool Retrieval 怎么接入?3 步用 Python、tool_search 和 defer_loading 实现工具按需加载

接入 Gemini Tool Retrieval 需要做三件事。第一,在 tools 数组里加入 {"type": "tool_search"},并给低频业务函数设置 defer_loading: True。第二,用 v1beta 版本的 Interactions API 发起请求,然后从 interaction.steps 里找到 function_call。第三,在本地执行函数,按 call_id 构造 function_result,再带上完整 tools 数组回传。整个过程不需要自己写工具搜索器,服务端会完成工具检索和参数 Schema 装载。

需要先说清楚:Tool Retrieval 只改变“工具参数定义什么时候进入模型上下文”,函数仍然要由开发者执行。 它也不保证一定省钱。工具少、上下文长的场景,Token 消耗反而可能上升。

您读完此文能了解到什么?

  • Gemini Tool Retrieval 支持哪些模型、需要哪个 SDK 版本,以及为什么必须显式指定 v1beta
  • 一份变量名前后一致的 Python 完整示例:库存与订单两个延迟工具,从检索到最终回答
  • tool_search_call、tool_search_result、function_call、function_result 分别由谁处理
  • 远程 MCP 延迟加载、客户端检索与自建 Tool Registry 三条扩展路线的区别
  • HTTP 400 等常见错误的集中排查方法,以及启用前如何判断是否划算

索引:先用 To Know 表格解释核心字段,再用“影响速览”说明这项预览功能对不同角色意味着什么。“客观事实”部分按接入顺序展开:准备环境、定义工具、观察检索步骤、回传函数结果,最后扩展到 MCP 和客户端检索,错误排查集中放在这一部分末尾。“分析判断”部分结合 Google 给出的两组假设性算例,讨论 Tool Retrieval 适合和不适合的场景。

gemini-tool-retrieval-python-tool-search-defer-loading-image-0


Gemini Tool Retrieval 关键概念(To Know)

概念 简要解释
google-genai Google 官方 Python SDK 包名,导入方式为 from google import genai
v1beta 预览接口版本,Tool Retrieval 必须使用,本文在客户端初始化时显式指定
Interactions API Google 面向 Agent 工作流的接口,支持有状态对话和可观察的执行步骤
tool_search 声明启用工具检索的特殊工具类型,单个请求最多一个
defer_loading 让指定函数或 MCP 服务器的完整参数定义延迟进入模型上下文
short_description 模型最初能看到的延迟函数简述,只能用于延迟函数
tool_search_call 服务端检索流程中由模型发起的搜索步骤
tool_search_result 服务端返回匹配工具完整 Schema 的步骤
function_call 模型要求开发者代码执行某个函数,并给出参数
function_result 应用把函数执行结果交还给模型时使用的输入类型
call_id 把函数执行结果与原始 function_call.id 对应起来的标识
previous_interaction_id 让后续请求接续服务端已保存交互记录的标识
signature 无状态会话回放历史步骤时,需要随原步骤一起原样传回的签名字段

Gemini Tool Retrieval 影响速览

人群 实际影响
Agent 开发者 工具多的 Agent 可以把长尾工具延迟加载,不必自建向量检索,但要改用 Interactions API
已用 generateContent 的团队 旧方法不支持 Tool Retrieval,需要迁移接口和返回结构解析
MCP 集成方 可以在 mcp_server 层整体设置 defer_loading,不用逐个声明工具
成本负责人 没有单独的功能费,但每次服务端搜索都会产生额外的计费模型调用,需要盯住 total_tool_use_tokens
小工具库项目 十几个工具、长上下文的场景未必划算,静态加载可能更省

Gemini Tool Retrieval 客观事实:发布信息与接入流程

Gemini Tool Retrieval 发布状态与支持模型

2026 年 11 月 19 日(北京时间 11 月 20 日凌晨),Google 在官方博客发布《Introducing Tool Retrieval in the Gemini API》,在 Interactions API 中开放 Tool Retrieval 预览。作者是 Gemini API 产品经理 Lucia Loher 和 Google DeepMind 研究科学家 Nora Kassner。目前功能处于 Preview 状态,正式发布前接口可能调整。

公告的表述比较宽泛:“Gemini 3.6 及更新模型,包括所有 Gemini 4 模型”。但开发文档截至 2026 年 11 月 20 日只明确列出了 4 个模型 ID:gemini-4-hydrogen、gemini-4-argon、gemini-3.8-flash、gemini-3.6-flash。接入时应以文档名单为准。对不支持的模型设置 defer_loading,会直接返回 HTTP 400。

Gemini Tool Retrieval 接入前准备:SDK 与 v1beta

Google 官方 Python SDK googleapis/python-genai 于 2026 年 11 月 18 日发布 v3.6.0,新增了 Tool Retrieval 和函数结果相关的公共 Schema。安装命令如下:

pip install -U "google-genai>=3.6.0"
export GEMINI_API_KEY="your-key"   # 不要把真实密钥写进代码

版本号有一个容易踩的坑。SDK 从 v3.0.0 起,Gemini Developer API 客户端默认使用 v1,而 Tool Retrieval 要求 v1beta,所以初始化时必须显式指定:

from google import genai

client = genai.Client(
    http_options={"api_version": "v1beta"}
)

SDK 会从环境变量 GEMINI_API_KEY 读取凭据。如果使用 REST,对应的 Endpoint 是 POST https://generativelanguage.googleapis.com/v1beta/interactions,鉴权头为 x-goog-api-key。

第一步:用 tool_search 和 defer_loading 定义 Gemini 工具

演示场景只有两个业务工具:get_inventory 查询商品库存,get_order_status 查询订单状态,两者都设置为延迟加载。tools 数组里各字段的分工如下:

  • {"type": "tool_search"}:开启服务端检索,默认 execution 为 server。没有它就设置 defer_loading,会报 defer_loading requires tool_search。
  • defer_loading: True:完整 parameters 不进入初始上下文,模型一开始只看到名称和简述。
  • short_description:初始列表中的简述。不填时取 description 的第一句。在非延迟函数上填写会被判定为非法。
  • parameters:仍然必须完整提交。延迟的是 Schema 进入模型上下文的时机,服务端仍然需要拿到完整定义。

什么工具适合延迟?Google 的建议是混合使用:高频工具保持直接加载,低频、专业化的长尾工具延迟加载。另外,系统指令里会直接点名的工具不要设为延迟。否则模型可能绕过搜索直接调用,导致缺少加载上下文而出错。名称相近的工具建议加上业务命名空间,例如用 billing_get_customer 和 crm_get_customer 区分,不要都叫 get_customer。

第二步:发送请求并观察 Gemini 工具检索步骤

下面是完整的演示代码。库存“12 件”、订单状态 demo_pending 都是本地模拟数据,不会查询真实系统。运行代码需要有效的 Gemini API Key 和模型访问权限。

import json
from google import genai

MODEL = "gemini-4-hydrogen"

client = genai.Client(
    http_options={"api_version": "v1beta"}
)

tools = [
    {"type": "tool_search"},
    {
        "type": "function",
        "name": "get_inventory",
        "description": "Retrieve the available inventory for a product SKU.",
        "short_description": "Check product inventory by SKU.",
        "defer_loading": True,
        "parameters": {
            "type": "object",
            "properties": {"sku": {"type": "string"}},
            "required": ["sku"]
        }
    },
    {
        "type": "function",
        "name": "get_order_status",
        "description": "Retrieve the status of a customer order.",
        "short_description": "Check an order's current status.",
        "defer_loading": True,
        "parameters": {
            "type": "object",
            "properties": {"order_id": {"type": "string"}},
            "required": ["order_id"]
        }
    }
]

def execute_demo_tool(name, arguments):
    """本地模拟业务函数,不查询真实库存或订单。"""
    if name == "get_inventory":
        return {"sku": arguments["sku"], "available": 12, "data_source": "local_demo"}
    if name == "get_order_status":
        return {"order_id": arguments["order_id"], "status": "demo_pending", "data_source": "local_demo"}
    raise ValueError(f"Unknown tool: {name}")

# 第一次请求:由模型发现并选择需要的工具
interaction = client.interactions.create(
    model=MODEL,
    input="查询商品 SKU-42 的可用库存。",
    tools=tools
)

print("执行步骤:")
for step in interaction.steps:
    print(step.type, getattr(step, "name", ""))

打印出的 interaction.steps 一般按以下顺序出现。具体顺序和检索结果由模型决定,一轮里也可能发生多次搜索。

  1. tool_search_call:模型发现手头没有合适的已加载工具,发起服务端搜索。
  2. tool_search_result:API 返回匹配的 get_inventory 完整参数 Schema。
  3. function_call:模型读取 Schema 后,生成 get_inventory(sku="SKU-42") 这样的调用。

这三步发生在同一次外部 API 请求中,应用不需要另写搜索器,也不用再发一次检索请求。前两步只需观察和记录,不要在本地重复执行搜索。但“同一次请求”不等于“只跑一次推理”:每次服务端搜索都会触发额外的模型调用,这部分 Token 照常计费。调试时还有一点要注意:不能只看 interaction.status。即使状态不是 requires_action,steps 里也可能包含待执行的 function_call。

gemini-tool-retrieval-python-tool-search-defer-loading-image-1

第三步:执行函数并回传 function_result

Tool Retrieval 只负责找到工具和装载参数,真正的业务函数仍由应用执行,这部分沿用标准的 Function Calling 机制。接着上面的代码继续写:

# 只执行真正的业务函数调用,不在应用侧执行 tool_search_call
function_results = []

for step in interaction.steps:
    if step.type != "function_call":
        continue
    result = execute_demo_tool(step.name, step.arguments)
    function_results.append({
        "type": "function_result",
        "name": step.name,
        "call_id": step.id,
        "result": [{"type": "text", "text": json.dumps(result, ensure_ascii=False)}]
    })

# 将本地函数结果送回 Gemini
if function_results:
    followup = client.interactions.create(
        model=MODEL,
        previous_interaction_id=interaction.id,
        tools=tools,
        input=function_results
    )
    print("最终回答:", followup.output_text)
else:
    print("当前回答:", interaction.output_text)

这段代码有三处需要注意。第一,call_id 必须取自原始 function_call 的 step.id。一轮里有多个调用时,模型靠它对应每个结果。第二,previous_interaction_id=interaction.id 让服务端接续已保存的交互记录,包括已经检索过的工具。第三,第二轮仍要传入整个 tools 数组。API 会保留步骤历史,但不会保留工具声明,tool_search、所有延迟和非延迟工具、MCP 配置每轮都要重新提交。

这个示例只演示一次函数调用闭环,没有包含通用的多轮 Agent 调度器。如果 followup 里还有 function_call,按同样的方式继续处理即可。

🎯 技术建议:Tool Retrieval 本身依赖 Google 官方的 v1beta Interactions API。如果你想先用标准 Function Calling 跑通业务函数、对比不同模型选工具和填参数的表现,可以在 API易 apiyi.com 用同一个 Key 切换 Gemini、Claude、GPT 等模型做基线测试。

扩展:远程 MCP 与 Gemini 客户端检索

远程 MCP 服务器可以在服务器这一层设置延迟加载,它暴露的工具会按需装载:

mcp_tools = [
    {"type": "tool_search"},
    {
        "type": "mcp_server",
        "name": "weather_service",
        "url": "https://gemini-api-demos.uc.r.appspot.com/mcp",
        "defer_loading": True
    }
]

和自定义函数不同,远程 MCP 工具由 API 代为执行,steps 中出现的是 mcp_server_tool_call 和 mcp_server_tool_result,应用不需要回传结果。官方文档目前没有给出“最大可延迟工具数”。

如果企业已经有自己的工具注册表、向量检索或用户级权限过滤,可以改用客户端检索:设置 "execution": "client",并提供完整的 name、description 和 parameters。这时第一轮返回的是对 search_tool_registry 的普通 function_call。应用检索后,在 function_result.result 中返回完整工具声明对象数组,不要序列化成一个 JSON 字符串。客户端模式不使用 defer_loading,并且同一请求不能混用两种模式。

gemini-tool-retrieval-python-tool-search-defer-loading-image-2

维度 服务端检索 客户端检索(Gemini) 自建 Tool Registry(通用方案)
检索执行方 Gemini API 开发者应用 开发者应用
关键配置 tool_search + defer_loading tool_search + execution: client 普通 Function Calling
是否要提前声明全部工具 需要 不需要 不需要
额外网络往返 无 每次搜索 +1 轮 每次搜索 +1 轮
动态新增工具 不便 支持 支持
典型场景 大型、相对固定的工具库 多租户、私有注册表 跨模型复用、多厂商切换
可用平台 Google 官方 v1beta Google 官方 v1beta API易 apiyi.com 等 OpenAI 兼容接口

最后一列不是 Gemini Tool Retrieval,而是一种思路相近的工程实现:先只暴露一个搜索函数,检索命中后再把对应 Schema 加进 tools。它适合需要在多家模型之间切换的团队。最小写法如下:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["APIYI_API_KEY"],
    base_url="https://api.apiyi.com/v1"  # API易 OpenAI 兼容接口
)
MODEL = "your-model-name"  # 以平台模型列表为准

search_tool = {"type": "function", "function": {
    "name": "search_tool_registry",
    "description": "Search internal business tools by keyword.",
    "parameters": {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}}}
查看自建 Tool Registry 的完整两段式调用
import json, os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["APIYI_API_KEY"],
    base_url="https://api.apiyi.com/v1"
)
MODEL = "your-model-name"  # 以平台模型列表为准

TOOL_REGISTRY = {
    "get_inventory": {"type": "function", "function": {
        "name": "get_inventory",
        "description": "Retrieve the available inventory for a product SKU.",
        "parameters": {"type": "object", "properties": {"sku": {"type": "string"}}, "required": ["sku"]}}},
    "get_order_status": {"type": "function", "function": {
        "name": "get_order_status",
        "description": "Retrieve the status of a customer order.",
        "parameters": {"type": "object", "properties": {"order_id": {"type": "string"}}, "required": ["order_id"]}}},
}
search_tool = {"type": "function", "function": {
    "name": "search_tool_registry",
    "description": "Search internal business tools (inventory, orders) by keyword.",
    "parameters": {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}}}

def search_registry(query):
    q = query.lower()
    return [name for name, t in TOOL_REGISTRY.items()
            if any(w in t["function"]["description"].lower() for w in q.split())]

def execute_demo_tool(name, args):
    if name == "get_inventory":
        return {"sku": args["sku"], "available": 12, "data_source": "local_demo"}
    if name == "get_order_status":
        return {"order_id": args["order_id"], "status": "demo_pending", "data_source": "local_demo"}
    raise ValueError(name)

messages = [{"role": "user", "content": "查询商品 SKU-42 的可用库存。"}]
tools = [search_tool]

for _ in range(4):  # 简单循环上限,防止死循环
    resp = client.chat.completions.create(model=MODEL, messages=messages, tools=tools)
    msg = resp.choices[0].message
    if not msg.tool_calls:
        print("最终回答:", msg.content)
        break
    messages.append(msg)
    for call in msg.tool_calls:
        args = json.loads(call.function.arguments)
        if call.function.name == "search_tool_registry":
            names = search_registry(args["query"])
            tools += [TOOL_REGISTRY[n] for n in names if TOOL_REGISTRY[n] not in tools]
            content = json.dumps({"loaded_tools": names})
        else:
            content = json.dumps(execute_demo_tool(call.function.name, args), ensure_ascii=False)
        messages.append({"role": "tool", "tool_call_id": call.id, "content": content})

💡 选择建议:注册表路线的检索质量取决于你的搜索函数,示例中的关键词匹配只用于演示。在 API易 apiyi.com 上切换模型跑同一组任务,比较“是否搜到正确工具”和“参数是否填对”,就能看出哪个模型更适合你的工具库。

Gemini Tool Retrieval 常见错误集中排查

现象 原因 处理
defer_loading requires tool_search 声明了延迟函数,但没有服务端 tool_search 在 tools 中加入 {"type": "tool_search"}
short_description 不合法 写在了非延迟函数上 只给 defer_loading=True 的函数使用
HTTP 400 unsupported model 模型不在支持名单内 改用文档列出的 4 个模型 ID
请求不生效或报版本错误 SDK 默认走 v1,或调用了 generateContent 显式设置 api_version="v1beta" 并改用 Interactions API
第二轮 HTTP 400 store=False 时遗漏检索步骤或 signature 原样回放 tool_search_call/result 及所有签名
模型误用旧工具、工具不可用 后续请求漏传 tools 每轮重新提交完整 tools 数组
检索后参数为空 延迟工具只提交了名称和简述 延迟工具也要提交完整 parameters
客户端检索配置失败 缺少 name、description 等字段 补全客户端搜索函数定义

无状态模式(store=False)需要单独说明。这时不能依赖 previous_interaction_id,应用要自行保存并按原样回放用户输入、tool_search_call、tool_search_result、function_call、function_result 以及所有 signature。删改其中任何一步,服务端都可能无法重建检索上下文。另外,服务端没搜到匹配工具时,可能直接返回一段文本,而不是结构化错误。所以“请求没报错”不等于“检索成功”,验证时应逐项检查 steps 里是否出现了预期的检索步骤和函数调用。


Gemini Tool Retrieval 分析判断:什么时候值得接入

判断一:收益取决于工具库规模和上下文长度,不是开启就省钱。 Google 文档给了两组方向相反的假设性算例,并明确说明它们不是生产 Benchmark。第一组是 200 个工具、每个 400 Tokens、基础上下文 2,000 Tokens、请求 2 次,静态加载约 164,000 Tokens,Tool Retrieval 约 23,650 Tokens,按此推算下降约 85.6%。第二组是 10 个工具、基础上下文 30,000 Tokens,静态加载 68,000 Tokens,Tool Retrieval 反而达到 92,830 Tokens,增加约 36.5%,原因是额外的搜索推理要重新处理整段长上下文。Google 的工程建议是:少于约 20 个稳定工具时,静态加载通常就够了。

gemini-tool-retrieval-python-tool-search-defer-loading-image-3

判断二:评估成本要看 total_tool_use_tokens,不能只看首轮输入。 官方早期测试中,每个延迟工具的简述平均约占 26 Tokens,100 个工具大约是 2,600 Tokens,这是近似值。真正需要盯住的是搜索引发的额外模型调用,以及已加载 Schema 在会话中的累积。当前文档没有提供卸载已检索工具的机制,长会话中检索的工具越多,上下文就越大。缓存也不是无条件受益:初始提示词变短后,可能低于隐式缓存的最低门槛。

判断三:按需工具加载已经成为行业共识,但各家数据不能横向套用。 Anthropic 在 2025 年 11 月推出 Tool Search Tool,OpenAI 在 2026 年 3 月随 GPT-5.4 推出 Tool Search,两家都公布过各自条件下的实测节省数据。Google 这次只给出了假设性算例。截至 2026 年 11 月 20 日,还没有可核验的 Gemini Tool Retrieval 独立生产实测。因此,“Gemini 实测省 85%”之类的说法目前都站不住。

对开发者的建议:先把现有 Agent 的工具按调用频率分层,高频工具直接加载,长尾工具延迟加载;再用同一批任务对比静态加载和 Tool Retrieval 的总 Token、端到端耗时、选对工具的比例和参数正确率。功能仍处于预览阶段,正式发布时间未定,生产环境中最好保留一条回退到静态加载的开关。在模型选型阶段,可以先借助 API易 apiyi.com 的统一接口低成本跑通标准 Function Calling 基线,再迁移到官方 v1beta 验证 Tool Retrieval 的净收益。

工具越多,越要先想清楚每把工具什么时候拿出来。正如《论语·卫灵公》所言:“工欲善其事,必先利其器。”


📚 参考资料

  1. Introducing Tool Retrieval in the Gemini API:Google 官方发布公告

    • 链接: blog.google/innovation-and-ai/technology/developers-tools/gemini-api-tool-retrieval
    • 说明: 发布日期、设计目标、MCP 与两种检索模式
  2. Tool retrieval 官方文档:配置、限制、计费与算例

    • 链接: aistudio.google.com/docs/tool-retrieval
    • 说明: 本文代码、错误规则、无状态回放和 Token 算例的主要依据
  3. Function Calling 官方文档:函数执行与结果回传

    • 链接: aistudio.google.com/docs/function-calling
    • 说明: function_result 与 call_id 的标准用法
  4. Interactions API 官方文档:接口结构与执行步骤

    • 链接: aistudio.google.com/docs/interactions-overview
    • 说明: 有状态对话、steps 与 generateContent 的区别
  5. python-genai v3.6.0 / v3.0.0 Release:SDK 版本记录

    • 链接: github.com/googleapis/python-genai/releases
    • 说明: Tool Retrieval Schema 支持与默认 API 版本变化

作者:APIYI 技术团队
技术交流:多模型 Function Calling 对比测试可访问 API易 apiyi.com,更多接入资料见 docs.apiyi.com 文档中心

延伸阅读

类似文章