How to Set Up an A2UI Local Development Environment

Setting up an A2UI local development environment requires Node.js ≥18, Python 3.10+, the uv package manager, and a Gemini API key to clone the repository, install dependencies, and run the full-stack restaurant finder demo with the Lit renderer.

A2UI (Agent-to-UI) is a Google framework that enables generative AI agents to produce declarative JSON messages rendered as native UI components on the client. This guide walks through configuring the complete A2UI local development environment using the repository's three-layer architecture—specifications, the core message engine, and framework renderers—to build and extend interactive agent-driven applications.

Prerequisites and System Requirements

Before cloning the repository, ensure your system meets the following baseline requirements for the A2UI local development environment:

• Node.js version 18 or higher (required for all web renderers)
• Python version 3.10 or higher (for the sample agent)
• uv – the fast Python package manager from Astral (installs dependencies and runs the agent)
• Gemini API key – the sample restaurant finder agent requires access to Google Gemini to generate A2UI protocol messages

Install uv using the official installer script if it is not already available:

curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.cargo/bin:$PATH"

Understanding the Repository Structure

The google/A2UI repository organizes code into three logical layers. Understanding this structure is essential for navigating the A2UI local development environment effectively.

Layer	Purpose	Key Locations
Specification & Catalogs	Defines the A2UI protocol (v0.8 and v0.9) and standard component schemas	specification/ (e.g., v0_9/json/), docs/guides/renderer-development.md
Core Message Engine	Framework-agnostic processor shared by all web renderers (@a2ui/web-lib)	renderers/web_core/ – contains MessageProcessor, SurfaceModel, validation logic
Renderers & Samples	Concrete UI bindings and end-to-end demos	renderers/react/, renderers/lit/, renderers/angular/, samples/client/lit/, samples/agent/adk/restaurant_finder/

The Web Core layer in renderers/web_core/ implements the shared TypeScript library including MessageProcessor, SurfaceGroupModel, and expression parsing. All renderers depend on this core package, allowing you to switch between React, Lit, or Angular without rewriting protocol logic.

Step-by-Step Installation Guide

Follow these exact commands to configure your A2UI local development environment from a fresh terminal. All paths are relative to the repository root.

1. Clone the Repository

git clone https://github.com/google/A2UI.git
cd A2UI

2. Export Required Environment Variables

The sample agent requires a Gemini API key to stream generative UI messages:

export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

3. Install Client Dependencies

The Lit renderer is the recommended starting point for the A2UI local development environment due to its minimal dependency tree. Navigate to the sample client and install packages:

cd samples/client/lit
npm install

This command pulls @a2ui/web-lib (the core message engine), lit, and @lit-labs/signals as defined in the client setup documentation at docs/guides/client-setup.md.

Running the Full-Stack Demo

With dependencies installed, launch the complete application stack using the provided npm script. This command orchestrates both the Python agent and the Vite development server:

npm run demo:all

The demo:all script performs three operations sequentially:

1. Synchronizes Python dependencies using uv sync
2. Starts the restaurant finder agent with uv run . (located in samples/agent/adk/restaurant_finder/)
3. Boots the Vite dev server on http://localhost:5173

The Python agent streams A2UI protocol messages (JSONL format) to the client, where the MessageProcessor in renderers/web_core/ parses surfaceUpdate and dataModelUpdate messages before triggering rendering.

Development Workflow

For iterative development in your A2UI local development environment, run the agent and client in separate terminals to enable hot reloading and independent debugging.

Terminal 1 – Agent Process:

cd samples/agent/adk/restaurant_finder
uv run .

Terminal 2 – Client Dev Server:

cd samples/client/lit
npm run dev

The Vite dev server watches the src/ directory and rebuilds automatically when you modify renderer code or component mappings. Because all UI state lives in the core library (@a2ui/web-lib), you can focus exclusively on mapping A2UI component types to framework-specific widgets in the thin renderer layer.

Core Architecture Highlights

When extending the A2UI local development environment, reference these key architectural components implemented in the source code.

MessageProcessor – Located in @a2ui/web_core, this class parses the JSONL stream from agents, buffers surfaceUpdate and dataModelUpdate messages, and triggers rendering only after receiving beginRendering (v0.8) or createSurface (v0.9) signals.

SurfaceModel / SurfaceGroupModel – These classes maintain per-surface component trees and data models, enabling multiple independent UI surfaces to coexist on a single page without state collision.

ComponentModel – Stores the adjacency-list representation defined in the specification (see specification/v0_9/json/server_to_client_list.json) and resolves it into a renderable tree structure for the target framework.

Data Binding Resolution – BoundValue objects may contain literals, paths, or both. The core library resolves paths against the surface's data model according to the "Data Binding Resolution" section in docs/guides/renderer-development.md.

Extending with Custom Components

To add a custom component in the A2UI local development environment, define the mapping in your renderer's component registry. The Lit renderer at renderers/lit/src/0.8/index.js demonstrates this pattern by re-exporting core functionality and registering framework-specific implementations.

Example custom component definition:

// src/custom-components.ts
import { defineComponent } from '@a2ui/web_lib';
import { html } from 'lit';

export const FancyBadge = defineComponent('FancyBadge', (props) => {
  return html`<span class="badge">${props.text}</span>`;
});

Register this mapping in the Lit renderer's component map, then reference FancyBadge in your agent-generated A2UI messages to render it within the surface managed by SurfaceModel.

Summary

• A2UI enables agents to generate declarative UI through JSON messages processed by the @a2ui/web-lib core engine.
• Prerequisites for the A2UI local development environment include Node ≥18, Python 3.10+, uv, and a GEMINI_API_KEY.
• Repository layers include Specifications, Web Core (renderers/web_core/), and concrete renderers (Lit, React, Angular).
• Quick start uses npm run demo:all in samples/client/lit/ to launch both the Python agent and Vite dev server on port 5173.
• Architecture relies on MessageProcessor for stream parsing and SurfaceModel for state management, allowing renderers to remain thin mapping layers.

Frequently Asked Questions

What are the minimum system requirements for A2UI development?

You need Node.js version 18 or higher, Python 3.10 or higher, and the uv package manager. The restaurant finder demo also requires a Gemini API key because the sample Python agent streams Google Gemini-generated A2UI messages. All renderers share the core TypeScript library located in renderers/web_core/.

How does the MessageProcessor handle incoming agent messages?

The MessageProcessor class in @a2ui/web-lib parses the JSONL stream from the agent and buffers surfaceUpdate and dataModelUpdate messages. It triggers rendering only after receiving a beginRendering (v0.8) or createSurface (v0.9) message, ensuring the complete component tree is available before the first paint. This implementation is detailed in docs/guides/renderer-development.md.

Can I develop with React or Angular instead of Lit?

Yes. The repository includes renderers for React (renderers/react/), Angular (renderers/angular/), and Lit (renderers/lit/). All depend on the shared @a2ui/web-lib core in renderers/web_core/, so you can switch frameworks by installing the respective client dependencies and following the same MessageProcessor integration pattern. The Lit renderer is recommended for initial setup due to its minimal footprint.

Where is the A2UI protocol specification defined?

The canonical protocol definitions live in specification/v0_9/json/server_to_client_list.json for version 0.9, with v0.8 specifications in the adjacent directory. These JSON files define valid message types including createSurface, surfaceUpdate, and dataModelUpdate that the MessageProcessor validates against at runtime.

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