Google ADK（Agent Development Kit）2.0：Google 官方智能体开发套件完整中文说明

官方信息

项目背景

Agent Development Kit（ADK）是 Google 推出的开源、代码优先（code-first）Python 框架，用于构建、评估和部署复杂的 AI 智能体。它把成熟的软件工程原则应用到 AI 智能体的创建过程中，目标是让智能体开发像写普通后端程序一样有结构、可测试、可版本管理。ADK 设计上高度灵活、模块化，既能搭简单的单任务智能体，也能编排从简单任务到复杂系统的完整工作流。

虽然 ADK 针对 Gemini 模型做了深度优化，但它本身是模型无关（model-agnostic）、部署无关（deployment-agnostic）的，并且与其他主流智能体框架兼容。官方还维护了一系列配套生态：示例代码在 adk-recipes，可视化开发界面在 adk-web，社区贡献的工具与集成放在 adk-python-community 仓库。

所谓"模型无关"，意思是 ADK 不绑定某一家大模型厂商：你可以把 Agent 的 model 参数指向 Gemini，也可以换成 OpenAI、Anthropic 或任何 OpenAI 兼容服务；所谓"部署无关"，意思是同一份智能体代码，可以本地用 Docker 跑，也可以一键搬到 Google Cloud 的 Cloud Run，还可以用 Vertex AI Agent Engine 做托管扩缩。这两点设计让 ADK 的定位区别于"某模型专属 SDK"，更像一个通用的智能体应用工程框架。ADK 2.0 是一个大版本，核心变化是把"工作流"提升为与"智能体"并列的一等概念：过去智能体之间的编排往往靠提示词和手写循环，2.0 则提供了基于图的执行引擎，让路由、并行、循环、重试这些控制流都变成声明式的配置。

核心特性（Key Features 逐条）

ADK 2.0 的官方特性清单如下，逐条解释：

• 工作流运行时（Workflow Runtime）：一个基于图（graph）的执行引擎，用来为智能体应用编排确定性的执行流程。它支持路由（routing）、扇出/扇入（fan-out/fan-in）、循环（loops）、重试（retry）、状态管理（state management）、动态节点（dynamic nodes）、人在回路（human-in-the-loop）以及嵌套工作流（nested workflows）。

• 任务 API（Task API）：结构化的智能体到智能体委派机制，支持多轮任务模式、单轮受控输出、混合委派模式、人在回路，还可以把任务智能体直接当作工作流节点来用。

• 模块化多智能体系统：通过把多个专精的智能体组合成灵活的层级结构，来设计可扩展的应用，而不是把所有逻辑塞进一个大提示词。

• 丰富的工具生态：可以直接使用内置工具、自定义函数、OpenAPI 规范、MCP 工具，也能集成已有工具，让智能体获得多样化能力，并且与 Google 生态紧密集成。

• 代码优先开发：智能体逻辑、工具、编排全部直接用 Python 定义，从而获得最大的灵活性、可测试性和版本管理能力。

• 智能体配置（Agent Config）：支持不写代码、通过配置来构建智能体，详见官方文档的 Agent Config 章节。

• 工具确认（Tool Confirmation）：提供一个工具确认流程（人在回路），可以在工具真正执行前要求用户显式确认，甚至要求用户补充输入，从而守住"高风险操作必须人来拍板"这道关。

• 随处部署（Deploy Anywhere）：可以轻松把智能体容器化部署到 Cloud Run，也可以用 Vertex AI Agent Engine 无缝扩缩容。

环境要求与安装

稳定版（推荐）

ADK 要求 Python 3.11 及以上，用 pip 安装最新稳定版：

pip install google-adk

为了防止传递依赖版本冲突，官方建议配合约束文件（constraints file）一起安装，约束文件覆盖 Python 3.11 到 3.15。根据你的 Python 版本选择对应文件，例如 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]"

ADK 的发布节奏大约是每两周一个版本，意味着新特性和修复会比较快地进入 PyPI。约束文件的作用是把传递依赖（比如 grpc、pydantic、google-genai 这些间接装进来的包）钉死在经过测试的版本上，避免某次 pip install 因为依赖升级而把你本地环境搞崩；如果你只是在隔离的虚拟环境里玩一玩，也可以不用约束文件，但生产部署强烈建议带上。

开发版

Bug 修复和新特性会先合并到 GitHub 的 main 分支。如果你需要用到尚未发版到 PyPI 的改动，可以直接从 main 分支安装：

pip install git+https://github.com/google/adk-python.git@main

注意：开发版是从最新代码提交直接构建的，虽然包含最新修复和特性，但也可能含有尚未在稳定版中出现的实验性改动或 bug，建议仅用于测试即将发布的改动，或在正式发版前紧急需要某个关键修复时使用。

快速开始（Quick Start）

入门提示：ADK 应用主要由两个核心类构成——Agent（定义一个 AI 的指令、工具和行为）和 Workflow（以图的方式编排智能体和任务）。

定义一个最简单的 Agent

from google.adk import Agent

root_agent = Agent(
    name="greeting_agent",
    model="gemini-3.5-flash",
    instruction="You are a helpful assistant. Greet the user warmly.",
)

这个 Agent 名为 greeting_agent，绑定模型 gemini-3.5-flash，系统指令是"你是一个乐于助人的助手，热情地向用户打招呼"。

用 Workflow 编排多个 Agent

from google.adk import Agent, Workflow

generate_fruit_agent = Agent(
    name="generate_fruit_agent",
    instruction="Return the name of a random fruit. Return only the name.",
)

generate_benefit_agent = Agent(
    name="generate_benefit_agent",
    instruction="Tell me a health benefit about the specified fruit.",
)

root_agent = Workflow(
    name="root_agent",
    edges=[("START", generate_fruit_agent, generate_benefit_agent)],
)

这里定义了两个 Agent：第一个随机返回一种水果的名字，第二个针对这种水果讲一条健康益处。然后用 Workflow 把它们串成一条边 ("START", generate_fruit_agent, generate_benefit_agent)，即从 START 出发先跑生成水果的智能体，再把结果交给生成益处的智能体。这就是 ADK 2.0 里多智能体编排的基本单位。

在传统的单智能体写法里，"先做 A 再做 B"这种流程往往要靠提示词里写"请你先……然后……"来实现，模型一旦不听话就容易乱序；而 Workflow 把这部分控制流从提示词里抽出来，变成由框架保证的图执行：哪个节点先跑、哪个节点并行、出错了重试几次、状态怎么在节点之间传递，全部由运行时负责，模型只负责在自己那一步里给出高质量输出。这也是 ADK 官方反复强调"把软件工程原则应用到智能体"的核心含义。

本地运行

ADK 自带命令行工具，安装后即可使用：

# 交互式 CLI
adk run path/to/my_agent

# Web UI（支持多智能体目录，也可以直接指向单个智能体文件夹）
adk web path/to/agents_dir

开发 UI

ADK 内置了一个开发用 UI，帮助你测试、评估、调试和展示自己的智能体。官方提供了一个演示视频，可以在 YouTube 上观看 ADK Web Demo。

评估智能体

ADK 内置了评估能力，可以从仓库根目录运行官方打包的评估示例：

adk eval \
    contributing/samples/evaluation/home_automation_agent \
    contributing/samples/evaluation/basic_criteria/home_automation.evalset.json \
    --config_file_path contributing/samples/evaluation/basic_criteria/eval_config.json

这条命令做的事情是：用 home_automation_agent 这个家居自动化智能体，在 home_automation.evalset.json 定义的评测集上，按 eval_config.json 配置的标准进行打分。这说明 ADK 把"评估"当作和"运行"同等重要的一等公民，而不是事后再补。

对一个真实项目来说，智能体最容易出问题的地方不是"能不能跑"，而是"改了提示词或换了模型之后，以前好用的案例会不会变差"。ADK 的评估命令正是为这种回归测试设计的：你把验收场景固化成评测集，每次改动都跑一遍 adk eval，就能看到质量是上升还是下降，从而把智能体开发从"凭感觉调 prompt"变成有数据支撑的工程活动。

部署选项

用 Docker 容器在本地部署智能体：

adk deploy docker --with_ui <agent-folder>

部署到 Google Cloud（Cloud Run）：

adk deploy cloud_run --with_ui <agent-folder>

本地 Docker 适合开发联调和内网部署；Cloud Run 适合把智能体做成一个可对外访问的 HTTPS 服务，自动扩缩、按用量计费；Vertex AI Agent Engine 则是 Google 托管的智能体运行时，适合需要长期运行、多租户、企业级权限管控的生产场景。命令里的 --with_ui 参数表示同时把开发调试界面一起部署上去，方便你在线观察智能体运行情况。

环境变量既可以直接写在 adk 命令里，也可以放在 .env 文件中，例如：

adk deploy cloud_run --with_ui --env GOOGLE_GENAI_USE_ENTERPRISE=1 <agent-folder>

常见问题（FAQ）

问：ADK 对 Python 版本有什么要求？ 答：要求 Python 3.11 及以上。官方还为 Python 3.11 到 3.15 分别提供了约束文件（constraints-3.11.txt 等），建议安装时用 -c 参数指定，避免传递依赖装到不兼容的版本。

问：稳定版和开发版该怎么选？ 答：日常使用选 PyPI 稳定版 pip install google-adk，发布节奏约为每两周一次；只有当你急需某个尚未发版的 bug 修复或想提前体验新特性时，才从 main 分支安装开发版。开发版可能含有实验性改动，不建议直接上生产。

问：Agent 和 Workflow 有什么区别？ 答：Agent 描述的是"一个 AI 角色"——它有名字、绑定模型、有系统指令、可以挂工具；Workflow 描述的是"这些智能体之间怎么配合"——用一条边把多个智能体串成图，支持顺序、并行、路由、循环。简单应用可以直接用单个 Agent，一旦出现"先让 A 查资料、再让 B 写报告、最后让 C 校对"这类多步流程，就应该用 Workflow 编排。

问：ADK 怎么保证高风险操作不出错？ 答：ADK 提供工具确认（Tool Confirmation）这一人在回路机制。你可以给某些工具加上确认要求，智能体在真正执行"发邮件、删数据、调 API"这类动作之前，会先停下来等用户确认，甚至可以要求用户补充输入，从而把最终决定权留给人。

问：ADK 怎么接入外部工具？ 答：工具来源非常多：可以直接把 Python 函数注册成工具，可以导入现成工具库，可以用 OpenAPI 规范自动生成工具，也可以通过 MCP 协议接入社区服务器。这让 ADK 智能体既能调用 Google 生态的服务，也能复用你已有的内部系统。

问：怎么知道我的智能体做得好不好？ 答：ADK 内置了评估命令 adk eval，你只需要准备一份评测集（.evalset.json）和一份评估配置（eval_config.json），就能批量跑测试并打分，把智能体质量变成可量化、可回归的指标，而不是靠人工点几次试试。

问：ADK 支持哪些部署方式？ 答：三种：本地 Docker（adk deploy docker）、Google Cloud Run（adk deploy cloud_run）、以及 Vertex AI Agent Engine 托管扩缩。三种方式跑的是同一份智能体代码，只是把它放到不同的运行环境里。

文档与学习资源

• 入门指南：adk.dev
• 教程：仓库里的 docs/guides/ 目录提供面向任务的讲解，覆盖智能体、工具、事件、插件和工作流。
• 示例：仓库里的 contributing/samples/ 目录提供可以直接运行的示例智能体。

参与贡献与社区

官方欢迎社区贡献，无论是 bug 报告、特性请求、文档改进还是代码提交。贡献流程见通用贡献指南，代码规范见仓库内的 CONTRIBUTING.md。此外还有一个 adk-python-community 社区仓库，汇集社区贡献的工具、第三方服务集成和部署脚本。

对中文使用者来说，ADK 的学习路径建议是：先在 adk.dev 走完官方入门，然后把 contributing/samples/ 下的示例跑通，再照着 docs/guides/ 的任务教程把自己的业务场景拆成若干个 Agent，用 Workflow 串起来，最后用 adk eval 建一份属于自己的评测集。

Vibe Coding 支持

如果你想用"氛围编程"（vibe coding）的方式，让大模型直接帮你写 ADK 智能体，官方在文档站上发布了两个文件：llms.txt 是精简版摘要，llms-full.txt 是包含完整文档的版本，适合喂给大上下文窗口的 LLM 作为上下文。使用时把这两个文件之一作为系统上下文喂给编码模型，它就能在不额外查文档的情况下，按 ADK 的真实 API 写出可运行的智能体代码，大幅降低"凭印象写错 API"的概率。

社区活动

ADK 的第一次社区会议已于 2025 年 10 月 15 日（周三）举办，录像和演示文稿可以通过加入 adk-community 邮件组 获取。

跳转链接

• 开源仓库：google/adk-python
• 官方文档：adk.dev
• PyPI：google-adk
• 示例代码：adk-recipes
• 开发 UI：adk-web
• 社区仓库：adk-python-community
• 社区讨论：Reddit r/agentdevelopmentkit
• 其他语言版：Java ｜ Kotlin ｜ Go ｜ TypeScript