Agent Development Kit：從工具呼叫到可部署 Agent
課程概述
Agent Development Kit（ADK）是 Google 開源的 Agent 開發框架。它把模型、工具、Session、事件與執行流程整理成一致的介面，讓開發者可以在本機除錯、跑評估，再部署到 Agent Runtime、Cloud Run 或 GKE。和單次呼叫模型相比，差別不在於「更會聊天」，而是應用可以在明確權限內查資料、呼叫系統，並根據工具結果繼續完成任務。
Instruction 定義 Agent 的工作方式，工具讓它能行動，Session 保留這段對話需要的狀態，Runner 則處理事件串流與執行生命週期。真正的安全邊界仍來自工具介面、身分權限、輸入驗證、逾時與稽核紀錄。
你將學到
- 分清楚單次模型呼叫與具備工具迴圈的 Agent
- 掌握 Agent、Tool、Runner、Session 與長期記憶的責任邊界
- 寫出輸入輸出明確、可授權、可重試的 Tool
- 在本機檢查事件、工具呼叫與狀態變化，不依賴模型的自我說明
- 從固定評估案例走到 Agent Runtime、Cloud Run 或 GKE 的部署選擇
核心概念
什麼是 AI Agent？
AI Agent 通常是由模型根據使用者目標與目前狀態，選擇要回覆、呼叫工具或交給其他 Agent。工具執行結果會成為下一輪輸入，直到任務完成、超過步數／時間上限，或需要真人確認。常見教材會把它簡化成 ReAct 的「推理 → 行動 → 觀察」，但正式系統不必、也不該把模型的私密逐步思考當成可稽核紀錄；應追蹤的是輸入、工具選擇、參數、結果、狀態變更與最終輸出。
工具呼叫不是一次 API：每輪都要驗證、執行、觀察並更新狀態，再決定繼續或回應。逾時、重試、循環上限與 Trace Log 讓這個不確定迴圈維持在可控範圍內。
ADK 執行時的幾個主要角色
| 元件 | 角色 | 說明 |
|---|---|---|
| Agent | 行為定義 | 設定模型、Instruction、可用工具與子 Agent |
| Tool | 受控能力 | 將查詢、API 或業務動作包成有 Schema 的介面 |
| Runner | 執行協調 | 接收事件、呼叫 Agent、執行工具並把輸出寫回事件流 |
| Session Service | 對話狀態 | 依 app、user、session 保存同一段互動的事件與 State |
| Memory Service | 跨段記憶 | 選擇性保存跨 Session 需要的資訊；不應直接等同完整聊天紀錄 |
| Artifact Service | 大型產物 | 存放檔案、報表等不適合塞進 Session State 的內容 |
狀態要放在正確範圍：短暫工具事件、跨輪 Session、長期記憶與大型 Artifact 各有用途。敏感資料先分類，只保存完成任務真正需要的內容。
Tool 的描述只是起點，權限才是底線
Tool 的名稱、描述、參數型別會影響模型能不能選對工具，但文字提醒不是安全控制。每個 Tool 至少要做到：
- 功能單一且明確，一個 Tool 只做一件事
- 輸入輸出有明確 Schema，伺服器端重新驗證，不直接相信模型參數
- 使用最小權限的 Agent 身分；讀取、寫入與高風險操作分開
- 設定逾時、重試上限、冪等鍵與可判讀的錯誤類型
- 高影響動作先顯示預覽與影響範圍，再取得真人核准
- 記錄工具、參數摘要、授權結果與外部系統回應，不把 Secrets 寫進 Log
Agent 與 Prompt Engineering 的關係
Agent 的 System Instruction 會說明任務、工具選用原則、遇到資料不足時如何處理，以及何時應停下來問人。它能降低誤用，卻不能代替 IAM、Allowlist 或交易核准。外部文件和工具回傳也要視為不可信資料，不能因為它們被放進模型上下文，就允許改寫 System Instruction 或自行擴權。
Session、Memory 與 Artifact 不要混在一起
Session 適合保存同一段對話的事件與任務進度；Memory Bank 則用來抽取跨 Session 仍有價值的個人化資訊，而且必須由應用觸發、設定範圍與保存政策，不是所有對話都會自動變成長期記憶。報表、圖片或大型工具輸出應放在 Artifact 儲存層，只在 State 留識別碼與摘要。敏感資料是否能保存、保存多久、誰能刪除，也要在寫入前決定。
部署名稱已更新
Google Cloud 在 2026 年把 Vertex AI Agent Engine 改名為 Gemini Enterprise Agent Platform 的 Agent Runtime，詳見官方版本說明。Runtime 提供受管部署與擴縮，並可整合 Sessions、Memory Bank 與可觀測性；Cloud Run 和 GKE 仍是可選部署目標。新工作流程可使用 Agents CLI統一建立、評估與部署，但不論用哪個 Runtime，上線前的工具權限、評估資料與回滾策略仍由團隊負責。
流程圖暫時無法顯示，請重新整理頁面後再試。
實作重點
- ADK 現行官方支援 Python、TypeScript、Go 與 Java；依團隊語言選 SDK，不必把 Python 當成唯一選擇
- 模型 ID、地區和生命週期會更新；實驗可用 Alias，正式版本應固定已評估的模型與設定
- Tool 函式要有型別與清楚描述，執行端仍需自行做授權和參數驗證
- 舊 Lab 常用
adk web，新版 Agents CLI 則提供 Playground、Eval 與多種部署目標 - 測試時查看事件、工具呼叫、延遲與錯誤，不要把畫面上的自然語言理由當成真實執行證據
Lab 導讀
Lab 連結：Build Intelligent Agents with Agent Development Kit — Google Cloud Skills Boost
這個 Lab 會做出能查天氣和匯率的 Agent。除了看模型有沒有挑對 Tool，也請故意測缺少參數、錯誤幣別、API 逾時、重複送出和要求越權操作。若教材仍使用舊版 Vertex AI 或 Agent Engine 名稱，把它對應到現在的 Agent Platform 與 Agent Runtime 即可。
延伸學習
- Gemini Enterprise 入門（前身 Agentspace） — 了解企業級 Agent 部署平台
- 部署多代理系統 — 進階：多個 Agent 協同工作
- Prompt Engineering 進階技巧 — Agent 的 System Instruction 設計基礎
相關文章
您可能也會對這些文章感興趣
Agent Development Kit：從工具呼叫到可部署 Agent
用 ADK 把模型、工具、Session 與 Runner 組成可測試的 Agent，並補齊權限、錯誤處理、評估與部署前檢查
部署多代理系統：先確認真的需要拆
用 ADK 設計循序、平行與動態委派流程，建立可驗收的交接契約、狀態邊界與故障隔離，再部署到 Agent Runtime
AI Agent 安全：別只叫模型「不要洩密」
從 Prompt Injection、工具越權與資料外洩，到 Model Armor、IAM、VPC Service Controls 和人工核准的分層防禦
