Gemini 3.0 Pro ADK Demo

基於 Google ADK Python 的 Gemini 3.0 Pro 示範應用。

🚀 特性

• ✅ 使用最新的 Gemini 3.0 Pro 模型
• ✅ 基於 Google ADK Python 框架
• ✅ 使用 uv 進行快速套件管理
• ✅ Makefile 簡化安裝和運行
• ✅ 豐富的 CLI 互動體驗（使用 Rich）
• ✅ 支援 Vertex AI 和 Gemini API
• ✅ 完整的開發工具鏈（Black, Ruff, MyPy）

📋 需求

• Python 3.10+
• uv (快速 Python 套件管理器)
• Google Cloud 專案（使用 Vertex AI）或 Gemini API 密鑰

🛠️ 快速開始

1. 克隆專案

cd ~/workspace
git clone <your-repo-url> gemini-3-adk-demo
cd gemini-3-adk-demo

2. 初始化專案

make setup

這會：

• 檢查並安裝 uv
• 創建虛擬環境
• 複製 .env.example 到 .env

3. 配置環境變數

編輯 .env 文件並設置你的 API 密鑰：

# 方法 1: 使用 Vertex AI（推薦）
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=global

# 方法 2: 使用 Gemini API
GOOGLE_API_KEY=your-api-key-here

# 模型配置
GEMINI_MODEL=gemini-3-pro-preview  # Gemini 3 Pro Preview 版本

4. 安裝依賴

# 激活虛擬環境
source .venv/bin/activate

# 安裝依賴
make install

5. 運行應用

make run

📚 可用命令

使用 make help 查看所有可用命令：

make help

主要命令

命令	說明
make setup	初始化專案環境
make install	安裝所有依賴
make run	運行主應用
make test	運行測試
make format	格式化代碼
make lint	檢查代碼質量
make clean	清理生成的文件
make env-check	檢查環境配置
make info	顯示專案資訊

🎯 使用範例

Travel Advisor Demo

專案包含一個完整的 AI 旅遊顧問示範，整合了：

• ✈️ Google Flights (fast-flights)
• 🗺️ Google Maps
• 🤖 Gemini 3.0 Pro + ADK

# 進入虛擬環境
source .venv/bin/activate

# 運行旅遊顧問 demo
python examples/travel_advisor.py

Demo 會展示：

1. 航班搜尋功能（TPE → NRT）
2. 景點推薦功能（東京熱門景點）
3. 完整 3 天 2 夜旅遊行程規劃

基本使用

# 運行示範程式
make run

# 檢查環境配置
make env-check

# 查看專案資訊
make info

開發模式

# 格式化代碼
make format

# 檢查代碼質量
make lint

# 運行測試
make test

📁 專案結構

gemini-3-adk-demo/
├── src/
│   └── gemini_adk_demo/
│       ├── __init__.py          # 套件初始化
│       ├── config.py             # 配置管理
│       ├── agent.py              # Gemini Agent 封裝
│       └── main.py               # 主程式入口
├── tests/                        # 測試目錄
├── .env.example                  # 環境變數範例
├── .gitignore                    # Git 忽略文件
├── Makefile                      # 自動化任務
├── pyproject.toml                # 專案配置
└── README.md                     # 專案說明

🔧 開發指南

安裝開發依賴

make install

這會安裝：

• pytest - 測試框架
• black - 代碼格式化
• ruff - 代碼檢查
• mypy - 類型檢查

代碼格式化

make format

代碼質量檢查

make lint

運行測試

make test

🌟 核心功能

1. Gemini Agent

agent.py 提供了 Gemini 3.0 Pro 的封裝：

from gemini_adk_demo.agent import create_agent

# 創建 Agent
agent = create_agent(
    model="gemini-3-pro-preview",
    name="my_assistant"
)

# 發送查詢
response = agent.query("解釋量子計算")
print(response)

2. 配置管理

config.py 管理所有環境配置：

from gemini_adk_demo.config import config

# 訪問配置
print(config.gemini_model)
print(config.google_cloud_project)

# 驗證配置
config.validate()

3. 互動式 CLI

main.py 提供豐富的 CLI 體驗：

• 彩色輸出（使用 Rich）
• 互動式提示
• 示範問題
• 錯誤處理

🐛 疑難排解

ModuleNotFoundError: No module named 'fast_flights'

如果遇到此錯誤，請確保：

1. 虛擬環境已啟動：

source .venv/bin/activate

2. 依賴已完整安裝：

make install
# 或
uv pip install -e .

3. 手動安裝 fast-flights（如果需要）：

uv pip install fast-flights

航班搜尋失敗

fast-flights 可能會遇到 Google Flights 的反爬蟲機制限制。這是正常的 demo 限制。

解決方案：

• 使用付費 API（如 Amadeus Flight API）
• 查看 BLOG.md 中的替代方案說明

Python 版本問題

確保使用 Python 3.10+：

python --version

🚧 待辦事項

• 添加更多示範範例
• 實作串流回應
• 添加多模態輸入支援
• 增加更多工具整合
• 實作多 Agent 系統
• 添加完整的測試覆蓋
• 部署到 Cloud Run

📖 參考資源

• Google ADK Python 文檔
• Google ADK GitHub
• Gemini 3 Pro Model Card
• Gemini API 文檔
• Vertex AI 文檔

🤝 貢獻

歡迎提交 Issue 和 Pull Request！

📝 授權

MIT License

👤 作者

Agent-JimmyLiao

---

快速開始指令回顧：

make setup      # 初始化專案
make install    # 安裝依賴
make run        # 運行應用

享受使用 Gemini 3.0 Pro！ 🚀