# 🔄 Google ADK 迁移指南

## 📋 迁移概述

本指南将帮助您将项目从当前的 OpenRouter/OpenAI Swarm 架构迁移到 Google Agent Development Kit (ADK)。

## 🎯 迁移目标

- **从**: OpenRouter + OpenAI Swarm + 多厂商AI模型
- **到**: Google ADK + Gemini 模型 + Express Mode API
- **保持**: 稷下学宫八仙论道系统的核心逻辑和哲学框架

## 📦 第一步：安装 Google ADK

### 1.1 更新 Python 环境要求

<mcreference link="https://google.github.io/adk-docs/get-started/quickstart/" index="1">1</mcreference>

```bash
# 确保 Python 3.9+ 版本
python --version

# 创建新的虚拟环境（推荐）
python -m venv .venv

# 激活虚拟环境
# macOS/Linux:
source .venv/bin/activate
# Windows CMD:
# .venv\Scripts\activate.bat
# Windows PowerShell:
# .venv\Scripts\Activate.ps1
```

### 1.2 安装 Google ADK

<mcreference link="https://pypi.org/project/google-adk/" index="2">2</mcreference>

```bash
# 安装稳定版本
pip install google-adk

# 或安装最新开发版本
pip install git+https://github.com/google/adk-python.git@main
```

## 🔑 第二步：配置 API 密钥

### 2.1 获取 Gemini API 密钥

<mcreference link="https://google.github.io/adk-docs/get-started/quickstart/" index="1">1</mcreference>

您有三种选择：

**选项A: Google AI Studio (推荐开发环境)**
- 前往 [Google AI Studio](https://aistudio.google.com/) 获取免费 API 密钥
- 环境变量：`GOOGLE_API_KEY`

**选项B: Google Cloud Vertex AI Express Mode**
- 在 Google Cloud 项目中启用 Express Mode
- 环境变量：`GOOGLE_API_KEY` + `GOOGLE_GENAI_USE_VERTEXAI=TRUE`

**选项C: Google Cloud Vertex AI (完整版)**
- 需要 Google Cloud 认证，使用 IAM 而非 API 密钥

### 2.2 更新 Doppler 配置

在您的 Doppler 项目中添加新的环境变量：

```bash
# 添加 Gemini API 密钥
doppler secrets set GOOGLE_API_KEY=YOUR_GEMINI_API_KEY

# 如果使用 Express Mode
doppler secrets set GOOGLE_GENAI_USE_VERTEXAI=TRUE

# 保留现有的 RapidAPI 配置（数据源仍然需要）
# RAPIDAPI_KEY=your_rapidapi_key
```

## 🏗️ 第三步：重构核心组件

### 3.1 更新配置管理

需要更新 `config/settings.py`：

```python
def get_google_api_key() -> str:
    """获取 Google API 密钥"""
    return get_secret('GOOGLE_API_KEY')

def get_google_genai_config() -> Dict[str, str]:
    """获取 Google GenAI 配置"""
    return {
        'api_key': get_google_api_key(),
        'use_vertex_ai': get_secret('GOOGLE_GENAI_USE_VERTEXAI', 'FALSE'),
        'project_id': get_secret('GOOGLE_CLOUD_PROJECT_ID', '')
    }
```

### 3.2 重构稷下学宫智能体系统

将基于 OpenAI Swarm 的八仙论道系统迁移到 ADK：

**原架构**: `src/jixia/debates/swarm_debate.py` (OpenAI Swarm)
**新架构**: `src/jixia/debates/adk_debate.py` (Google ADK)

### 3.3 ADK 智能体定义

每个"仙"将成为独立的 ADK Agent：

```python
# 示例：铁拐李智能体
from google_adk import Agent, FunctionTool

tie_guai_li_agent = Agent(
    name="铁拐李",
    model="gemini-2.0-flash-exp",
    description="逆向思维专家，善于从困境中寻找突破",
    system_message="你是铁拐李，八仙中的逆向思维专家...",
    tools=[
        FunctionTool(name="逆向分析", function=reverse_analysis),
        FunctionTool(name="困境突破", function=breakthrough_analysis)
    ]
)
```

## 🔄 第四步：分阶段迁移策略

### 阶段1：基础设施迁移 (第1-2天)
- [ ] 安装 Google ADK
- [ ] 配置 API 密钥
- [ ] 创建简单的测试智能体
- [ ] 验证基本功能

### 阶段2：核心逻辑迁移 (第3-5天)
- [ ] 重构八仙智能体定义
- [ ] 迁移论道逻辑
- [ ] 保持数据源 (RapidAPI) 集成
- [ ] 测试单个智能体功能

### 阶段3：系统集成 (第6-7天)
- [ ] 多智能体协作
- [ ] Streamlit 界面适配
- [ ] 完整功能测试
- [ ] 性能优化

### 阶段4：部署和监控 (第8天)
- [ ] 部署配置
- [ ] 监控设置
- [ ] 文档更新

## 📊 功能对照表

| 当前 (OpenRouter/Swarm) | 迁移后 (Google ADK) | 状态 |
|-------------------------|-------------------|------|
| OpenAI Swarm 多智能体 | ADK Multi-Agent | ✅ 等价替换 |
| OpenRouter 模型池 | Gemini 模型系列 | ✅ 统一模型 |
| 自定义 Tool 系统 | ADK FunctionTool | ✅ 等价替换 |
| 论道逻辑 | ADK Agent协作 | ✅ 保持逻辑 |
| RapidAPI 数据源 | 保持不变 | ✅ 无需改动 |
| Streamlit 界面 | ADK Dev UI + Streamlit | ✅ 双界面 |

## 🎛️ 开发工具对比

### 当前工具
- OpenRouter API 测试
- 自定义调试脚本
- Streamlit 界面

### ADK 工具
<mcreference link="https://google.github.io/adk-docs/get-started/quickstart/" index="1">1</mcreference>

```bash
# ADK 开发界面 (推荐)
adk web

# 命令行运行
adk run multi_tool_agent

# API 服务器模式
adk api_server
```

## 🚨 注意事项

### 保留的组件
- **RapidAPI 数据源**: 继续使用，无需更改
- **MongoDB 数据库**: 继续使用
- **Doppler 配置管理**: 继续使用，仅添加新密钥
- **稷下学宫哲学框架**: 完全保持

### 移除的组件
- OpenAI Swarm 依赖
- OpenRouter API 调用
- 多厂商 API 密钥管理

### 新增优势
- **统一的模型生态**: 专注 Gemini 系列
- **更强的 Google 服务集成**: Search、Cloud 等
- **官方支持的框架**: 长期维护保证
- **更好的开发工具**: ADK Dev UI

## 📝 下一步行动

1. **立即开始**: 运行第一步的环境配置
2. **获取 API 密钥**: 访问 Google AI Studio
3. **阅读 ADK 文档**: [官方文档](https://google.github.io/adk-docs/)
4. **测试简单智能体**: 验证基本功能

准备好开始迁移了吗？我可以帮您逐步执行每个阶段！