GuangYu/Agent-Docs

Fork 0

Files

Nelson 514723dbe7 init

2026-04-06 12:36:04 +08:00

13 KiB

Raw Blame History

第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 安装步骤

步骤一：创建虚拟环境（推荐）

# 创建虚拟环境
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

# 安装稳定版本（推荐）
pip install google-adk

# 如果需要使用非 Gemini 模型（如 DeepSeek、OpenAI 等），还需安装 litellm
pip install google-adk litellm

# 如果需要安装开发版本
pip install git+https://github.com/google/adk-python.git@main

步骤三：验证安装

# 检查 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 模型（默认）

# 在项目目录下创建 .env 文件
echo 'GOOGLE_API_KEY="你的_GEMINI_API_KEY"' > .env

💡 获取 Gemini API Key：访问 Google AI Studio 创建 API Key。

使用其他模型

# 在 .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：

"""
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: 安装失败怎么办？

# 尝试升级 pip
pip install --upgrade pip

# 使用国内镜像源
pip install google-adk -i https://pypi.tuna.tsinghua.edu.cn/simple

Q2: Python 版本不满足要求？

# 检查 Python 版本
python --version

# 如果低于 3.10，需要升级 Python
# 推荐使用 pyenv 或 conda 管理 Python 版本

Q3: adk 命令找不到？

# 确保虚拟环境已激活
# 确认 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 → 创建并运行你的第一个 Agent！

13 KiB Raw Blame History Unescape Escape