欢迎使用 ADK 2.0¶

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

• 基于图的工作流：构建确定性智能体工作流，更好地控制任务的路由和执行方式。
• 动态工作流：使用基于代码的逻辑构建更复杂的工作流，包括迭代循环和基于复杂决策的分支。
• 协作工作流：构建具有协调者智能体和多个共同工作的子智能体的复杂智能体架构。

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

ADK Python 1.x 兼容性¶

ADK 2.0 设计为与使用 ADK 1.x 版本开发的智能体兼容。但是，在将 ADK 1.x 项目升级到 ADK 2.0 之前，有一些破坏性变更需要注意。

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

事件 Schema 与自定义会话存储¶

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

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

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

智能体执行：BaseAgent 到 BaseNode¶

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

• 执行驱动自定义覆写： 抽象基类契约已发生变化。1.x 抽象方法的自定义覆写（如 _run_async_impl() 或 generate_content()）不再是驱动执行的正确方式。工作流图引擎完全绕过这些遗留覆写。如果你通过覆写这些方法注入自定义遥测或状态管理，这些调用将被静默忽略。

迁移操作： 将自定义执行逻辑从 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 Python 1.0 到 ADK 2.0 的不兼容问题，请通过问题追踪器报告。

安装 ADK Python 1.x¶

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

• Python 3.10 或更高版本
• pip 用于安装包

要安装最新版本的 ADK 1.x，请按以下步骤操作：

1. 启用 Python 虚拟环境。请参阅下方的说明。

2. 使用 pip 并通过兼容版本 ~= 操作符安装 ADK 1.x 的包：

   pip install "google-adk~=1.0"
   

python3 -m venv .venv

.venv\Scripts\activate.bat

.venv\Scripts\Activate.ps1

source .venv/bin/activate

ADK Go 1.x 兼容性¶

ADK Go 2.0 设计为与使用 ADK Go 1.x 版本开发的智能体兼容。但是，在将 ADK Go 1.x 项目升级到 ADK Go 2.0 之前，有一些破坏性变更需要注意。

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

模块导入路径¶

ADK Go 2.0 使用新的主版本模块路径。你必须更新 Go 源文件和 go.mod 文件中的所有导入路径。

• 1.x 导入路径： google.golang.org/adk
• 2.0 导入路径： google.golang.org/adk/v2

迁移操作： 运行 go get google.golang.org/adk/v2，并将源文件中所有导入语句从 google.golang.org/adk/... 更新为 google.golang.org/adk/v2/...。

智能体执行：Agent 接口变更¶

在 ADK Go 1.x 中，智能体通过提供 Run 方法来实现 agent.Agent 接口。在 ADK Go 2.0 中，智能体在新的工作流图引擎中作为单独的节点进行评估。

• 执行驱动自定义覆写： 覆盖内部执行行为的自定义智能体类型可能不再按预期工作。工作流图引擎管理执行调度和事件发出，绕过这些机制的自定义实现将被静默忽略。

迁移操作： 将自定义执行逻辑移入标准化的 BeforeAgentCallback 和 AfterAgentCallback 钩子中，安全地将自定义逻辑注入执行生命周期。

事件构造：session.NewEvent 签名变更¶

session.NewEvent 现在需要 context.Context 作为第一个参数：

// 之前（ADK Go 1.x）
ev := session.NewEvent(ctx.InvocationID())
// 或
ev := session.NewEventWithContext(ctx, ctx.InvocationID())

// 之后（ADK Go 2.0）
ev := session.NewEvent(ctx, ctx.InvocationID())

事件 ID 和时间戳现在通过 platform 包获取，因此安装在 ctx 上的时间或 UUID 提供者会控制它们。这使得工作流引擎能够产生确定性的、可重放的安全事件。之前的无参数上下文形式和临时的 NewEventWithContext 辅助函数已被移除。

迁移操作： 将当前作用域中的 context 作为第一个参数传递给 session.NewEvent。任何 context.Context 都可以使用——智能体、工具或回调的 ctx（它们都嵌入了 context.Context）、请求上下文，或者在测试中使用 t.Context()。如果调用 NewEvent 的辅助函数尚未接收 context，请添加 ctx context.Context 参数并从调用者处向下传递。避免在调用链中间创建新的 context.Background()；仅在 main、init 和顶层测试设置中使用它。

事件 Schema 与自定义会话存储¶

ADK Go 2.0 向核心 Event 结构体添加了五个新字段，以支持图路由、工作流状态和人机协作暂停：

• 自定义会话存储： 如果你实现了自定义的 session.Service，例如使用固定 schema 将会话存储在自己的 SQL 或 NoSQL 数据库中，则必须更新底层数据库 schema 以容纳所有五个新字段。将 2.0 的 Event 插入 1.x 的固定数据库表中会导致插入或反序列化失败。但是，如果你的自定义会话服务将事件存储为序列化的 JSON blob，则不需要更新 schema。

迁移操作： 更新你的数据库 schema 和下游客户端验证器，使其能够在所有 Event 负载中接收并存储这五个新字段。请特别注意 Routes、RequestedInput 和 Output，它们没有 JSON 结构体标签，因此会按照上面显示的 Go 字段名称进行序列化。

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

安装 ADK Go 1.x¶

如果你想继续使用 ADK Go 1.x，但尚未准备好升级到 ADK Go 2.0，请将依赖固定到 1.x 版本线：

go get google.golang.org/adk@v1

下一步¶

阅读使用 ADK 2.0 功能构建智能体的开发者指南：

• 基于图的工作流
• 协作智能体
• 动态工作流

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

感谢你关注 ADK 2.0！我们期待你的反馈——请在 ADK Go 或 ADK Python 上告诉我们。