Agent Development Kit（ADK）2.0 实战指南：用 Python 构建、评估与部署 AI Agent

Agent Development Kit（ADK）2.0 实战指南：用 Python 构建、评估与部署 AI Agent

【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python

本文基于仓库根目录 README.md 与 src/google/adk 源码，系统讲解 ADK（Agent Development Kit）2.0 的核心能力与上手路径：从安装配置、Agent/Workflow两大核心类的代码优先开发，到本地运行（CLI 与 Web 开发 UI）、自动化评估与 Docker/Cloud Run 部署的完整闭环。读完本文，你将掌握用 ADK 快速搭建带工具调用的单 Agent 与图编排多 Agent 应用，并理解其 2.0 版本相对 1.x 的关键变化与底层实现原理。

ADK 是什么：一套"代码优先"的 Agent 开发框架

Agent Development Kit（ADK）是一个开源、模块化的 Python 框架，将软件开发工程实践引入 AI Agent 的创建过程，帮助开发者从简单任务到复杂系统地构建、编排与部署 Agent 工作流。根据 README.md 的定位，ADK 在设计上遵循四条原则：

• 代码优先（Code-First）：Agent 的逻辑、工具与编排方式直接以 Python 代码定义，从而获得极致的灵活性、可测试性与版本管理能力；
• 模型无关（Model-Agnostic）：虽然针对 Gemini 做了深度优化，但框架本身不绑定特定模型厂商，可通过模型层接入不同 LLM（仓库中同时存在 hello_world_anthropic、hello_world_litellm、hello_world_ollama 等示例）；
• 部署无关（Deployment-Agnostic）：既能在本地以 CLI/Web UI 运行，也能容器化部署到 Cloud Run，或通过 Vertex AI Agent Engine 弹性扩缩容；
• 框架兼容：可与 LangChain（见 langchain_structured_tool_agent）等现有工具生态协同。

从仓库结构看，ADK 的功能模块非常完整：agents（Agent 实现）、workflow（图编排引擎）、tools（工具生态）、events（事件模型）、sessions（会话存储）、evaluation（评估体系）、flows（LLM 流程）、auth（认证）、memory（记忆服务）与live（实时流式能力）等均位于 src/google/adk 下。google.adk顶层包通过惰性加载对外暴露五个核心对象，见init.py：

__all__ = ['Agent', 'Context', 'Event', 'Runner', 'Workflow']

这五个符号构成了 ADK 编程模型的主干：Agent定义智能体的指令、工具与行为；Workflow以图的方式编排多个 Agent 与任务；Context贯穿一次运行携带状态；Event描述运行中产生的事件流；Runner负责驱动执行。

版本提示：2.0 与 1.x 的破坏性变更

仓库当前版本为2.8.0（见 version.py）。README 在显著位置给出了 1.x 升级警告，这是理解本项目必须注意的兼容性边界：

• 2.0 对Agent API、事件模型（event model）与会话模式（session schema）引入了破坏性变更；
• 由 ADK 2.0 生成的会话（session）可被 ADK 1.28+ 读取（多余字段会被忽略），但与更早的 1.x 版本不兼容。

这意味着：如果你有基于 1.x 构建的存量应用，升级前需要核对 Agent 构造方式、事件消费逻辑与持久化会话的读写兼容性；而新项目应直接从 2.0 起步，并注意不能把 2.0 的会话数据回灌到 1.28 之前的旧版本中。

核心特性全景

README 将 ADK 的能力归纳为八个关键特性，理解它们有助于把握框架的适用场景：

其中 Workflow Runtime 的图执行引擎在源码中有清晰印证：workflow/_workflow.py 中Workflow继承自BaseNode，其_run_impl()即图编排主循环（SETUP 建图与播种触发器 → LOOP 通过NodeRunner调度就绪节点 → FINALIZE 收集终态输出），并提供了edges、max_concurrency、graph等字段；_graph.py、_dynamic_node_scheduler.py、_retry_config.py、_parallel_worker.py等模块则对应路由、动态节点、重试与并行扇出等图能力。相关可运行示例集中在 contributing/samples/workflows（含 loop、retry、route、fan_out_fan_in、dynamic_nodes、nested_workflow 等）与 contributing/samples/multi_agent。

安装与依赖管理

稳定版安装（推荐）

官方发布到 PyPI，包名为google-adk，直接使用pip安装：

pip install google-adk

环境要求：Python 3.10+。这一约束同时体现在 pyproject.toml 的requires-python = ">=3.10"中，项目为此提供了 3.10～3.14 的完整版本分类器。

传递依赖锁定：使用约束文件

为保证传递依赖安全，官方建议搭配配套的 constraints 文件（覆盖 Python 3.10 至 3.14）。仓库根目录已包含 constraints-3.10.txt、constraints-3.11.txt、constraints-3.12.txt、constraints-3.13.txt、constraints-3.14.txt，安装时按 Python 版本选择即可：

# 例如 Python 3.10 curl -o constraints-3.10.txt https://raw.githubusercontent.com/google/adk-python/main/constraints-3.10.txt pip install google-adk -c constraints-3.10.txt rm constraints-3.10.txt

通过-c参数指定约束文件，可以把google-adk的依赖版本钉在官方验证过的组合上，避免第三方依赖升级带来的意外破坏。

可选扩展

若需要 BigQuery、Spanner、Pub/Sub、LiveKit、MCP 等可选集成能力，可安装带扩展的版本：

pip install "google-adk[extensions]"

从 pyproject.toml 可以看到extensions之外的完整 extras 组织：a2a（A2A 协议支持）、agent-identity（Google Cloud Agent Identity 凭据）、all（所有解锁运行时特性的 extra 的并集），以及 benchmark/community/dev/docs/test 等面向构建与测试自身的分组。all分组中包含了google-cloud-aiplatform[agent-engines,evaluation]、mcp、langgraph、litellm、openai、anthropic、livekit等关键依赖，这也是"模型无关、生态兼容"设计的具体体现。

另外需要注意：官方发布节奏约为每两周一次（bi-weekly），生产环境建议跟随稳定版，而非随时更新的开发分支。

开发版安装

Bug 修复与新特性会先合入 main 分支；若需要尚未进入 PyPI 正式版本的能力，可直连源码安装：

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

开发版直接从最新提交构建，包含最新的修复与特性，但可能包含实验性变更或尚未修复的缺陷，建议仅用于验证新特性或提前获取关键修复。

快速上手：Agent 与 Workflow

README 给新手划出了重点：ADK 应用由两个核心类构成——Agent（定义 AI 的指令、工具与行为）与Workflow（以图流程编排 Agent 与任务）。

定义一个最小 Agent

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

这里的Agent实际指向 llm_agent.py 中的LlmAgent类（由init.py 的惰性映射'Agent': '.agents.llm_agent'导出）。name用于在事件流与图编排中标识节点，model指定底层 LLM（字符串形式，经LLMRegistry解析），instruction是系统提示词。

带工具的真实 Agent：以官方 Quickstart 为例

更贴近实战的是带工具调用的 Agent。contributing/samples/core/quickstart/agent.py 演示了一个天气/时间查询 Agent：两个普通 Python 函数get_weather与get_current_time直接作为工具挂载到 Agent 上，函数签名（类型注解）与 docstring 会被自动转换为模型可理解的工具声明：

from google.adk.agents.llm_agent import Agent def get_weather(city: str) -> dict: """Retrieves the current weather report for a specified city. Args: city (str): The name of the city for which to retrieve the weather report. Returns: dict: status and result or error msg. """ if city.lower() == "new york": return { "status": "success", "report": ( "The weather in New York is sunny with a temperature of 25 degrees" " Celsius (77 degrees Fahrenheit)." ), } else: return { "status": "error", "error_message": f"Weather information for '{city}' is not available.", } root_agent = Agent( name="weather_time_agent", description=( "Agent to answer questions about the time and weather in a city." ), instruction=( "I can answer your questions about the time and weather in a city." ), tools=[get_weather, get_current_time], )

从源码看，tools参数是一个联合类型ToolUnion（Callable | BaseTool | BaseToolset），在 llm_agent.py 中定义，并由_convert_tool_union_to_tools（llm_agent.py）统一转换为BaseTool列表：

• 普通可调用对象 → 包装为FunctionTool；
• BaseTool实例 → 直接使用；
• BaseToolset→ 调用get_tools_with_prefix拉取工具集（MCP 工具集即走此路径）；
• BaseNode（含 Workflow）→ 包装为NodeTool，从而实现"把工作流/节点当作工具"的能力（但 Agent 本身不允许作为 NodeTool 包装，必须按子 Agent 方式调用）。

值得留意的是内置搜索工具在多工具场景下的自动适配逻辑：当 Agent 同时配置了多个工具时，GoogleSearchTool与VertexAiSearchTool会被自动替换为GoogleSearchAgentTool/DiscoveryEngineSearchTool包装，以规避内置工具与其他工具并用的限制（见 llm_agent.py 的注释与实现）。

用 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)], )

edges中的三元组("START", A, B)表示从入口节点START出发、依次执行 A 再执行 B。从 workflow/_workflow.py 可以看到，Workflow的edges字段在模型初始化阶段（model_post_init）会被编译为内部Graph（若未显式提供），max_concurrency用于限制图边触发的并行节点数（None表示不限；动态节点由父节点内联 await，不受此限制，以免死锁）。START等内置节点定义于 workflow/_base_node.py。更多编排样例（loop、retry、route、fan_out_fan_in、dynamic_nodes、nested_workflow、parallel_worker 等）见 contributing/samples/workflows，对应的多 Agent 组合示例见 contributing/samples/multi_agent。

本地运行：CLI 与 Web 开发 UI

Agent 定义完成后（建议放在独立的 agent 目录，内含agent.py），即可通过 ADK 命令行在本地驱动它：

# 交互式 CLI adk run path/to/my_agent # Web UI（支持多 Agent 目录，也可直接指向单个 Agent 文件夹） adk web path/to/agents_dir

adk run提供交互式对话体验，适合快速验证 Agent 行为；adk web则启动内置的 Web 开发界面，用于测试、评估、调试与展示 Agent。两者的 CLI 定义位于 src/google/adk/cli，其中 cli.py 实现了run的交互/单次执行逻辑，cli_tools_click.py 提供了web_options()等 Click 选项声明，Web 服务本体由 adk_web_server.py 与 dev_server.py 实现。

Development UI：内置的开发调试界面

README 特别介绍了内置的开发 UI：它帮助你在一个界面中测试、评估、调试并展示你的 Agent。下图即仓库 assets 中保存的 ADK Web 开发界面截图（README 中直接引用）：

从文件名与 README 的引用关系看，两张图分别展示了开发 UI 的主界面与工具（函数）调用视图——后者对排查"Agent 是否按预期调用工具、传参是否正确"尤其有用。Web UI 支持多 Agent 目录导航，也能直接指向单个 Agent 文件夹启动，与adk web命令的行为一一对应。

评估 Agent：adk eval

除调试外，ADK 还内置了评估（evaluation）能力，用评测集驱动 Agent 的自动化质量检验：

adk eval \ samples_for_testing/hello_world \ samples_for_testing/hello_world/hello_world_eval_set_001.evalset.json

adk eval接收两个核心参数：Agent 目录与评测集文件（.evalset.json）。评估相关的 CLI 入口在 cli_eval.py 与 cli_tools_click.py 的eval_options()/eval_set()中，评估框架本体位于 src/google/adk/evaluation，支持 LLM 裁判（llm-as-judge）、Rubric 评分、多轮任务成功率、工具使用质量、轨迹质量等多种评估器（对应 tests/unittests/evaluation 下的大量测试）。面向任务的评估指南见 docs/guides/evaluation（含 agent_evaluator、eval_config、eval_service 等子主题）。你也可以先在 contributing/samples/evaluation 中查看 basic_criteria、llm_judge_match、rubric_criteria 等评测集示例，再对照构造自己的评测文件。

部署：Docker 与 Cloud Run

ADK 提供一行命令式的部署能力，支持本地容器化与 Google Cloud 两种目标：

本地 Docker 部署

adk deploy docker --with_ui <agent-folder>

--with_ui会同时打包 Web UI，使部署后的服务自带可视化交互界面。

Cloud Run 部署

adk deploy cloud_run --with_ui <agent-folder>

部署命令支持环境变量注入，可以直接写在adk命令中，也可以放在.env文件中：

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

这里--env传入的GOOGLE_GENAI_USE_ENTERPRISE=1用于切换到 Gemini Enterprise 模式，实际生产环境可按需替换为其他运行时配置。部署器实现位于 src/google/adk/cli/deployers，其中 _docker_deployer.py 与 _cloud_run_deployer.py 分别对应两种目标，CLI 命令定义见 cli_deploy.py。此外，README 提到可通过 Vertex AI Agent Engine 实现无缝弹性扩展（对应google-cloud-aiplatform[agent-engines,evaluation]依赖），适合对规模化运行有要求的场景。

继续深入：文档、示例与 LLM 上下文

• 任务导向指南：官方提供了分主题的 walkthrough 文档，覆盖 agents、tools、events、plugins、workflows 等主题，见仓库内的 docs/guides（含 agents/config、workflow/graph、tools/mcp_tool、evaluation/agent_evaluator、auth/tool_auth 等条目）；
• 可运行示例：大量开箱即用的示例 Agent 集中在 contributing/samples，涵盖 core（hello_world、quickstart、function_tools、parallel_functions 等）、multi_agent、workflows、live（流式多模态）、integrations（BigQuery、MCP、GCS、Spanner、LiveKit 等）、evaluation 与 managed_agent 等多个方向，且多数带有 README 与测试；
• Agent Config（免代码构建）：如果你希望用声明式 YAML/JSON 而非 Python 定义 Agent，可参考 docs/guides/agents/config 与 contributing/samples/config 中的示例；
• Vibe Coding：仓库提供了面向 LLM 的上下文文件——llms.txt 为精炼摘要版，llms-full.txt 为完整信息版（适用于上下文窗口足够大的 LLM）。如果你希望通过"对话式编程"让 LLM 辅助开发 Agent，可直接把这两个文件作为上下文喂给模型；
• 社区生态：官方还维护了 adk-python-community 仓库，汇集社区贡献的工具、第三方服务集成与部署脚本，用于扩展 ADK 核心能力。

参与贡献与许可

• 代码贡献流程见仓库内的 CONTRIBUTING.md 与 AGENTS.md；
• 本项目采用Apache 2.0 许可证，详见 LICENSE；
• 核心依赖与元数据（包名google-adk、Python 版本要求、extras 分组）均可在 pyproject.toml 中查阅。

小结

ADK 2.0 的核心心智模型可以概括为一句话：用Agent定义"会做什么"，用Workflow定义"按什么顺序做"，用工具生态扩展"能调用什么"，再用 CLI/Web UI、评估与部署命令打通从开发到上线的全链路。本文基于 README.md 并结合仓库源码，覆盖了安装（含约束文件与扩展）、快速上手（Agent + Workflow）、本地运行（adk run/adk web）、评估（adk eval）与部署（Docker / Cloud Run）的完整流程。上手时建议从 contributing/samples/core/quickstart 这类最小示例开始，再逐步深入到 workflows 与 multi_agent 的图编排场景。

【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python