このページは Cloud Translation API によって翻訳されました。

ADK でマルチエージェントシステムを作成し、Agent Engine にデプロイして、A2A プロトコルを使用する

1. このラボの目的

このハンズオンラボでは、プロンプトに基づいて画像を生成し、プロンプトに対して評価するマルチエージェントアプリケーションを構築します。画像がプロンプトで説明されている要件を十分に満たしていない場合、エージェントは要件を満たす画像が生成されるまで画像を生成し続けます。このハンズオンの各エージェントには単一の目的があり、エージェントは互いに協力して全体的な目標を達成します。

学習内容

ADK の基本を理解し、マルチエージェントシステムを作成する方法を学びます。
GCP でエージェントを簡単にデプロイして使用する方法について説明します。
A2A プロトコルの基本を理解する
A2A プロトコルと ADK を組み合わせてオープンエージェントを作成する方法について説明します。

2. 始める前に

使用できるプロジェクトがまだない場合は、GCP コンソールで新しいプロジェクトを作成する必要があります。
このラボでは、GCP Cloud Shell を使用してタスクを実行します。Cloud Shell を開き、Cloud Shell を使用してプロジェクトを設定します。
Cloud Shell エディタボタンを押して、GCP Cloud Shell エディタを開きます。[シェルを承認] ポップアップが表示されたら、クリックして Cloud Shell エディタを承認します。
次のコマンドを使用して、プロジェクトがすでに認証されているかどうかを確認できます。

gcloud auth list

Cloud Shell で次のコマンドを実行して、プロジェクトを確認します。

gcloud config list project

プロジェクトが設定されていない場合は、次のコマンドを使用して設定します。

gcloud config set project <YOUR_PROJECT_ID>

このラボを実行するには、いくつかのサービスを有効にする必要があります。Cloud Shell で次のコマンドを実行します。

gcloud services enable aiplatform.googleapis.com

3. 概要: エージェント開発キットのメリット

Agent Development Kit には、エージェントアプリケーションを構築するデベロッパーにとって次のような重要なメリットがあります。

マルチエージェントシステム: 複数の専門エージェントを階層構造で構成して、モジュール式でスケーラブルなアプリケーションを構築します。複雑な調整と委任を可能にします。
豊富なツールエコシステム: エージェントに多様な機能を提供します。事前構築済みのツール（検索、コード実行など）を使用したり、カスタム関数を作成したり、サードパーティのエージェントフレームワーク（LangChain、CrewAI）のツールを統合したり、他のエージェントをツールとして使用したりできます。
柔軟なオーケストレーション: ワークフローエージェント（SequentialAgent、ParallelAgent、LoopAgent）を使用して予測可能なパイプラインのワークフローを定義するか、LLM を活用した動的ルーティング（LlmAgent 転送）を使用して適応型動作を実現します。
統合されたデベロッパーエクスペリエンス: 強力な CLI とインタラクティブな開発 UI を使用して、ローカルで開発、テスト、デバッグを行います。イベント、状態、エージェントの実行をステップごとに検査します。
組み込みの評価: 最終回答の品質とステップごとの実行軌跡の両方を事前定義されたテストケースと照らし合わせて評価することで、エージェントのパフォーマンスを体系的に評価します。
デプロイの準備: エージェントをコンテナ化して任意の場所にデプロイします。ローカルで実行する、Vertex AI Agent Engine でスケーリングする、Cloud Run または Docker を使用してカスタムインフラストラクチャに統合するなどの方法があります。

他の Gen AI SDK やエージェントフレームワークでも、モデルのクエリやツールによるモデルの強化は可能ですが、複数のモデル間の動的な調整には、ユーザー側でかなりの作業が必要になります。

Agent Development Kit は、これらのツールよりも高レベルのフレームワークを提供します。これにより、複数のエージェントを簡単につなぎ合わせて、複雑でありながら保守しやすいワークフローを実現できます。

4. A2A の概要

Agent2Agent（A2A）プロトコルは、異なるフレームワーク、ベンダー、ドメインの自律型 AI エージェント間のシームレスで安全な通信とコラボレーションを可能にするように設計されたオープンスタンダードです。

ユニバーサルな相互運用性: A2A により、基盤となるテクノロジーに関係なくエージェントが連携して動作できるため、真のマルチエージェントエコシステムが実現します。つまり、異なるプラットフォームで異なる企業によって構築されたエージェントが通信して連携できます。
機能の検出: エージェントは、ID、サポートされている A2A 機能、スキル、認証要件を記述した「エージェントカード」（JSON ドキュメント）を使用して、機能をアドバタイズできます。これにより、他のエージェントは特定のタスクに最適なエージェントを見つけて選択できます。
デフォルトで安全性を確保: セキュリティは中核的な原則です。A2A には、HTTPS/TLS、JWT、OIDC、API キーなどの標準を利用して安全なやり取りを確保し、機密データを保護するエンタープライズグレードの認証メカニズムと認可メカニズムが組み込まれています。
モダリティに依存しない: このプロトコルは、テキスト、音声、動画のストリーミング、インタラクティブなフォーム、埋め込み iframe など、さまざまな通信モダリティをサポートしています。この柔軟性により、エージェントはタスクとユーザーに最適な形式で情報を交換できます。
構造化されたタスク管理: A2A は、タスクの委任、モニタリング、完了に関する明確なプロトコルを定義します。関連するタスクをグループ化し、一意のタスク ID を使用してさまざまなエージェント間で管理できます。タスクは、定義されたライフサイクル（送信済み、処理中、完了など）を移行できます。
不透明な実行: エージェントは、内部の推論プロセス、メモリ、特定のツールを他のエージェントに開示する必要がないことが重要な特徴です。呼び出し可能なサービスのみを公開し、モジュール性とプライバシーを促進します。
既存の標準に基づく: A2A は、HTTP、リアルタイムストリーミング用のサーバー送信イベント（SSE）、構造化データ交換用の JSON-RPC などの確立されたウェブテクノロジーを活用しているため、既存の IT インフラストラクチャとの統合が容易になります。
非同期通信: このプロトコルは、非同期通信を主な考慮事項として設計されており、柔軟なタスクの進行を促進し、接続が永続的に維持されていない場合でも更新のプッシュ通知を有効にします。

5. エージェントアーキテクチャ

このラボでは、仕様に従って画像を生成し、画像を評価してからユーザーに提示するマルチエージェントアプリケーションを作成します。

システムは、プロセス全体を調整する image_scoring というメインエージェントで構成されています。このメインエージェントには image_generation_scoring_agent というサブエージェントがあり、このサブエージェントには、より具体的なタスクを行うための独自のサブエージェントがあります。これにより、メインエージェントがサブエージェントにタスクを委任する階層関係が作成されます。図 2: エージェントの全体的なフロー。

すべてのエージェントのリスト

image_scoring（メインエージェント）:
目的: ワークフロー全体を管理するルートエージェントです。終了条件が満たされるまで、image_generation_scoring_agent と checker_agent をループで繰り返し実行します。
サブエージェント:

image_generation_scoring_agent
checker_agent_instance

image_generation_scoring_agent（image_scoring のサブエージェント）:
目的: このエージェントは、画像の生成とスコアリングのコアロジックを担当します。このために、3 つのサブエージェントのシーケンスを実行します。
サブエージェント:

image_generation_prompt_agent
image_generation_agent
scoring_images_prompt

checker_agent_instance（image_scoring のサブエージェント）:
目的: このエージェントは、画像スコアリングプロセスを続行するか終了するかをチェックします。check_tool_condition ツールを使用して終了条件を評価します。
image_generation_prompt_agent（image_generation_scoring_agent のサブエージェント）:
目的: このエージェントは、画像生成用のプロンプトの作成に精通しています。入力テキストを受け取り、画像生成モデルに適した詳細なプロンプトを生成します。
image_generation_agent（image_generation_scoring_agent のサブエージェント）:
目的: このエージェントは、Imagen 3 を使用した画像の作成に精通しています。image_generation_prompt_agent からプロンプトを取得し、画像を生成します。
scoring_images_prompt（image_generation_scoring_agent のサブエージェント）:
目的: このエージェントは、さまざまな基準に基づいて画像を評価し、スコアを付ける専門家です。生成された画像を受け取り、スコアを割り当てます。

エージェントが使用するツール

check_tool_condition:
説明: このツールは、ループ終了条件が満たされているかどうか、または最大反復回数に達しているかどうかを確認します。いずれかに該当する場合、ループは停止します。
使用元: checker_agent_instance
generate_images:
説明: このツールは、Imagen 3 モデルを使用して画像を生成します。生成された画像を Google Cloud Storage バケットに保存することもできます。
使用元: image_generation_agent
get_policy:
説明: このツールは、JSON ファイルからポリシーを取得します。このポリシーは、image_generation_prompt_agent が画像生成プロンプトを作成するために使用し、scoring_images_prompt が画像のスコアリングに使用します。
使用元: image_generation_prompt_agent、scoring_images_prompt
get_image:
説明: このツールは、生成された画像アーティファクトを読み込んでスコアリングできるようにします。
使用元: scoring_images_prompt
set_score:
説明: このツールは、生成された画像の合計スコアをセッション状態に設定します。
使用元: scoring_images_prompt

6. タスク 1. ADK をインストールして環境を設定する

このハンズオンでは、Cloud Shell を使用してタスクを実行します。

Vertex AI の推奨 API を有効にする

Google Cloud コンソールの上部で「Vertex AI」を検索して、Vertex AI に移動します。
[すべての推奨 API を有効にする] をクリックします。

Cloud Shell エディタのタブを準備する

Google Cloud コンソールウィンドウを選択した状態で、キーボードの G キーを押してから S キーを押して、Cloud Shell を開きます。または、Google Cloud コンソールの右上にある Cloud Shell ボタンをクリックすることもできます。
[続行] をクリックします。
Cloud Shell を承認するよう求められたら、[承認] をクリックします。
Cloud Shell ペインの右上にある [新しいウィンドウで開く] ボタンをクリックします。
ペインの上部にある [エディタを開く] 鉛筆アイコン（）をクリックして、ファイルを表示します。
左側のナビゲーションメニューの上部にあるエクスプローラアイコンをクリックして、ファイルエクスプローラを開きます。
[Open Folder] ボタンをクリックします。
このラボの残りの部分では、このウィンドウを Cloud Shell エディタと Cloud Shell ターミナルを備えた IDE として使用できます。

このラボの ADK とコードサンプルをダウンロードしてインストールする

次のコマンドを実行して、必要なソースを GitHub から複製し、必要なライブラリをインストールします。

#create the project directory
mkdir imagescoring
cd imagescoring
#clone the code in the local directory
git clone https://github.com/haren-bh/multiagenthandson.git

#Create the virtual environment
python3 -m venv pythonenv
source pythonenv/bin/activate

#install google-adk and a2a sdk
python3 -m pip install google-adk==1.8.0
python3 -m pip install a2a-sdk==0.2.16

poetry を使用して、追加の要件をインストールします。

cd multiagenthandson #go to the application directory
pip install poetry poetry-plugin-export
poetry install --with deployment

Cloud Storage バケットがない場合は、Google Cloud Storage で新しいバケットを作成します。gsutil コマンドを使用してバケットを作成することもできます。

gsutil mb gs://YOUR-UNIQUE-BUCKETNAME

エディタで [View] -> [Toggle hidden files] に移動します。また、image_scoring フォルダに次の内容の .env ファイルを作成します。プロジェクト名や Cloud Storage バケットなどの必要な詳細情報を追加します。

GOOGLE_GENAI_USE_VERTEXAI=1 #1 if VERTEXAI has to be used. Can be 0 if API_KEY is specified
GOOGLE_CLOUD_PROJECT=YOUR CLOUD PROJECT NAME
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_CLOUD_STORAGE_BUCKET=YOUR BUCKET NAME  # Only required for deployment on Agent Engine
GCS_BUCKET_NAME=YOUR BUCKET NAME #Bucket for storing generated images.
SCORE_THRESHOLD=40 # Min threshold for image_score. Max Score is 50 , hence should be less than 50. 
#If the computed score is higher then loop will terminate
#MAX_ITERATIONS=5 #Max iterations for evaluating the image_score before terminating the loop.
IMAGEN_MODEL="imagen-3.0-generate-002" 
GENAI_MODEL="gemini-2.5-flash"
#AGENT_ENGINE_ID=<AGENT_ENGINE_ID> #The Agent Engine ID obtained after deploying to the agent engine.

ソースコードでエージェントの構造を確認します。agent.py から始めます。このエージェントには、他のエージェントに接続するルートエージェントが含まれています。
ターミナルの最上位ディレクトリ multiagenthandson に戻り、次のコマンドを実行してエージェントをローカルで実行します。

# Run the following command to run agents locally
export GCS_BUCKET_NAME=your gcs bucket name
adk web

図 1

ターミナルに表示された http:// URL を Ctrl キーを押しながらクリック（MacOS の場合は CMD キーを押しながらクリック）して、ADK のブラウザベースの GUI クライアントを開きます。図 2 のようになります。

画像を生成してみましょう。以下のプロンプトまたは独自のプロンプトを試してください。
夕暮れの穏やかな山岳風景
自転車に乗る猫

図 2

7. タスク 2. Agent Engine にデプロイする

次に、エージェントを Agent Engine にデプロイします。Agent Engine は、GCP にエージェントをデプロイするためのフルマネージドサービスです。Agent Engine は ADK と互換性があるため、ADK で構築されたエージェントを Agent Engine にデプロイできます。

環境変数をいくつか定義する

export GOOGLE_CLOUD_LOCATION='us-central1'
export GOOGLE_CLOUD_PROJECT='your project id'

poetry を使用して requirements.txt ファイルを作成します。Poetry は pyproject.toml を使用して requirements.txt ファイルを作成します。コマンドを実行したら、requirements.txt ファイルが作成されたかどうかを確認します。

# Go to the parent folder containing pyproject.toml file
# install poetry-plugin-export
pip install poetry-plugin-export

#Create requirements.txt file
poetry export -f requirements.txt --output requirements.txt --without-hashes

パッケージを作成します。アプリを .whl Python パッケージにバンドルする必要があります。これには poetry を使用します。コマンドを実行したら、dist フォルダが作成され、その中に .whl ファイルが含まれていることを確認します。

# Go to the parent folder containing pyproject.toml file
#Create python package, to create whl file
poetry build

次に、デプロイスクリプトを準備します。デプロイスクリプトは、画像スコアリングエージェントまたはエージェントエンジンサービスをデプロイします。image_scoring フォルダ内の deploy.py の内容を次のように変更します。

# Change the content of the following. Look for #change this comment
import vertexai
from .agent import root_agent
import os
import glob # To easily find the wheel file

PROJECT_ID = "YOUR PROJECT ID" #change this your project
LOCATION = "us-central1" #change this
STAGING_BUCKET = "gs://YOUR BUCKET " #change this to your bucket

from vertexai import agent_engines

vertexai.init(
   project=PROJECT_ID,
   location=LOCATION,
   staging_bucket=STAGING_BUCKET,
)

remote_app = agent_engines.create(
   agent_engine=root_agent,
   requirements=open(os.path.join(os.getcwd(), "requirements.txt")).readlines()+["./dist/image_scoring-0.1.0-py3-none-any.whl"],#change this to your local location
   extra_packages=[
       "./dist/image_scoring-0.1.0-py3-none-any.whl", # change this to your location
   ]
)

print(remote_app.resource_name)

これで、デプロイスクリプトを実行できます。

#run deploy script from the parent folder containing deploy.py
python3 -m image_scoring.deploy

デプロイ後、次のような画面が表示されます。

図 3

次に、デプロイされたエージェントをテストします。リモートでデプロイされたエージェントエンジンをテストするには、まずターミナルのデプロイ出力からエージェントの場所をコピーします。projects/85469421903/locations/us-central1/reasoningEngines/7369674597261639680 のようになります。
testclient フォルダに移動し、remote_test.py ファイルを開いて、次の行を編集します。

PROJECT_ID = "" #change this
LOCATION = "" #change this
STAGING_BUCKET = "" #change this

#replace the id with your own.
reasoning_engine_id="your agent engine id"

#You can replace this with your own prompt
image_prompt="A cat riding a bicycle"

#execute remote_test.py
python3 remote_test.py

8. タスク 3. A2A エージェントを作成する

このステップでは、前のステップで作成したエージェントに基づいて、シンプルな A2A エージェントを作成します。既存の ADK エージェントは A2A プロトコルで公開できます。このステップで学習する主な内容は次のとおりです。

A2A プロトコルの基本を学びます。
ADK プロトコルと A2A プロトコルの連携について説明します。
A2A プロトコルを操作する方法について説明します。

このハンズオンでは、image_scoring_adk_a2a_server フォルダのコードを使用します。タスクを開始する前に、ディレクトリをこのフォルダに変更してください。

A2A エージェントカードを作成する

A2A プロトコルでは、エージェントのケーパビリティやエージェントの使用ガイドなど、エージェントに関するすべての情報を含むエージェントカードが必要です。A2A エージェントがデプロイされると、「.well-known/agent-card.json」リンクを使用してエージェントカードを表示できます。クライアントは、この情報を参照してエージェントにリクエストを送信できます。

remote_a2a/image_scoring フォルダに、次の内容の agents.json があることを確認します。

{
 "name": "image_scoring",
 "description": "Agent that generates images based on user prompts and scores their adherence to the prompt.",
 "url": "http://localhost:8001/a2a/image_scoring",
 "version": "1.0.0",
 "defaultInputModes": ["text/plain"],
 "defaultOutputModes": ["image/png", "text/plain"],
 "capabilities": {
   "streaming": true,
   "functions": true
 },
 "skills": [
   {
     "id": "generate_and_score_image",
     "name": "Generate and Score Image",
     "description": "Generates an image from a given text prompt and then evaluates how well the generated image adheres to the original prompt, providing a score.",
     "tags": ["image generation", "image scoring", "evaluation", "AI art"],
     "examples": [
       "Generate an image of a futuristic city at sunset",
       "Create an image of a cat playing a piano",
       "Show me an image of a serene forest with a hidden waterfall"
     ]
   }
 ]
}

A2A エージェントを作成する

ルートフォルダ image_scoring_adk_a2a_server 内に、a2a エージェントのエントリポイントである a2a_agent.py ファイルがあることを確認します。次の内容が含まれている必要があります。

from google.adk.agents.remote_a2a_agent import RemoteA2aAgent

root_agent = RemoteA2aAgent(
   name="image_scoring",
   description="Agent to give interesting facts.",
   agent_card="http://localhost:8001/a2a/image_scoring/.well-known/agent.json",
  
   # Optional configurations
   timeout=300.0,          # HTTP timeout (seconds)
   httpx_client=None,      # Custom HTTP client
)

A2A エージェントを実行する

これで、エージェントを実行する準備が整いました。エージェントを実行するには、トップフォルダ image_scoring_adk_a2a_server 内から次のコマンドを実行します。

#set some environmental variables
export GOOGLE_CLOUD_PROJECT=datapipeline-372305
export GOOGLE_CLOUD_LOCATION=us-central1
export GCS_BUCKET_NAME=haren-genai-bucket

#following command runs the ADK agent as a2a agent
adk api_server --a2a --port 8001 remote_a2a

A2A エージェントをテストする

エージェントが実行されたら、エージェントのテストに進みます。まず、エージェントカードを確認しましょう。

#Execute the following 
curl http://localhost:8001/a2a/image_scoring/.well-known/agent.json

上記を実行すると、A2A エージェントのエージェントカードが表示されます。これは主に、前の手順で作成した agent.json のコンテンツです。

それでは、エージェントにリクエストを送信しましょう。curl を使用してエージェントにリクエストを送信できます。

curl -X POST   http://localhost:8001/a2a/image_scoring   -H 'Content-Type: application/json'   -d '{
    "id": "uuid-123",
    "params": {
      "message": {
        "messageId": "msg-456",
        "parts": [{"text": "Create an image of a cat"}],
        "role": "user"
      }
    }
  }'

上記のリクエストでは、「Create an image of a cat」の行を変更することで、プロンプトを変更できます。コマンドを実行したら、指定した Google Cloud Storage で出力イメージを確認できます。

9. クリーンアップ

作成したものをクリーンアップしましょう。

作成した Agent Engine サーバーを削除します。Google Cloud コンソールの検索バーに「Vertex AI」と入力して、Vertex AI に移動します。左側の [Agent Engine] をクリックします。[削除] をクリックしてエージェントを削除できます。

図 4

Cloud Shell でファイルを削除する

#Execute the following to delete the files
rm -R imagescoring

バケットを削除します。GCP コンソール -> Cloud Storage に移動し、バケットを選択して削除します。

ADK でマルチエージェント システムを作成し、Agent Engine にデプロイして、A2A プロトコルを使用する