Gemini API 工作流程：可控 AI Agent 的工具、驗證與版本管理

把 Gemini 接進 AI 工作流程，不是把一個模型名稱放進提示詞就完成了。真正可維護的設計，會把任務拆成可觀察的節點：理解需求、取得資料、呼叫工具、驗證結果、人工核准與回覆。舊文提到 Gemini 1.5 Flash，但模型端點、參數與能力會隨版本演進；新專案不應假設舊版模型仍是合適的預設值，而要先查看 Google 的最新模型指南與淘汰公告。

本文保留「圖結構 AI agent」的核心概念，但將它改成平台無關的工作流設計方法。Gemini 是推理與工具選擇的一個節點；流程圖、狀態、權限與最終責任，仍由應用程式和團隊設計。依 Google 目前文件，新的 Interactions API 可支援多步工具編排、結構化輸出與可觀察的執行步驟，但不會取代應用端的驗證與安全控制。

先分清楚：模型、工具與工作流是三層不同的事

模型層：負責理解、分類、摘要、規劃或產生結構化候選結果。模型版本、成本、延遲與可用能力都要記錄。
工具層：將模型輸出的結構化參數送到資料庫、搜尋、CRM、排程或其他 API。工具真正執行動作，模型本身不會直接執行你的程式。
工作流層：決定節點順序、分支、重試、逾時、人工核准、錯誤處理與審計。這層才是「圖結構」的來源。

把三層混在同一段提示詞裡，容易造成無法測試、無法重跑、也無法說明誰做了什麼。先把每個節點的輸入、輸出、允許工具和失敗行為寫清楚，模型才有可控的工作邊界。

一個可控的工作流可以長什麼樣子？

以「協助內部人員查詢訂單狀態」為例，流程不必讓模型直接修改任何資料。可先由分類節點判斷意圖，再以結構化輸出抽取訂單編號；接著由受限的讀取工具查詢資料，驗證節點檢查查詢結果與使用者權限，最後由模型把已驗證資料整理成回覆。若使用者要求退款、地址變更或其他有影響的操作，流程應改走明確的人工核准或交易系統規則。

這種設計的優點不是讓圖越複雜，而是讓每個分支可以獨立測試：資料不存在怎麼回？工具逾時要重試還是轉人工？模型提出不在 allowlist 的工具怎麼拒絕？哪些節點需要寫入稽核紀錄？

Function calling：模型提議，應用程式負責執行

Gemini 的 function calling 文件說明了基本循環：應用程式先宣告函式名稱、用途與參數 schema；模型根據使用者需求提出函式呼叫與參數；應用程式自行執行該函式，並把結果帶回模型產生最終回覆。這個界線非常重要：模型輸出的函式呼叫是請求，不是可直接信任的授權命令。

對每一個會讀取或改寫外部資料的函式，應在應用端驗證身分、權限、參數範圍、資源歸屬與業務規則。對有副作用的動作，例如發送郵件、建立付款、變更帳號或刪除資料，還要處理冪等鍵、人工確認、失敗補償與完整日誌。

用結構化輸出降低流程的模糊度

Structured Outputs 可讓模型依 JSON Schema 回傳可預期的欄位，適合分類、資料擷取與下一個工具節點的輸入。它能降低解析錯誤，但不保證欄位內容在商業或事實上正確；schema 驗證之後，仍要做資料型別、範圍、來源與權限驗證。

實作時可把輸出分成兩類：一類是只供介面呈現的建議，另一類是會觸發工具的結構化命令。後者應有更嚴格的 schema、allowlist 與審核規則，不能因為 JSON 格式正確就自動放行。

模型選型與版本管理

Google 的模型頁面建議生產環境優先採用明確的 stable model ID，而不是長期依賴會自動變動的 latest 別名。不同 Flash／Flash-Lite 模型的速度、成本、推理能力和工具支援度不同；選型前應以自己的任務集評測，而不是以「模型很快」推論整個 agent 一定更好。

建議把模型 ID、API 版本、提示版本、工具 schema、系統指示、測試集與評測結果一起版控。模型或 API 改版時，先在測試流量中比較工具成功率、結構化輸出有效率、回覆品質、延遲、token 成本與安全拒絕率，再決定是否全面切換。