工具一多 Agent 就乱选?Gemini 工具检索配置教程

给 Agent 接了七八个 MCP 服务器、上百个函数以后,常见的毛病是每次请求都背着几万 token 的参数定义,模型还越来越容易挑错工具。谷歌 11 月 19 日(美国时间)给 Gemini API 加了 Tool Retrieval(工具检索)预览版:工具库一次声明全,参数 schema 等模型要用时再加载。下面按官方文档讲服务端检索、远程 MCP 延迟加载、客户端检索和计费怎么算,代码都抄自文档。
前置条件:只有 Interactions API 和 4 个模型能用
- 用 Interactions API,不是
generateContent,后者不支持工具检索。功能处于预览阶段,要用v1beta,Python SDK 里写genai.Client(http_options={"api_version": "v1beta"})。 - 模型限定为
gemini-4-hydrogen、gemini-4-argon、gemini-3.8-flash、gemini-3.6-flash。在别的模型上设defer_loading会直接返回 400。 - 先数一下自己的工具。官方的选型表写得很直白:稳定的工具不到 20 个左右,就继续全量发送,用不着检索。工具和 MCP 的基本概念可以先看站内的 MCP 是什么。
文档顶部写明 API 在正式版之前可能会变,下面的字段名以 11 月 20 日的文档为准。
先算账:工具多才省,上下文大反而更贵
检索本身也要花 token。每个延迟加载的工具仍会在输入里占一行,内容是工具名加 short_description(没设就取 description 第一句),谷歌早期测试大约每个工具 26 token。打开服务端 tool_search 还会多一小段固定的检索说明。最贵的是检索本身:每次服务端检索,API 都要带着完整上下文和新加载的 schema 再调一次模型,这部分记在 total_tool_use_tokens,按输入价计费。
文档给了一个示意算例(整数估算,不含输出和缓存):一次对话 2,000 token,模型加载 2 个工具、每个 400 token,前后两次请求。
| 场景 | 全量发送(输入 token) | 工具检索(输入 + 工具调用 token) |
|---|---|---|
| 200 个工具,每个 400 token | 164,000 | 约 23,650 |
| 10 个工具,上下文 30,000 token | 68,000 | 约 92,830 |
第一行省了八成多,第二行反而多花三成多:工具少,能省的本来就不多,上下文又大,每次检索都要把 30,000 token 再发一遍。
工具库越大、每次请求用到的工具越少,检索越划算;工具少、上下文长、几乎每轮都要检索时,反而更贵。
第一步:开启服务端检索,长尾工具延迟加载
在 tools 数组里加一条 {"type": "tool_search"},再给想延迟加载的函数加 defer_loading: true。模型能看到这些工具的名字和描述,看不到参数 schema。下面是文档里的写法,同时演示了函数和远程 MCP 服务器:
from google import genai
client = genai.Client(http_options={"api_version": "v1beta"})
tools = [
{"type": "tool_search"},
{
"type": "function",
"name": "convert_currency",
"description": "Convert an amount from one currency to another.",
"defer_loading": True,
"parameters": {
"type": "object",
"properties": {
"amount": {"type": "number"},
"to": {"type": "string"},
},
"required": ["amount", "to"],
},
},
{
"type": "mcp_server",
"name": "weather_service",
"url": "https://gemini-api-demos.uc.r.appspot.com/mcp",
"defer_loading": True,
},
]
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="Check the temperature in London and convert 100 USD to EUR.",
tools=tools,
)
for step in interaction.steps:
print(step.type, getattr(step, "name", ""))
一次调用里会依次出现 tool_search_call(模型按名字要工具)、tool_search_result(API 返回完整 schema),然后是正常的 function_call。前两步你只看不用处理。MCP 服务器上的工具由 API 直接调用,返回 mcp_server_tool_call 和 mcp_server_tool_result;自己的函数照常执行,再回一个 function_result。MCP 工具在检索结果里的名字带服务器前缀,比如 weather_service:get_weather。
每个请求只能有一个 tool_search。服务端的 tool_search 不要写 name、description、parameters,写了会报错。
第二步:用 short_description 压缩清单
有些函数的描述又长又细,全塞进延迟清单也占地方。给设了 defer_loading 的函数加一个 short_description,检索阶段模型只看这句短的:
{
"type": "function",
"name": "convert_currency",
"description": "Convert an amount between currencies using live mid-market rates, with optional rounding and historical date lookup.",
"short_description": "Convert an amount between currencies.",
"defer_loading": true,
"parameters": { ... }
}
没设 defer_loading 却写了 short_description,会返回 400。几个服务都有相似操作时,文档建议函数名带服务前缀,比如 billing_get_customer 和 crm_get_customer,short_description 开头也写上服务名,模型才分得清。
第三步:多轮对话每次都发完整 tools
工具声明不会在请求之间保留,用了 previous_interaction_id 也一样。回传 function_result 的那次请求,必须带上和第一轮相同的完整数组:tool_search、全部延迟工具(包括 MCP 服务器)、全部常规工具。漏了的话,模型只记得之前调过的工具,可能去调本次没声明的函数。
fc_step = next(s for s in interaction.steps if s.type == "function_call")
followup = client.interactions.create(
model="gemini-4-hydrogen",
previous_interaction_id=interaction.id,
tools=tools,
input=[{
"type": "function_result",
"name": fc_step.name,
"call_id": fc_step.id,
"result": [{"type": "text", "text": '{"amount": 92.4, "currency": "EUR"}'}],
}],
)
print(followup.output_text)
如果你自己管会话状态(store=False,每次把完整历史塞进 input),tool_search_call 和 tool_search_result 两个步骤要原样回传,signature 字段一个字都不能动,位置也要放在用到该工具的 function_call 之前。文档建议直接 history.append(step.model_dump()),并用认得这两种步骤类型的新版 SDK。
第四步:自己有工具注册表,就用客户端检索
已经有向量索引、按命名空间分组的注册表,或者要按用户权限过滤工具,就把检索交回给自己的代码。声明时加 "execution": "client",name 和 description 必填,参数自己定:
tools = [{
"type": "tool_search",
"execution": "client",
"name": "search_tool_registry",
"description": "Search the internal tool registry for functions.",
"parameters": {
"type": "object",
"properties": {
"query": {"type": "string"},
"namespace": {"type": "string"},
"limit": {"type": "integer"},
},
"required": ["query"],
},
}]
模型会像调普通函数一样发出 search_tool_registry 的 function_call,你跑完检索,把完整的函数声明作为对象数组放进 function_result.result(别序列化成 JSON 字符串),模型下一轮就能调用这些新工具。工具不必事先声明,用户中途接入一个新集成,也能把它的工具临时塞进对话。
| 服务端检索 | 客户端检索 | |
|---|---|---|
| 检索代码 | 不用写 | 搜索、排序、过滤都自己写 |
| 工具要事先声明 | 要 | 不用 |
| 支持 MCP 服务器 | 支持 | 不适用 |
| 额外往返 | 无,在一次调用内完成 | 每次检索多一次请求 |
| 适合 | 工具多但固定 | 自有注册表、按用户的工具集 |
两种模式在一个请求里只能选一种,客户端模式下也不能再用 defer_loading。对延迟敏感的应用,文档推荐服务端检索。
常见坑
- 系统提示里点名的工具被延迟了。工具名出现在系统指令或别的工具输出里,模型可能不检索就直接调用,第二次请求报
Server side tool call context must be circulated,对话没法继续。点名的工具别延迟。 - 延迟工具只给了名字和短描述。完整
parameters照样要写,没加载的 schema 不计费;缺了 schema,检索回来是空的,模型调不了。 - 靠 status 判断要不要执行函数。返回了
function_call时,status不一定是requires_action,每次都去steps里找。 - 检索落空当成报错处理。没匹配到工具时模型返回文字,不会有结构化的检索错误。客户端检索搜不到时,文档建议回一句短说明,列出能搜什么。
- 加载过的工具卸不掉。被检索进来的 schema 会留在上下文里,之后每轮都按输入计费。另外工具一延迟,提示变短,原本靠工具 schema 才过缓存门槛的提示可能就进不了隐式缓存了。
完成标准
- 每轮都用到的几个工具没有延迟,长尾工具和大的 MCP 服务器设了
defer_loading。 - 系统指令里加了一句「现有工具都做不了时,用 tool search 找一个」这类说明。
- 多轮请求每次带完整
tools;自管状态时检索步骤连同signature原样回传。 - 用自己的真实流量对比开关前后的
total_input_tokens、total_tool_use_tokens、total_cached_tokens,确认是净节省。
功能发布当天的要点见站内快讯 Gemini API 上线工具检索;工具该做成 Skill 还是 MCP,可以看 Skill 和 MCP 的区别。
最后
先挑一个工具最多的 Agent,只给长尾工具加 defer_loading,跑一天真实流量,对比 usage 再决定要不要全面铺开。