I. 前言：從「有工具」到「會用工具」

Day 1 至 Day 4 完成了工具的標準化，我們有了一個定義完整、規則明確、而且已經部署得出去的 MCP Server。但到目前為止，它都只是躺在那裡等人呼叫 —— 決定何時呼叫哪個工具的，還是我們寫死在驗證腳本裡的程式碼。

從今天開始，情況會不一樣。操作這些工具的將是由 LLM 驅動的 Agent，而這意味著一個本質上的轉變：執行路徑不再由程式碼決定，而是由模型的判斷決定。

在眾多 Agent 開發框架中，這個系列選擇 Google Agent Development Kit（Google ADK）。原因不只是它與 Gemini 的整合度高，更關鍵的是它提供了 adk api_server —— 一個能把 Agent 包成標準 HTTP 服務的能力，而這正是評測階段之後所有評測工作的基礎。

期待在這篇文章中，能夠讓大家對 Google ADK 這個框架有個整體的輪廓 —— 知道它由哪些東西組成、什麼時候該用哪一種跑法，以及有哪一件事現在不記下來、之後會很麻煩。

II. 本系列使用的版本

這個系列全程使用 Google ADK 2.x，撰寫時的最新版本是 2.7.1（2026-08-17）。

.venv/bin/pip install "google-adk>=2.7,<3"     # 需要 Python 3.10+

2.x 帶來兩個對本系列特別有用的東西：Workflow Runtime（用圖描述確定性流程）與 Tool Confirmation（框架層的人機協同）。後者在明天之後談 HITL 路線時會拿來與 MCP 的機制對照。

這裡先提醒大家一件事

Google ADK 2.0 對 event model 與 session schema 做過調整。

這件事現在看起來無關緊要，但它會在評測階段變得很重要 —— 評測工具是靠解析 event stream 來抽取工具呼叫的，而 event model 一旦不同，解析邏輯就要跟著改。

所以請把版本記下來：您用哪一版 Google ADK，決定了評測工具需不需要調整。 沿用本系列的 2.7.1 最省事；若您用的是更新的版本，接評測工具時務必先驗證能不能正確抽出工具呼叫。

.venv/bin/pip show google-adk | head -2      # 隨時確認手上是哪一版

III. 兩個核心類別

Google ADK 的 README 給了一個很清楚的入門提示 —— 整個框架先認得兩個類別就夠了：

ADK 應用由兩個主要的類別構成：Agent 負責定義一個 AI 的 instruction、工具與行為，Workflow 則負責用圖的形式編排多個 agent 與任務。

（我翻譯自官方 README。）

Agent

from google.adk import Agent

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

Agent 實際上就是 LlmAgent——兩個名字指向同一個類別（google.adk.agents.llm_agent），from google.adk import Agent 只是頂層的便捷寫法。文件裡兩種寫法都會出現，看到時不必困惑。

Workflow

Workflow 是 2.0 的新東西，用圖來描述執行流程：

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)],
)

除了 Workflow，Google ADK 也提供了幾個結構化的組合 agent：SequentialAgent、ParallelAgent、LoopAgent。這個階段後面談 multi-agent 時會用到。

Agent 與 Workflow 的分界在於誰做決定。 Agent 裡的流程由模型決定（要不要呼叫工具、呼叫哪個）；Workflow 的流程由您在程式碼裡定死。需要確定性的地方用 Workflow，需要彈性的地方用 Agent。

IV. 三種執行方式

這三個指令的差別，決定了您在不同階段怎麼跟 Agent 互動：

adk api_server 是最容易被忽略但對這個系列最重要的一個。它會在 localhost:8000 開一組 REST endpoint。

Port 提醒：Day 3 的 MCP Server 已經佔用 8090，Google ADK 用 8000，兩者不衝突。但如果您當初讓 MCP Server 留在預設的 8000，這裡就會撞車——這是把它移到 8090 的原因。

實際操作。先起服務 —— 參數是放 agent 的那層目錄，省略的話就用目前目錄：

.venv/bin/adk api_server agents        # agents/leave_copilot/ 在裡面

# 列出可用的 agent，回傳 ["leave_copilot"]
curl -X GET http://localhost:8000/list-apps

# 建立 session
curl -X POST http://localhost:8000/apps/leave_copilot/users/u_123/sessions/s_123 \
  -H "Content-Type: application/json" \
  -d '{"key1": "value1"}'

# 執行 agent，一次回傳所有事件
curl -X POST http://localhost:8000/run \
  -H "Content-Type: application/json" \
  -d '{
    "appName": "leave_copilot",
    "userId": "u_123",
    "sessionId": "s_123",
    "newMessage": {
      "role": "user",
      "parts": [{"text": "把 LV-7f3a91 改成處理中"}]
    }
  }'

兩個細節值得記住：

• 欄位用 camelCase（appName、userId、sessionId、newMessage）。底層的 pydantic 模型開了 populate_by_name，所以 snake_case 其實也收得下，但文件與 OpenAPI schema 給的都是 camelCase —— 挑一種寫到底，不要混用。
• /run 會收集所有事件後一次回傳，/run_sse 則是 SSE 串流。之後的評測工具用的是前者。

Python/TypeScript 版本還會在 http://localhost:8000/docs 提供 Swagger UI，開發時很方便。

V. Google ADK 內建的評估功能

這裡要先講清楚一件事，否則評測階段會讓人困惑：Google ADK 本身就有評估指令。

# 官方 README 的範例，路徑是 adk-python repo 裡的
.venv/bin/adk eval \
    samples_for_testing/hello_world \
    samples_for_testing/hello_world/hello_world_eval_set_001.evalset.json

那評測階段為什麼還要另外一套工具？

因為定位不同。adk eval 是 CLI 導向、跟專案綁在一起的測試工具，適合放進 CI；而探索階段需要的是實驗管理、視覺化的軌跡檢視與可以反覆調整測試案例的介面。兩者不衝突，解決的是開發流程中不同階段的問題 —— 這個對照留到真正要選工具那天再展開。

VI. Agent 的基礎循環

不論用哪種執行方式，底下的循環都是同一個：

Day 1 至 Day 4 那四個難點，全部發生在「要呼叫工具嗎、呼叫哪個、參數填什麼」這個決策點上。而模型做這個決策時，唯一的依據就是 Instruction、對話歷史與工具的 JSON Schema。

Day 2 埋的伏筆在這裡收線：跨呼叫依賴、狀態機約束這些規則，JSON Schema 表達不了，只能寫在 Instruction 或 tool description 的自然語言裡。模型會不會照做，是機率問題。

明天開始把這個機率量化。

VII. 結語

Google ADK 的設計，反映了 Agent 開發正從「Prompt 拼裝」邁向「軟體工程」的轉變。它把 Agent、Workflow、Runner、Session 這些概念明確切分，讓開發者能用熟悉的工程思維處理原本相當模糊的 LLM 應用。

總結來說，今天提到三個重點：

• adk api_server 是後續所有工作的基礎： 它把 Agent 暴露成標準 HTTP 服務，讓評測階段、系列後期的多模型對比都能透過同一組 endpoint 進行。這是選擇 Google ADK 最實際的理由。
• Agent 與 Workflow 的分界在於「誰做決定」： Agent 內的流程由模型判斷，Workflow 的分支由程式碼寫死。需要彈性的地方用前者，需要確定性的地方用後者 —— 這個判準在設計複雜 Agent 系統時會反覆用到。
• 記下您用的 Google ADK 版本，它會影響後續的評測： 2.0 對 Event Model 做過調整，而評測工具是靠解析 Event Stream 抽取工具呼叫的。換版本時，解析邏輯必須重新驗證 —— 這是後面最容易被忽略、卻會讓整批數據失真的一個變數。

明天，我將會提到如何把第一個 Agent 真正跑起來，從專案結構、Instruction 的寫法，一路到 state 插值。而在那之前想先提醒大家一個習慣：從第一天就開始把 Event Stream 存下來 —— 這些看似隨手的測試紀錄，到了訓練資料階段就是訓練樣本的原料。再請大家回來閱讀後續章節囉！

參考來源

• google/adk-python README——Agent / Workflow 用法、adk run / adk web / adk eval
• PyPI・google-adk——版本與發布日期（撰寫時最新為 2.7.1）
• Google ADK・API Server——adk api_server endpoints 與 camelCase 欄位
• src/google/adk/agents/__init__.py——Agent 與 LlmAgent 同源

查證日期：2026-09-03。本篇的類別、CLI 指令、預設 port 與 /run 的欄位名稱，都在 google-adk 2.7.1 / Python 3.13 的環境實際跑過。

I am Simon

大家好，我是 Simon 劉育維，是一位 AI 領域解決方案專家，目前也擔任 Google Cloud AI 領域開發者專家 (GDE)，期待能夠幫助企業導入人工智慧相關技術解決問題。如果這篇文章對您有幫助，歡迎在我的 Linkedin 上留言提供意見，並與我一起討論有關人工智慧的主題，期待能夠對大家有所幫助！

我的個人部落格資訊：https://medium.com/@simon3458