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.

Configure authentication and deploy the A2A agent to Cloud Run

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.

Configure Cloud Run service authentication

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

  • 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:

    • You must provide crucial authentication information in your A2A agent's card using the securitySchemes and security parameters. For more information, see A2A Specification: SecurityScheme Object Details.
    • Use the --allow-unauthenticated flag during deployment.

    For more information about how to allow public access to your Cloud Run service, see Google Cloud Run Public Access Authentication.

  • 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 roles/run.invoker role to invoke your Cloud Run service. For more information, see Google 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.

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.us-central1.run.app

Execute the deployment command

To deploy your A2A agent, test the deployment process using an existing ADK sample. Use the gcloud run deploy command, specifying the required parameters.

  • Access:
    • --no-allow-unauthenticated utilizes IAM-based service authentication.
    • --allow-unauthenticated makes the services visible publicly on the internet.
  • Secrets: DB_USER, DB_PASS.
  • Service account: a2a-service-account
  • Environment variables:
    • APP_URL
    • DB_INSTANCE
    • DB_NAME
    • GOOGLE_GENAI_USE_VERTEXAI = true

To debug deployment failures, set verbosity to info, such as --verbosity=info. Replace PROJECT_ID and PROJECT_NUMBER with your project ID and project number, respectively.

Before you run the deployment command, navigate to the directory that contains your A2A agent source code:

cd path/to/your/agent-directory

Alternatively, update the --source flag in the command with the full path to your agent code.

Deploy with an in-memory TaskStore configuration

For local testing, use 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="us-central1" \
    --project="{PROJECT_ID}" \
    --service-account a2a-service-account \
    --set-env-vars=GOOGLE_GENAI_USE_VERTEXAI=true,\
     GOOGLE_CLOUD_PROJECT="{PROJECT_ID}",\
     GOOGLE_CLOUD_LOCATION="us-central1",\
     APP_URL="https://sample-a2a-agent-{PROJECT_NUMBER}.us-central1.run.app"

Deploy with AlloyDB for PostgreSQL for persistent task storage

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="us-central1" \
    --project="{PROJECT_ID}" \
    --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="us-central1",\
     APP_URL="https://sample-a2a-agent-{PROJECT_NUMBER}.us-central1.run.app",\
     USE_ALLOY_DB="True",\
     DB_INSTANCE="projects/{PROJECT_ID}/locations/us-central1/clusters/{CLUSTER_NAME}/instances/primary-instance",\
     DB_NAME="postgres"

Debug deployment failures

Debug Cloud Run deployment failures by setting the --verbosity=info flag for detailed deployment logs.

In scenarios where the run.app URL returned by the deploy command differs from the expected deterministic URL, manually update the APP_URL environment variable for your Cloud Run service.

gcloud run services update --region="us-central1" sample-a2a-agent --update-env-vars APP_URL="{RUN_APP_URL}"