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

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

この例では、一般公開されているサンプルコードを使用しています。このチュートリアルのサンプルコードのフォルダ構造は次のとおりです。

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

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

ファイル/ディレクトリ 説明
/samples/community/agent/adk/gemini_enterprise/v0_9 このチュートリアルのサンプル構成とデータを含むディレクトリ。
__init__.py ディレクトリを Python パッケージとしてマークします。
__main__.py エージェントをローカルで実行するためのエントリ ポイント。
agent.py エージェント、スキル、動作を定義します。
agent_executor.py 実行フローとツールのインタラクションを管理します。
deploy.sh エージェントをビルドして Cloud Run にデプロイするスクリプト。
examples/ コンポーネント テンプレートの例を含むディレクトリ。
gemini_enterprise_composite_catalog.json 標準の Material コンポーネントとカスタムの Gemini Enterprise コンポーネントを定義するコンポーネント カタログ。
main.py メイン アプリケーション エントリ ポイント（FastAPI アプリ）。
prompt_builder.py モデルのプロンプトを構築するヘルパー。
pyproject.toml プロジェクトの構成と依存関係。
examples/0.9/material_table_orders.json 最近の注文のデモのレイアウトとモックデータを含むサンプル UI テンプレート。
tools.py エージェントが使用できるツール（関数）を定義します。

始める前に

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

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

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

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

    git clone https://github.com/a2ui-project/a2ui.git
cd a2ui/samples/community/agent/adk/gemini_enterprise/v0_9

API を有効にする

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

コンソール

次の API を有効にします。

  • Vertex AI 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 PROJECT_ID a2ui-demo-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": "a2ui-demo-agent",
  "displayName": "A2UI v0.9 Demo Agent",
  "description": "A demo agent that showcases A2UI v0.9 UI templates.",
  "a2aAgentDefinition": {
      "jsonAgentCard": "{\"protocolVersion\": \"0.3.0\", \"name\": \"A2UI v0.9 Demo\", \"description\": \"A demo agent that showcases A2UI v0.9 UIs built from the Material component catalog and Gemini Enterprise custom components (Canvas, Iframe). Ask it what can you do? to see the available demos.\", \"url\": \"AGENT_URL\", \"version\": \"1.0.0\", \"capabilities\": {\"streaming\": true, \"preferredTransport\": \"JSONRPC\", \"extensions\": [{\"uri\": \"https://a2ui.org/a2a-extension/a2ui/v0.9\", \"description\": \"Ability to render A2UI v0.9\", \"required\": false, \"params\": {\"supportedCatalogIds\": [\"https://www.gstatic.com/vertexaisearch/a2ui/v0_9/gemini_enterprise_composite_catalog.json\"]}}]}, \"skills\": [{\"id\": \"a2ui_demo\", \"name\": \"A2UI v0.9 Component Demo\", \"description\": \"Demonstrates A2UI v0.9 UIs built from the Material catalog and Gemini Enterprise custom components: cards, forms & inputs, tabs, tables, progress indicators, dialogs & menus, the Canvas side panel, and the Iframe (IFrameSrcdoc / IFrameUrl) components.\"}], \"defaultInputModes\": [\"text/plain\"], \"defaultOutputModes\": [\"text/plain\"]}"
    }
}'

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

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

エージェントの登録を解除する（省略可）

エージェントの登録を解除する場合は、次の curl コマンドを実行します。

curl -X DELETE -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/AGENT_ID

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

  • PROJECT_NUMBER: Google Cloud プロジェクトの番号。
  • LOCATION: データストアのマルチリージョン（global、us、eu）
  • ENGINE_ID: エージェントが登録されているアプリの ID。
  • AGENT_ID: 削除するエージェントの ID。

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

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

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

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

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

    Gemini Enterprise

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

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

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

エージェントを使用する

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

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

たとえば、Show me the recent orders table などのプロンプトを使用して、サンプル データに含まれる最近の注文に関する情報を取得できます。エージェントは material_table_orders.json から注文情報を取得し、次の例に示すように、カスタム UI コンポーネントを使用してチャットにリストを表示します。

最近の注文の表の例