AI-Chain
應用場景 Google ADK 多代理系統 工作流

不只會呼叫模型：Google ADK 2.0 如何把 Agent 工作流變成可部署的 Python 軟體系統

Google ADK 2.0 將 Agent 應用拆成負責推理與工具使用的 Agent，以及負責執行順序與狀態的 Workflow。本文從原始碼與官方文件拆解工作流執行模型、Task API、多代理、MCP 工具、評估與部署，並整理導入 production 前的實務檢查表。

分享:
不只會呼叫模型：Google ADK 2.0 如何把 Agent 工作流變成可部署的 Python 軟體系統

不只會呼叫模型：Google ADK 2.0 如何把 Agent 工作流變成可部署的 Python 軟體系統

摘要

大多數 Agent 範例停留在「收到問題、呼叫模型、回傳答案」：一旦加入路由、重試、平行執行、人工確認、工具權限、評估與部署，Prompt 就會逐漸變成難以測試的控制流程。Google 的 Agent Development Kit（ADK）2.0 將 Agent 應用拆成兩個可組合的層次：負責推理與工具使用的 Agent，以及負責執行順序與狀態的 Workflow。本文從 google/adk-python 的原始碼與官方文件出發，實際拆解它的工作流執行模型、Task API、多代理組合、工具整合、評估與部署路徑，最後整理它適合的場景與導入時必須正視的限制。

文章大綱

  • 先理解 ADK 2.0 的 Agent、Workflow 與 Runtime 三層抽象。
  • 再拆解 graph-based workflow、Task API、多代理委派與 MCP 工具治理。
  • 接著串起本機開發、評估、版本管理與 Cloud Run 等部署路徑。
  • 最後用適用場景與導入檢查表，判斷什麼時候應該採用 ADK，什麼時候維持普通 Python 與模型 SDK。

為什麼值得現在研究 ADK 2.0？

google/adk-python 是 Google 維護的開源、code-first Python Agent toolkit，定位不只是模型 SDK，而是用軟體工程方法建立、評估與部署 Agent 的框架。[1][2] GitHub 頁面在本次查證時顯示約 2.13 萬顆 stars，主分支近期仍持續提交；最新提交涉及巢狀工作流中的多輪 Human-in-the-loop 暫停與恢復。[7] 這兩個訊號很重要：它已經有足夠的社群能見度，同時仍在快速演進，值得工程團隊把它當成架構候選，而不是只當成教學範例。

更值得注意的是，2.0 帶來了 Agent API、事件模型與 Session schema 的 breaking changes；2.0 產生的 Session 可由 ADK 1.28 以上讀取，但不相容於更早的 1.x 版本。[2] 這表示升級不是單純換一個套件版本，而是一次執行模型與資料契約的重新檢查。

ADK 2.0 的核心抽象：Agent 負責決策，Workflow 負責控制流

ADK 2.0 把「Agent 是什麼」和「Agent 何時執行」分開。Agent 可以描述模型、指令、工具與行為；Workflow 則以圖狀執行引擎編排節點，處理 routing、fan-out/fan-in、loop、retry、狀態管理、動態節點、人工介入與巢狀工作流。[2]

這個切分解決了常見的架構問題：如果所有流程都塞進一個超長 System Prompt，模型既要做決策，又要猜測流程狀態與錯誤處理規則。改用顯式 Workflow 後，確定性控制流可以由程式碼測試，只有需要語意判斷的部分交給模型。

可以把一個 ADK 應用想成三層：

  1. 決策層：Agent 根據 instruction、上下文與工具回應產生下一步。
  2. 控制層：Workflow 決定節點順序、分支、迴圈、重試與人工確認。
  3. 執行層：Session、事件、工具與 Runtime 保存中間狀態，讓一次 Agent run 能被觀察、暫停、恢復與評估。

這不是把 Agent 包一層 DAG 就結束。真正的價值在於，執行語意成為框架的一部分，後續才能把追蹤、評估與部署接在同一個模型上。

從最小 Agent 開始：程式碼就是可版本控制的規格

ADK 的最小 Agent 定義很接近一般 Python 物件：

from google.adk import Agent

root_agent = Agent(
    name="greeting_agent",
    model="gemini-2.5-flash",
    instruction="You are a helpful assistant. Greet the user warmly.",
)

這段程式碼沒有隱藏的流程魔法：模型、名稱與指令都是顯式設定。官方 README 將 ADK 定位為 model-agnostic 與 deployment-agnostic，雖然它針對 Gemini 做了最佳化，也能整合其他模型與框架。[2] 對團隊而言，這代表 Agent 定義可以像一般應用程式一樣進入 code review、單元測試與版本管理，而不是散落在某個平台的視覺化設定中。

在實際專案裡，應把 instruction 視為業務規格，而不是安全邊界。工具權限、資料存取範圍、輸入驗證與人工確認仍必須由程式碼與基礎設施強制執行；模型產生的文字不能單獨成為授權依據。

Workflow：把多代理協作變成可測試的執行圖

ADK README 提供的基本 Workflow 範例，是先產生水果名稱，再把結果交給另一個 Agent 產生健康益處：[2]

from google.adk import Agent, Workflow

generate_fruit_agent = Agent(
    name="generate_fruit_agent",
    instruction="Return the name of a random fruit. Return only the name.",
)

generate_benefit_agent = Agent(
    name="generate_benefit_agent",
    instruction="Tell me a health benefit about the specified fruit.",
)

root_agent = Workflow(
    name="root_agent",
    edges=[("START", generate_fruit_agent, generate_benefit_agent)],
)

範例很小，但它揭示了實作型 Agent 框架的關鍵：第二個 Agent 不必自行尋找第一個 Agent，也不必靠 Prompt 猜測「前一個步驟是否完成」。流程圖清楚表達了依賴關係。

官方文件也說明，ADK 的 workflow agents 用來控制一個或多個子 Agent 的執行；在 Python 與 Go 的 ADK 2.0 中，較早的 template workflows 正逐步由更有彈性的 graph-based workflow 結構取代。[4] 這個方向讓流程可以從線性鏈逐步擴張成：

  • 路由：先由分類 Agent 判斷請求類型，再送往不同專家。
  • 平行與匯合：同時讓多個 Agent 產生獨立分析，最後交給彙整 Agent。
  • 迴圈：讓審查 Agent 反覆檢查草稿，直到通過品質門檻或達到上限。
  • 重試：只對暫時性失敗的節點重跑，不讓整個流程從頭開始。
  • Human-in-the-loop：危險工具或低信心結果先暫停，等待人員確認。

工程上最容易被忽略的是「停止條件」。任何 loop 都必須同時設計最大迭代次數、逾時、成本上限與失敗出口；否則圖狀流程只是把無限迴圈藏到另一個抽象裡。

Task API 與多代理：從對話協作走向工作協定

除了把 Agent 放進 Workflow，ADK 2.0 也提供 Task API，支援 Agent-to-Agent delegation、multi-turn task、single-turn controlled output、混合 delegation，以及把 task agent 當作 workflow node。[2] 這種設計比「讓一個 Agent 在 Prompt 裡呼叫另一個 Agent」更接近真正的服務邊界：任務有輸入、輸出、生命週期與失敗語意。

一個可維護的多代理系統，至少要先定義四件事：

  1. 任務契約：輸入與輸出採用結構化 schema，不讓下游依賴自由文字。
  2. 責任邊界：研究、規劃、執行、審查各自擁有明確工具集合。
  3. 狀態來源：區分 Session 狀態、任務結果與外部資料庫，避免不同 Agent 同時寫入同一份可變文字。
  4. 失敗策略：定義重試、補償、人工接管與取消，而不只是捕捉例外後再呼叫一次模型。

ADK 的 Task API 可以承載這些語意，但不會自動替團隊做完治理。多代理數量越多，通訊成本、狀態同步與除錯複雜度也會一起增加。若一個流程其實是三個確定性函式，直接寫 Python 函式通常比拆成三個 Agent 更可靠、更便宜。

工具整合：MCP 是連接器，不是權限模型

ADK 的工具生態包含預建工具、自訂函式、OpenAPI spec 與 MCP tools，也能整合既有工具。[2] 這讓 Agent 可以從純文字生成器進化成能查資料、呼叫 API、操作外部系統的應用程式。

但工具接上去之後，風險才真正開始。建議每個工具至少具備以下控制：

  • 明確輸入 schema 與嚴格型別驗證。
  • 服務端重新檢查租戶、使用者與資源範圍。
  • 將讀取與寫入工具分開，寫入操作預設需要確認。
  • 對高風險動作採用一次性授權、冪等鍵與可回滾設計。
  • 記錄呼叫者、參數摘要、結果狀態與延遲，但不要把密鑰或完整個人資料寫入 log。

MCP 解決的是工具描述與連線互通，不代表工具天然安全。ADK 2.0 README 提到的 tool confirmation flow 可在工具執行前取得明確確認與自訂輸入。[2] 這應該被視為最小的人機協作控制，而不是可以取代後端授權的萬用開關。

從 adk run 到正式環境：開發、評估、部署是一條鏈

ADK 把本機開發入口做得很直接：互動式 CLI 使用 adk run，Web UI 使用 adk web；官方也提供 adk eval 搭配評估資料集執行 Agent 評估。[2] 這種命令列介面對 CI 很重要，因為它能把一個原本只能在聊天視窗手動點選的流程變成可重播的測試案例。

評估不應只看最後答案是否「像人」。一個實用的評估集合可以同時記錄：

  • 任務是否完成，以及輸出 schema 是否有效。
  • 工具選擇是否正確，是否出現不必要或危險呼叫。
  • 每一步的延遲、token、重試次數與成本。
  • 在不同輸入、權限與外部服務失敗時，流程是否安全降級。
  • 需要人工確認的情境是否真的停下，而不是繞過控制。

官方評估文件將 Evaluation 列為 ADK 的獨立組成，並與 Criteria、User Simulation、Custom Metrics 等概念並列。[5] 這個架構提醒我們：Agent 的品質不是單一分數，而是一組可針對產品風險定義的指標。

部署方面，README 列出 Cloud Run 與 Vertex AI Agent Engine 等路徑；官方部署文件也涵蓋容器、Cloud Run、GKE 與已部署 Agent 的測試。[2][6] 因此可以用一個漸進式路線：

  1. 在本機用 CLI 與 Web UI 建立可重現的 Agent。
  2. 用固定 eval set 驗證輸出、工具與安全條件。
  3. 將 Runtime 包成容器，在與本機相同的設定契約下部署。
  4. 針對流量、Session 儲存、秘密管理、觀測性與成本設定正式環境控制。

「可以部署」不等於「適合 production」。正式上線前仍需處理模型供應商的可用性、資料落地位置、租戶隔離、取消執行、逾時與版本回滾。

安裝與版本策略：2.0 的 breaking change 不能被忽略

ADK 的 Python 套件要求 Python 3.10 以上；專案 metadata 也把套件定位為 Python library，並提供包含多種整合功能的 optional extras。[2][3] README 建議穩定版從 PyPI 安裝，並可使用對應 Python 版本的 constraints file 保護傳遞依賴。[2]

對團隊而言，建議把以下內容鎖進專案：

Python 版本
google-adk 版本
constraints file
模型與模型版本
工具 schema 版本
Session／事件資料遷移策略

不要在 production 直接追 main。README 明確區分穩定版與直接從主分支安裝的開發版，後者可能包含尚未正式發布的實驗性變更。[2] 更不要只升級依賴後就執行部署；2.0 的 API、事件模型與 Session schema 變動，應配合 replay 測試與資料相容性檢查。

ADK 適合什麼，不適合什麼？

適合：

  • 需要多步驟控制流、工具使用與人工確認的 AI 應用程式。
  • 想以 Python code review、測試與 CI 管理 Agent 行為的團隊。
  • 需要把多個專業 Agent 組成可觀察、可評估工作流的產品。
  • 已使用 Google Cloud，且希望保留 Cloud Run 或 Agent Engine 部署選項的團隊。

不一定適合：

  • 只有一次模型呼叫、沒有工具與流程狀態的簡單功能；直接使用模型 SDK 會更輕量。
  • 需要完全供應商中立、且不想採用 Google 生態整合的極簡服務；雖然 ADK 宣稱 model-agnostic，實際整合深度仍需逐項驗證。[2]
  • 需要高度確定性的資料處理流程；若決策可以用規則或一般程式碼完成，不要為了「Agent 化」而增加模型節點。

導入前的實務檢查表

  1. 先畫出流程圖，標註哪些節點必須確定性執行，哪些節點才需要模型判斷。
  2. 為每一個工具建立權限、輸入驗證、逾時、冪等與審計設計。
  3. 為 Session 與事件模型建立版本化策略，尤其是從 ADK 1.x 升級到 2.0 時。
  4. 用真實失敗案例建立 eval set，不要只測 happy path。
  5. 為每一個 loop、retry 與 delegation 設定成本、時間與數量上限。
  6. 先在本機與容器中驗證，再決定使用 Cloud Run、GKE 或 Agent Engine。
  7. 將模型、套件、constraints 與工具 schema 一起鎖版，讓一次執行可以重播。

結語：把 Agent 當成軟體系統，而不是 Prompt 魔法

ADK 2.0 最有價值的地方，不是它又提供了一個呼叫 LLM 的 API，而是它把 Agent 系統裡最容易失控的部分——工作流、任務委派、工具、評估與部署——拉回軟體工程的語境。Agent 負責在需要語意判斷的地方做決策，Workflow 負責把順序、狀態、重試與人工介入明確化，評估與部署則讓這個系統能被重播與營運。[2][4]

如果你的產品已經從單輪聊天走向「需要協作、工具與可恢復執行」的階段，ADK 2.0 值得做一個小型 vertical slice：選一個有明確輸入輸出的工作流，加入一個工具、一次人工確認與一組失敗測試，再觀察它是否真的降低了控制流的複雜度。若答案是肯定的，才逐步擴大多代理與部署範圍；不要一開始就把所有業務邏輯都交給模型。

Sources

[1] https://github.com/google/adk-python

[2] https://raw.githubusercontent.com/google/adk-python/main/README.md

[3] https://raw.githubusercontent.com/google/adk-python/main/pyproject.toml

[4] https://google.github.io/adk-docs/agents/workflow-agents

[5] https://google.github.io/adk-docs/evaluate

[6] https://google.github.io/adk-docs/deploy

[7] https://github.com/google/adk-python/commits/main.atom