A2A エージェントを Cloud Run にデプロイする

Cloud Run にデプロイする Agent2Agent（A2A）エージェントを準備して構成します。

このガイドでは、A2A エージェントのデプロイに必要な手順について説明します。

プロジェクトを構成する
IAM ロールを確立する
クラウド環境を構成する
エージェントのデプロイ
デプロイの失敗をデバッグする
テストとモニタリングを行う

A2A 仕様とサンプルエージェントを確認する

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

エージェント通信の公式の A2A 仕様とエージェント通信のコンセプトを確認します。
既存のサンプルエージェントを確認します。
ADK Cloud Run のサンプルを確認します。

始める前に

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Install the Google Cloud CLI.

外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

gcloud CLI を初期化するには、次のコマンドを実行します。

gcloud init

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Install the Google Cloud CLI.

外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

gcloud CLI を初期化するには、次のコマンドを実行します。

gcloud init

サービスアカウントを作成するには、次のコマンドを実行します。

gcloud iam service-accounts create A2A_SERVICE_ACCOUNT_NAME \
  --description="DESCRIPTION" \
  --display-name="DISPLAY_NAME"

次の値を置き換えます。

A2A_SERVICE_ACCOUNT_NAME: サービスアカウントの名前
DESCRIPTION: サービスの説明（省略可）
DISPLAY_NAME: Google Cloud コンソールに表示するサービスアカウント名を入力します

サービスアカウントのロールを付与する

プロジェクトで自分のアカウントに必要な IAM ロールを付与するには:

     gcloud projects add-iam-policy-binding PROJECT_ID \
         --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
         --role="ROLE"

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

PROJECT_ID: プロジェクト ID
A2A_SERVICE_ACCOUNT_NAME: サービスアカウントの名前
ROLE: サービスアカウントに付与するロール

必要なロール

A2A エージェントのデプロイに必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

プロジェクトに対する Cloud Run ソースデベロッパー（roles/run.sourceDeveloper）
プロジェクトに対するプロジェクト IAM 管理者（roles/resourcemanager.projectIamAdmin）
プロジェクトに対する Secret Manager 管理者（roles/secretmanager.admin）
サービス ID に対するサービスアカウントユーザー（roles/iam.serviceAccountUser）
サービスアカウントに対する Secret Manager のシークレットアクセサー（roles/secretmanager.secretAccessor）
サービスアカウントに対する Vertex AI ユーザー（roles/aiplatform.user）
AlloyDB for PostgreSQL を使用してデプロイする場合は、次のロールを付与します。
- サービスアカウントに対する AlloyDB for PostgreSQL クライアント（roles/alloydb.client）
- サービスアカウントに対するプロジェクト IAM 管理者（roles/resourcemanager.projectIamAdmin）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

ロールを付与する

コンソール

Google Cloud コンソールで、[IAM] ページに移動します。
IAM に移動
プロジェクトを選択します。
[アクセスを許可] をクリックします。
[新しいプリンシパル] フィールドに、ユーザー ID を入力します。これは通常、Cloud Run サービスのデプロイに使用されるメールアドレスです。
[ロールを選択] リストでロールを選択します。
追加のロールを付与するには、[ 別のロールを追加] をクリックして各ロールを追加します。
[保存] をクリックします。

gcloud

プロジェクトで自分のアカウントに必要な IAM ロールを付与するには:

     gcloud projects add-iam-policy-binding PROJECT_ID \
         --member=PRINCIPAL \
         --role=ROLE

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

PROJECT_NUMBER: Google Cloud プロジェクト番号。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。
PRINCIPAL: バインディングを追加するアカウント。これは通常、Cloud Run サービスのデプロイに使用されるメールアドレスです。
ROLE: デプロイするアカウントに付与するロール。

Cloud Run のデプロイの準備

このセクションでは、Python コードサンプルで A2A エージェントを Cloud Run にデプロイする準備に必要な構成について説明します。

A2A エージェントを準備する

ローカルマシンにサンプルアプリのリポジトリのクローンを作成して、コードサンプルを取得します。
```
git clone https://github.com/a2aproject/a2a-samples
```
サンプルコードが入っているディレクトリに移動します。
```
cd a2a-samples/samples/python/agents/adk_cloud_run
```

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

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

エージェントは、タスクを完了するために外部サービスにアクセスする必要があります。シークレットは、そのアクセス権を付与するための安全なメカニズムです。AlloyDB for PostgreSQL を使用してデプロイする場合は、ユーザーとパスワードが必要です。gcloud CLI で次のコマンドを実行して、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 によってコンテナイメージが自動的にビルドされます。

Dockerfile は、コンテナイメージの詳細を決定します。次に示すのは、以前にクローンを作成したサンプル 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 は一般的なプログラミング言語に対する組み込みサポートを提供しており、これによりコンテナ化プロセスが簡素化されます。

Cloud Run 上の Python アプリケーション: Cloud Run は、Python サービスをビルドしてデプロイするための main.py ファイルを検索します。詳細については、Cloud Run への Python サービスのデプロイのクイックスタートをご覧ください。
Cloud Run 上の Node.js アプリケーション: Cloud Run は、Node.js サービスをビルドしてデプロイするために index.js ファイルを探します。Cloud Run に Node.js サービスをデプロイするクイックスタートをご覧ください。

Cloud Run に A2A エージェントをデプロイする

インメモリ TaskStore 構成または AlloyDB for PostgreSQL を使用して A2A アプリケーションをデプロイします。

インメモリ TaskStore 構成は、すべてのデータを Cloud Run コンテナインスタンス内にのみ保存します。つまり、コンテナインスタンスがシャットダウン、スケールダウン、再起動されると、すべてのタスクデータが失われます。
AlloyDB for PostgreSQL はデータの永続性を提供し、エージェントの水平スケーリングを可能にします。また、コンテナの再起動、スケーリングイベント、デプロイ後もタスクが存続するようにします。

インメモリ TaskStore 構成は、ローカル環境での A2A エージェントの開発に適しています。AlloyDB for PostgreSQL は、本番環境での A2A エージェントのスケーリングに適しています。

次のコマンドは、Cloud Run サービスで IAM ベースの認証を使用する方法を示しています。デプロイ時に --no-allow-unauthenticated フラグを使用することは、Gemini Enterprise などの内部 Google Cloud クライアントの認証を構成する際に推奨されるアプローチです。

A2A サーバーが公開アクセス用に設計されており、エージェントレベルの認証を処理する必要がある場合は、デプロイ時に --allow-unauthenticated フラグを指定できます。詳細については、Cloud Run の公開アクセス認証をご覧ください。Cloud Run サービスへの公開アクセスを許可するには、securitySchemes パラメータと security パラメータを使用して、A2A エージェントのカードに重要な認証情報も指定する必要があります。詳細については、A2A 仕様: SecurityScheme オブジェクトの詳細をご覧ください。

インメモリ `TaskStore` 構成でデプロイする

インメモリ TaskStore 構成で A2A エージェントをデプロイするには、A2A エージェントのソースコードを含むディレクトリで次のコマンドを実行します。

gcloud run deploy sample-a2a-agent \
    --port=8080 \
    --source="." \
    --no-allow-unauthenticated \
    --region=REGION \
    --project=PROJECT_ID \
    --memory=1Gi \
    --service-account=A2A_SERVICE_ACCOUNT_NAME \
    --set-env-vars=GOOGLE_GENAI_USE_VERTEXAI=true,GOOGLE_CLOUD_PROJECT="PROJECT_ID",GOOGLE_CLOUD_LOCATION="REGION",APP_URL="https://sample-a2a-agent-PROJECT_NUMBER.REGION.run.app"

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

REGION: サービスをデプロイする Google Cloud リージョン（europe-west1 など）。
PROJECT_ID: プロジェクト ID。
PROJECT_NUMBER: プロジェクトの番号。
A2A_SERVICE_ACCOUNT_NAME: A2A サービスアカウントの名前。

AlloyDB for PostgreSQL を使用してデプロイする

A2A タスクを永続化するには、AlloyDB for PostgreSQL を使用します。AlloyDB for PostgreSQL を永続タスクストレージとして A2A エージェントをデプロイするには、次のコマンドを使用します。

gcloud run deploy sample-a2a-agent \
    --port=8080 \
    --source="." \
    --no-allow-unauthenticated \
    --region=REGION \
    --project=PROJECT_ID \
    --memory=1Gi \
    --update-secrets=DB_USER=alloy_db_user:latest,DB_PASS=alloy_db_pass:latest \
    --service-account=A2A_SERVICE_ACCOUNT_NAME \
    --set-env-vars=GOOGLE_GENAI_USE_VERTEXAI=true,GOOGLE_CLOUD_PROJECT="PROJECT_ID",GOOGLE_CLOUD_LOCATION="REGION",APP_URL="https://sample-a2a-agent-PROJECT_NUMBER.REGION.run.app",USE_ALLOY_DB="True",DB_INSTANCE="projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_NAME/instances/primary-instance",DB_NAME="postgres"

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

REGION: サービスをデプロイする Google Cloud リージョン（europe-west1 など）。
PROJECT_ID: プロジェクト ID。
PROJECT_NUMBER: プロジェクトの番号。
CLUSTER_NAME: AlloyDB for PostgreSQL クラスタの名前。
A2A_SERVICE_ACCOUNT_NAME: A2A サービスアカウントの名前。

デプロイの失敗をデバッグする

エラーや Cloud Run のデプロイが失敗した場合は、次の点を考慮してください。

詳細なログ: 詳細なデプロイログを取得するには、gcloud run deploy コマンドで --verbosity=info フラグを設定します。
URL の不一致: デプロイコマンドから返された run.app URL が想定される決定論的 URL と異なる場合は、以下を実行して、Cloud Run サービスの APP_URL 環境変数を更新します。
1. 次のコマンドを使用して、APP_URL 環境変数を更新します。
```
gcloud run services update SERVICE_NAME \
    --project="PROJECT_ID" \
    --region="REGION" \
    --update-env-vars=APP_URL="CLOUD_RUN_SERVICE_URL"
```
  次のように置き換えます。
  - SERVICE_NAME: Cloud Run サービスの名前。
  - PROJECT_ID: プロジェクト ID。
  - REGION: サービスをデプロイする Google Cloud リージョン。例: europe-west1。
  - CLOUD_RUN_SERVICE_URL: Cloud Run サービスの URL。
2. サービスを記述して、APP_URL が正しく更新されていることを確認します。
```
gcloud run services describe SERVICE_NAME \
    --project="PROJECT_ID" \
    --region="REGION"
```

Cloud Run アプリケーションの URL を理解する

デプロイが成功すると、Cloud Run は run.app URL を自動的に提供します。この URL は、アクティブな A2A サービスに対してクエリを実行するエンドポイントとして機能します。サービス名が所定の短さの場合、URL は決定的かつ予測可能です。

Cloud Run の URL 形式: https://TAG---SERVICE_NAME-PROJECT_NUMBER.REGION.run.app
URL の例: https://sample-a2a-agent-1234.europe-west1.run.app

A2A エージェントのデプロイをテストおよびモニタリングする

A2A エージェントを Cloud Run に正常にデプロイしたら、その機能を十分にテストします。継続的なパフォーマンスと信頼性を確保するために、確固たるモニタリング手法を確立してください。

A2A インスペクタ: エージェントのコンプライアンスを検証する

a2a-inspector ツールを使用して、デプロイした Google A2A エージェントを検査、デバッグ、検証します。このツールを使用すると、エージェントが A2A 仕様に完全に準拠し、正しく機能していることを確認できます。

接続が成功すると、インスペクタは次のアクションを実行します。

エージェントカードを表示する: エージェントのカードが自動的に表示されます。
コンプライアンスを検証する: カードが A2A 仕様を満たしているかどうか確認されます。
チャットを有効にする: エージェントとメッセージをやり取りできます。
元データを表示する: デバッグ用に、JSON-RPC 2.0 メッセージの元データがコンソールに表示されます。

デプロイされた A2A エージェントを CLI で操作する

A2A サンプルリポジトリのコマンドラインインターフェース（CLI）ツールを使用して、デプロイされたサービスを操作します。この CLI は、署名なしトークンベースの認証をサポートしています。

サービスで IAM ベースの認証を使用している場合は、正常に操作できるように、gcloud トークンをエクスポートします。

export A2A_CLI_BEARER_TOKEN=$(gcloud auth print-identity-token)
# From CLI directory
uv run . --agent CLOUD_RUN_SERVICE_URL

CLOUD_RUN_SERVICE_URL は、デプロイされた Cloud Run サービスの URL に置き換えます。

注: デプロイと呼び出しが成功するとエージェントカードが表示され、新しいタスクが開始されて、入力が求められます。CLI の各イベントには、タスク ID、ステータス、タイムスタンプなどの詳細が含まれます。

デプロイされた A2A サービスのローカルテスト

デプロイされた Cloud Run サービスをローカルでテストできます。これは、IAM ベースの認証を実装する場合に特に便利です。

Cloud Run エージェントの IAM ベースの認証をテストする

Identity and Access Management（IAM）で保護された Cloud Run サービスとやり取りするクライアントは、roles/run.invoker IAM ロールを所有している必要があります。

gcloud auth print-identity-token コマンドを使用して、デプロイされたサービスの認証フローをローカルでテストします。

curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" CLOUD_RUN_SERVICE_URL/.well-known/agent.json

CLOUD_RUN_SERVICE_URL は、デプロイされた Cloud Run サービスの URL に置き換えます。

A2A エージェントを Cloud Run にデプロイする コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

A2A 仕様とサンプル エージェントを確認する

始める前に

サービス アカウントのロールを付与する

必要なロール

ロールを付与する

コンソール

gcloud

Cloud Run のデプロイの準備

A2A エージェントを準備する

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

コンテナ化用の Dockerfile

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

Cloud Run に A2A エージェントをデプロイする

インメモリ TaskStore 構成でデプロイする

AlloyDB for PostgreSQL を使用してデプロイする

デプロイの失敗をデバッグする

Cloud Run アプリケーションの URL を理解する

A2A エージェントのデプロイをテストおよびモニタリングする

A2A インスペクタ: エージェントのコンプライアンスを検証する

デプロイされた A2A エージェントを CLI で操作する

デプロイされた A2A サービスのローカルテスト

Cloud Run エージェントの IAM ベースの認証をテストする

A2A エージェントを Cloud Run にデプロイする

A2A 仕様とサンプルエージェントを確認する

サービスアカウントのロールを付与する

インメモリ `TaskStore` 構成でデプロイする