# How to Set Up an A2UI Local Development Environment

> Set up your A2UI local development environment quickly. Follow our guide to install Node.js Python uv and get your Gemini API key to run the full-stack demo.

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

---

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

```bash
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`](https://github.com/google/A2UI/blob/main/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

```bash
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:

```bash
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:

```bash
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`](https://github.com/google/A2UI/blob/main/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:

```bash
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:**

```bash
cd samples/agent/adk/restaurant_finder
uv run .

```

**Terminal 2 – Client Dev Server:**

```bash
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`](https://github.com/google/A2UI/blob/main/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`](https://github.com/google/A2UI/blob/main/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`](https://github.com/google/A2UI/blob/main/renderers/lit/src/0.8/index.js) demonstrates this pattern by re-exporting core functionality and registering framework-specific implementations.

Example custom component definition:

```ts
// 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`](https://github.com/google/A2UI/blob/main/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`](https://github.com/google/A2UI/blob/main/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.