Host an A2UI agent with Cloud Run

This tutorial explains how to deploy an Agent-to-Agent (A2A) agent, built with the Google Agent Development Kit (ADK) and the A2UI extension, to Cloud Run. You also learn how to register the deployed agent with Gemini Enterprise.

The sample code for this tutorial has the following folder structure.

Tutorial folder structure

The project has the following folder structure:

File/Directory Description
examples/0.8/ Directory containing example configurations or data.
__init__.py Marks the directory as a Python package.
agent.py Defines the agent, its skills, and behavior.
agent_executor.py Manages the execution flow and tool interactions.
contact_data.json Sample data used by the agent (for example, mock contacts).
deploy.sh Script to build and deploy the agent to Cloud Run.
main.py The main application entry point (FastAPI app).
prompt_builder.py Helper to construct prompts for the model.
pyproject.toml Project configuration and dependencies.
tools.py Defines the tools (functions) the agent can use.

Before you begin

Before you begin, make sure you have the following:

  • The Discovery Engine Admin role.

  • An existing Gemini Enterprise app. To create an app, see Create an app.

  • Clone the repository and navigate to the cloud_run sample directory:

    git clone https://github.com/google/A2UI.git
cd A2UI/samples/agent/adk/gemini_enterprise/cloud_run

Enable APIs

Enable the following APIs for your project:

Console

Enable the following APIs:

  • Agent Platform API
  • Cloud Build API
  • Artifact Registry API
  • Cloud Run API
  • Cloud Logging API
  • Discovery Engine API
  • Cloud Storage API
  • Identity and Access Management (IAM) API

Enable APIs

REST

You can enable these APIs from the Google Cloud console or by using the following gcloud CLI command:

gcloud services enable aiplatform.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com run.googleapis.com logging.googleapis.com discoveryengine.googleapis.com storage.googleapis.com iam.googleapis.com

Grant permissions

Grant permission to the Cloud Run Invoker (roles/run.invoker) role.

gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com" \
   --role="roles/run.invoker"

Replace the following:

  • PROJECT_ID : the ID of your project.
  • PROJECT_NUMBER: Your Google Cloud project number.

Deploy the agent

The deploy.sh script automates the deployment process. To deploy your agent, run the script from the project directory with your Google Cloud ID and a name for your new service. You can also optionally specify the Gemini model to use.

The script performs the following actions:

  1. Builds a container image from your source code.
  2. Pushes the image to Artifact Registry.
  3. Deploys the image to Cloud Run.
  4. Sets environment variables, including the MODEL and the public AGENT_URL of the service itself.
chmod +x deploy.sh
./deploy.sh YOUR_PROJECT_ID contacts-agent MODEL_NAME

Replace the following:

  • PROJECT_ID: the ID of your project.
  • MODEL_NAME: Optional. This is the third argument to the script. Supported values are gemini-2.5-pro and gemini-2.5-flash. If not provided, the script defaults to gemini-2.5-flash.

Once the script completes, it prints the service URL of your deployed agent. You need this Service URL in the next step.

Register agent with Gemini Enterprise

Now that your agent is deployed, you need to register it with Gemini Enterprise to make it discoverable.

Run the following curl command, replacing the placeholders with your own values:

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/ENGINE_ID/assistants/default_assistant/agents -d '{
"name": "contacts-agent",
"displayName": "Contacts Agent",
"description": "This is a test agent which lists the contacts.",
"a2aAgentDefinition": {
  "jsonAgentCard": "{\"protocolVersion\": \"0.3.0\", \"name\": \"contacts-agent\", \"description\": \"This is a test agent which lists the contacts.\", \"url\": \"AGENT_URL\", \"version\": \"1.0.0\", \"capabilities\": {\"streaming\": true, \"extensions\": [{\"uri\": \"https://a2ui.org/a2a-extension/a2ui/v0.8\", \"description\": \"Ability to render A2UI\", \"required\": false, \"params\": {\"supportedCatalogIds\": [\"https://a2ui.org/specification/v0_8/standard_catalog_definition.json\"]}}]}, \"skills\": [], \"defaultInputModes\": [\"text/plain\"], \"defaultOutputModes\": [\"text/plain\"]}"
}
}'

Replace the following:

  • PROJECT_NUMBER: Your Google Cloud project number.
  • LOCATION: The multi-region of your data store: global, us, or eu
  • ENGINE_ID: The ID of the app with which you want to register the agent.
  • AGENT_URL: The service URL of your deployed agent.

Use the agent on the Gemini Enterprise web app

After an agent is created and registered, you can start using and interacting with it on the Gemini Enterprise web app.

Get the web app URL

To use the agent, you first need to get the web app URL. A Gemini Enterprise administrator can get and share the web app URL by following these steps:

  1. In the Google Cloud console, go to the Gemini Enterprise page.

    Gemini Enterprise

  2. Click the name of the app that you registered the agent with.

  3. Click Integrations.

  4. Copy the The link to your web app: and share it with the users in the organization.

Use the agent

To use and interact with the agent, do the following:

  1. Open the web app URL in a new browser tab.
  2. In the web app navigation menu, click Agents.
  3. Go to the From your organization section, and click the agent that you created.
  4. This opens the conversational interface for the agent. Start asking questions and interacting with the agent.

For example, you can ask the agent to list all contacts. The agent uses the list_contacts tool to retrieve the contacts from contact_data.json and renders the list in the chat using custom UI elements, as shown in the following example:

Contacts Agent Example