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

Google Agent Development Kit (ADK) 指南 第二章环境搭建与快速开始系列教程这是《Google ADK 指南》系列的第二章。前置知识已完成第一章了解 ADK 基本概念。目录前置要求GCP 账号配置ADK 安装第一个 Agent 应用本地调试技巧常见问题1. 前置要求1.1 硬件要求配置最低要求推荐配置CPU2 核4 核内存4GB8GB磁盘10GB20GB网络可访问 GCP可访问 GCP1.2 软件要求Python 3.10pip 21.0GitGCP 账号1.3 检查环境# 检查 Python 版本python--version# 预期Python 3.10.x 或更高# 检查 pippip--version# 检查 Gitgit--version2. GCP 账号配置2.1 创建 GCP 账号访问 https://console.cloud.google.com使用 Google 账号登录创建新项目或选择现有项目绑定支付方式新用户有$300 免费额度2.2 启用必要 API# 设置项目 IDexportPROJECT_IDyour-project-idgcloud configsetproject$PROJECT_ID# 启用 Vertex AI APIgcloud servicesenableaiplatform.googleapis.com# 启用 Cloud Logging APIgcloud servicesenablelogging.googleapis.com# 启用 Cloud Storage APIgcloud servicesenablestorage.googleapis.com2.3 配置认证方式 1服务账号推荐生产# 创建服务账号gcloud iam service-accounts create adk-service-account\--display-nameADK Service Account# 分配角色gcloud projects add-iam-policy-binding$PROJECT_ID\--memberserviceAccount:adk-service-account$PROJECT_ID.iam.gserviceaccount.com\--roleroles/aiplatform.admin# 生成密钥gcloud iam service-accounts keys create adk-key.json\--iam-accountadk-service-account$PROJECT_ID.iam.gserviceaccount.com# 设置环境变量exportGOOGLE_APPLICATION_CREDENTIALS./adk-key.json方式 2用户认证开发测试# 登录 GCPgcloud auth application-default login# 验证gcloud auth application-default print-access-token2.4 验证配置# 检查项目配置gcloud config get-value project# 检查 API 状态gcloud services list--enabled# 检查认证gcloud auth list3. ADK 安装3.1 创建虚拟环境# 创建项目目录mkdiradk-projectcdadk-project# 创建虚拟环境python-mvenv venv# 激活环境# Linux/macOSsourcevenv/bin/activate# Windowsvenv\Scripts\activate3.2 安装 ADK# 安装 ADK 核心包pipinstallgoogle-adk# 安装额外组件pipinstallgoogle-adk[all]# 验证安装python-cfrom google.adk import Agent; print(ADK 安装成功)3.3 安装开发工具# 安装开发依赖pipinstallpytest black pylint jupyter# 安装 ADK CLI 工具pipinstallgoogle-adk-cli3.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.md4. 第一个 Agent 应用4.1 基础示例创建src/main.pyfromgoogle.adkimportAgentfromgoogle.adk.modelsimportGemini# 创建 AgentagentAgent(namehello_assistant,modelGemini(gemini-2.0-flash),instruction你是一个友好的 AI 助手用简洁中文回答用户问题。)# 运行对话if__name____main__:print( Hello Assistant 已就绪输入 quit 退出。\n)whileTrue:user_inputinput( 你)ifuser_input.lower()quit:print( 再见)breakresponseagent.run(user_input)print(f 助手{response.text}\n)4.2 运行应用# 设置环境变量exportGOOGLE_CLOUD_PROJECTyour-project-idexportGOOGLE_CLOUD_LOCATIONus-central1# 运行应用python src/main.py预期输出Hello Assistant 已就绪输入 quit 退出。 你你好 助手你好有什么我可以帮助你的吗 你今天天气怎么样 助手抱歉我无法获取实时天气信息。我是一个 AI 助手... 你quit 再见4.3 添加工具创建src/tools/weather_tool.pyfromgoogle.adkimportToolimportrequestsTool(nameget_weather,description获取指定城市的天气信息,parameters{city:{type:string,description:城市名称}})defget_weather(city:str)-str:获取天气信息# 示例使用天气 APIapi_keyyour_weather_api_keyurlfhttp://api.weatherapi.com/v1/current.json?key{api_key}q{city}try:responserequests.get(url)dataresponse.json()returnf{city}当前天气{data[current][condition][text]}, 温度{data[current][temp_c]}°CexceptExceptionase:returnf获取天气失败{str(e)}更新src/main.pyfromgoogle.adkimportAgentfromgoogle.adk.modelsimportGeminifromtools.weather_toolimportget_weather# 创建带工具的 AgentagentAgent(nameweather_assistant,modelGemini(gemini-2.0-flash),tools[get_weather],instruction你是一个天气助手可以查询城市天气。)# 运行对话if__name____main__:print(️ 天气助手已就绪\n)whileTrue:user_inputinput( 你)ifuser_input.lower()quit:breakresponseagent.run(user_input)print(f 助手{response.text}\n)4.4 添加记忆fromgoogle.adkimportAgentfromgoogle.adk.modelsimportGeminifromgoogle.adk.memoryimportConversationBufferMemory# 创建带记忆的 AgentagentAgent(namechat_assistant,modelGemini(gemini-2.0-flash),memoryConversationBufferMemory(max_turns10),instruction你是一个友好的聊天助手。)# 运行多轮对话if__name____main__:print( 聊天助手已就绪\n)whileTrue:user_inputinput( 你)ifuser_input.lower()quit:breakresponseagent.run(user_input)print(f 助手{response.text}\n)5. 本地调试技巧5.1 启用调试日志importlogging# 配置日志logging.basicConfig(levellogging.DEBUG,format%(asctime)s - %(name)s - %(levelname)s - %(message)s)# ADK 特定日志logging.getLogger(google.adk).setLevel(logging.DEBUG)5.2 使用 ADK CLI# 查看帮助adk--help# 列出 Agentadk agent list# 运行 Agentadk agent run hello_assistant# 查看日志adk logstail--agenthello_assistant5.3 本地 Mock 测试fromunittest.mockimportMock,patchfromgoogle.adkimportAgentdeftest_agent_with_mock():# 创建 Mock 模型mock_modelMock()mock_model.generate.return_value这是测试回复# 创建 AgentagentAgent(nametest_agent,modelmock_model,instruction测试助手)# 测试responseagent.run(测试问题)assertresponse.text这是测试回复5.4 性能分析importtimefromgoogle.adkimportAgentdefprofile_agent():agentAgent(...)# 预热agent.run(hello)# 性能测试starttime.time()foriinrange(10):agent.run(f测试问题{i})endtime.time()print(f平均响应时间{(end-start)/10:.2f}秒)6. 常见问题6.1 认证问题Q: 提示 “无法找到凭证”# 解决# 1. 检查服务账号密钥exportGOOGLE_APPLICATION_CREDENTIALS./adk-key.json# 2. 或重新登录gcloud auth application-default login# 3. 验证gcloud auth application-default print-access-token6.2 API 配额问题Q: 提示 “超出配额限制”# 解决# 1. 查看配额使用gcloud services quotas list--serviceaiplatform.googleapis.com# 2. 申请提升配额gcloud services quotas update\--serviceaiplatform.googleapis.com\--quotaREQUESTS_PER_MINUTE\--value1006.3 安装问题Q: pip install 失败# 解决# 1. 升级 pippipinstall--upgradepip# 2. 使用国内镜像pipinstallgoogle-adk-ihttps://pypi.tuna.tsinghua.edu.cn/simple# 3. 检查 Python 版本python--version# 需要 3.106.4 网络问题Q: 无法连接 GCP# 解决# 1. 检查网络连接pingaiplatform.googleapis.com# 2. 配置代理如需要exportHTTPS_PROXYhttp://proxy:port# 3. 检查防火墙6.5 成本优化Q: 如何控制成本# 1. 设置 Token 限制agentAgent(...,generation_config{max_output_tokens:1000,temperature:0.7})# 2. 使用缓存fromgoogle.adk.cachingimportResponseCache cacheResponseCache(ttl3600)# 3. 监控用量fromgoogle.adkimportusage_tracking usage_tracking.enable()系列教程导航第一章ADK 简介与对比第二章环境搭建与快速开始 ← 本章第三章核心概念与架构第四章Agent 开发与编排第五章工具集成与自定义第六章记忆与状态管理第七章企业级功能与安全第八章实战案例与最佳实践