Google Agent Development Kit (ADK) 指南第二章：环境搭建与快速开始

系列教程：这是《Google ADK 指南》系列的第二章。

前置知识：已完成第一章，了解 ADK 基本概念。

1. 前置要求

1.1 硬件要求

配置	最低要求	推荐配置
CPU	2 核	4 核+
内存	4GB	8GB+
磁盘	10GB	20GB+
网络	可访问 GCP	可访问 GCP

1.2 软件要求

Python 3.10+
pip 21.0+
Git
GCP 账号

1.3 检查环境

bash 复制代码

# 检查 Python 版本
python --version
# 预期：Python 3.10.x 或更高

# 检查 pip
pip --version

# 检查 Git
git --version

2. GCP 账号配置

2.1 创建 GCP 账号

访问 https://console.cloud.google.com
使用 Google 账号登录
创建新项目（或选择现有项目）
绑定支付方式（新用户有$300 免费额度）

2.2 启用必要 API

bash 复制代码

# 设置项目 ID
export PROJECT_ID="your-project-id"
gcloud config set project $PROJECT_ID

# 启用 Vertex AI API
gcloud services enable aiplatform.googleapis.com

# 启用 Cloud Logging API
gcloud services enable logging.googleapis.com

# 启用 Cloud Storage API
gcloud services enable storage.googleapis.com

2.3 配置认证

方式 1：服务账号（推荐生产）

bash 复制代码

# 创建服务账号
gcloud iam service-accounts create adk-service-account \
  --display-name="ADK Service Account"

# 分配角色
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:adk-service-account@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.admin"

# 生成密钥
gcloud iam service-accounts keys create adk-key.json \
  --iam-account=adk-service-account@$PROJECT_ID.iam.gserviceaccount.com

# 设置环境变量
export GOOGLE_APPLICATION_CREDENTIALS="./adk-key.json"

方式 2：用户认证（开发测试）

bash 复制代码

# 登录 GCP
gcloud auth application-default login

# 验证
gcloud auth application-default print-access-token

2.4 验证配置

bash 复制代码

# 检查项目配置
gcloud config get-value project

# 检查 API 状态
gcloud services list --enabled

# 检查认证
gcloud auth list

3. ADK 安装

3.1 创建虚拟环境

bash 复制代码

# 创建项目目录
mkdir adk-project && cd adk-project

# 创建虚拟环境
python -m venv venv

# 激活环境
# Linux/macOS
source venv/bin/activate

# Windows
venv\Scripts\activate

3.2 安装 ADK

bash 复制代码

# 安装 ADK 核心包
pip install google-adk

# 安装额外组件
pip install google-adk[all]

# 验证安装
python -c "from google.adk import Agent; print('ADK 安装成功！')"

3.3 安装开发工具

bash 复制代码

# 安装开发依赖
pip install pytest black pylint jupyter

# 安装 ADK CLI 工具
pip install google-adk-cli

3.4 项目结构

复制代码

adk-project/
├── venv/                    # 虚拟环境
├── src/                     # 源代码
│   ├── __init__.py
│   ├── agents/             # Agent 定义
│   │   ├── __init__.py
│   │   └── assistant.py
│   ├── tools/              # 工具定义
│   │   ├── __init__.py
│   │   └── custom_tools.py
│   └── main.py             # 入口文件
├── tests/                  # 测试代码
│   ├── __init__.py
│   └── test_agents.py
├── configs/                # 配置文件
│   ├── dev.yaml
│   └── prod.yaml
├── .env                    # 环境变量
├── requirements.txt        # 依赖列表
└── README.md

4. 第一个 Agent 应用

4.1 基础示例

创建 src/main.py：

python 复制代码

from google.adk import Agent
from google.adk.models import Gemini

# 创建 Agent
agent = Agent(
    name="hello_assistant",
    model=Gemini("gemini-2.0-flash"),
    instruction="你是一个友好的 AI 助手，用简洁中文回答用户问题。"
)

# 运行对话
if __name__ == "__main__":
    print("🤖 Hello Assistant 已就绪！输入 'quit' 退出。\n")
    
    while True:
        user_input = input("👤 你：")
        if user_input.lower() == 'quit':
            print("🤖 再见！")
            break
        
        response = agent.run(user_input)
        print(f"🤖 助手：{response.text}\n")

4.2 运行应用

bash 复制代码

# 设置环境变量
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"

# 运行应用
python src/main.py

预期输出：

复制代码

Hello Assistant 已就绪！输入 'quit' 退出。

你：你好
助手：你好！有什么我可以帮助你的吗？

你：今天天气怎么样？
助手：抱歉，我无法获取实时天气信息。我是一个 AI 助手...

你：quit
再见！

4.3 添加工具

创建 src/tools/weather_tool.py：

python 复制代码

from google.adk import Tool
import requests

@Tool(
    name="get_weather",
    description="获取指定城市的天气信息",
    parameters={
        "city": {"type": "string", "description": "城市名称"}
    }
)
def get_weather(city: str) -> str:
    """获取天气信息"""
    # 示例：使用天气 API
    api_key = "your_weather_api_key"
    url = f"http://api.weatherapi.com/v1/current.json?key={api_key}&q={city}"
    
    try:
        response = requests.get(url)
        data = response.json()
        return f"{city} 当前天气：{data['current']['condition']['text']}, 温度：{data['current']['temp_c']}°C"
    except Exception as e:
        return f"获取天气失败：{str(e)}"

更新 src/main.py：

python 复制代码

from google.adk import Agent
from google.adk.models import Gemini
from tools.weather_tool import get_weather

# 创建带工具的 Agent
agent = Agent(
    name="weather_assistant",
    model=Gemini("gemini-2.0-flash"),
    tools=[get_weather],
    instruction="你是一个天气助手，可以查询城市天气。"
)

# 运行对话
if __name__ == "__main__":
    print("🌤️ 天气助手已就绪！\n")
    
    while True:
        user_input = input("👤 你：")
        if user_input.lower() == 'quit':
            break
        
        response = agent.run(user_input)
        print(f"🤖 助手：{response.text}\n")

4.4 添加记忆

python 复制代码

from google.adk import Agent
from google.adk.models import Gemini
from google.adk.memory import ConversationBufferMemory

# 创建带记忆的 Agent
agent = Agent(
    name="chat_assistant",
    model=Gemini("gemini-2.0-flash"),
    memory=ConversationBufferMemory(max_turns=10),
    instruction="你是一个友好的聊天助手。"
)

# 运行多轮对话
if __name__ == "__main__":
    print("💬 聊天助手已就绪！\n")
    
    while True:
        user_input = input("👤 你：")
        if user_input.lower() == 'quit':
            break
        
        response = agent.run(user_input)
        print(f"🤖 助手：{response.text}\n")

5. 本地调试技巧

5.1 启用调试日志

python 复制代码

import logging

# 配置日志
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

# ADK 特定日志
logging.getLogger('google.adk').setLevel(logging.DEBUG)

5.2 使用 ADK CLI

bash 复制代码

# 查看帮助
adk --help

# 列出 Agent
adk agent list

# 运行 Agent
adk agent run hello_assistant

# 查看日志
adk logs tail --agent=hello_assistant

5.3 本地 Mock 测试

python 复制代码

from unittest.mock import Mock, patch
from google.adk import Agent

def test_agent_with_mock():
    # 创建 Mock 模型
    mock_model = Mock()
    mock_model.generate.return_value = "这是测试回复"
    
    # 创建 Agent
    agent = Agent(
        name="test_agent",
        model=mock_model,
        instruction="测试助手"
    )
    
    # 测试
    response = agent.run("测试问题")
    assert response.text == "这是测试回复"

5.4 性能分析

python 复制代码

import time
from google.adk import Agent

def profile_agent():
    agent = Agent(...)
    
    # 预热
    agent.run("hello")
    
    # 性能测试
    start = time.time()
    for i in range(10):
        agent.run(f"测试问题 {i}")
    end = time.time()
    
    print(f"平均响应时间：{(end-start)/10:.2f}秒")

6. 常见问题

6.1 认证问题

Q: 提示 "无法找到凭证"

bash 复制代码

# 解决：
# 1. 检查服务账号密钥
export GOOGLE_APPLICATION_CREDENTIALS="./adk-key.json"

# 2. 或重新登录
gcloud auth application-default login

# 3. 验证
gcloud auth application-default print-access-token

6.2 API 配额问题

Q: 提示 "超出配额限制"

bash 复制代码

# 解决：
# 1. 查看配额使用
gcloud services quotas list --service=aiplatform.googleapis.com

# 2. 申请提升配额
gcloud services quotas update \
  --service=aiplatform.googleapis.com \
  --quota=REQUESTS_PER_MINUTE \
  --value=100

6.3 安装问题

Q: pip install 失败

bash 复制代码

# 解决：
# 1. 升级 pip
pip install --upgrade pip

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

# 3. 检查 Python 版本
python --version  # 需要 3.10+

6.4 网络问题

Q: 无法连接 GCP

bash 复制代码

# 解决：
# 1. 检查网络连接
ping aiplatform.googleapis.com

# 2. 配置代理（如需要）
export HTTPS_PROXY=http://proxy:port

# 3. 检查防火墙

6.5 成本优化

Q: 如何控制成本？

python 复制代码

# 1. 设置 Token 限制
agent = Agent(
    ...,
    generation_config={
        "max_output_tokens": 1000,
        "temperature": 0.7
    }
)

# 2. 使用缓存
from google.adk.caching import ResponseCache
cache = ResponseCache(ttl=3600)

# 3. 监控用量
from google.adk import usage_tracking
usage_tracking.enable()

系列教程导航：

第一章：ADK 简介与对比
第二章：环境搭建与快速开始 ← 本章
第三章：核心概念与架构
第四章：Agent 开发与编排
第五章：工具集成与自定义
第六章：记忆与状态管理
第七章：企业级功能与安全
第八章：实战案例与最佳实践

Google Agent Development Kit (ADK) 指南 第二章：环境搭建与快速开始

Google Agent Development Kit (ADK) 指南 第二章：环境搭建与快速开始

目录

1. 前置要求

1.1 硬件要求

1.2 软件要求

1.3 检查环境

2. GCP 账号配置

2.1 创建 GCP 账号

2.2 启用必要 API

2.3 配置认证

2.4 验证配置

3. ADK 安装

3.1 创建虚拟环境

3.2 安装 ADK

3.3 安装开发工具

3.4 项目结构

4. 第一个 Agent 应用

4.1 基础示例

4.2 运行应用

4.3 添加工具

4.4 添加记忆

5. 本地调试技巧

5.1 启用调试日志

5.2 使用 ADK CLI

5.3 本地 Mock 测试

5.4 性能分析

6. 常见问题

6.1 认证问题

6.2 API 配额问题

6.3 安装问题

6.4 网络问题

6.5 成本优化

Google Agent Development Kit (ADK) 指南第二章：环境搭建与快速开始

Google Agent Development Kit (ADK) 指南第二章：环境搭建与快速开始