Day 30 - 終極部署：把 Agent 送上戰場，也送走這場連載

18th鐵人賽 google adk

seanlin040

團隊HIT靈機一動萬象成章

2026-09-28 02:08:53

117 瀏覽

分享至

Day 30 | 終極部署：把 Agent 送上戰場，也送走這場連載

主張：部署選項沒有標準答案，只有「你的團隊是開發者還是平台團隊」這個問題的答案。
讀完能做到：在 Agent Runtime、Cloud Run、GKE 之間做出有依據的選擇，並且知道每條路各自容易踩的坑。

從Day 1 開場講的是 Google 為什麼要重寫 ADK 的執行引擎——從階層式的樹狀執行，改成圖形化的 Workflow Runtime。

走到今天，你應該已經知道怎麼用這套引擎定義 agent（Day 3）、給它工具（Day 6–8）、管它的記憶與 context（Day 9–11）、串成 multi-agent 系統（Day 13–20）、加上串流與語音（Day 21–23）、量測它的品質與安全性（Day 26–28）。

這條路走到終點，只剩下一個問題還沒回答：這一切怎麼變成一個使用者真的能打進來的服務？

四條部署的方法

官方文件把部署選項攤成四條路，但真正的決策點不是「哪個功能比較多」，而是「你的團隊想維運到哪個層次」。

Agent Runtime on Agent Platform 是 Google Cloud 上專為 agent 設計的全託管自動擴展服務。Cloud Run 是全託管、容器化、自動擴展的通用運算平台。GKE 是 Google 的 Kubernetes 託管服務，需要更多控制權、或要跑 open models 時選它。第四條路是其他容器友善的基礎設施——把 agent 打包成一般的 container image，丟到任何支援容器的環境跑，包含完全離線、不連 Google Cloud 的情境，本地用 Docker 或 Podman 都行。

Google Cloud 自己有一份《The New Agentic Landscape》企業轉型框架文件，裡面給了一個很有說服力的三方比較框架，把選擇邏輯攤得更白：

Agent Runtime（文件寫作當時還叫 Agent Engine）：部署只要一行 agent_engines.create()，observability 內建在 console 裡，ADK、LangGraph、AG2 這些框架都有官方管理的樣板，Sessions 是第一方支援，品質與評估直接接 Gen AI Evaluation 與 Example Store。目標使用者是開發者，意思是你只想寫 agent 邏輯，不想碰基礎設施。
Cloud Run：一樣是 serverless，但你得自己把 agent 包進 Flask 或 FastAPI 這類 web framework 裡。目標使用者同樣是開發者，只是要多做一點組裝工作，換來的是更高的彈性（比如自訂路由、嵌進既有的 API 服務）。
GKE：介於獨立 VM 與 serverless 之間——你不用管個別機器，但仍然要維運一整個 Kubernetes 叢集，官方給的部署步驟多達九步；好處是有 GKE Inference Gateway 這種 LLM-aware 的路由能力與動態 LoRA adapter serving。目標使用者是平台團隊，也就是你的組織已經有專門的基礎設施團隊，要對接進更大的 Kubernetes 生態。
其他容器友善的基礎設施：把 agent 手動打包成 container image，丟到任何支援容器的環境跑，本地用 Docker 或 Podman 都行。

這張比較表有個使用上的但書值得記下來：它寫「MCP/A2A 支援：Agent Engine 當時是 WIP，Cloud Run 與 GKE 已支援」——這是 PDF 當時的快照，現在的官方文件（deploy/agent-runtime 與 MCP 工具頁都已經有 Agent Runtime 的 MCP 部署說明）很可能已經不是這個狀態了。引用這類比較表，永遠要標日期，這也是這三十天反覆強調的規則：版本與時間標記不是嚴謹癖，是這個框架現階段真實會咬人的地方。

三段 adk deploy 指令接下來會逐一出現，它們都建立在一個前提上：你已經跑過 gcloud auth login 完成登入，也跑過 gcloud auth application-default login 讓本機拿到 Application Default Credentials，並且把指令裡 $GOOGLE_CLOUD_PROJECT 這類變數換成你自己專案的實際值。這件事沒有捷徑——跳過這一步，三段指令會在本機端就先失敗，而不是等到接觸雲端資源才出錯。

Cloud Run 部署

Cloud Run 的部署有兩種做法。用 adk deploy cloud_run 是官方推薦的捷徑，一行指令搞定：

adk deploy cloud_run \
--project=$GOOGLE_CLOUD_PROJECT \
--region=$GOOGLE_CLOUD_LOCATION \
--service_name=$SERVICE_NAME \
--app_name=$APP_NAME \
--with_ui \
$AGENT_PATH

這裡有個部署後很容易讓人一頭霧水的陷阱：--session_service_uri 和 --artifact_service_uri 不設定的話，容器就退回 in-memory 服務——這代表每次 Cloud Run instance 被回收（這在 serverless 環境是常態，不是意外），session 與 artifact 資料就整個消失。任何需要保留對話記錄或檔案的部署，都必須明確指定這兩個 URI，比如 --session_service_uri=agentengine://<agent_engine> 接 Agent Runtime 管理的 session 服務，或是 sqlite://<path> 接自架資料庫；--artifact_service_uri 則像 gs://<bucket_name> 這樣接 Cloud Storage。把這兩個 flag 補進上面的指令，長這樣：

adk deploy cloud_run \
--project=$GOOGLE_CLOUD_PROJECT \
--region=$GOOGLE_CLOUD_LOCATION \
--service_name=$SERVICE_NAME \
--app_name=$APP_NAME \
--session_service_uri=agentengine://<agent_engine> \
--artifact_service_uri=gs://<bucket_name> \
--with_ui \
$AGENT_PATH

--with_ui 才會一併部署 ADK dev UI，預設只有 API server。

另一條路是完全不用 adk CLI，自己寫 Dockerfile 配 gcloud run deploy，官方附了完整的 main.py（用 get_fast_api_app() 組出 FastAPI app）、requirements.txt、Dockerfile 三件套——這條路彈性更高，適合要把 agent 嵌進既有 FastAPI 應用、或想在同一個服務裡跑多個 agent（每個子資料夾各自的 root_agent）的情境。

GKE 部署

GKE 一樣有手動與自動兩條路。自動路徑是 adk deploy gke，但這裡有個版本限制值得標紅——目前僅支援 Python，Go 的 agent 必須走手動路徑，自己寫 Kubernetes manifest。

adk deploy gke \
    --project myproject \
    --cluster_name test \
    --region us-central1 \
    --with_ui \
    ~/agents/multi_tool_agent/

命令會自動建 container image、推到 Artifact Registry、產生 Deployment 與 Service 兩份 manifest 並套用到叢集。--service_type 預設是 ClusterIP（只在叢集內可見），要暴露到公網得明確指定 LoadBalancer。

這裡最容易踩的坑是權限：如果 agent 用 Agent Runtime（即 Agent Platform）當模型後端，跑在叢集裡的 workload 需要有呼叫 Agent Platform API 的權限。

手動部署路徑要自己建一個 Kubernetes service account 並綁定 Agent Platform User role；但 adk deploy gke 產生的 manifest 用的是 default namespace 底下的 default service account，綁權限的對象要跟著換。

漏掉這一步，典型的症狀是 agent 的 pod 能順利啟動、服務也能連上，但每次呼叫模型都回 403 PERMISSION_DENIED——錯誤訊息本身不會直接告訴你是 IAM 綁錯了物件。

Agent Runtime 部署

Agent Runtime 的部署也分成標準路徑（Cloud Console + ADK CLI，一步步來，適合已經熟悉 GCP 專案設定、準備正式上生產的團隊）與 Agents CLI 路徑（一次到位設好含 CI/CD、infrastructure-as-code 的完整環境，適合想快速起步的團隊）。它是付費服務，超過免費額度會產生費用。CLI 指令是：

adk deploy agent_engine \
        --project=$PROJECT_ID \
        --region=$LOCATION_ID \
        --display_name="My First Agent" \
        multi_tool_agent

本機要能跑這段指令，環境得能 import vertexai——純 pip install google-adk 不會帶入這個依賴，得裝 pip install "google-adk[gcp]"（或 [all]）才會一併拉進 google-cloud-aiplatform，不然指令會在推進到雲端部署前先卡在 No module named 'vertexai'。

成功之後你會拿到一個 reasoningEngines 資源名稱，可以在其他 session 裡用 vertexai.agent_engines.get('projects/.../reasoningEngines/...') 取用。

順帶一提，官方文件現在把這個服務叫 Agent Runtime on Agent Platform，但 CLI 指令跟拿到的資源型別（agent_engine、reasoningEngines）都還沒跟著改名，兩種說法目前並存，對照文件時不用懷疑自己找錯地方。

部署之後：三條路殊途同歸的驗證方式

不管走哪條路，部署完的驗證邏輯是共通的模式：

列出已部署的 app（GET /list-apps）
建立或更新一個 session
把訊息 POST 到 /run_sse

Cloud Run 與 GKE 的文件都附了完整的 curl 範例，差別只在 URL 前綴——如果你部署的是 Go 版本的 agent，注意 API 路徑預設多一層 /api 前綴、JSON 欄位也從 Python 的 snake_case 換成 Go 的 camelCase（app_name 對 appName），這是少數幾個「同一個功能、換語言連 API 合約都不一樣」的地方，跨語言團隊協作時很容易在這裡卡住。

GKE 另外附了一份實用的疑難排解清單：

Gemini 模型的 403 錯誤
404
SQLite 唯讀資料庫（通常是本地產生的 session 資料庫被一起打進了 container image，修法是部署前刪掉本地檔案或加進 .dockerignore）
Cloud Build 權限不足
Live API 模型在 Dev UI 裡語音功能失敗（通常是選錯了不支援 Live API 的模型）

收尾：這三十天，你其實學的是一套判斷框架

回頭看這三十天，如果只留一句話，我會留 Day 1 就埋下的那個命題：ADK 2.0 不把編排邏輯當成一段可以無限延伸的 prompt，而是當成一份可以被檢查、被版本控制、被測試的圖。工具限制、context 管理、multi-agent 模式、評估準則、安全防護、部署選項——這些看起來是分散在三十天裡的獨立主題，但貫穿它們的其實是同一個判斷框架：什麼該讓模型自己決定，什麼該由開發者用確定性的程式碼鎖死。

Google ADK 官方網站
 GitHub - Agent Development Kit (ADK) 2.0

GitHub 開源實作：https://github.com/SeanLinH/adk_tutor