Deploy A2A agents to Cloud Run

Prepare and configure Agent2Agent (A2A) agents for deployment on Cloud Run.

This guide covers essential steps for deploying A2A agents:

• Configure your project
• Establish IAM roles
• Configure your cloud environment
• Deploy your agent
• Debug deployment failures
• Test and monitor

Review the A2A specification and sample agents

Before you start developing and deploying your A2A agent, familiarize yourself with the following concepts and resources:

• Review the official A2A specification and agent communication concepts for agent communication.
• Explore existing sample agents.
• Review the ADK Cloud Run sample.

Before you begin

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Install the Google Cloud CLI.

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

To initialize the gcloud CLI, run the following command:

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Install the Google Cloud CLI.

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

To initialize the gcloud CLI, run the following command:

gcloud init

1. To create a service account, run the following command:

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

Replace the following values:

• A2A_SERVICE_ACCOUNT_NAME: the name of the service account

• DESCRIPTION: an optional description of the service account

• DISPLAY_NAME: a service account name to display in the Google Cloud console

Grant the service account roles

To grant the required IAM roles to your account on your project:

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

Replace:

• PROJECT_ID: your project ID
• A2A_SERVICE_ACCOUNT_NAME: the name of your service account
• ROLE: the role you are adding to the service account

Required roles

To get the permissions that you need to deploy A2A agents, ask your administrator to grant you the following IAM roles:

• Cloud Run Source Developer (roles/run.sourceDeveloper) on the project
• Project IAM Admin (roles/resourcemanager.projectIamAdmin) on the project
• Secret Manager Admin (roles/secretmanager.admin) on the project
• Service Account User (roles/iam.serviceAccountUser) on the service identity
• Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) on the service account
• Vertex AI User (roles/aiplatform.user) on the service account
• If you are deploying with AlloyDB for PostgreSQL, grant the following roles:
  • AlloyDB for PostgreSQL client (roles/alloydb.client) on the service account
  • Project IAM Admin (roles/resourcemanager.projectIamAdmin) on the service account

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Grant the roles

Console

1. In the Google Cloud console, go to the IAM page.

   Go to IAM
2. Select the project.
3. Click Grant access.

4. In the New principals field, enter your user identifier. This is typically the email address that is used to deploy the Cloud Run service.

5. In the Select a role list, select a role.
6. To grant additional roles, click Add another role and add each additional role.
7. Click Save.

gcloud

To grant the required IAM roles to your account on your project:

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

Replace:

• PROJECT_NUMBER with your Google Cloud project number.
• PROJECT_ID with your Google Cloud project ID.
• PRINCIPAL with the account you are adding the binding for. This is typically the email address that is used to deploy the Cloud Run service.
• ROLE with the role you are adding to the deployer account.

Prepare for Cloud Run deployment

This section describes the configurations required to prepare your A2A agent for deployment to Cloud Run for a Python code sample.

Prepare A2A agent

1. Retrieve the code sample by cloning the sample app repository to your local machine:

   git clone https://github.com/a2aproject/a2a-samples
   

2. Change to the directory that contains the sample code:

   cd a2a-samples/samples/python/agents/adk_cloud_run
   

Configure secrets for Cloud Run services

Provide all sensitive credentials, such as API keys and database passwords, to your A2A server using a secure mechanism. Cloud Run supports providing secrets as environment variables or dynamically mounted volumes. For more information, see Configure secrets in Cloud Run.

Agents need access to external services to complete their tasks. Secrets are the secure mechanism for granting that access. When deploying with AlloyDB for PostgreSQL, you need the user and password. Create and manage the database user and password secrets within Secret Manager by running the following commands in the gcloud CLI:

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"

For more information, see Create a secret.

Dockerfile for containerization

Cloud Run can deploy services either from already hosted container images or directly from your source code. When deploying from source code, Cloud Run automatically builds a container image if a Dockerfile is present in your project's root directory.

The Dockerfile determines the details of the container image. The following is the Dockerfile from the sample A2A agent you cloned earlier:

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

Deploy from source code without a Dockerfile

For source code repositories without a Dockerfile, Cloud Run offers built-in support for certain popular programming languages, simplifying the containerization process.

• Python applications on Cloud Run: Cloud Run looks for a main.py file to build and deploy Python services. For more information, see the Deploy a Python service on Cloud Run quickstart.
• Node.js applications on Cloud Run: Cloud Run looks for an index.js file to build and deploy Node.js services. See the Deploy a Node.js service on Cloud Run quickstart.

Deploy the A2A agent to Cloud Run

Deploy your A2A application with an in-memory TaskStore configuration or with AlloyDB for PostgreSQL.

• An in-memory TaskStore configuration stores all its data exclusively within the Cloud Run container instance. This means that all task data is lost when the container instance shuts down, scales down, or restarts.
• AlloyDB for PostgreSQL provides data persistence, enabling agents to scale horizontally, and ensuring tasks survive container restarts, scale events, and deployments.

An in-memory TaskStore configuration is suitable for developing A2A agents in the local environment, and AlloyDB for PostgreSQL is suitable for scaling the A2A agent in production.

The following commands show how to use IAM-based authentication for your Cloud Run service. Using the --no-allow-unauthenticated flag at deployment is the recommended approach for configuring authentication for internal Google Cloud clients, such as Gemini Enterprise.

If your A2A server is designed for public access, and needs to handle agent-level authentication, you can specify the --allow-unauthenticated flag during deployment. See Cloud Run public access authentication for more details. To allow for public access to your Cloud Run service, you must also 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.

Deploy with an in-memory TaskStore configuration

To deploy your A2A agent with an in-memory TaskStore configuration, run the following command in the directory that contains your A2A agent source code:

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"

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.
• A2A_SERVICE_ACCOUNT_NAME: the name of your A2A service account.

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

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.
• A2A_SERVICE_ACCOUNT_NAME: the name of your A2A service account.

Debug deployment failures

If you encounter errors or 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"
     

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

Test and monitor A2A agent deployment

After successfully deploying your A2A agent to Cloud Run, thoroughly test its functionality. Establish strong monitoring practices to ensure continuous performance and reliability.

A2A inspector: Validate agent compliance

Use the a2a-inspector tool to inspect, debug, and validate your deployed Google A2A agent. This tool ensures that your agent fully complies with the A2A specification and functions correctly.

After a successful connection, the inspector performs the following actions:

• Displays the agent card: Automatically shows your agent's card.
• Validates compliance: Checks that the card meets A2A specifications.
• Enables live chat: Lets you send and receive messages with the agent.
• Shows raw data: Displays raw JSON-RPC 2.0 messages in a console for debugging.

CLI interaction with a deployed A2A agent

Use the command-line interface (CLI) tools from the A2A samples repository to interact with your deployed service. This CLI supports bearer token-based authentication.

If your service uses IAM-based authentication, export the gcloud token for successful interaction:

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

Replace CLOUD_RUN_SERVICE_URL with the URL of your deployed Cloud Run service.

Note: Upon successful deployment and invocation, the agent card appears, initiating a new task and prompting you for input. Each event in the CLI includes details such as the task ID, status, and timestamp.

Local testing of deployed A2A services

You can test your deployed Cloud Run service locally. This is particularly useful when implementing IAM-based authentication.

Test IAM-based authentication for Cloud Run agents

Clients interacting with your Identity and Access Management (IAM)-secured Cloud Run service must possess the roles/run.invoker IAM role.

Locally test your deployed service authentication flow using the gcloud auth print-identity-token command:

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

Replace CLOUD_RUN_SERVICE_URL with the URL of your deployed Cloud Run service.