Gemini API 推出 Tool Retrieval:按需加载工具 Schema,降低 Token 开销
今天,我们在 Gemini API 中推出 Tool Retrieval(工具检索)功能,目前已在 Interactions API 中开启预览。
当一个 agent 接入了数十甚至上百个工具时,每次请求都发送完整的参数 schema,开销会迅速累积:不仅推高输入 token 数量和延迟,候选工具一多,模型选择工具的准确率也会下降。有了 Tool Retrieval,你可以让 agent 把完整的工具库放在“待命”状态,只在当前任务需要时才加载对应的参数 schema。
工作原理
启用 Tool Retrieval 的方法很简单:在请求中添加一个 tool_search 工具,并给需要延后加载的工具设置 defer_loading: true。模型仍然能看到每个延后加载工具的名称和描述,因此知道自己有哪些工具可用,但参数 schema 不会占用上下文。当模型需要某个工具时,它会按名称发起请求,API 加载完整 schema,然后模型调用该函数——这一切都在同一次请求内完成。
from google import genai
client = genai.Client()
tools = [
{"type": "tool_search"},
{
"type": "function",
"name": "issue_refund",
"description": "Refund an order to the original payment method.",
"defer_loading": True,
"parameters": {
"type": "object",
"properties": {
"order_id": {"type": "string"},
"amount": {"type": "number"},
},
"required": ["order_id", "amount"],
},
},
# ... 50+ other deferred functions (leave frequent tools undeferred)
]
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="Order A-1042 arrived damaged. Please refund 40 dollars.",
tools=tools,
)
在这单次 API 调用中,模型会搜索 issue_refund,API 加载其 schema,模型再发出 function_call。这三个步骤都会记录在 interaction.steps 中,方便你在调试工具名称或描述时,查看模型考虑了哪些工具:
"steps": [
{
"type": "tool_search_call",
"id": "tsc_7f2a",
"arguments": {"function_names": ["issue_refund"]},
"signature": "..."
},
{
"type": "tool_search_result",
"call_id": "tsc_7f2a",
"result": [{"type": "function", "name": "issue_refund", "parameters": {...}}],
"signature": "..."
},
{
"type": "function_call",
"id": "fc_91c3",
"name": "issue_refund",
"arguments": {"order_id": "A-1042", "amount": 40}
}
]
之后的流程就是普通的函数调用了:你的代码执行退款操作,并返回一个 function_result。
不需要构建或托管任何索引。搜索由 Gemini 在服务端完成,所以代码改动只有两处:添加新工具,以及给需要延迟加载的工具加个标志位。你可以把最常用的工具预先加载,而把长尾工具交给延迟加载。
Tool Retrieval 还能与前缀缓存良好配合。延迟加载的 schema 不会出现在 prompt 开头,模型加载的 schema 会在对话靠后的位置添加,因此各轮对话的缓存前缀保持不变。
Tool Retrieval 同样支持 Gemini API 中的远程 MCP 服务器。只需在 mcp_server 工具上设置 defer_loading: true,该服务器暴露的所有工具都会按需加载,无需逐一列举即可连接大型服务器。
客户端检索的工作方式
如果你自己维护工具注册表、embedding 索引或基于用户的权限过滤,可以在声明 tool_search 时设置 "execution": "client" 并定义搜索参数。客户端检索每搜索一次会多一轮往返,因为查找由你的应用执行。工具无需预先声明,因此当用户在对话中途接入某个集成时,你也能即时暴露新工具:
tools = [{
"type": "tool_search",
"execution": "client",
"name": "search_tools",
"description": "Search the internal tool registry for functions.",
"parameters": {
"type": "object",
"properties": {"query": {"type": "string"}},
"required": ["query"],
},
}]
# 当模型发出对 "search_tools" 的 function_call 时,
# 在 function_result 中返回匹配的 {"type": "function", ...} schema:
followup = client.interactions.create(
model="gemini-4-hydrogen",
previous_interaction_id=interaction.id,
tools=tools,
input=[{
"type": "function_result",
"name": "search_tools",
"call_id": step.id,
"result": my_registry.search(**step.arguments),
}],
)
定价与支持的模型
Tool Retrieval 不单独收费,输入和输出 token 按所调用模型的标准费率计费。开启 tool_search 会增加一小块固定的输入 token,而模型加载的每个 schema 会按输入计费,贯穿本次会话余下的对话,与一开始就声明的工具计费方式相同。只要未加载的 schema 数量多于已加载的(大型工具库通常如此),就能省下 token。建议结合你自己的实际流量来评估。
Tool Retrieval 支持 Gemini 3.6 及更高版本的模型,包括所有 Gemini 4 模型,均通过 Interactions API 使用。
如何上手
- 阅读文档 — 包含完整设置指南和示例
- 对比 Gemini 各模型 — 为你的使用场景找到最合适的模型
- 加入 Discord 讨论 — 向团队反馈意见