接入 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 关键概念(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 一般按以下顺序出现。具体顺序和检索结果由模型决定,一轮里也可能发生多次搜索。
tool_search_call:模型发现手头没有合适的已加载工具,发起服务端搜索。tool_search_result:API 返回匹配的get_inventory完整参数 Schema。function_call:模型读取 Schema 后,生成get_inventory(sku="SKU-42")这样的调用。
这三步发生在同一次外部 API 请求中,应用不需要另写搜索器,也不用再发一次检索请求。前两步只需观察和记录,不要在本地重复执行搜索。但“同一次请求”不等于“只跑一次推理”:每次服务端搜索都会触发额外的模型调用,这部分 Token 照常计费。调试时还有一点要注意:不能只看 interaction.status。即使状态不是 requires_action,steps 里也可能包含待执行的 function_call。

第三步:执行函数并回传 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 官方的
v1betaInteractions 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 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 个稳定工具时,静态加载通常就够了。

判断二:评估成本要看 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 的净收益。
工具越多,越要先想清楚每把工具什么时候拿出来。正如《论语·卫灵公》所言:“工欲善其事,必先利其器。”
📚 参考资料
-
Introducing Tool Retrieval in the Gemini API:Google 官方发布公告
- 链接:
blog.google/innovation-and-ai/technology/developers-tools/gemini-api-tool-retrieval - 说明: 发布日期、设计目标、MCP 与两种检索模式
- 链接:
-
Tool retrieval 官方文档:配置、限制、计费与算例
- 链接:
aistudio.google.com/docs/tool-retrieval - 说明: 本文代码、错误规则、无状态回放和 Token 算例的主要依据
- 链接:
-
Function Calling 官方文档:函数执行与结果回传
- 链接:
aistudio.google.com/docs/function-calling - 说明:
function_result与call_id的标准用法
- 链接:
-
Interactions API 官方文档:接口结构与执行步骤
- 链接:
aistudio.google.com/docs/interactions-overview - 说明: 有状态对话、steps 与 generateContent 的区别
- 链接:
-
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 文档中心
