大家好！歡迎回到「Build on Google AI」的工程挑戰。

在協助團隊導入架構時發現一個痛點：工程師在本地端把代理人 (Agent) 寫得很完美，但當專案經理 (PM) 或是行銷團隊想要測試功能時，總不能叫他們自己去拉 GitHub 程式碼、裝 Python 虛擬環境吧？

為了解決這個協作瓶頸，並落實我們「研發與工程創新」的主軸，我們必須將代理人系統封裝起來。今天，我們將施展「容器化魔法」，替 ADK 內建的 Web Interface 撰寫一份輕量級的 Dockerfile，為接下來部署到 Cloud Run 打造完美的雲端戰情室前哨站！

第一步：理解 ADK Web Interface 的運行機制
在把應用程式裝進 Docker 之前，我們先來複習一下 ADK Python 版本的網頁介面啟動方式。根據官方規範，我們需要使用 adk web --port 8000 指令來啟動這個帶有聊天介面的網頁伺服器。但這裡有一個非常重要的細節：這個指令必須在包含你代理人專案（例如 my_agent/）的「父目錄」下執行。也就是說，如果你的程式碼在 agents/my_agent/ 裡面，你必須在 agents/ 目錄下執行指令。

⚠️ 架構與安全提醒：
官方文件有特別發出警告：ADK Web 介面主要是為了開發與除錯 (development and debugging) 所設計，並不建議直接用於正式的生產環境部署 (production deployments)。 不過，作為我們內部團隊早期測試用的「戰情室 Prototype」，這個內建 UI 是極佳的過渡方案。未來在進階篇章中，我們也會探討如何打造更嚴謹的客製化 API Server。

第二步：撰寫輕量級 Dockerfile
為了確保環境一致性，我們將基於 Python 3.10 以上的版本（ADK Python 的最低要求）來建立 Docker Image。 請在專案的「父目錄」（也就是包含 my_agent/ 資料夾的同一層）建立一個名為 Dockerfile 的檔案，並填入以下內容：

# 使用輕量級的 Python 3.10 slim 版本作為基底
FROM python:3.10-slim

# 設定工作目錄
WORKDIR /app

# 將本地端的專案資料夾複製到容器內的 /app/my_agent
COPY my_agent/ ./my_agent/

# 安裝 ADK 核心套件
RUN pip install --no-cache-dir google-adk

# 暴露 8000 port 以供外部連線
EXPOSE 8000

# 設定容器啟動時執行的預設指令，並在父目錄 (/app) 下執行
CMD ["adk", "web", "--port", "8000"]

第三步：設立 .dockerignore 守護資安
如同昨天設定 GitHub 版控一樣，我們絕對不能把機密金鑰打包進 Docker Image 裡。當未來我們將容器部署到 Cloud Run 等 Google Cloud 代管環境時，系統會自動提供所需的認證憑證，因此我們不需要（也不應該）在容器內放入任何金鑰檔案。 請在 Dockerfile 旁邊建立一個 .dockerignore 檔案：

# 忽略虛擬環境
.venv/
venv/
__pycache__/

# 絕對不能打包的機密設定
.env
*.json

第四步：本地端建置與測試
魔法陣畫好了，讓我們來啟動它！打開終端機，確認你在 Dockerfile 所在的目錄：

1 建置 Docker Image：

docker build -t my-adk-web-room .

2 運行 Docker Container：
在這裡，我們需要將本地端的金鑰透過環境變數 -e 注入到容器中，並將容器的 8000 port 映射到本機：

docker run -p 8000:8000 -e GOOGLE_API_KEY="你的金鑰" my-adk-web-room

接著打開瀏覽器前往 http://localhost:8000，如果你看到熟悉的對話介面，恭喜你！你的代理人已經成功在完全隔離的容器環境中運作了。

小結
今天我們透過簡潔的 Dockerfile，成功將 ADK 專案容器化。這不僅消除了「在我的電腦上明明可以跑」的窘境，更讓 PM 或非技術人員未來只要點擊一個網址，就能與你開發的代理人進行互動測試。