适用于MongoDB Atlas Agent Engine SDK 的 Google ADK 2 适配器。
该适配器在 AER模式下仅具有持久性。在 agent.yaml 中设置 features.durable_workflow: true。省略或 false 不会回退到原生ADK 会话；第一次调用失败。编排引擎拥有交叉回合状态并将其提供给每次尝试；该适配器不维护单独的 ADK 会话数据库。拓扑结构背后的平台概念、支持和身份规则限制如下： 持久工作流。 Atlas Agent Engine ctx.resume 不是 ADK检查点恢复。并行 ADK 路由可能会一起暂停；适配器通过运行器静止收集它们，并提交一个原子 OE 等待边界。一旦该边界得到解答，就会提交其步骤，并且 ADK 可能会继续进入另一个串行或并行边界。
暂停和恢复
作者使用官方构造函数 `FunctionTool(..., require_confirmation=True) < 在代理构建器中编写原生ADK 等待。 https://adk.dev/graphs/Human-input/#tool-confirmation-approval-prompts-in-llm-agents >`__ 和 LongRunningFunctionTool。传递 app.tools() 中的可调用对象，而不是原始 @app.tool 函数：@app.tool 仅注册工具； app.tools() 会应用Atlas Agent Engine 安全包装器。 Atlas Agent Engine 将每次等待记录为一个 OE 活动，并在一个命令中最终确定完整的边界。 Atlas Agent Engine 中断 ID 是那些活动 ID，而不是 ADK 函数调用 ID。继续需要一个完整的 resume_map；这是一次新的尝试，再次遍历原始用户消息； OE 返回已记录的回答；适配器向 ADK 提供批处理由本次运行的函数调用 ID 键入的 FunctionResponse 部分。没有Atlas助手引擎 app.suspend()。确认回答是 ADK 的 {confirmed: true|false}对象。 RequestInput回答是 ADK 的 FunctionResponse.response 字典接受的任何内容： JSON对象或适配器包装为 {result: ...} 的非空标量/大量。 JSON null 不是回答。
attempt 1: original message → ADK runs to quiescence → OE frontier 1 SUSPENDED attempt 2: replay frontier 1 → COMPLETED → commit step 1 → continue ADK → frontier 2 SUSPENDED attempt 3: replay step 1 → replay frontier 2 → COMPLETED → commit step 2 → continue
网站 | 角色 |
|---|---|
|
|
| 稳定的公共 ADK 运行程序和不可变的 |
| 绑定 OE 尝试，重建原始消息，并识别当前恢复边界 |
| 遍历 |
| 继续遍历已解决的边界，直到下一个新的等待或完成 |
| 将规范 ADK节点路径绑定到共享持久性操作路径 |
| 在其规范父路径下保留已配置的子代理传输 |
| 原生等待映射到一个有序边界并构建响应批处理 |
| 以原子方式完成所有等待，并按持久性位置匹配 OE 结果 |
|
|
| Prefix LLM 和工具是Atlas Agent Engine 活动，因此继续不会重新运行这些副作用 |
该适配器接受 ADK BaseAgent 或 ADK 2 Workflow。 ADK 未定义 LangGraph 样式的超级步生命周期。因此， Atlas助手引擎仅在静态协调边界引入步骤：该边界中的所有等待都以原子方式加入，已解析的边界提交其步骤，下一个 Runner.run_async 延续开始下一步。
工作流和代理路径
ADK 通过不同的配置 API 公开 Workflow 组合和代理协作，但配置的执行在相同的运行时基元中满足：工作流节点和代理都是 BaseNode 实例，ADK 为每次运行分配一个规范 Context.node_path。适配器将该一条路径映射到 OE 操作路径；它不会从模型文本或会话事件中重建代理祖先。
持久性适配器在构建应用程序时需要完整的工作流和代理拓扑结构。这与持久性LangGraph图表适配器具有相同的静态拓扑约束：在外部工作开始后，任意运行时控制流都不能被视为持久性图表边界。
ADK功能 | 持久支持 |
|---|---|
普通 | 受支持 |
静态配置的 | 受支持 |
嵌套串行和并行 | 受支持 |
由 | 受支持 |
具有已配置传输的工作流代理节点 | 当所属代理使用以下项时支持 |
公共 | 执行前被拒绝；使用已配置的 |
对已配置节点内的模型、工具和等待活动进行建模 | 受支持 |
应用程序创建的节点在运行时传递给 | 在动态子项运行前被拒绝 |
| 在其子级运行之前被拒绝 |
运行时创建的目标传递给 | 在动态子项运行前被拒绝 |
普通 | 支持；在父模型运行之前，已解析的 |
在运行节点之前，ADK 会为其分配规范的 Context.node_path。 ADK 使用相同的值进行工作流簿记，并在发出的事件上将其记录为 Event.node_info.path。适配器封装公共 BaseNode.run 边界，以便模型和工具活动准入可以在事件存在之前使用该路径。
ADK node path: outer@1/inner@1/review@1 OE path: agent -> inner -> review
配置的 ADK 根 (outer@1) 映射到 OE 的现有 agent 根。剩余的段成为子边界，它们的完整 ADK 前缀仍然是出现键：
inner occurrence: outer@1/inner@1 review occurrence: outer@1/inner@1/review@1
对于并行 left 和 right，每个节点包装器在请求本地上下文中绑定自己的规范路径，因此完成顺序无法交换它们的 OE 身份。 review 调用的工具会继承 review 作用域。如果 review 发出等待，则在活动节点作用域结束后，其事件会携带相同的路径，并且暂停会记录相同的边界。不同工作流祖先下的相同叶名称保持不同，因为标识来自完整路径，而不是全局名称查找。格式不正确的节点路径和没有节点路径的等待事件显式失败。
配置的子代理
传输是对已配置的 sub_agents 边缘的运行时选择。模型响应会告诉 ADK 要运行哪个子进程，但适配器会等待 ADK 输入该子进程，并使用 ADK 分配给执行的规范路径。示例：
configured: router -> reviewer -> specialist ADK path: router@1/reviewer@1/specialist@1 OE path: agent -> reviewer -> specialist
重复传输会收到新的 ADK运行ID。当 ADK 进入时，适配器会保留所选的子边界，因此对 specialist 的两次访问会成为 specialist 序数词 1 和 2，即使配置相同的代理对象两次运行也是如此。
支持将已配置的代理树作为应用程序根或在工作流节点内。拥有 sub_agents 的工作流程代理必须显式使用 mode="chat"。否则，ADK 会将该节点默认为 single_turn，这会在代理内部运行传输一次，然后从包含的工作流再次运行传输。适配器在持久会话构造期间拒绝该生命周期，而不是允许重复的子效果。在本地开发中，在模型或工具活动启动之前，此错误会出现在第一次 Playground 调用时。
在聊天模式下，每次配置的传输都保留在 ADK 的一个公共节点生命周期中。在模型、工具或暂停活动开始之前，适配器会绑定完整的规范节点路径，包括工作流祖先和活动代理链。 ADK 在进入工作流时克隆代理节点，因此路由安装在公共 BaseNode.run 边界上，并通过请求本地适配器状态进行选择。配置的模板仅包含 ADK 复制到其克隆中的不透明来源，从而允许适配器拒绝在运行时动态创建的同名、同类型节点。
恢复时，缓存的已配置传输会留在 ADK 的传输循环内，并且已解析的等待传输目标会运行直至完成。这会保留最终的代理响应，而不是将原始恢复值公开为工作流输出。
代理协作树可以从嵌套、串行或并行工作流图表中任何静态配置的代理节点开始。不允许通过 Context.run_node() 动态创建的代理或其他节点；那些在执行开始之前仍被拒绝的情况。
agent root: router agent -> reviewer -> specialist composed: outer Workflow -> router agent -> reviewer -> specialist
传输保留在以该工作流节点为根的已配置代理树内，并受 ADK 的代理传输规则约束；工作流不是传输目标。当代理树完成时，控制权将返回到工作流调度程序，并继续沿着配置的图表前进。
AgentTool 故意位于此功能之外。 ADK 通过私有 Runner 运行其子进程，因此子进程不会继承调用者的规范节点路径或外部等待边界。支持该生命周期需要一个单独的持久性桥接器；当前适配器在执行之前失败，而不是推断路径。
回合级倒带
App.runner 是Atlas Agent Engine 的稳定公共 ADK 运行器。其 rewind_async() 方法保留 Google 记录的参数名称，并将 rewind_before_invocation_id 直接映射到 OE 会话分支：
branch = await app.runner.rewind_async( user_id="user-1", session_id="session-1", rewind_before_invocation_id="execution-3", )
一次 ADK 调用相当于一次 OE 执行，因此倒带目标仅是整圈。该调用必须在活动的持久性调用内运行，并且 session_id 必须命名该调用的会话。 SDK 通过 OE 的现有执行回调路由发送当前执行ID 。 OE 加载该执行以派生其组织、 项目、 Workspace 和 session ；客户端不会发送这些坐标或尝试凭证。执行ID与流、工具结果和执行程序回调具有相同的角色：它路由已经在工作负载到 OE回调信任边界内的请求，并且不是公共管理档案。在一个ACID 事务中，OE 会验证该执行是否仍具有活动的持久性租约，解析要在同一会话中排除的第一个执行，并将前一回合的终止状态复制到新的休眠会话中。要在祖先会话中倒带，请调用该祖先会话并直接请求其分叉；子会话不会继承修改祖先历史记录的权限。响应包含新的 session_id 和待处理的 execution_id；该会话上的下一个普通调用使用替换用户请求声明挂起的执行。
这是有意延长 ADK 的返回合同。原生 ADK 会更改指定会话并返回 None； Atlas Agent Engine 保持该会话不可变并返回 SessionForkResponse，以便调用者可以继续使用新的 session_id 和 execution_id。方法名称和参数仍然是 ADK 记录的接口，但 app.runner 是Atlas助手引擎拥有的类型，具有正确的返回注解。 Google 的 Runner 仍然是私有的、尝试范围内的执行细节。普通轮仍通过平台调用接口进入；公共运行器不会创建备用执行路径。
该适配器不会扫描 ADK 事件、保留执行目录、计算步骤序数、提交快照字节或选择分支键。在第一个回合之前倒回、命名事件ID 或定位另一个会话拥有的回合都会失败。在活动的持久性调用之外调用 rewind_async() 也会失败；不支持乱序管理倒带。每次重试都是一个新的分支请求；没有客户端幂等键。
快速入门
安装
pip install agent-engine-sdk-adk
或者在 uv项目中：
uv add agent-engine-sdk-adk
开发中
要求
Python >= 3.11
Google ADK >= 2.4.0, < 3
开发设置
uv sync --extra dev
测试
./scripts/test.sh agent-engine-sdk-adk
存储库拥有的套件同步工作区包，并使用与 CI 相同的路径运行 Ruff、Pyright 和 pytest。
2026 MongoDB, Inc. 版权所有。根据Apache许可证版本 2.0 获得许可。