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

このドキュメントでは、A2A エージェントを Cloud Run にデプロイする方法について説明します。これらの手順により、クラウド環境での安全で効率的かつスケーラブルな運用を確保できます。

始める前に

  1. 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.

  2. 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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Install the Google Cloud CLI.

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

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

    gcloud init

  7. 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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  8. Verify that billing is enabled for your Google Cloud project.

  9. Install the Google Cloud CLI.

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

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

    gcloud init
  12. A2A エージェントのソースコードが含まれるディレクトリに移動します。

      cd PATH_TO_YOUR_AGENT_DIRECTORY

  13. 必要な IAM ロールと権限については、Cloud Run A2A エージェントの IAM ロールと権限をご覧ください。

    14. Cloud Run サービスの認証を構成する

    A2A エージェントの開発が完了し、デプロイ環境の準備が整ったら、認証を構成し、gcloud run deploy コマンドを使用してエージェントを Cloud Run にデプロイする必要があります。

    次のいずれかの方法で、A2A Cloud Run サービスのアクセスと認証を構成します。

    • 内部 Google Cloud クライアントの IAM ベースの認証: Google Cloud内で動作するクライアント（例: Agentspace などの内部サービス）には、セキュアなアプローチとして IAM ベースの認証が推奨されます。これらのクライアントはサービス アカウントを使用し、Cloud Run サービスを呼び出すには Cloud Run 起動元（roles/run.invoker）ロールが必要です。詳細については、Cloud Run サービス間認証をご覧ください。

      Cloud Run サービスの IAM ベースの認証を有効にするには:

      • デプロイ時に --no-allow-unauthenticated フラグを使用する必要があります。

    • 公開用のエージェント レベルの認証: A2A サーバーが公開アクセス用に設計されている場合、エージェント レベルの認証を処理します。

      Cloud Run サービスへの公開アクセスを許可するには:

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

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

    既存の ADK サンプルを使用して、A2A エージェントをデプロイします。gcloud run deploy コマンドを使用する場合は、次のパラメータを指定します。

    • アクセス構成:
      • IAM ベースのサービス認証を使用する場合は、--no-allow-unauthenticated フラグを使用します。
      • サービスをインターネット上で公開する場合は、--allow-unauthenticated フラグを使用します。
    • メモリ: コンテナ インスタンスを実行するための最小メモリ要件は 1Gi です。
    • シークレット: シークレットを使用するには、DB_USER パラメータと DB_PASS パラメータを指定します。
    • サービス アカウント: サービス アカウントを指定するには、a2a-service-account パラメータを使用します。
    • 環境変数: 環境変数を指定するには、次の変数を使用します。
      • APP_URL
      • DB_INSTANCE
      • DB_NAME
      • GOOGLE_GENAI_USE_VERTEXAI = true

    ローカルテストでは、インメモリ TaskStore 構成を使用します。サービスを本番環境にデプロイする際には、本番環境の A2A サーバーに永続ストレージを使用する必要があります。AlloyDB for PostgreSQL のデプロイ セクションの例をご覧ください。

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

    インメモリ TaskStore 構成で A2A エージェントをデプロイする場合は、次の gcloud run deploy コマンドを使用します。

    gcloud run deploy sample-a2a-agent \
    --port=8080 \
    --source="." \
    --no-allow-unauthenticated \
    --region=REGION \
    --project=PROJECT_ID \
    --memory=1Gi \
    --service-account=a2a-service-account \
    --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"

    現在のディレクトリに A2A エージェントのソースコードが含まれていない場合は、エージェント コードのフルパスで --source フラグを更新します。

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

    • REGION: サービスをデプロイする Google Cloud リージョン。例: europe-west1。
    • PROJECT_ID: プロジェクト ID。
    • PROJECT_NUMBER: プロジェクトの番号。

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

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

    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 \
    --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"

    現在のディレクトリに A2A エージェントのソースコードが含まれていない場合は、エージェント コードのフルパスで --source フラグを更新します。

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

    • REGION: サービスをデプロイする Google Cloud リージョン。例: europe-west1。
    • PROJECT_ID: プロジェクト ID。
    • PROJECT_NUMBER: プロジェクトの番号。
    • CLUSTER_NAME: AlloyDB for PostgreSQL クラスタの名前。

    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

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

    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"