Cloud Run での A2A エージェントのホストに関する概要

このガイドでは、Cloud Run にデプロイする Agent2Agent（A2A）エージェントを準備して設定する方法の概要について説明します。クラウド環境の設定、必要な Identity and Access Management（IAM）ロールの構成、エージェントのデプロイ準備など、基本的な手順について説明します。

始める前に

A2A エージェントの開発とデプロイを開始する前に、以下のコンセプトとリソースについて理解を深めてください。

A2A エージェントのデプロイ ロードマップ

エージェントをデプロイするには、以下の手順を実施します。

アーキテクチャの概要

A2A エージェントの中核は、Cloud Run などのサービスおよびオーケストレーション レイヤです。このレイヤは、Gemini や Vertex AI などの AI モデル、AlloyDB や A2A TaskStore などのメモリ ストレージ、API を介した外部ツールとのインタラクションを管理します。クライアントは、「エージェント カードを取得」や「メッセージを送信」などのリクエストを送信してエージェントとやり取りし、タスクの更新を受け取ります。

次の図は、A2A クライアント（ユーザーまたはエージェント）と A2A エージェントがやり取りする、A2A エージェント システムのアーキテクチャを示しています。

サービスレイヤとオーケストレーション レイヤを介したクライアントとエージェントのインタラクションを示す A2A エージェントのアーキテクチャ。
A2A エージェント アーキテクチャ

A2A リクエストのライフサイクルについては、A2A リクエストのライフサイクルのセクションをご覧ください。

Cloud Run A2A エージェントの IAM ロールと権限

Cloud Run サービスが他の Google Cloudサービスと安全にやり取りするには、IAM ロールが適切に構成されていることが重要となります。運用上のセキュリティと効率性を確保するために、専用のサービス アカウントを作成し、次のセクションに記載されている特定の権限を付与します。

Cloud Run サービス アカウントを作成する

gcloud コマンドを実行する前に、認証されていることを確認します。次のコマンドを実行して、 Google Cloud アカウントにログインします。

gcloud auth login

デプロイする A2A サービス インスタンス専用のサービス アカウントを作成します。gcloud iam service-accounts create コマンドを使用します。

gcloud iam service-accounts create A2A_SERVICE_ACCOUNT_NAME \
  --description="Service account for A2A Cloud Run service" \
  --display-name="A2A Cloud Run Service Account"

A2A_SERVICE_ACCOUNT_NAME は、サービス アカウントの名前に置き換えます。

A2A エージェントの IAM ロールを構成する

A2A エージェントがやり取りする Google Cloudサービスに基づいて、次の IAM ロールをサービス アカウントに割り当てます。

セキュリティ認証情報のための Secret Manager へのアクセス

  • ロール: Secret Manager Secret Accessor （roles/secretmanager.secretAccessor）

  • 目的: Cloud Run サービス アカウントが Secret Manager からデータベース認証情報などのシークレットを安全に取得できるようにします。

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

AI 機能のための Vertex AI モデルへのアクセス

  • ロール: Vertex AI User（roles/aiplatform.user）

  • 目的: Cloud Run サービス アカウントが Vertex AI モデルの　Prediction API を呼び出すために必要です。

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

永続ストレージのための Alloy DB インスタンスへのアクセス（該当する場合）

  • ロール: AlloyDB Client（roles/alloydb.client）と Service Usage Consumer（roles/serviceusage.serviceUsageConsumer）

  • 目的: Cloud Run サービス ID が AlloyDB クラスタとやり取りして、永続タスク ストレージを実現できるようにします。これは、本番環境の A2A エージェントにとって不可欠です。

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/alloydb.client"

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/serviceusage.serviceUsageConsumer"

Cloud Run へのデプロイに向けた A2A エージェントの準備

このセクションでは、A2A エージェントを Cloud Run へデプロイする準備に必要な設定について説明します。これにより、クラウドでの安全かつ効率的でスケーラブルな運用を確保することができます。

Cloud Run サービスのシークレットを構成する

API キーやデータベース パスワードなどの機密性の高い認証情報を、安全なメカニズムを用いて A2A サーバーに指定します。Cloud Run では、環境変数または動的にマウントされたボリュームとしてシークレットを指定できます。詳細については、Cloud Run でのシークレットの構成をご覧ください。

たとえば、gcloud CLI を使用して、Google Secret Manager 内でデータベースのユーザーとパスワードのシークレットを作成して管理します。詳細については、シークレットの作成をご覧ください。

gcloud secrets create alloy_db_user --replication-policy="automatic"
# Create a file user.txt with contents of secret value
gcloud secrets versions add alloy_db_user --data-file="user.txt"

gcloud secrets create alloy_db_pass --replication-policy="automatic"
# Create a file pass.txt with contents of secret value
gcloud secrets versions add alloy_db_pass --data-file="pass.txt"

コンテナ化用の Dockerfile を作成する

Cloud Run では、すでにホストされているコンテナ イメージから、またはソースコードから直接サービスをデプロイできます。ソースコードからデプロイする場合、Dockerfile がプロジェクトのルート ディレクトリにあると、Cloud Run によってコンテナ イメージが自動的にビルドされます。

A2A エージェントのデプロイにおける Dockerfile の例を次に示します。

FROM python:3.13-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
EXPOSE 8080
WORKDIR /app
COPY . ./
RUN uv sync
ENTRYPOINT ["uv", "run", ".", "--host", "0.0.0.0", "--port", "8080"]

Dockerfile なしでソースコードからデプロイする

Dockerfile のないソースコード リポジトリの場合、Cloud Run は一般的なプログラミング言語に対する組み込みサポートを提供しており、これによりコンテナ化プロセスが簡素化されます。

次のステップ