Host A2A agents on Cloud Run overview

This guide provides an overview of how to prepare and configure Agent2Agent (A2A) agents for deployment on Cloud Run. It covers essential steps such as setting up a cloud environment, configuring required Identity and Access Management (IAM) roles, and preparing your agent for deployment.

A2A agent deployment roadmap

To deploy your agent, complete the following steps:

Prerequisite for A2A agent development and deployment

Before you begin developing and deploying your A2A agent, you should familiarize yourself with the following foundational concepts and available resources:

High-level architecture overview

The A2A Agent's core is a serving and orchestration layer, such as Cloud Run. This layer manages interactions with AI models like Gemini and Vertex AI, memory storages like AlloyDB and A2A TaskStore, and external tools through APIs. Clients interact with the agent by sending requests, such as "Get Agent Card" or "send message," and receive task updates.

The following diagram illustrates the architecture of an A2A Agent system, showing an A2A Client (user or agent) interacting with the A2A Agent.

A2A Agent architecture showing client interaction with the agent through a serving and orchestration layer.
A2A agent architecture

For information about A2A request lifecycle, see the A2A Request Lifecycle section.

IAM roles and permissions for Cloud Run A2A agents

Properly configured IAM roles are important for your Cloud Run service to interact securely with other Google Cloud services. Create a dedicated service account and grant the specific permissions listed in the following sections to ensure operational security and efficiency.

Create a Cloud Run service account

Before you run any gcloud commands, ensure you are authenticated. Run the following command to sign in to your Google Cloud account:

gcloud auth login

Create a service account specifically for your deployed A2A service instance. Use the gcloud iam service-accounts create command.

gcloud iam service-accounts create a2a-service-account \
  --description="Service account for A2A Cloud Run service" \
  --display-name="A2A Cloud Run Service Account"

Configure IAM roles for A2A agent

Assign the following IAM roles to your service account based on the Google Cloud services your A2A agent interacts with:

Secret Manager access for secure credentials

  • Role: Secret Manager Secret Accessor (roles/secretmanager.secretAccessor)

  • Purpose: Allows the Cloud Run service account to securely fetch secrets, such as database credentials, from Secret Manager.

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:a2a-service-account@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

Vertex AI model access for AI capabilities

  • Role: Vertex AI User (roles/aiplatform.user)

  • Purpose: Required for the Cloud Run service account to invoke prediction APIs on Vertex AI models.

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:a2a-service-account@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

Alloy DB instance access for persistent storage (if applicable)

  • Roles: AlloyDB Client (roles/alloydb.client) and Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

  • Purpose: Enables the Cloud Run service identity to interact with the AlloyDB cluster for persistent task storage, which is crucial for production A2A agents.

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:a2a-service-account@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/alloydb.client"

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:a2a-service-account@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/serviceusage.serviceUsageConsumer"

Prepare A2A agent for Cloud Run deployment

This section describes the configurations required to prepare your A2A agent for deployment to Cloud Run, ensuring secure, efficient, and scalable operation in the cloud.

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 Configuring secrets in Cloud Run.

For example, create and manage database user and password secrets within Google Secret Manager using the gcloud CLI. For more information, see Create a secret.

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"

Create 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 following is a sample Dockerfile for A2A agent deployment:

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 in-built support for certain popular programming languages, simplifying the containerization process.

What's next