教程2026-11-20 · 智涌AI

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

Gemini 工具检索教程头图:左侧大字 Gemini 工具检索与每个延迟工具约 26 token、4 个支持模型、每个请求 1 个检索工具 数据卡,右侧终端展示 tools 数组里的 tool_search、给函数和 MCP 服务器设 defer_loading,以及 tool_search_call、tool_search_result、function_call 三个步骤

给 Agent 接了七八个 MCP 服务器、上百个函数以后,常见的毛病是每次请求都背着几万 token 的参数定义,模型还越来越容易挑错工具。谷歌 11 月 19 日(美国时间)给 Gemini API 加了 Tool Retrieval(工具检索)预览版:工具库一次声明全,参数 schema 等模型要用时再加载。下面按官方文档讲服务端检索、远程 MCP 延迟加载、客户端检索和计费怎么算,代码都抄自文档。

前置条件:只有 Interactions API 和 4 个模型能用

文档顶部写明 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 token164,000约 23,650
10 个工具,上下文 30,000 token68,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。对延迟敏感的应用,文档推荐服务端检索。

常见坑

完成标准

功能发布当天的要点见站内快讯 Gemini API 上线工具检索;工具该做成 Skill 还是 MCP,可以看 Skill 和 MCP 的区别。

最后

先挑一个工具最多的 Agent,只给长尾工具加 defer_loading,跑一天真实流量,对比 usage 再决定要不要全面铺开。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。