Gemini API Tool Retrieval 怎麼用?工具一多就吃 token,defer_loading 什麼時候真的省
本文目錄
agent 接了三、四個 MCP server,再加上自己寫的幾十個 function,每次請求都要把全部工具的參數 schema 送給模型。實際上一個任務通常只用到兩三個工具,其他幾萬個 token 每次都白付,工具一多,模型挑錯工具的機率也跟著變高。
Google 在 2026 年 11 月 19 日替 Gemini API 推出 Tool Retrieval,目前是預覽版,只能在 Interactions API 用。做法是先只讓模型看到工具的名稱和簡短描述,需要哪個再載入它的完整 schema,整個過程在同一次 API 呼叫裡完成,不另外收費。Google 官方公告
開法:加一個 tool_search,在長尾工具設 defer_loading
在 tools 陣列加上 {"type": "tool_search"},再替想延後載入的工具設 defer_loading: true。mcp_server 也可以設,那個 server 提供的所有工具都會改成需要時才載入。以下片段來自官方 Tool retrieval 文件,加上中文註解,沒有實際送出請求:
from google import genai
# Tool Retrieval 是預覽功能,要指定 v1betaclient = 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, # 整個 MCP server 的工具都延後載入 },]
interaction = client.interactions.create( model="gemini-4-hydrogen", input="Check the temperature in London and convert 100 USD to EUR.", tools=tools,)有三個設定細節:
generateContent不支援,要用client.interactions.create。- 延後載入的工具還是要附完整
parameters。 沒載入的 schema 不計費;只給名稱的話,模型搜到後拿回空的 schema,沒辦法呼叫。 - 描述很長的工具可以加
short_description,延後載入時模型只看這一行摘要。這個欄位只能搭配defer_loading: true,單獨設會回 400。
最常用的幾個工具建議維持一般載入,只把長尾工具延後,官方也是這樣建議。
回應裡會多兩個 step
模型需要工具時,會先發出 tool_search_call,API 回傳 tool_search_result(裡面是載入的 schema),接著才是一般的 function_call。這兩個 step 會出現在 interaction.steps 裡,不用自己處理,但很適合拿來除錯:看模型搜了哪些名稱,就知道工具命名或描述是不是不夠清楚。
MCP server 的工具會由 API 直接執行,回應裡會看到 mcp_server_tool_call 和 mcp_server_tool_result;自己的 function 則和平常一樣,執行後回傳 function_result。官方特別提醒,function_call 要從 steps 裡找,回應的 status 不一定是 requires_action。
什麼時候省、什麼時候反而更貴
Tool Retrieval 不另外收費,但多了三種輸入 token:
- 延後工具清單:每個工具一行名稱加摘要,官方早期測試約每個工具 26 個 token。
- 固定的搜尋說明:開了
tool_search的每個請求都會加上一小段。 - 每次搜尋多跑一輪模型:搜到工具後,API 會帶著完整上下文和新載入的 schema 再呼叫一次模型,這段記在
usage.total_tool_use_tokens,以輸入價計費。等於每搜一次,就差不多再付一次整段 prompt 的錢(快取命中的部分除外)。
官方文件用整數做了兩個示意情境(不含輸出和快取),下表另外用 Gemini 4 Hydrogen Standard 付費層每百萬輸入 token $1.50 換算金額,價格引自 Gemini API 定價表:
| 情境 | 全部工具直接載入 | 用 Tool Retrieval |
|---|---|---|
| 200 個工具、每個 400 token,對話 2,000 token | 164,000 token(約 $0.246) | 約 23,650 token(約 $0.035) |
| 10 個工具、每個 400 token,對話 30,000 token | 68,000 token(約 $0.102) | 約 92,830 token(約 $0.139) |
第二種情況反而貴了三成多:工具少,省下的 schema 不多,上下文又長,每次搜尋都要把 3 萬 token 重送一遍。官方的選擇表也寫得很直接,工具少於約 20 個、而且固定不變,就照舊全部載入;工具庫大、每次只用少數幾個,才是 Tool Retrieval 划算的情況。
還有一個跟快取有關的細節:延後載入後 prompt 變短,如果原本是靠一大堆 schema 才超過模型的最低快取長度,改完可能就吃不到隱式快取了。上線前用自己的流量比較 total_input_tokens、total_tool_use_tokens 和 total_cached_tokens 三個欄位,會比套用官方範例估得準。
常見的 400 錯誤
| 錯誤訊息(節錄) | 原因 | 處理 |
|---|---|---|
tool_search tool must be specified when using defer_loading. | 有工具設了 defer_loading,但請求裡沒有 tool_search | 加上 {"type": "tool_search"} |
When defer_loading is set on a FunctionDeclaration... | 後續請求漏送 tool_search,或只宣告了 client-side 的 tool_search | 每個請求都送完整 tools 陣列 |
deferred loading is not supported for this model | 模型不支援 | 換成支援清單上的模型 |
Server side tool call context must be circulated... | 自己管理對話紀錄(store=False)時,沒把 tool_search_call、tool_search_result 送回去 | 兩個 step 原封不動送回,signature 也要保留 |
Tool call part is missing thought_signature. | 送回的 step 被拿掉 signature | 照收到的原樣送回 |
Server side tool call context must be circulated 有兩個容易困惑的地方:它出現在送回 function_result 的第二個請求,第一個請求是成功的;而且就算 step 都有送回,只要 system instructions 或其他工具的輸出裡直接提到某個延後工具的名稱,模型可能跳過搜尋直接呼叫,對話就接不下去。官方建議,會被點名的工具不要延後載入。
另外,用 previous_interaction_id 串接多輪對話時,API 會幫忙保存搜尋 step,但不會保存工具宣告。每一輪都要重送同一份 tools,漏送的話,模型只記得之前用過的工具。
支援哪些模型
官方公告寫的是 Gemini 3.6 以後的模型,包含所有 Gemini 4 模型。不過 11 月 20 日查到的文件支援清單只列了四個:gemini-4-hydrogen、gemini-4-argon、gemini-3.8-flash、gemini-3.6-flash,不支援的模型設 defer_loading 會回 400。用 Gemini 4 Neon 或 Carbon 的流程,先送一個小請求確認,再決定要不要開。Hydrogen 的換模比較方式可以參考 Gemini 4 Hydrogen 從 Flash 換過來的驗收方法。
自己有工具索引的話,用 client-side retrieval
如果工具清單要依使用者權限過濾,或已經有自己的 embedding 索引,可以把 tool_search 設成 "execution": "client",並給它 name、description 和參數 schema。模型會像呼叫一般 function 一樣呼叫它,由程式自己搜,再把符合的工具宣告放進 function_result 回傳。
這個模式的工具不用事先宣告,使用者中途連上新的整合時也能加進來;代價是每次搜尋多一趟來回,對延遲敏感的服務還是用 server-side。兩種模式不能在同一個請求裡混用。
工具很多的 agent,延後載入之前也值得先盤點一次哪些工具真的需要,接 MCP 前先做能力盤點整理了判斷方式。盤點後還是有幾十個以上的工具,再挑一條實際流量開 Tool Retrieval,對照開啟前後的 usage 欄位,確定有省再擴大。
參考資料:
Introducing Tool Retrieval in the Gemini API