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

Agent Development KitADK2.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 源码系统讲解 ADKAgent Development Kit2.0 的核心能力与上手路径从安装配置、Agent/Workflow两大核心类的代码优先开发到本地运行CLI 与 Web 开发 UI、自动化评估与 Docker/Cloud Run 部署的完整闭环。读完本文你将掌握用 ADK 快速搭建带工具调用的单 Agent 与图编排多 Agent 应用并理解其 2.0 版本相对 1.x 的关键变化与底层实现原理。ADK 是什么一套代码优先的 Agent 开发框架Agent Development KitADK是一个开源、模块化的 Python 框架将软件开发工程实践引入 AI Agent 的创建过程帮助开发者从简单任务到复杂系统地构建、编排与部署 Agent 工作流。根据 README.md 的定位ADK 在设计上遵循四条原则代码优先Code-FirstAgent 的逻辑、工具与编排方式直接以 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 的功能模块非常完整agentsAgent 实现、workflow图编排引擎、tools工具生态、events事件模型、sessions会话存储、evaluation评估体系、flowsLLM 流程、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基于图的执行引擎用于编排确定性的执行流支持路由routing、扇出/扇入fan-out/fan-in、循环loops、重试retry、状态管理、动态节点、人机协同HITL与嵌套工作流Task API结构化的 Agent 间任务委派支持多轮任务模式、单轮受控输出、混合委派模式、人机协同以及将任务型 Agent 作为工作流节点模块化多 Agent 系统通过组合多个专职 Agent 构建灵活的分层体系支撑可扩展应用丰富工具生态预置工具、自定义函数、OpenAPI 规范、MCP 工具并与 Google 生态深度集成代码优先开发Agent 逻辑、工具、编排全部用 Python 直接定义Agent Config不写代码也能构建 Agent声明式配置方式工具确认Tool Confirmation人机协同确认流程可对工具执行设置显式确认与自定义输入随处部署容器化部署到 Cloud Run或通过 Vertex AI Agent Engine 弹性扩展其中 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.103.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 组织a2aA2A 协议支持、agent-identityGoogle 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 githttps://github.com/google/adk-python.gitmain开发版直接从最新提交构建包含最新的修复与特性但可能包含实验性变更或尚未修复的缺陷建议仅用于验证新特性或提前获取关键修复。快速上手Agent 与 WorkflowREADME 给新手划出了重点ADK 应用由两个核心类构成——Agent定义 AI 的指令、工具与行为与Workflow以图流程编排 Agent 与任务。定义一个最小 Agentfrom google.adk import Agent root_agent Agent( namegreeting_agent, modelgemini-2.5-flash, instructionYou 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: fWeather information for {city} is not available., } root_agent Agent( nameweather_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参数是一个联合类型ToolUnionCallable | BaseTool | BaseToolset在 llm_agent.py 中定义并由_convert_tool_union_to_toolsllm_agent.py统一转换为BaseTool列表普通可调用对象 → 包装为FunctionToolBaseTool实例 → 直接使用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( namegenerate_fruit_agent, instructionReturn the name of a random fruit. Return only the name., ) generate_benefit_agent Agent( namegenerate_benefit_agent, instructionTell me a health benefit about the specified fruit., ) root_agent Workflow( nameroot_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 开发 UIAgent 定义完成后建议放在独立的 agent 目录内含agent.py即可通过 ADK 命令行在本地驱动它# 交互式 CLI adk run path/to/my_agent # Web UI支持多 Agent 目录也可直接指向单个 Agent 文件夹 adk web path/to/agents_diradk 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命令的行为一一对应。评估 Agentadk eval除调试外ADK 还内置了评估evaluation能力用评测集驱动 Agent 的自动化质量检验adk eval \ samples_for_testing/hello_world \ samples_for_testing/hello_world/hello_world_eval_set_001.evalset.jsonadk 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 RunADK 提供一行命令式的部署能力支持本地容器化与 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_ENTERPRISE1 agent-folder这里--env传入的GOOGLE_GENAI_USE_ENTERPRISE1用于切换到 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涵盖 corehello_world、quickstart、function_tools、parallel_functions 等、multi_agent、workflows、live流式多模态、integrationsBigQuery、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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考