init
This commit is contained in:
Nelson
356
ADKLearning/google-adk-tutorial/01-introduction-and-setup.md
Normal file
356
ADKLearning/google-adk-tutorial/01-introduction-and-setup.md
Normal file
@@ -0,0 +1,356 @@
|
||||
# 第01章：ADK 简介与环境搭建
|
||||
|
||||
## 📌 本章目标
|
||||
|
||||
- 理解 Google ADK 是什么、能做什么
|
||||
- 了解 ADK 的核心架构和设计理念
|
||||
- 完成开发环境的安装和配置
|
||||
- 验证安装是否成功
|
||||
|
||||
---
|
||||
|
||||
## 1.1 什么是 Google ADK？
|
||||
|
||||
**Agent Development Kit（ADK）** 是 Google 开源的一个灵活、模块化的 AI 智能体（Agent）开发框架。它让开发者能够像开发软件一样来构建、评估和部署 AI 智能体。
|
||||
|
||||
### 核心定位
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Google ADK │
|
||||
│ │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
|
||||
│ │ 模型无关 │ │ 部署无关 │ │ 框架兼容 │ │
|
||||
│ │Model │ │Deploy │ │ Framework │ │
|
||||
│ │Agnostic │ │Agnostic │ │ Compatible │ │
|
||||
│ └──────────┘ └──────────┘ └──────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
|
||||
│ │ 代码优先 │ │ 模块化 │ │ 多智能体支持 │ │
|
||||
│ │Code First│ │Modular │ │ Multi-Agent │ │
|
||||
│ └──────────┘ └──────────┘ └──────────────────┘ │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### ADK vs 其他框架对比
|
||||
|
||||
| 特性 | Google ADK | LangGraph | OpenAI Agents SDK |
|
||||
|------|-----------|-----------|-------------------|
|
||||
| **开发语言** | Python/Go/Java | Python | Python/TypeScript |
|
||||
| **模型支持** | 模型无关（优化 Gemini） | 模型无关 | 优化 OpenAI |
|
||||
| **多智能体** | ✅ 原生支持层级架构 | ✅ 图结构编排 | ✅ Handoff 机制 |
|
||||
| **工具生态** | 丰富（Google Search、MCP 等） | 丰富（LangChain 生态） | 丰富（OpenAI 生态） |
|
||||
| **部署** | Cloud Run / Vertex AI | 多种选择 | OpenAI 平台 |
|
||||
| **评估** | ✅ 内置评估系统 | ❌ 需第三方 | ❌ 需第三方 |
|
||||
|
||||
---
|
||||
|
||||
## 1.2 核心架构
|
||||
|
||||
### 1.2.1 Agent 类型体系
|
||||
|
||||
ADK 的所有智能体都继承自 `BaseAgent`，主要分为三大类：
|
||||
|
||||
```
|
||||
BaseAgent（基础智能体）
|
||||
│
|
||||
┌─────────────┼─────────────┐
|
||||
│ │ │
|
||||
LlmAgent WorkflowAgent CustomAgent
|
||||
（LLM 智能体） （工作流智能体） （自定义智能体）
|
||||
│ │
|
||||
│ ┌──────┼──────┐
|
||||
│ │ │ │
|
||||
│ Sequential Parallel Loop
|
||||
│ （顺序） （并行） （循环）
|
||||
│
|
||||
Agent（别名）
|
||||
```
|
||||
|
||||
| 类型 | 说明 | 适用场景 |
|
||||
|------|------|----------|
|
||||
| **LlmAgent** | 使用 LLM 作为核心引擎 | 自然语言理解、推理、工具调用 |
|
||||
| **SequentialAgent** | 顺序执行子智能体 | 数据处理流水线 |
|
||||
| **ParallelAgent** | 并行执行子智能体 | 多任务同时处理 |
|
||||
| **LoopAgent** | 循环执行子智能体 | 轮询、迭代优化 |
|
||||
| **CustomAgent** | 继承 BaseAgent 自定义 | 特殊逻辑、非标准流程 |
|
||||
|
||||
### 1.2.2 运行时架构
|
||||
|
||||
```
|
||||
用户输入
|
||||
│
|
||||
▼
|
||||
┌─────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ Runner │───▶│ Session │───▶│ Agent │
|
||||
│ （运行器）│ │ Service │ │ （智能体） │
|
||||
└─────────┘ │ （会话服务） │ └──────┬───────┘
|
||||
└──────────────┘ │
|
||||
┌──────────────┐ ▼
|
||||
│ Memory │ ┌──────────────┐
|
||||
│ Service │ │ Tools │
|
||||
│ （记忆服务） │ │ （工具集） │
|
||||
└──────────────┘ └──────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1.3 核心特性详解
|
||||
|
||||
### 1.3.1 丰富的工具生态
|
||||
|
||||
ADK 提供了三大类工具：
|
||||
|
||||
**Gemini 原生工具：**
|
||||
- **Google Search** — 网络搜索
|
||||
- **Code Execution** — 代码执行与调试
|
||||
- **Computer Use** — 操作计算机界面
|
||||
|
||||
**Google Cloud 工具：**
|
||||
- BigQuery、Spanner、Bigtable — 数据库
|
||||
- Vertex AI RAG Engine — 私有数据检索
|
||||
- Vertex AI Search — 企业搜索
|
||||
- API Registry — MCP 工具集成
|
||||
|
||||
**第三方工具：**
|
||||
- GitHub、GitLab — 代码管理
|
||||
- Notion、Linear — 项目管理
|
||||
- Stripe、PayPal — 支付
|
||||
- ElevenLabs、Cartesia — 语音生成
|
||||
- Qdrant — 向量搜索
|
||||
|
||||
### 1.3.2 多智能体协作模式
|
||||
|
||||
ADK 支持多种多智能体协作模式：
|
||||
|
||||
| 模式 | 说明 | 实现方式 |
|
||||
|------|------|----------|
|
||||
| **协调器/调度器** | 父 Agent 分配任务给子 Agent | LlmAgent + sub_agents |
|
||||
| **顺序流水线** | Agent 按顺序执行 | SequentialAgent |
|
||||
| **并行扇出** | Agent 同时执行 | ParallelAgent |
|
||||
| **层级任务分解** | 多层 Agent 分解任务 | 嵌套 sub_agents |
|
||||
| **人机协作** | 人工审批关键步骤 | Human-in-the-Loop |
|
||||
| **评审/批评** | 生成器 + 评审器协作 | LoopAgent + 条件退出 |
|
||||
|
||||
### 1.3.3 上下文管理
|
||||
|
||||
ADK 在架构层面分离了三种上下文：
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────┐
|
||||
│ 上下文管理架构 │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────┐ │
|
||||
│ │ Session（会话） │ │
|
||||
│ │ - 当前对话线程 │ │
|
||||
│ │ - 消息历史 │ │
|
||||
│ │ - 临时状态 │ │
|
||||
│ └──────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────┐ │
|
||||
│ │ State（状态） │ │
|
||||
│ │ - 会话内数据 │ │
|
||||
│ │ - 购物车、用户偏好等 │ │
|
||||
│ │ - temp: 临时状态 │ │
|
||||
│ └──────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────┐ │
|
||||
│ │ Memory（记忆） │ │
|
||||
│ │ - 跨会话持久化知识 │ │
|
||||
│ │ - 可搜索的知识库 │ │
|
||||
│ │ - 外部数据源 │ │
|
||||
│ └──────────────────────────────────┘ │
|
||||
└────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1.4 环境搭建
|
||||
|
||||
### 1.4.1 系统要求
|
||||
|
||||
| 要求 | 最低版本 | 推荐版本 |
|
||||
|------|----------|----------|
|
||||
| Python | 3.10 | 3.11+ |
|
||||
| pip | 最新版 | 最新版 |
|
||||
| 操作系统 | Windows/macOS/Linux | 任意 |
|
||||
|
||||
### 1.4.2 安装步骤
|
||||
|
||||
#### 步骤一：创建虚拟环境（推荐）
|
||||
|
||||
```bash
|
||||
# 创建虚拟环境
|
||||
python -m venv adk_env
|
||||
|
||||
# 激活虚拟环境
|
||||
# macOS / Linux：
|
||||
source adk_env/bin/activate
|
||||
|
||||
# Windows CMD：
|
||||
adk_env\Scripts\activate.bat
|
||||
|
||||
# Windows PowerShell：
|
||||
adk_env\Scripts\Activate.ps1
|
||||
```
|
||||
|
||||
#### 步骤二：安装 ADK
|
||||
|
||||
```bash
|
||||
# 安装稳定版本（推荐）
|
||||
pip install google-adk
|
||||
|
||||
# 如果需要使用非 Gemini 模型（如 DeepSeek、OpenAI 等），还需安装 litellm
|
||||
pip install google-adk litellm
|
||||
|
||||
# 如果需要安装开发版本
|
||||
pip install git+https://github.com/google/adk-python.git@main
|
||||
```
|
||||
|
||||
#### 步骤三：验证安装
|
||||
|
||||
```bash
|
||||
# 检查 ADK 版本
|
||||
adk --help
|
||||
|
||||
# 应该看到以下输出：
|
||||
# Usage: adk [OPTIONS] COMMAND [ARGS]...
|
||||
#
|
||||
# Agent Development Kit CLI tools.
|
||||
#
|
||||
# Options:
|
||||
# --version Show the version and exit.
|
||||
# --help Show this message and exit.
|
||||
#
|
||||
# Commands:
|
||||
# api_server Starts a FastAPI server for agents.
|
||||
# create Creates a new app in the current folder with prepopulated agent template.
|
||||
# deploy Deploys agent to hosted environments.
|
||||
# eval Evaluates an agent given the eval sets.
|
||||
# run Runs an interactive CLI for a certain agent.
|
||||
# web Starts a FastAPI server with Web UI for agents.
|
||||
```
|
||||
|
||||
### 1.4.3 配置 API Key
|
||||
|
||||
#### 使用 Gemini 模型（默认）
|
||||
|
||||
```bash
|
||||
# 在项目目录下创建 .env 文件
|
||||
echo 'GOOGLE_API_KEY="你的_GEMINI_API_KEY"' > .env
|
||||
```
|
||||
|
||||
> 💡 获取 Gemini API Key：访问 [Google AI Studio](https://aistudio.google.com/app/apikey) 创建 API Key。
|
||||
|
||||
#### 使用其他模型
|
||||
|
||||
```bash
|
||||
# 在 .env 文件中添加对应的 API Key
|
||||
echo 'OPENAI_API_KEY="你的_OPENAI_API_KEY"' >> .env
|
||||
echo 'DEEPSEEK_API_KEY="你的_DEEPSEEK_API_KEY"' >> .env
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1.5 ADK CLI 工具详解
|
||||
|
||||
安装 ADK 后，会获得一个 `adk` 命令行工具：
|
||||
|
||||
| 命令 | 说明 | 示例 |
|
||||
|------|------|------|
|
||||
| `adk create` | 创建新的 Agent 项目 | `adk create my_agent` |
|
||||
| `adk run` | 在命令行中运行 Agent | `adk run my_agent` |
|
||||
| `adk web` | 启动 Web UI 界面 | `adk web --port 8000` |
|
||||
| `adk api_server` | 启动 FastAPI 服务器 | `adk api_server` |
|
||||
| `adk eval` | 评估 Agent 性能 | `adk eval my_agent eval_set.json` |
|
||||
| `adk deploy` | 部署到托管环境 | `adk deploy my_agent` |
|
||||
|
||||
---
|
||||
|
||||
## 1.6 代码验证：环境搭建
|
||||
|
||||
以下代码用于验证 ADK 是否安装成功，详见 `code/setup_demo.py`：
|
||||
|
||||
```python
|
||||
"""
|
||||
Google ADK 环境搭建验证脚本
|
||||
验证 ADK 是否正确安装，并打印版本信息
|
||||
"""
|
||||
|
||||
# 导入 ADK 核心模块，验证安装是否成功
|
||||
from google.adk.agents import Agent # 智能体模块
|
||||
from google.adk.runners import Runner # 运行器模块
|
||||
from google.adk.sessions import InMemorySessionService # 内存会话服务
|
||||
|
||||
# 打印安装验证信息
|
||||
print("=" * 50) # 打印分隔线
|
||||
print("Google ADK 环境验证") # 打印标题
|
||||
print("=" * 50) # 打印分隔线
|
||||
print("✅ ADK 核心模块导入成功！") # 确认导入成功
|
||||
|
||||
# 验证 Agent 类是否可用
|
||||
agent = Agent( # 创建一个简单的测试 Agent
|
||||
name="test_agent", # 设置 Agent 名称
|
||||
model="gemini-2.0-flash", # 使用 Gemini 模型
|
||||
instruction="你是一个测试助手。", # 设置系统指令
|
||||
)
|
||||
print(f"✅ Agent 创建成功：{agent.name}") # 打印 Agent 名称
|
||||
|
||||
# 验证 Runner 类是否可用
|
||||
print("✅ Runner 模块可用") # 确认 Runner 可用
|
||||
|
||||
# 验证 SessionService 是否可用
|
||||
session_service = InMemorySessionService() # 创建内存会话服务
|
||||
print("✅ SessionService 可用") # 确认会话服务可用
|
||||
|
||||
print("=" * 50) # 打印分隔线
|
||||
print("🎉 所有模块验证通过！") # 打印成功信息
|
||||
print("可以开始使用 Google ADK 了！") # 提示用户
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1.7 常见问题
|
||||
|
||||
### Q1: 安装失败怎么办？
|
||||
|
||||
```bash
|
||||
# 尝试升级 pip
|
||||
pip install --upgrade pip
|
||||
|
||||
# 使用国内镜像源
|
||||
pip install google-adk -i https://pypi.tuna.tsinghua.edu.cn/simple
|
||||
```
|
||||
|
||||
### Q2: Python 版本不满足要求？
|
||||
|
||||
```bash
|
||||
# 检查 Python 版本
|
||||
python --version
|
||||
|
||||
# 如果低于 3.10，需要升级 Python
|
||||
# 推荐使用 pyenv 或 conda 管理 Python 版本
|
||||
```
|
||||
|
||||
### Q3: adk 命令找不到？
|
||||
|
||||
```bash
|
||||
# 确保虚拟环境已激活
|
||||
# 确认 google-adk 已安装
|
||||
pip show google-adk
|
||||
|
||||
# 如果安装了但找不到命令，尝试重新安装
|
||||
pip install --force-reinstall google-adk
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📌 本章小结
|
||||
|
||||
- ADK 是 Google 开源的模块化 AI 智能体开发框架
|
||||
- 支持多种 Agent 类型：LlmAgent、WorkflowAgent、CustomAgent
|
||||
- 提供丰富的工具生态和完善的上下文管理
|
||||
- 安装简单：`pip install google-adk`
|
||||
- 提供 CLI 工具 `adk` 用于项目创建、运行和部署
|
||||
|
||||
**下一章**：[第02章 - 快速开始：Hello World](./02-quick-start-hello-world.md) → 创建并运行你的第一个 Agent！
|
||||
Reference in New Issue
Block a user