所有原始碼放在 Github
https://github.com/alan-nanpie/coffee-barista-agent/tree/main

使用 Google ADK 和 Cloud Run，在 Streamlit 中部署 RAG AI 代理程式
https://codelabs.developers.google.com/codelabs/cloud-run/build-streamlit-rag-agent-google-adk-cloud-run?hl=zh-tw#0

這份 Codelab（實驗教學）的主題為 Deploy a RAG AI Agent in Streamlit using Google ADK and Cloud Run，旨在引導你為一家咖啡廳開發並部署一個互動式的「AI 咖啡師（AI Barista）」代理程式。

以下是該實驗的詳細解析：

核心技術與概念

• Google ADK (Agent Development Kit): Google 的開源代理開發套件。
• Gemini 3.5 Flash: 實驗中使用的核心 AI 模型。
• RAG (檢索增強生成): 讓 AI 代理程式能夠根據特定的資料集（如咖啡廳菜單）來提供建議，確保回答具有事實基礎。
• Streamlit: 用於打造具有對話歷史管理功能的網頁聊天介面。
• Google Cloud Run: 負責託管與部署應用程式的雲端服務。

實作內容與目標 (What you'll do)

透過這個實驗，你將會依序完成以下任務：

1. 建立資料來源： 建立一個名為 menu.json 的模擬菜單資料集，裡面包含咖啡品項、標籤以及過敏原等資訊。
2. 建構 AI 代理程式： 使用 ADK 的 LlmAgent，並連結 Python 工具來載入剛建立的菜單資料。
3. 打造使用者介面： 將開發好的 AI 代理程式包裝進 Streamlit 聊天應用程式中。
4. 雲端部署： 透過原始碼部署（Source-based deployment）將 Streamlit 應用程式部署至 Cloud Run。
5. 測試與驗證： 測試 AI 的 RAG 行為，確認它能根據菜單準確回答，並測試其對過敏原的感知能力。
6. 進階挑戰（選做）： 學習如何利用具備向量搜尋（Vector Search）功能的 Firestore 來作為 AI 代理程式的資料基礎。

事前準備與門檻 (What you'll need)

• 必備工具： 網頁瀏覽器（如 Chrome）以及一個已啟用計費功能的 Google Cloud 專案。
• 技術需求： 適合所有層級的開發者（包含初學者），只需具備基礎的 Python 知識即可。
• 預估花費： 完成此實驗的雲端資源成本預計低於 1.00 美元。

雖然目前頁面僅提供 Codelab 的簡介與大綱，但根據 Google Cloud Run 原始碼部署（Source-based deployment）與 AI 代理程式的標準開發架構，我為你整理了完整的 CLI 建置流程。

你可以在終端機（Terminal）或 Google Cloud Shell 中依序執行以下步驟來完成這個「AI 咖啡師」的開發與部署：

1. 專案設定與環境準備

首先，我們需要登入 Google Cloud 並設定要使用的專案，同時啟用必要的 API 服務。

# 1. 登入 Google Cloud 帳號
gcloud auth login

# 2. 設定你的 Google Cloud 專案 ID（請將 [YOUR_PROJECT_ID] 替換為實際的 ID）
gcloud config set project [YOUR_PROJECT_ID]

# 3. 啟用 Cloud Run 與 AI Platform (Vertex AI/Gemini) 相關 API
gcloud services enable run.googleapis.com aiplatform.googleapis.com

2. 建立開發資料夾與虛擬環境

在本地端建立一個專屬的工作目錄，並設定 Python 虛擬環境以隔離套件。

# 1. 建立並進入專案資料夾
mkdir ai-barista-agent
cd ai-barista-agent

# 2. 建立 Python 虛擬環境
python3 -m venv venv

# 3. 啟動虛擬環境 (Windows 系統請使用 venv\Scripts\activate)
source venv/bin/activate

3. 建立 RAG 資料來源 (Mock Menu)

透過 CLI 快速建立一個名為 menu.json 的檔案，這會作為 AI 代理程式進行 RAG（檢索增強生成）的事實基礎。

# 使用 cat 指令建立 menu.json 並寫入模擬菜單資料
cat <<EOF > menu.json
[
  {
    "item": "經典拿鐵",
    "description": "濃縮咖啡與熱牛奶的完美結合。",
    "tags": ["熱飲", "咖啡", "暢銷"],
    "allergens": ["牛奶"]
  },
  {
    "item": "燕麥奶焦糖瑪奇朵",
    "description": "以燕麥奶調製，加入香甜焦糖醬。",
    "tags": ["熱飲", "咖啡", "素食"],
    "allergens": ["麩質"]
  }
]
EOF

4. 設定套件依賴清單

建立 requirements.txt，告訴 Cloud Run 部署時需要安裝哪些 Python 套件。

cat <<EOF > requirements.txt
streamlit==1.32.0
google-adk  # Google Agent Development Kit
google-cloud-aiplatform
EOF

5. 撰寫 Streamlit 與 ADK 應用程式碼

建立主程式 app.py。這裡展示的是將 ADK LlmAgent 與 Streamlit 結合的概念性架構：

cat <<EOF > app.py
import streamlit as st
import json
# 假設的 ADK 匯入方式，具體依 Codelab 提供的 API 為準
# from google_adk import LlmAgent 

st.title("☕ AI 咖啡師 (AI Barista)")

# 讀取 RAG 資料來源
@st.cache_data
def load_menu():
    with open('menu.json', 'r', encoding='utf-8') as f:
        return json.load(f)

menu_data = load_menu()

# 初始化對話歷史
if "messages" not in st.session_state:
    st.session_state.messages = []

# 顯示對話歷史
for message in st.session_state.messages:
    with st.chat_message(message["role"]):
        st.markdown(message["content"])

# 接收使用者輸入
if prompt := st.chat_input("你想喝點什麼？"):
    # 顯示使用者訊息
    st.chat_message("user").markdown(prompt)
    st.session_state.messages.append({"role": "user", "content": prompt})
    
    # 這裡會呼叫 ADK Agent 處理邏輯 (結合 menu_data)
    # response = agent.generate_response(prompt, context=menu_data)
    
    # 模擬 AI 回應
    response = f"根據菜單，我推薦你試試我們的特色飲品！你剛才提到：{prompt}"
    
    # 顯示 AI 回應
    with st.chat_message("assistant"):
        st.markdown(response)
    st.session_state.messages.append({"role": "assistant", "content": response})
EOF

6. 透過原始碼部署至 Cloud Run

這是這個 Codelab 的核心亮點。你不必自己寫 Dockerfile，Cloud Run 會在背景自動將原始碼打包並部署。這裡將部署區域設定為台灣所在的 asia-east1。

# 執行原始碼部署
gcloud run deploy ai-barista-app \
  --source . \
  --region asia-east1 \
  --allow-unauthenticated \
  --port 8501 

• --source .：告訴 Cloud Run 從當前目錄取得原始碼（它會自動偵測 requirements.txt 並建置容器）。
• --allow-unauthenticated：允許所有人透過網址公開存取你的 Streamlit 應用程式。
• --port 8501：Streamlit 的預設對外通訊埠。

部署完成後，終端機會回傳一段 Service URL（例如 [https://ai-barista-app-xxx-de.a.run.app](https://ai-barista-app-xxx-de.a.run.app)），點擊該網址就能開啟並測試你的 Streamlit RAG 介面了。

7. 清理資源 (選用)

實驗結束後，如果你不想讓這個服務繼續計費，可以使用以下指令將其刪除：

gcloud run services delete ai-barista-app --region asia-east1