Deploy A2A agents to Cloud Run

This document describes how to deploy your A2A agent to Cloud Run. These steps ensure secure, efficient, and scalable operation in the cloud environment.

Before you begin

  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.

    Go to project selector

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

  4. Install the Google Cloud CLI.

  5. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  6. To initialize the gcloud CLI, run the following command: 

    gcloud init

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

    Go to project selector

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

  9. Install the Google Cloud CLI.

  10. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  11. To initialize the gcloud CLI, run the following command: 

    gcloud init
  12. Navigate to the directory that contains your A2A agent source code:

      cd PATH_TO_YOUR_AGENT_DIRECTORY

  13. For the required IAM roles and permissions, see IAM roles and permissions for Cloud Run A2A agents.

Configure Cloud Run service authentication

After your A2A agent is fully developed and its deployment environment is prepared, you must configure authentication and use the gcloud run deploy command to deploy the agent to Cloud Run.

Use one of the following options to configure access and authentication for your A2A Cloud Run service:

  • IAM-based authentication for internal Google Cloud clients: For clients operating within Google Cloud, such as internal services like Agentspace, IAM-based authentication is the recommended secure approach. These clients use service accounts and require the Cloud Run Invoker (roles/run.invoker) role to invoke your Cloud Run service. For more information, see Cloud Run service-to-service authentication.

    To enable IAM-based authentication for your Cloud Run service:

    • You must use the --no-allow-unauthenticated flag during deployment.

  • Agent-level authentication for public exposure: If your A2A server is designed for public access, it handles agent-level authentication.

    To allow public access to your Cloud Run service:

Deploy the A2A agent to Cloud Run

Use the existing ADK sample to deploy your A2A agent. Specify the following parameters when you use the gcloud run deploy command:

  • Access configuration:
    • To use IAM-based service authentication, use the --no-allow-unauthenticated flag.
    • To make the services public on the internet, use the --allow-unauthenticated flag.
  • Memory: The minimum memory requirement for the container instance to run is 1Gi.
  • Secrets: To use secrets, specify the DB_USER and DB_PASS parameters.
  • Service account: To specify a service account, use the a2a-service-account parameter.
  • Environment variables: To specify environment variables, use the following variables:
    • APP_URL
    • DB_INSTANCE
    • DB_NAME
    • GOOGLE_GENAI_USE_VERTEXAI = true

For local testing, use an in-memory TaskStore configuration. For deploying your service to production, you must use persistent storage for a production A2A server. See an example in the AlloyDB for PostgreSQL deployment section.

Deploy with an in-memory TaskStore configuration

To deploy your A2A agent with an in-memory TaskStore configuration, use the following gcloud run deploy command:

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"

If you are not in the directory that contains your A2A agent source code, update the --source flag with the full path to your agent code.

Replace the following:

  • REGION: the Google Cloud region where you want to deploy your service. For example europe-west1.
  • PROJECT_ID: your project ID.
  • PROJECT_NUMBER: your project number.

Deploy with AlloyDB for PostgreSQL

To persist A2A tasks, use AlloyDB for PostgreSQL. To deploy your A2A agent with AlloyDB for PostgreSQL for persistent task storage, use the following gcloud run deploy command:

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"

If you are not in the directory that contains your A2A agent source code, update the --source flag with the full path to your agent code.

Replace the following:

  • REGION: the Google Cloud region where you want to deploy your service. For example europe-west1.
  • PROJECT_ID: your project ID.
  • PROJECT_NUMBER: your project number.
  • CLUSTER_NAME: the name of your AlloyDB for PostgreSQL cluster.

Understand the Cloud Run application URL

On successful deployment, Cloud Run automatically provides a run.app URL, which serves as the endpoint to query your active A2A service. The URL is deterministic and predictable if your service name is sufficiently short.

  • Cloud Run URL format: https://TAG---SERVICE_NAME-PROJECT_NUMBER.REGION.run.app
  • Example URL: https://sample-a2a-agent-1234.europe-west1.run.app

Debug deployment failures

To debug Cloud Run deployment failures, consider the following:

  • Detailed logs: For detailed deployment logs, set the --verbosity=info flag in your gcloud run deploy command.

  • URL mismatch: If the run.app URL returned by the deploy command differs from the expected deterministic URL, update the APP_URL environment variable for your Cloud Run service:

    1. Use the following command to update the APP_URL environment variable:

      gcloud run services update SERVICE_NAME \
    --project="PROJECT_ID" \
    --region="REGION" \
    --update-env-vars=APP_URL="CLOUD_RUN_SERVICE_URL"

      Replace the following:

      • SERVICE_NAME: the name of your Cloud Run service.
      • PROJECT_ID: your project ID.
      • REGION: the Google Cloud region where you want to deploy your service. For example europe-west1.
      • CLOUD_RUN_SERVICE_URL: the URL of your Cloud Run service.

    2. Verify that the APP_URL is updated correctly by describing the service:

      gcloud run services describe SERVICE_NAME \
    --project="PROJECT_ID" \
    --region="REGION"