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

Deploy A2UI in production by pushing a stable v0.8 catalog and ADK agent to Vertex AI Agent Engine via 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.

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.
• 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.
• 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 (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 (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.

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.

Example Production Catalog

{
  "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 script automates building the ADK agent, registering it with Agent Engine, and managing deployment metadata.

Prerequisites

pip install -r samples/personalized_learning/requirements.txt

Deployment Command

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

The script executes the following steps (lines 53–120 of 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

python samples/personalized_learning/deploy.py --list

Python Agent Initialization Pattern

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 (lines 29–32).

Hosting the A2UI Frontend on Cloud Run

The 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

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

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

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.
• Versioned catalog – Store catalog JSON in GCS with a permanent URI; avoid inline catalogs.
• Agent Engine – Deploy with 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 and 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 to compile and register the ADK agent with a stable v0.8 catalog stored in GCS.
• Use 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) and external catalog patterns (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 and avoid development or beta versions for live systems.

How do I secure A2UI deployments on Cloud Run?

The 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 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).

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 (lines 58–74), inline catalogs are discouraged for production because they prevent independent versioning and updates.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}