搭配 Gemini API 使用工具¶
工具能擴充 Gemini 模型的能力,讓模型能在現實世界中採取行動、存取即時資訊,並執行複雜的運算工作。模型既能在標準的請求與回應互動中使用工具,也能透過 Live API 在即時串流工作階段中使用工具。
工具是模型可用來回答查詢的特定能力(例如 Google 搜尋或程式碼執行)。Gemini API 提供一整套由 Google 完全代管的內建工具,你也可以透過函式呼叫定義自訂工具。
如要建構多步驟、以目標為導向的系統,請參閱代理總覽。
可用的內建工具¶
| 工具 | 說明 | 使用案例 |
|---|---|---|
| Google 搜尋 | 以網路上的時事與事實為回應接地,降低幻覺發生的機率。 | 回答近期事件相關問題、以多元來源查證事實。 |
| Google Maps | 建構具備地點感知能力的助理,能尋找地點、取得路線,並提供豐富的在地脈絡。 | 規劃包含多個停靠點的旅遊行程、依使用者條件尋找在地商家。 |
| 程式碼執行 | 讓模型撰寫並執行 Python 程式碼,精確解出數學問題或處理資料。 | 解出複雜的數學方程式、精確處理與分析文字資料。 |
| URL 上下文 | 指示模型讀取並分析特定網頁或文件的內容。 | 根據特定 URL 或文件回答問題、跨不同網頁擷取資訊。 |
| Computer Use | 讓 Gemini 能檢視螢幕,並產生與網頁瀏覽器 UI 互動的操作(用戶端執行)。 | 自動化重複性的網頁工作流程、測試網頁應用程式的使用者介面。 |
| File Search | 為你自己的文件建立索引並進行搜尋,以實現檢索增強生成(RAG)。 | 搜尋技術手冊、針對專有資料進行問答。 |
特定工具的相關費用詳情,請參閱定價頁面。
工具的執行方式¶
工具讓模型能在對話過程中要求執行操作。流程會依工具是內建(由 Google 代管)或自訂(由你代管)而有所不同。
內建工具流程¶
使用內建工具(Google 搜尋、Google Maps、URL 上下文、File Search、程式碼執行)時,整個流程都在單一 API 呼叫內完成:
-
You 送出提示詞:「GOOG 最新股價的平方根是多少?」
-
Gemini 判斷需要使用工具,並在 Google 的伺服器上執行(例如先搜尋股價,再執行 Python 程式碼計算平方根)。
-
Gemini 回傳以工具結果為依據接地的最終答案。
自訂工具流程(函式呼叫)¶
使用自訂工具與 Computer Use 時,執行工作由你的應用程式處理:
-
You 送出提示詞,並一併送出函式(工具)宣告。
-
Gemini 可能回傳結構化 JSON 來呼叫特定函式(例如
{"name": "get_order_status", "args": {"order_id": "123"}}),且一律附帶唯一的id。 -
You 在你的應用程式或環境中執行該函式。
-
You 將函式結果連同與函式呼叫相同的
id一起送回 Gemini。 -
Gemini 運用結果產生最終回應,或發出另一次工具呼叫。
預覽版:對於同時使用 bash 與自訂工具進行建構的開發者,Gemini 3.1 Pro Preview 另透過 API 提供一個獨立端點,稱為 gemini-3.1-pro-preview-customtools。
詳情請參閱函式呼叫指南。
結合內建與自訂工具的流程¶
預覽版:Gemini 4 與 Gemini 3 系列模型支援在單一回合中結合內建工具與自訂工具的選項。
對於結合內建工具與自訂工具(函式呼叫)的請求,模型會運用工具上下文流通來協調不同環境之間的執行:
-
You 送出提示詞,宣告要啟用的內建工具與自訂函式,並設定旗標開啟組合支援。
-
Gemini 執行內建工具;若產生任何用戶端函式呼叫,則交由使用者處理(何者先執行,取決於提示詞與模型的判斷)。它會回傳一份回應,其中包含:
-
工具呼叫的確認
-
工具回應的結果(若模型產生了兩個平行函式呼叫,這可能會出現在 JSON 之後)
-
用來呼叫你的函式的結構化 JSON
-
用於保留上下文的加密思考簽章
-
You 在你的應用程式或環境中執行該函式。
-
You 回傳 Gemini 回應的所有部分,再加上你的函式呼叫結果。
-
Gemini 運用所有合併後的上下文產生最終回應。
如要瞭解如何開啟內建與自訂工具組合的支援,以及上下文流通的範例,請參閱工具組合指南。
結構化輸出與函式呼叫的比較¶
Gemini 提供兩種產生結構化輸出的方法。當模型需要連接你自己的工具或資料系統來執行中間步驟時,請使用函式呼叫。當你嚴格要求模型的最終回應必須符合特定結構定義(例如用於算繪自訂 UI)時,請使用結構化輸出。
搭配工具使用結構化輸出¶
預覽版:此功能僅適用於 Gemini 4 與 Gemini 3 系列模型。
你可以將結構化輸出與內建工具結合,確保以外部資料或運算結果接地的模型回應,依然符合嚴格的結構定義。
程式碼範例請參閱搭配工具使用結構化輸出。