AI エージェント向け: ドキュメントインデックスは https://www.mongodb.com/ja-jp/docs/llms.txt で利用できます。すべてのページの markdown バージョンは、いずれかの URL パスに .md を追加することで利用できます。

Google ADKでエージェントをビルドする

このガイドでは、Google Agent Development Kit (ADK) を使用してエージェントをビルドし、実行する方法を学びます。agent-engine-sdk-adk パッケージは、ADK と MongoDB Atlas エージェント エンジンの間のアダプターです。このアダプターは、ADK エージェント、ワークフローノード、ツールを呼び出すことを、プラットフォームのオーケストレーションエンジンが実行するおよびレコードする操作に変換します。

アダプターは耐久性があるため、ADKエージェントは耐久性のあるワークフローモードで実行されます。各セッションの状態を保存するのはADKではなく、Orchestration エンジンです。プラットフォームは、各モデル呼び出しとツール呼び出しの結果も保存します。再開された実行は、実行アクションを繰り返すのではなく、記録された結果を再生します。

Google ADKの検討事項

Atlas エージェント エンジン上でADKエージェントをビルドする際は、以下の重要な点に留意してください。

  • Google ADK SDKはPythonでのみ利用可能です。TypeScriptでエージェントをビルドするには、TypeScript SDKガイドを参照してください。

  • エージェントは、agent.yamlファイルでfeatures.durable_workflow値をtrueに設定する必要があります。このフィールドを省略するか、falseに設定すると、最初の呼び出しは失敗します。agent.yamlファイルで使用可能なフィールドの詳細については、エージェント.yamlスキーマを参照してください。

  • agent-engine-sdk-adkパッケージは、エージェントのルートとしてADK BaseAgentまたはADK 2 Workflowのいずれかを受け入れます。

前提条件

開始する前に、以下の前提条件を満たしていることを確認してください。

  • Python 3.11 以降。

  • uv パッケージ マネージャー。

  • agentengine CLIがインストールされ、認証されました。方法を学ぶには、「プロジェクトの作成」を参照してください。

  • Google ADK バージョン 2.9.0 以降。ADKのインストール方法を学ぶには、ADKインストールガイドをご覧ください。

  • LLMプロバイダーのAPIキー。agentengine createコマンドはキーの入力を求め、それをLLM_API_KEYとして.envファイルに保存します。

手順

1

ADKスターターテンプレートからプロジェクトを作成します。

ADKテンプレートのいずれかを使用して agentengine create コマンドを実行します。

agentengine create --template hello-world-agent-adk

hello-world-agent-adk テンプレートは、最小限のエージェントを作成します。insurance-agent-adk テンプレートは、保険ドメインのエージェントを作成します。利用可能なすべてのテンプレートと agentengine create コマンドオプションについて学ぶには、「サポートされているテンプレート」を参照してください。

2

テンプレートコードを検討する。

プロジェクトのエントリポイントモジュールを開きます。テンプレートはすでにツールを登録し、エージェントをビルドしています。このモジュールは、次のSDK機能を使用します。

  • @app.tool()関数をプラットフォームのツールとして登録します。このデコレーターは、ツールをエージェントに自動的に公開するわけではありません。

  • @app.entrypoint: ADK エージェントを返す関数をマークします。

  • app.llm(): ADK BaseLlm インスタンスをラップし、プラットフォームがすべてのモデルを呼び出すを監査するようにします。

  • app.tools(): プラットフォームのセキュアなラッパーが適用された登録済みツールを返します。

重要

@app.tool()でデコレートした関数ではなく、app.tools()関数が返すツールをエージェントに渡してください。

3

エージェントをローカルで実行します。

エージェントのディレクトリから、次のコマンドを実行してローカル開発環境を起動します。

agentengine dev up

ホットリロードモードと分離モードについて学ぶには、「エージェントをローカルで実行するおよびテストする」を参照してください。

4

エージェントを配置する。

次のコマンドを実行して、エージェントを1ステップでビルドして配置します。

agentengine deploy --auto

配置されたエージェントには、LLM APIキーも必要です。配置されたエージェントにシークレットを提供する方法を学ぶには、「クラウドシークレットのプロビジョニング」を参照してください。

ビルドする方法と配置する方法を別々のステップとして学ぶには、「エージェントイメージをビルドする」と「ビルドを配置する。」を参照してください。

ツールに人間による検討するを追加する

人間がツール呼び出しを承認するまで実行を一時停止するには、呼び出し可能なツール関数をADK FunctionToolクラスでラップし、コンストラクターにrequire_confirmation=Trueオプションを渡します。実行を一時停止して承認以外の入力を収集するには、ADK LongRunningFunctionToolクラスを使用します。@app.tool() でデコレーションした生の関数ではなく、app.tools() が返す呼び出し可能なツール関数をラップしてください。

次の例では、app.tools() が返す各呼び出す可能なツールを FunctionTool クラスでラップし、すべてのツール呼び出すが実行する前に人間の承認を待つようにします。

import os
from google.adk.agents import LlmAgentfrom google.adk.models.lite_llm import LiteLlmfrom google.adk.tools.function_tool import FunctionTool
@app.entrypointdef build_agent():    return LlmAgent(        name="daily",        instruction="You are a helpful assistant.",        model=app.llm(            LiteLlm(                model="<model-name>",                api_key=os.environ["LLM_API_KEY"],            )        ),        tools=[            FunctionTool(tool, require_confirmation=True)            for tool in app.tools()        ],    )

注意

app.tools() が返すリモート MCP ツールは ADK BaseTool オブジェクトであり、単純な呼び出し可能オブジェクトではないため、FunctionTool クラスでラップすることはできません。プラットフォームは、Orchestration エンジン のポリシーとガードレールを通じて MCP ツールを呼び出すことを管理します。

ツールリクエストへの応答

確認の答えには、ADKオブジェクト構文{confirmed: true|false}があります。プラットフォームは各一時停止をOrchestration エンジンのアクティビティとしてレコードし、アクティビティIDを割り込みIDとして使用します。

一時停止した実行を再開するには、同じセッションのエンドポイントとなる接続されたデバイスにリクエストを送信します。リクエストには、保留中の各一時停止のIDをその答えるにマッピングするresume_mapオブジェクトを含めます。保留中のすべての一時停止には、同じリクエストで答える必要があります。IDを見つけるには、一時停止された実行のsuspend_context.interruptsリストを読み取ります。詳細を学ぶには、Invocation APIを参照してください。

以下のリクエストボディの例は、保留中の2つのポーズに答えるものです。最初の答えるは、確認が必要なツールを呼び出すことを承認します。2番目の答えることは、別の保留中のツールが要求した入力を返します。

{  "resume_map": {    "<activity-id-1>": { "confirmed": true },    "<activity-id-2>": "us-east-1"  }}

CLI から再開するには、agentengine invoke コマンドの --session オプションと --resume オプションを使用します。学ぶ詳細については、「CLI からのエージェントの呼び出し」を参照してください。

注意

ADKエージェントは耐久性のあるワークフローモードで実行されるため、Human-in-the-Loopガイドで説明されているdecisionリクエスト本文ではなく、resume_mapリクエストで再開します。

サポートされているエージェント構造

agent-engine-sdk-adkパッケージには、エージェントの起動時に完全なWorkflowとエージェント構造が必要です。プラットフォームは、その構造内のパスによって各ステップをレコードします。次の表に、agent-engine-sdk-adkパッケージがサポートするADK機能を示します。

ADK機能
サポート

プレーンな BaseAgent ルート

サポートあり

ネストされたシリアルグラフやパラレルグラフを含む、静的に構成された Workflow 個のノード

サポートあり

sub_agents パラメータが設定されています。このパラメータでは、モデルが transfer_to_agent 関数を呼び出すことで実行する子エージェントを選択します。

サポートあり

転送が設定されたワークフロー エージェント ノード

エージェントが以下を使用する場合にサポートされます： mode="chat"

AgentTool クラスでラップされたエージェント

実行前に拒否されました。代わりに構成済みの sub_agents を使用してください。

NodeTool および実行時に run_node() に渡されるノード

ネストされたエージェントまたはノードが開始される前にエラーで拒否されました。

その他のプラットフォーム機能の追加

以下のプラットフォーム機能は、ADK エージェントと連携します。

  • agent.yaml ファイルの mcp フィールドで宣言するリモート MCP サーバー。プラットフォームはスタートアップ時にツールを検出し、app.tools() からそれらを返します。詳細については、「Use Remote MCP サーバー」を参照してください。

  • ガードレールの出力を検討する。require_review アクションを持つ llm_output ガードレールは、レビュアーが出力を承認または拒否するまで、モデルの呼び出しを一時停止します。resume_map リクエストを通じて出力を検討する。

詳細

戻る
ディープエージェントをビルドする
このページを評価

項目一覧