Cloud Run で A2UI エージェントをホストする

このチュートリアルでは、Google Agent Development Kit（ADK）と A2UI 拡張機能で構築された Agent-to-Agent（A2A）エージェントを Cloud Run にデプロイする方法について説明します。また、デプロイしたエージェントを Gemini Enterprise に登録する方法についても説明します。

このチュートリアルのサンプルコードのフォルダ構造は次のとおりです。

チュートリアルのフォルダ構造

プロジェクトのフォルダ構造は次のとおりです。

ファイル/ディレクトリ 説明
examples/0.8/ 構成またはデータの例を含むディレクトリ。
__init__.py ディレクトリを Python パッケージとしてマークします。
agent.py エージェント、そのスキル、動作を定義します。
agent_executor.py 実行フローとツール操作を管理します。
contact_data.json エージェントが使用するサンプルデータ（モックの連絡先など）。
deploy.sh エージェントをビルドして Cloud Run にデプロイするスクリプト。
main.py メイン アプリケーションのエントリ ポイント（FastAPI アプリ）。
prompt_builder.py モデルのプロンプトを作成するヘルパー。
pyproject.toml プロジェクトの構成と依存関係。
tools.py エージェントが使用できるツール（関数）を定義します。

始める前に

Firebase を追加する前に、次の準備をしてください。

  • ディスカバリー エンジン管理者ロール。

  • 既存の Gemini Enterprise アプリ。アプリを作成するには、アプリを作成するをご覧ください。

  • リポジトリのクローンを作成し、cloud_run サンプル ディレクトリに移動します。

    git clone https://github.com/google/A2UI.git
cd A2UI/samples/agent/adk/gemini_enterprise/cloud_run

API を有効にする

プロジェクトで次の API を有効にします。

コンソール

次の API を有効にします。

  • Agent Platform API
  • Cloud Build API
  • Artifact Registry API
  • Cloud Run API
  • Cloud Logging API
  • Discovery Engine API
  • Cloud Storage API
  • Identity and Access Management（IAM）API

API を有効にする

REST

これらの API は、 Google Cloud コンソールから有効にするか、 次の gcloud CLI コマンドを使用して有効にできます。

gcloud services enable aiplatform.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com run.googleapis.com logging.googleapis.com discoveryengine.googleapis.com storage.googleapis.com iam.googleapis.com

権限を付与する

Cloud Run 起動元（roles/run.invoker）ロールに対する権限を付与します。

gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com" \
   --role="roles/run.invoker"

次のように置き換えます。

  • PROJECT_ID : 実際のプロジェクトの ID。
  • PROJECT_NUMBER：プロジェクトの番号。 Google Cloud

エージェントをデプロイする

deploy.sh スクリプトは、デプロイ プロセスを自動化します。エージェントをデプロイするには、プロジェクト ディレクトリから、プロジェクト Google Cloud ID と新しいサービスの名前を指定してスクリプトを実行します。必要に応じて、使用する Gemini モデルを指定することもできます。

スクリプトは次の処理を行います。

  1. ソースコードからコンテナ イメージをビルド します。
  2. イメージを Artifact Registry に push します。
  3. Cloud Run にイメージをデプロイ します。
  4. サービス自体の MODEL や一般公開の AGENT_URL などの環境変数を設定 します。
chmod +x deploy.sh
./deploy.sh YOUR_PROJECT_ID contacts-agent MODEL_NAME

次のように置き換えます。

  • PROJECT_ID: 実際のプロジェクトの ID。
  • MODEL_NAME: 省略可。これはスクリプトの 3 番目の引数です。サポートされる値は gemini-2.5-pro と gemini-2.5-flash です。 指定しない場合、スクリプトのデフォルトは gemini-2.5-flash です。

スクリプトが完了すると、デプロイされたエージェントのサービス URL が出力されます。次のステップでは、このサービス URL が必要になります。

Gemini Enterprise にエージェントを登録する

エージェントがデプロイされたら、検出できるように Gemini Enterprise に登録する必要があります。

次の curl コマンドを実行し、プレースホルダを独自の値に置き換えます。

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/ENGINE_ID/assistants/default_assistant/agents -d '{
"name": "contacts-agent",
"displayName": "Contacts Agent",
"description": "This is a test agent which lists the contacts.",
"a2aAgentDefinition": {
  "jsonAgentCard": "{\"protocolVersion\": \"0.3.0\", \"name\": \"contacts-agent\", \"description\": \"This is a test agent which lists the contacts.\", \"url\": \"AGENT_URL\", \"version\": \"1.0.0\", \"capabilities\": {\"streaming\": true, \"extensions\": [{\"uri\": \"https://a2ui.org/a2a-extension/a2ui/v0.8\", \"description\": \"Ability to render A2UI\", \"required\": false, \"params\": {\"supportedCatalogIds\": [\"https://a2ui.org/specification/v0_8/standard_catalog_definition.json\"]}}]}, \"skills\": [], \"defaultInputModes\": [\"text/plain\"], \"defaultOutputModes\": [\"text/plain\"]}"
}
}'

次のように置き換えます。

  • PROJECT_NUMBER: あなたの Google Cloud プロジェクトの番号。
  • LOCATION: データストアのマルチリージョン（global、us、eu）
  • ENGINE_ID: エージェントを登録するアプリの ID。
  • AGENT_URL: デプロイされたエージェントのサービス URL。

Gemini Enterprise ウェブアプリでエージェントを使用する

エージェントを作成して登録したら、Gemini Enterprise ウェブアプリで使用して操作を開始できます。

ウェブアプリの URL を取得する

エージェントを使用するには、まずウェブアプリの URL を取得する必要があります。Gemini Enterprise 管理者は、次の手順でウェブアプリの URL を取得して共有できます。

  1. コンソールで、[Gemini Enterprise] ページに移動します。 Google Cloud

    Gemini Enterprise

  2. エージェントを登録したアプリの名前をクリックします。

  3. [Integrations] をクリックします。

  4. [ウェブアプリへのリンク] をコピーして、組織内のユーザーと共有します。

エージェントを使用する

エージェントを使用して操作する手順は次のとおりです。

  1. 新しいブラウザタブでウェブアプリの URL を開きます。
  2. ウェブアプリのナビゲーション メニューで、[エージェント] をクリックします。
  3. [From your organization] セクションに移動し、作成したエージェントをクリックします。
  4. エージェントの会話型インターフェースが開きます。質問をして、エージェントとのやり取りを開始します。

たとえば、エージェントにすべての連絡先を一覧表示するように依頼できます。エージェントは list_contacts ツールを使用して contact_data.json から連絡先を取得し、次の例に示すように、カスタム UI 要素を使用してチャットにリストを表示します。

Contacts Agent の例