Gemini Agent 是什麼？Google AI Agent 如何呼叫工具、API 與函式

最後更新於 2026 年 8 月 18 日。本篇技術結論核實自 Google 官方文件：Managed Agents（Gemini Agent）、Function calling 與 Using Tools with Gemini API。

症狀：產品文件裏同時出現 Gemini、Agent、Tools、Function calling，團隊不知道該接 Interactions API、自管循環，還是託管 Agent。
最快解法：先分清「模型會生成調用意圖」和「誰真正執行副作用」；內置工具走 Google 沙箱，自定義函數必須由你的應用執行並回傳 function_result。

誰該看這篇：

• 要把 Google AI Agent 接到訂單、工單、知識庫或內部 API 的後端工程師；
• 正在比較自研 Agent Loop 與 Gemini Managed Agents 的架構負責人；
• 已經能聊天，但不能安全寫庫、發郵件或改配置的平臺團隊。

Gemini Agent 到底指哪一層

日常溝通裏的「Gemini Agent」至少有三層，混在一起就會把採購、權限和排障全部做反。

第一層是會推理的 Gemini 模型。它可以根據你聲明的函數 Schema，在回覆中產出結構化的 function_call，而不是只能輸出自然語言。這一層解決的是「模型知不知道該調什麼」，並不自動擁有你的數據庫密碼，也不會替你發真實 HTTP 請求。

第二層是Gemini API 的工具能力。官方把 Tools 定義爲可在一次對話或 Live 會話中被模型請求的能力：既可以是 Google Search、Code Execution、URL Context 這類託管工具，也可以是你自己聲明的 Function Calling。詳見 Gemini API Tools 文件。

第三層才是產品意義上的 Gemini Agent / Managed Agents。你可以把系統指令、預設工具、遠程 MCP、自定義函數、文件與 AGENTS.md/SKILL.md 固化成一個可按 ID 調用的 Agent；調用時用 Interactions API，而不是每次手寫完整循環。官方說明預設工具包含 code_execution、google_search 和 url_context，也可以在單次 interaction 覆蓋。見 Building Managed Agents。

對工程決策更有用的判斷是：如果你只需要一次結構化取數，Function calling 就夠了；如果你需要沙箱、搜索、代碼執行、遠程 MCP 和可復用的 Agent 配置，再上 Managed Agents。不要因爲名字裡有 Agent，就把所有業務寫進提示詞。

工具、API 與函數如何分工

標題裏的三個詞對應三條不同的執行路徑，不能互相替代。

• 工具（Tools）：給模型看的能力清單。內置工具由 Google 執行；自定義工具只是一份聲明，執行權仍在你這邊。
• API：你的業務接口、第三方 HTTP、數據庫查詢。模型永遠看不到密鑰，它只生成參數；由你的服務用正式鑑權去打真實 API。
• 函數（Functions）：本地代碼、SDK 方法、隊列生產者。聲明用 JSON Schema，運行時用 name + arguments + 唯一 id 對齊結果。

官方把 Function calling 的三類用途寫得很清楚：採取行動（預約、開票、發信）、增強知識（查庫、查文件）、擴展能力（計算器、出圖）。這和「讓模型直接生成最終 JSON 給前端渲染」不是一回事。需要中間步驟連接外部系統時用 Function calling；只要最終回答符合某個 Schema，用 Structured Outputs。見 Function calling 指南。

如果你已經在別的模型上踩過工具循環，可以把同一套編排紀律遷過來。例如我們寫過 Mac mini M5 值得等嗎？什麼時候買最划算：消息鏈、流式參數和冪等保護，在 Gemini 這邊同樣成立，只是字段名換成 function_call / function_result 與 previous_interaction_id。

一次完整的函數調用循環

一次可靠的調用，不是「模型吐了個函數名就算成功」。官方流程可以壓成五步，缺任何一步都會在生產裏表現爲重複下單或胡編參數。

1. 聲明：把 name、description 和 JSON Schema 參數交給模型。描述要寫清何時該用、何時不該用，而不是只寫「獲取數據」。
2. 請求：用戶輸入與 tools 一起發給 interactions.create 或 generateContent。
3. 模型決策：可能直接回答，也可能返回 function_call，帶上 id 和 arguments。
4. 你來執行：校驗類型、鑑權、超時、冪等鍵，再打真實 API 或本地函數。模型不會替你執行自定義代碼。
5. 回傳結果：用同一個 id 提交 function_result，必要時帶上 previous_interaction_id，讓模型生成用戶可讀回復，或繼續下一輪工具。

最小聲明長這樣——真正上線時把 order_id 等業務字段寫進 required，並禁止模型發明不存在的枚舉值：

{
  "type": "function",
  "name": "get_order_status",
  "description": "按訂單號查詢履約狀態，禁止用於創建或取消訂單。",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {"type": "string", "description": "業務訂單號，例如 OD-20260818-001"}
    },
    "required": ["order_id"]
  }
}

執行層不要把模型參數直接拼進 SQL 或 Shell。先做 Schema 校驗，再映射到內部 DTO，最後用服務賬號調用 API。返回給模型的內容只保留它下一輪推理需要的字段，不要把完整用戶檔案或密鑰回灌進上下文。

並行調用和組合調用是兩件不同的事。一次 turn 裏多個 function_call 可以同時查詢庫存和物流；組合調用則是先查地點再查天氣，必須等上一跳結果回來。官方 Interactions 示例用天氣和恆溫器說明：先 get_weather_forecast，再決定 set_thermostat_temperature。你的編排器要按 id 等待，而不是看到函數名就重放整條鏈。

內置工具與自定義函數的執行邊界

Google AI Agent 最容易寫錯的地方，是把「模型請求了工具」理解成「服務端已經做完」。官方 Tools 文件把兩條路徑拆開：

• 內置工具：搜索、代碼執行、URL 上下文等由 Google 管理。沙箱裡的步驟會自動產生匹配的 function_result。
• 自定義函數 / Computer Use：你的應用負責執行。模型只給出結構化 JSON，例如 {"name":"get_order_status","args":{"order_id":"123"}}，並帶唯一 id。

Managed Agents 把這件事說得更硬：當自定義函數和沙箱工具混用時，API 用 step matching。內置工具在服務端跑完；尚未執行的自定義調用會讓 interaction 進入 requires_action。客戶端要過濾已經有 function_result 的 call_id，只執行 pending 的 function_call，再把結果送回。漏過濾就會對同一 id 執行兩次，這在支付和建單場景裏是事故而不是重試。

因此，生產編排至少要保存四類證據：原始 function_call、本地執行日誌、回傳的 function_result、以及 interaction 狀態（完成 / requires_action / 失敗）。只看聊天窗口裡的「已調用工具」不夠。

本地 Agent 連不上模型時，問題往往在網關、密鑰和模型列表，而不是 Schema。排查順序可以參考 Prime Agent Ollama 2026：連不上排查：先證明傳輸層通，再談工具循環。

調用模式、MCP 與組合調用

模型什麼時候必須調工具，由配置約束，而不是靠提示詞碰運氣。Interactions 文件用 tool_choice 描述模式：

• auto（預設）：模型自己決定回答還是調用；
• any：強制產生函數調用，適合「這一步必須落到系統」的工作流節點；
• none：禁止調用，適合純解釋或復盤；
• validated（預覽）：強調 Schema 遵從。

把「查天氣」設成 any 沒問題；把「刪除生產數據」設成 any 且沒有人工審批，就是在用模型當定時炸彈。高副作用工具應預設 auto 或白名單，並在執行層再卡一道。

遠程 MCP 讓 Agent 接到外部工具服務器：配置裏提供 name 和 url。這對 IDE、內部網關和多團隊工具目錄很方便，但鑑權、網絡出口和工具可見範圍必須由你定義。不要把未鑑權的 MCP 暴露到公網，再指望模型「自己小心」。

多工具混用時，Gemini 3 系列可以在同一次 interaction 裏組合內置工具與自定義函數；previous_interaction_id 會把內置工具上下文帶下去。對你意味着：日誌必須按 interaction 而不是按單次 HTTP 請求歸檔，否則組合調用的第二跳會看起來像「模型無故又調了一次」。

流式場景還要凍結參數組裝。官方支持把函數參數以增量 arguments 推過來，你必須聚合完整 JSON 再執行，禁止對半截 order_id 打生產 API。

上線前必須卡住的風控點

Function calling 能跑通 Demo，離能跑無人值守任務差的是控制面。建議按下面六項驗收，全部通過再打開寫操作。

1. 權限最小化：讀訂單和改訂單分成兩個函數；模型看不到的能力不要出現在 Schema 裏。
2. 冪等：所有創建、扣款、發信帶業務冪等鍵，用 function_call.id 或你自己的 request-id 去重。
3. 超時與取消：自定義函數必須有 deadline；超時返回明確錯誤對象，而不是空字符串，以免模型換參數重試。
4. 結果最小化：回傳狀態碼、摘要、下一步建議，不要回傳完整行級數據。
5. 輪次與費用預算：限制單任務工具次數、牆鍾時間和 token；超限進入人工隊列。
6. 可回放：保存聲明版本、模型版本、arguments、結果哈希，才能判斷是 Schema 漂移還是業務 bug。

若工具結果可能已經寫入業務系統，禁止「再讓模型試一次」。先查冪等表。若只是前端把同一次調用渲染了兩遍，修日誌聚合，不要改提示詞。這些判斷和 Kimi 側的止損順序一致，差別只在 Gemini 多了 requires_action 這一狀態。

選型上可以記住三句話：只要結構化最終答案，用 Structured Outputs；只要連接你的 API，用 Function calling；要沙箱、搜索、MCP 和可復用配置，再用 Managed Agents。三套能力可以出現在同一條產品裏，但執行責任必須寫進架構圖，而不是寫進營銷頁。

把 Gemini Agent 的工具循環跑在會休眠的筆記本上，常見後果是 requires_action 回調丟失、日誌被截斷、MCP 長連接斷開。臨時雲主機能拉起進程，卻不容易長期保留完整 interaction 記錄和固定的 macOS 工具鏈。需要持續復現函數調用、保存調試日誌並遠程接管時，租用 Kvmkit 的 Mac 環境通常比佔用個人電腦更穩：機器可保持在線，Homebrew、Docker 與證書鏈也更好對齊。你可以先看 幫助中心 的遠程條件，再對照 美國東部 Mac mini 租用方案。若必須接本地 USB 或專網設備，自購仍然更合適；但對 Gemini 工具循環的夜間回歸和審計留存，穩定在線的遠程 Mac 更容易留下可核對的證據。