# 第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！