Gemini API 推出 Tool Retrieval,工具太多時改成需要才載入參數定義

Google 在 Interactions API 預覽 Tool Retrieval:把工具的參數 schema 延後到模型需要時才載入,減少每次請求的 token 與延遲。

重點

  • Google 11 月 19 日宣布 Gemini API 的 Tool Retrieval,目前是預覽版,只在 Interactions API 提供。
  • 做法是在請求加入 tool_search 工具,並對想延後載入的工具設 defer_loading: true;模型先只看到名稱與描述,需要時才由 API 載入完整參數 schema。
  • 不另外收費,照模型的 token 價格計;支援 Gemini 3.6 以上,含所有 Gemini 4 模型。
  • 也支援遠端 MCP server,以及自己管理工具索引的 client 端搜尋模式。
目錄(4 節)
  1. 發生什麼事
  2. 怎麼運作
  3. 費用與支援範圍
  4. 對你的影響

發生什麼事

Google 在 11 月 19 日的官方部落格介紹 Gemini API 的 Tool Retrieval。它處理的是一個常見問題:代理(agent)接上的工具越多,每次請求都要把所有工具的完整參數定義送給模型,輸入 token 變多、延遲變高,Google 也說工具清單變長時,模型選對工具的準確度可能下降。

Tool Retrieval 的思路是把工具庫「待命」,只在任務需要時才載入那個工具的參數 schema。目前是預覽版,只在 Interactions API 提供。

Gemini API 推出 Tool Retrieval,工具按需載入以節省 token。

怎麼運作

伺服器端模式:在請求裡加入 tool_search 工具,並對想延後載入的工具設定 defer_loading: true。模型一開始只看得到這些工具的名稱與描述;需要時它按名稱要求某個工具,API 把 schema 載入,模型接著送出函式呼叫,這些都在同一次請求內完成。tool_search_call、tool_search_result 與 function_call 會出現在 interaction.steps,方便除錯。不必自己建索引,搜尋由 Gemini 在伺服器端執行。常用工具可以不延後,只把長尾工具延後;延後的 schema 不放在 prompt 開頭,所以前綴快取在多輪對話中仍有效。

遠端 MCP:在 mcp_server 工具上設 defer_loading: true,該 server 提供的全部工具都會延後載入。

Client 端模式:把 tool_search 宣告為 "execution": "client" 並自訂搜尋參數,適合已有自己的工具註冊表、向量索引或權限過濾的團隊。每次搜尋會多一次來回,因為查找由你的應用程式執行;好處是工具不用事先宣告,可以在對話中途(例如使用者連接新整合時)才提供。

費用與支援範圍

沒有額外收費,輸入與輸出 token 按所用模型的標準價格計。啟用 tool_search 會多一小塊固定的輸入 token,而模型載入的每個 schema 在該對話後續都會計入輸入。Google 表示工具庫大、未載入的 schema 多於已載入的時候才會省,建議用自己的流量實測。支援 Gemini 3.6 以上,包含全部 Gemini 4 模型。

官方範例是一則退款請求:模型搜尋到被延後的 issue_refund 工具,API 載入 schema 後,模型填入訂單編號與金額送出呼叫。

對你的影響

  • 如果你的代理只接十來個工具,效益有限;工具數量到幾十個以上、或接了多個 MCP server 時,才值得試。
  • 它仍在預覽,且綁定 Interactions API;已經用其他 Gemini 介面的專案,要先確認能否搬過去。
  • 先拿真實流量比較開啟前後的 token 用量與工具選擇正確率,再決定是否上線。