Google ADK：code-first 的 Python Agent 开发框架｜安装与使用全指南

仓库：https://github.com/google/adk-python 官方文档：https://adk.dev/ 许可证：Apache-2.0 运行形态：Python 库（pip install google-adk），无 Web 端口

1. 项目简介

Agent Development Kit（ADK）2.0 是 Google 开源的 code-first Python 框架，用于构建、评估、部署复杂 AI Agent。它把软件工程原则用到 Agent 创建上，虽为 Gemini 优化，但模型无关、部署无关、兼容其他框架。

1.1 核心信息一览

1.2 适用场景

• 想用 Python 以代码优先方式构建 / 评估 / 部署 Agent；
• 需要图式工作流编排、多 Agent 层级；
• 想部署到 Cloud Run / Vertex AI Agent Engine。

1.3 能力边界（官方口径）

• 为 Gemini 优化但模型无关；
• 依赖版本建议用配套 constraints 文件保护；
• 开发版从 main 直接装，可能含实验性改动。

2. 功能特性

• Workflow Runtime：图式执行引擎，支持路由、fan-out/fan-in、循环、重试、状态管理、动态节点、HITL、嵌套工作流；
• Task API：结构化 Agent 间委派，多轮 / 单轮 / 混合模式；
• 模块化多 Agent：组合多个专责 Agent 成层级；
• 丰富工具生态：预建工具、自定义函数、OpenAPI、MCP；
• Agent Config：无代码构建 Agent；
• Tool Confirmation：HITL 工具确认流；
• 随处部署：Cloud Run、Vertex AI Agent Engine。

3. 官方界面预览

上图为官方 README logo（README 官方素材）。

4. 官方跳转链接汇总

• 仓库主页：https://github.com/google/adk-python
• 文档：https://adk.dev/
• Samples：https://github.com/google/adk-recipes
• ADK Web：https://github.com/google/adk-web
• ADK Java：https://github.com/google/adk-java
• ADK JS：https://github.com/google/adk-js
• Reddit：https://www.reddit.com/r/agentdevelopmentkit/

5. 前置要求与服务器配置

• Python 3.11+；
• 模型凭据（Gemini 或其他 Provider）；
• 无端口、无数据库。

6. 方式一：pip 安装（推荐）

pip install google-adk

用配套 constraints 保护依赖（以 Python 3.11 为例）：

curl -o constraints-3.11.txt https://raw.githubusercontent.com/google/adk-python/main/constraints-3.11.txt
pip install google-adk -c constraints-3.11.txt
rm constraints-3.11.txt

可选扩展：

pip install "google-adk[extensions]"

7. 方式二：开发版与源码

# 从 main 装最新代码
pip install git+https://github.com/google/adk-python.git@main

8. 配置项说明

9. 常用运维命令

# 安装
pip install google-adk

# 升级
pip install -U google-adk

# 扩展
pip install "google-adk[extensions]"

10. 常见故障排查

• 依赖冲突：用对应 Python 版本的 constraints 文件安装；
• Python 版本过低：需 3.11+；
• 想用最新修复：从 main 装开发版；
• 模型 401：检查 Gemini / Provider 凭据。

11. 风险与合规说明

• Apache-2.0 许可；
• 开发版可能含实验性改动；
• 模型调用费用由对应 Provider 账号承担；
• 本文为社区部署笔记，命令以官方文档最新版本为准。