MongoDB Atlas Agent Engine SDK 用の Google ADK 2 アダプター。
アダプターは、 AERモードで 耐久性 のみです。features.durable_workflow: true agent.yamlでfalse を設定します。省略した場合、または はネイティブの ADK セッションに戻りません。最初の呼び出しは失敗します。オーバーライド エンジンはクロスタームの状態を所有し、それを各試行に提供します。アダプターは別の ADK セッションデータベースを維持しません。以下のトポロジー制限の背後にあるプラットフォームの概念、有効化、ID ルールは耐久性のあるワークフローです。 Atlas エージェント エンジンctx.resume は ADKチェックポイント再開ではありません。並列 ADK ルートはまとめて一時停止する可能性があります。アダプターは ドライバーの休止段階 でそれらを収集し、1 つのアトミックな OA 待機するとコミットします。そのフレイテンシが応答されると、そのステップはコミットされ、ADK は別のシリアル または並列フされるまで続行できます。
一時停止と再開
作成者は、公式のコンストラクターを使用してエージェントビルダでネイティブ ADK`FunctionTool(..., require_confirmation=True) 待機を組み合わせます。 https://adk.ev/graphs/人間 の入力/#tool-confirm生の LongRunningFunctionToolapp.tools()関数ではなく、@app.tool からの呼び出し可能値を渡します。@app.tool はツールのみを登録します。app.tools() は、Atlas Agent セキュアラッパー を適用するものです。 Atlas エージェント エンジンは、各待機を 1 つの OA アクティビティとして記録し、1 つのコマンドで完全なフレイリーを終了します。 Atlas Agent Engine の割り込み ID は、ADK 関数呼び出し ID ではなく、それらのアクティビティ ID です。続行には完全な が 1 つ必要です。元のユーザーresume_map メッセージを再度ウォークスルーする新しい試行であるため、 OA は記録された応答を返します。アダプターは、この実行の関数呼び出し ID でキー付けされたFunctionResponse 部分の ADK 1バッチするをフィードします。 Atlas エージェント エンジンapp.suspend() はありません。確認応答は、ADK の{confirmed: true|false} オブジェクトです。 RequestIn put の結果は、ADK のFunctionResponse.response ディレクティブに受け入れられるものであれば、 JSONオブジェクト、またはアダプターが としてラップする null{result: ...} 以外のスカラーや配列でもかまいません。 JSONnull は応答ではありません。
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 ランサーと不変の |
| UE の試行をバインドし、元のメッセージを再ビルドし、現在の再開フレイターを特定する |
|
|
| 次の新しい待機または完了まで、解決されたフレイテンシを通過します。 |
| 標準の ADKノードパスを共有永続操作パスにバインド |
| 標準の親パスで構成されたサブエージェントの転送を予約する |
| ネイティブの待機時間を 1 つの順序付けされたフロン階層にマッピングし、応答バッチするを構築します |
| すべての待機をアトミックに終了し、耐久性のある位置で OA の結果を一致させます |
|
|
| プレフィックス LM とツールは Atlas エージェント エンジンのアクティビティであるため、それらのサイド 効果は再実行されません |
アダプターは、ADK BaseAgent または ADK 2 Workflow のいずれかを受け入れます。 ADK では、LingGraph 形式のスーパーステップのライフサイクルは定義されません。したがって、Atlas Agent Engine は、 休止状態の整合性の最前線にのみ ステップを導入します。その最上位のすべての待機者はアトミックに結合され、解決されたフ権はそのステップをコミットし、次の Runner.run_async の継続によって次のステップが開始されます。
ワークフローとエージェントのパス
ADK はさまざまな構成 API を通じて Workflow 構成とエージェントのコラボレーションを公開しますが、構成された実行は同じランタイム プリミティブを満たすため、ワークフロー ノードとエージェントの両方が BaseNode インスタンスであり、ADK はそれぞれの実行に 1 つの標準的な Context.node_path を割り当てます。アダプターは、その 1 つのパスを UE操作パスにマッピングします。モデル テキストまたはセッション イベントからエージェントの祖先を再構築することはありません。
耐久性のあるアダプターには、アプリケーション構築時に完全なワークフローとエージェントのトポロジーが必要です。これは耐久性のある LingGraphグラフアダプターと同じ静的トポロジーの制約です。任意のランタイム制御フローは、外部作業がすでに開始されていると、永続的なグラフ境界として扱われません。
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）は、UE の既存の agent ルートにマッピングします。残りのセグメントは子境界になり、完全な ADK プレフィックスは発生キーのままになります。
inner occurrence: outer@1/inner@1 review occurrence: outer@1/inner@1/review@1
並列leftと right の場合、各ノードラッパーはリクエスト ローカル コンテキストで独自の標準パスをバインドするため、完了順序は OA 識別子を交換できません。 review によって呼び出されるツールは review スコープを継承します。 review が待機を発行する場合、そのイベントは同じパスを渡し、ライブノードの範囲が終了した後に停止は同じ境界を記録します。異なるワークフローの祖先の下の等価リーフ名は、異なる状態であり、ID はグローバル名検索ではなく完全パスから取得されるためです。不正なノードパスと、ノードパスのない待機イベントは明示的に失敗します。
構成済みのサブエージェント
転送は、すでに構成された 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 への 2 回の訪問は、同じ構成のエージェントオブジェクトが両方回実行される場合でも、specialist 序数 1 と 2 になります。
構成されたエージェントツリーは、アプリケーションルート または ワークフローノード内でサポートされます。 sub_agents を所有するワークフローエージェントは、mode="chat" を明示的に使用する必要があります。それ以外の場合、そのノードはデフォルトで single_turn に設定されます。これにより、エージェント内で一度に転送が実行され、その後が含まれるワークフローから再度転送が実行されます。アダプターは、重複する子影響を許可するのではなく、永続的セッションの構築中にそのライフサイクルを拒否します。ローカル開発では、モデルまたはツールのアクティビティが開始される前に、最初のプレイグラウンド呼び出しにこのエラーが表示されます。
チャットモードでは、構成されたすべての転送は ADK の 1 つのパブリックノードライフサイクルに残ります。アダプターは、モデル、ツール、または停止アクティビティが開始される前に、ワークフロー祖先やアクティブなエージェントチェーンを含む完全な標準ノードをバインドします。 ADK はワークフローに入るときにエージェントノードをクローンするため、ルーティングはパブリック BaseNode.run 境界にインストールされ、 リクエストのローカル アダプター状態を通じて選択されます。構成されたテンプレートは、ADK がクローンにコピーする不変のの出所のみを保持するため、アダプターは実行時に動的に作成された同じ名前の同じタイプのノードを拒否できます。
再開すると、キャッシュされた構成済みの転送は ADK の転送ループ内に残り、解決された待機中の転送ターゲットは完了まで実行されます。これにより、未加工の再開値がワークフロー出力として公開されるのではなく、最終的なエージェント応答が保持されます。
エージェントコラボレーション ツリーは、ネストされたシリアル、シリアル、または並列の ワークフローグラフ内の静的に構成されたエージェントノードから開始できます。ただし、Context.run_node() を通じて動的に作成されたエージェントやノードは許可されません。これらは実行が開始される前に拒否されたままです。
agent root: router agent -> reviewer -> specialist composed: outer Workflow -> router agent -> reviewer -> specialist
転送は、 ADK のエージェント転送ルールに従って、その ワークフローノードをルートに構成されたエージェントツリー内に残ります。ワークフローは転送ターゲットではありません。エージェントツリーが終了すると、制御はワークフロー スケジューラーに戻り、構成されたグラフに沿って続行します。
AgentTool は、この機能の外部で意図的に使用されています。 ADK はプライベート オーナーを介して子を実行するため、子は呼び出し元の標準ノードパスまたは外部待機ドライバーを継承しません。そのライフサイクルをサポートするには、別の耐久性のあるブリッジが必要です。パスを推測する代わりに、現在のアダプターは実行前に失敗します。
タームレベルの巻き戻す
App.runner は、Atlas Agent Engine の安定版パブリック ADK ランサーです。そのrewind_async() メソッドは、Google のドキュメント化された引数名を保持し、rewind_before_invocation_id を OA セッション ブランチに直接マッピングします。
branch = await app.runner.rewind_async( user_id="user-1", session_id="session-1", rewind_before_invocation_id="execution-3", )
1 回の ADK 呼び出しは 1 回の OA の実行であるため、リビルドは 1 回の 回全体のみを対象とします。呼び出しはアクティブな永続呼び出し内で実行される必要があり、session_id はその呼び出しのセッションに名前を付ける必要があります。 SDK は、UE の既存の実行コールバック ルートを通じて現在の実行IDを送信します。 UE は、組織、プロジェクト、ワークスペース、およびセッションを生成するためにその実行を負荷します。クライアントはそれらの座標を送信したり、認証情報を試行したりしません。実行ID は、ストリーム、ツール結果、および実行プログラムのコールバックと同じロールを持ちます。このロールはリクエストをすでにワークロードから OA へのコールバックの信頼境界内にルーティングし、公開管理認証情報ではありません。 1 つのトランザクションで、UE は実行にまだアクティブな耐久性があることを確認し、同じセッションで除外する最初の実行を解決し、前のオンのターミナル状態を新しい休止セッションにコピーします。祖先セッションでタームを繰り返すには、その祖先セッションを呼び出し、その祖先セッションを直接リクエスト。子セッションは、祖先履歴を変更する権限を継承しません。レスポンスには新しい session_id と保留中の execution_id が含まれています。そのセッションでの次の通常の呼び出しは、置換ユーザーのリクエストで保留中の実行をクレームします。
これにより、ADK の返却契約が意図的に延長されます。ネイティブ ADK は指定されたセッションをミューテーションし、None を返します。 Atlas Agent Engine はそのセッションを不変に維持し、SessionForkResponse を返すため、呼び出し元は新しい session_id と execution_id を引き続き使用できます。メソッド名と引数は ADK のドキュメント化されたインターフェースのままですが、app.runner は正しい 戻り注釈 を持つ Atlas Agent Engine が所有する型です。 Google の Runner は、プライベート的な試行スコープの実行詳細のままになります。通常の は引き続きプラットフォーム呼び出しインターフェースを介して入力します。パブリック ランサーは代替実行パスを作成しません。
このアダプターは、ADK イベントをスキャンしたり、実行カタログを保持したり、ステップ数を計算したり、スナップショット バイトを送信したり、ブランチ キーを選択したりしません。最初のラウンドの前の巻き戻す、イベントID を指定する、または別のセッションが所有するタームをターゲットにするは失敗します。アクティブな永続呼び出し外で rewind_async() を呼び出す方法も失敗します。アウトバウンド管理ロールはサポートされていません。各再試行は新しいブランチリクエストです。クライアントの冪等性キーはありません。
クイック スタート
インストール
pip install agent-engine-sdk-adk
または ucプロジェクトの場合は次のようになります。
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 と同じパスを使用して Riff
コピーライト 2026 MongoDB, Inc. Apacheライセンス、バージョン 2.0 に基づいてライセンスされています。