# How to Deploy A2UI in Production: Vertex AI Agent Engine and Cloud Run Guide

> Deploy A2UI in production using Vertex AI Agent Engine and Cloud Run. This guide details pushing your catalog and agent, then hosting the renderer for a seamless deployment.

- Repository: [Google/A2UI](https://github.com/google/A2UI)
- Tags: how-to-guide
- Published: 2026-03-13

---

**Deploy A2UI in production by pushing a stable v0.8 catalog and ADK agent to Vertex AI Agent Engine via [`deploy.py`](https://github.com/google/A2UI/blob/main/deploy.py), then hosting the Lit-based renderer on Cloud Run behind Identity-Aware Proxy (IAP) and exposing it via Firebase Hosting using [`deploy_hosting.py`](https://github.com/google/A2UI/blob/main/deploy_hosting.py).**

The google/A2UI repository (Agent-to-Agent UI) enables LLM agents to dynamically generate UI components rendered by web clients. A production-grade deployment freezes the specification, containerizes the agent backend, and secures the frontend using Google Cloud managed services.

## A2UI Production Architecture

A production deployment consists of three integrated layers that handle specification stability, agent execution, and secure rendering.

**Core Components**

- **A2UI Renderer (`lit` or `angular`)** – Runs on Cloud Run and serves static assets while hosting the A2UI JavaScript library. It proxies API calls to the agent engine to avoid CORS issues. Source: [`renderers/lit/README.md`](https://github.com/google/A2UI/blob/main/renderers/lit/README.md).
- **A2UI Web Core (`web_core`)** – Provides low-level component primitives that the Lit renderer builds upon. Source: `renderers/web_core`.
- **Vertex AI Agent Engine** – Executes the Python agent, resolves UI catalog definitions, calls Gemini models, and returns A2UI JSON responses. Deployment logic resides in [`samples/personalized_learning/deploy.py`](https://github.com/google/A2UI/blob/main/samples/personalized_learning/deploy.py).
- **Catalog (JSON)** – Describes surfaces, components, and functions the agent may render. Must be stored in Google Cloud Storage (GCS) with a stable URI for production. Reference: [`docs/concepts/catalogs.md`](https://github.com/google/A2UI/blob/main/docs/concepts/catalogs.md) (lines 58–74).
- **Cloud IAM and IAP** – Secures the Cloud Run service, restricting access to specific domains or users. Configuration is handled in [`deploy_hosting.py`](https://github.com/google/A2UI/blob/main/deploy_hosting.py) (lines 23–30).
- **Firebase Hosting** – Provides a friendly HTTPS domain (e.g., `https://<site>.web.app`) that acts as a reverse proxy to the Cloud Run service.

**Production Data Flow**

```

[Browser] --HTTPS--> [Firebase Hosting] --reverse proxy-->
[Cloud Run] --REST--> [Vertex AI Agent Engine] --JSON--> [Cloud Run] --> UI rendered by A2UI

```

All traffic is encrypted, and the agent runs in a fully managed GCP service with no servers to maintain.

## Preparing the A2UI Catalog for Production

Production deployments require a **stable specification**. Use the current production release (v0.8) so that the catalog schema, surface model, and component library are frozen and supported. Reference: [`docs/specification/v0.8-a2ui.md`](https://github.com/google/A2UI/blob/main/docs/specification/v0.8-a2ui.md).

Store the catalog JSON in a GCS bucket with a permanent URI (e.g., `https://mycompany.com/1.0/learningCatalog.json`). Inline catalogs are discouraged for production environments according to [`docs/concepts/catalogs.md`](https://github.com/google/A2UI/blob/main/docs/concepts/catalogs.md).

**Example Production Catalog**

```json
{
  "catalogId": "https://mycompany.com/1.0/learningCatalog.json",
  "surfaces": {
    "learningContent": {
      "components": [
        {
          "type": "TextBlock",
          "content": "Welcome to personalized learning!"
        },
        {
          "type": "FlashcardList",
          "functionId": "generateFlashcards"
        }
      ]
    }
  },
  "functions": {
    "generateFlashcards": {
      "description": "Generates flashcards for a given topic",
      "inputSchema": { "type": "object", "properties": { "topic": { "type": "string" } } },
      "outputSchema": { "type": "array", "items": { "$ref": "#/components/Flashcard" } }
    }
  }
}

```

Upload this file to GCS, then reference it via the `CATALOG_URI` environment variable or pass it directly to the `Agent` constructor in your deployment code.

## Deploying the A2UI Agent to Vertex AI

The [`samples/personalized_learning/deploy.py`](https://github.com/google/A2UI/blob/main/samples/personalized_learning/deploy.py) script automates building the ADK agent, registering it with Agent Engine, and managing deployment metadata.

**Prerequisites**

```bash
pip install -r samples/personalized_learning/requirements.txt

```

**Deployment Command**

```bash
python samples/personalized_learning/deploy.py --project my-gcp-project

```

The script executes the following steps (lines 53–120 of [`deploy.py`](https://github.com/google/A2UI/blob/main/deploy.py)):

1. Initializes Vertex AI via `vertexai.init` (lines 99–105).
2. Creates an `AdkApp` wrapping the `Agent` (lines 29–32).
3. Reads the `CATALOG_URI` environment variable at runtime to load the external catalog.

**Listing Existing Deployments**

```bash
python samples/personalized_learning/deploy.py --list

```

**Python Agent Initialization Pattern**

```python
import json
import os
from google.adk.agents import Agent

with open("catalog.json", "r") as f:
    catalog = json.load(f)

agent = Agent(
    surface_id="learningContent",
    catalog=catalog,
    model_id=os.getenv("GENAI_MODEL", "gemini-2.5-flash"),
)

```

This mirrors the agent creation logic found in [`deploy.py`](https://github.com/google/A2UI/blob/main/deploy.py) (lines 29–32).

## Hosting the A2UI Frontend on Cloud Run

The [`samples/personalized_learning/deploy_hosting.py`](https://github.com/google/A2UI/blob/main/samples/personalized_learning/deploy_hosting.py) script automates containerization, IAP configuration, and Firebase Hosting linkage.

**Prerequisites**

- gcloud CLI authenticated (`gcloud auth login`)
- Firebase CLI installed (`npm install -g firebase-tools`)
- Firebase project linked to GCP (`firebase use --add`)

**Full Deployment Command**

```bash
python samples/personalized_learning/deploy_hosting.py \
    --project my-gcp-project \
    --service-name personalized-learning-demo \
    --region us-central1 \
    --allow-domain example.com

```

**Script Execution Steps** (lines 63–200 of [`deploy_hosting.py`](https://github.com/google/A2UI/blob/main/deploy_hosting.py)):

1. **Prepare build context** – Copies `web_core` and `lit` renderer dependencies into a temporary directory.
2. **Enable APIs** – Activates `run.googleapis.com` and `cloudbuild.googleapis.com` (lines 81–92).
3. **Build and push** – Uses Cloud Build to create a container image and pushes it to Artifact Registry.
4. **Deploy to Cloud Run** – Configures minimum instance settings and enables IAP (lines 23–30).
5. **Configure Firebase Hosting** – Links the Cloud Run service to a friendly HTTPS endpoint.

**Domain Restrictions**

The `--allow-domain` flag configures IAP to restrict access to specific corporate domains (lines 38–40). For production, tighten these rules to the minimum set of accounts requiring UI access.

**Verification**

```bash
gcloud run services list --project my-gcp-project
curl -v https://<service-name>-<region>.run.app

```

If the UI loads correctly, the Cloud Run service is successfully proxying requests to the Vertex AI Agent Engine.

## Production Deployment Checklist

Verify these items before handling live traffic:

- **Stable specification** – Pin to v0.8 per [`docs/specification/v0.8-a2ui.md`](https://github.com/google/A2UI/blob/main/docs/specification/v0.8-a2ui.md).
- **Versioned catalog** – Store catalog JSON in GCS with a permanent URI; avoid inline catalogs.
- **Agent Engine** – Deploy with [`deploy.py`](https://github.com/google/A2UI/blob/main/deploy.py); set `GENAI_MODEL` environment variable to a production-grade Gemini model.
- **Cloud Run concurrency** – Configure minimum instance concurrency in deployment flags if needed.
- **IAP restrictions** – Limit access to corporate Google accounts or specific domains using `--allow-domain`.
- **Service account permissions** – Grant `roles/run.invoker` to IAP-enabled identities and `aiplatform.user` plus `storage.objectViewer` to the agent service account.
- **Monitoring** – Enable Cloud Monitoring and Logging for both Cloud Run and Vertex AI; set alerts on error rates.
- **CI/CD integration** – Wrap [`deploy.py`](https://github.com/google/A2UI/blob/main/deploy.py) and [`deploy_hosting.py`](https://github.com/google/A2UI/blob/main/deploy_hosting.py) in Cloud Build steps or GitHub Actions for repeatable releases.

## Summary

- **Deploy A2UI in production** using a two-step process: agent deployment to Vertex AI Agent Engine and frontend hosting on Cloud Run.
- **Use [`samples/personalized_learning/deploy.py`](https://github.com/google/A2UI/blob/main/samples/personalized_learning/deploy.py)** to compile and register the ADK agent with a stable v0.8 catalog stored in GCS.
- **Use [`samples/personalized_learning/deploy_hosting.py`](https://github.com/google/A2UI/blob/main/samples/personalized_learning/deploy_hosting.py)** to containerize the Lit renderer, enable IAP security, and expose the service via Firebase Hosting.
- **Reference the v0.8 specification** ([`docs/specification/v0.8-a2ui.md`](https://github.com/google/A2UI/blob/main/docs/specification/v0.8-a2ui.md)) and external catalog patterns ([`docs/concepts/catalogs.md`](https://github.com/google/A2UI/blob/main/docs/concepts/catalogs.md), lines 58–74) to ensure production stability.
- **Secure the deployment** with IAP domain restrictions and least-privilege service accounts before accepting production traffic.

## Frequently Asked Questions

### What is the minimum A2UI specification version required for production?

Use **v0.8** for all production deployments. This version freezes the catalog schema, surface model, and component library, ensuring backward compatibility and support. Reference the stable specification in [`docs/specification/v0.8-a2ui.md`](https://github.com/google/A2UI/blob/main/docs/specification/v0.8-a2ui.md) and avoid development or beta versions for live systems.

### How do I secure A2UI deployments on Cloud Run?

The [`deploy_hosting.py`](https://github.com/google/A2UI/blob/main/deploy_hosting.py) script automatically enables **Identity-Aware Proxy (IAP)** during deployment (lines 23–30). Restrict access using the `--allow-domain` flag to whitelist specific corporate domains (lines 38–40), or configure IAM bindings manually to limit invocation to specific Google accounts or service accounts with the `roles/run.invoker` role.

### Can I deploy the A2UI agent without Vertex AI Agent Engine?

The provided [`deploy.py`](https://github.com/google/A2UI/blob/main/deploy.py) script is specifically designed for **Vertex AI Agent Engine**, which offers a managed, serverless environment for ADK agents. While you could theoretically run the agent in a custom container, the production reference implementation in `google/A2UI` relies on Agent Engine for scaling, monitoring, and secure model access via `vertexai.init` (lines 99–105 of [`deploy.py`](https://github.com/google/A2UI/blob/main/deploy.py)).

### Where should I store the A2UI catalog in production?

Store the catalog JSON file in **Google Cloud Storage** with a permanent, versioned URI (e.g., `https://mycompany.com/1.0/learningCatalog.json`). Set the `CATALOG_URI` environment variable to this location, or pass the URI directly to the `Agent` constructor. According to [`docs/concepts/catalogs.md`](https://github.com/google/A2UI/blob/main/docs/concepts/catalogs.md) (lines 58–74), inline catalogs are discouraged for production because they prevent independent versioning and updates.