Skip to content

欢迎使用 ADK 2.0

ADK 2.0 引入了构建复杂 AI 智能体的强大工具，帮助你以更强的可控性、可预测性和可靠性来构建智能体以执行具有挑战性的任务。ADK 2.0 适用于 Python，包含以下关键特性：

  • 基于图的工作流：构建确定性的智能体工作流，对任务的路由和执行方式有更强的控制。

  • 动态工作流：使用基于代码的逻辑构建更复杂的工作流，包括迭代循环和基于决策的复杂分支。

  • 协作工作流：通过协调者智能体和多个子智能体协同工作，构建复杂的智能体架构。

查看上面链接的主题以获取更多信息，并尝试使用 ADK 2.0 构建智能体的新方法！

ADK Python v2.0.0 正式发布

ADK Python 2.0 已于 2026 年 5 月 19 日正式发布（GA）。

ADK Python 1.x 兼容性

ADK 2.0 旨在与 ADK 1.x 版本开发的智能体保持兼容。但在将 ADK 1.x 项目升级到 ADK 2.0 之前，你应注意一些破坏性变更。

破坏性变更：ADK Python 1.x 到 2.0 的不兼容问题

自 ADK Python v2.0.0 起引入了若干已知的不兼容性和破坏性变更。升级前请查看这些变更，并在必要时采取缓解措施。

ADK 2.0 版本引入了工作流运行时，将 ADK 从分层智能体执行器转变为基于图的执行引擎。在这种新架构中，你的智能体、工具和函数在工作流图中作为独立的节点进行评估。如果你从 ADK 1.x 升级，请查看以下破坏性变更和迁移步骤，以确保生产应用的平滑过渡。

事件模式与自定义会话数据库

ADK 2.0 在核心 Event 模式中引入了新字段 node_info 和 output，用于追踪图状态和工作流输出。

  • 自定义会话存储： 如果你实现了自定义的 BaseSessionService（例如使用固定列在 SQL 或 NoSQL 数据库中存储会话），你的底层数据库模式必须更新以容纳这些新字段。将 2.0 的 Event 插入到固定的 1.x 数据库表中会导致插入或 ORM 反序列化失败。但如果你自定义的会话服务将事件存储为序列化的 JSON blob，而不是映射到显式列，则无需更新你的模式。
  • 严格的 JSON 验证： 如果你的部署包含下游 API 网关、移动客户端或执行严格 JSON 模式验证（包括设置 additionalProperties: false）的 Web 前端，则在更新预期模式之前，验证将拒绝 2.0 事件。

迁移操作： 更新你的数据库模式和下游客户端验证器，使其在所有 Event 负载中包含并存储 node_info 和 output 字段。在将 2.0 会话写入共享数据库之前，确保所有读取应用已更新以处理 2.0 格式。

智能体执行：从 BaseAgent 到 BaseNode

在 ADK 1.x 中，智能体是独立的执行器。在 ADK 2.0 中，BaseAgent 类现在继承自 BaseNode。智能体现在在新的 Workflow Graph 引擎中作为独立的节点进行评估。

  • 执行驱动自定义覆盖： ABC 契约已更改。1.x 抽象方法（如 _run_async_impl() 或 generate_content()）的自定义覆盖不再是驱动执行的正确方式。Workflow Graph 引擎完全绕过了这些旧版覆盖。如果你通过覆盖这些方法注入自定义遥测或状态管理，这些调用将被静默忽略。

迁移操作： 将自定义执行逻辑移出 run() 覆盖。改用标准化的 BeforeAgentCallback 和 AfterAgentCallback 接口，以安全地将自定义逻辑注入执行生命周期。

上下文与回调：原地变更

绕过框架手动追加事件不再安全。

  • 直接追加事件： 在 ADK 1.x 中，一些开发者通过 context.session.events.append(custom_event) 强行向会话追加事件。在 ADK 2.0 中，工作流运行器需要严格控制事件发射以管理状态、图路由和流式传输。手动追加到会话列表会绕过图引擎并破坏确定性。

迁移操作： 不要直接向会话追加事件，也不要直接使用 enqueue_event。你现在必须从节点或智能体内显式地 yield 事件，以便框架原生管理其持久化、路由和流式传输。

错误处理与自动重试

ADK 2.0 框架现在会自动捕获异常以实现自动重试、遥测和人在回路（HITL）暂停。

  • Try...except 和 BaseException： 在 ADK 1.x 中，框架没有原生的自动重试机制，因此开发者经常在工具内部编写手动的 try...except 循环来防止崩溃。在 ADK 2.0 中，如果你迁移工具并留下宽泛的 except Exception: 块，这段代码会向框架掩盖失败，从而永久禁用该步骤新的 2.0 自动重试机制。此外，捕获 BaseException 会无意中捕获 NodeInterruptedError，从而破坏框架暂停工作流以进行人在回路（HITL）输入的能力。

迁移操作： 允许标准异常从你的工具中传播出去，以便框架根据你配置的 RetryConfig（例如 RetryConfig(max_attempts=3)）进行评估。除非你显式地重新抛出异常，否则永远不要捕获 BaseException。

如果你遇到其他 ADK 1.0 到 ADK 2.0 的不兼容问题，请通过问题追踪器报告。

安装 ADK Python 1.x

如果你想更新 ADK 但尚未准备升级到 ADK 2.0，请确保在安装时指定 ADK 版本，或使用兼容性发布 ~= 运算符，如下所示。ADK 1.0 有以下系统要求：

  • Python 3.10 或更高版本
  • pip 21.0 或更高版本

按照以下步骤安装最新版本的 ADK 1.x：

  1. 使用 pip 的兼容性发布 ~= 运算符安装 ADK 1.x 的包：

    pip install "google-adk~=1.0"
推荐：创建并激活 Python 虚拟环境

创建 Python 虚拟环境：

python3 -m venv .venv

激活 Python 虚拟环境：

.venv\Scripts\activate.bat

.venv\Scripts\Activate.ps1

source .venv/bin/activate

下一步

阅读开发指南，了解如何使用 ADK 2.0 特性构建智能体：

查看这些 ADK 2.0 代码示例以进行测试并获取灵感：

感谢你对 ADK 2.0 的关注！我们期待你的反馈！