# How to Install A2UI: Complete Setup Guide for Google's Agent-to-User Interface

> Install A2UI quickly by cloning the repo, setting up Node.js, configuring your Gemini API key, and running npm to launch the agent and web client on localhost.

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

---

**You can install A2UI by cloning the google/A2UI repository, installing Node.js dependencies for the Lit renderer (which includes the shared `@a2ui/web-lib`), setting your Gemini API key, and running `npm run demo:all` to launch both the Python agent and web client on localhost:5173.**

A2UI (Agent-to-User Interface) enables LLM-powered agents to describe user interfaces as JSON that client renderers convert into native components. To install A2UI and run your first agent-driven UI, you need to set up both the Python backend and a web renderer from the google/A2UI repository. This guide walks through the complete installation process using the official quickstart workflow and manual setup options.

## Prerequisites to Install A2UI

Before you begin, ensure your environment meets the minimum requirements defined in the official quickstart documentation at [`docs/quickstart.md`](https://github.com/google/A2UI/blob/main/docs/quickstart.md).

- **Node.js** version 18 or higher
- **Python** version 3.10 or higher with the **uv** package manager installed
- A **Gemini API key** exported as the environment variable `GEMINI_API_KEY`

The **uv** package manager handles Python dependency resolution automatically when running the agent samples, eliminating the need for manual `pip install` commands.

## Step-by-Step A2UI Installation

### Clone the Repository

Start by cloning the google/A2UI repository and navigating to the project root:

```bash
git clone https://github.com/google/a2ui.git
cd a2ui

```

This downloads the complete project structure, including agent samples, web renderers, and the shared core library.

### Configure Environment Variables

Export your Gemini API key so the Python agents can access the LLM backend:

```bash
export GEMINI_API_KEY="your_gemini_api_key_here"

```

The agent samples located in `samples/agent/adk/restaurant_finder/` depend on this variable being set before execution.

### Install the Web Renderer and Shared Library

Navigate to the Lit renderer directory and install dependencies. The Lit renderer is the recommended starting point because it has the fewest dependencies while demonstrating all core features:

```bash
cd samples/client/lit
npm install

```

This command installs three key packages defined in [`samples/client/lit/package.json`](https://github.com/google/A2UI/blob/main/samples/client/lit/package.json):
- `@a2ui/web-lib` – the core message processor used by all web renderers
- `lit` – the Lit web components framework
- `@lit-labs/signals` – reactive state management for the components

If you prefer React or Angular, the installation commands are similar but target `renderers/react/` or `renderers/angular/` instead, as documented in [`docs/guides/client-setup.md`](https://github.com/google/A2UI/blob/main/docs/guides/client-setup.md).

### Run the Demo Launcher

Execute the all-in-one demo script to build the project and start both the Python agent and web server:

```bash
npm run demo:all

```

As implemented in [`samples/client/lit/package.json`](https://github.com/google/A2UI/blob/main/samples/client/lit/package.json), this script performs four actions sequentially:
1. Installs any missing npm packages for the renderer and core library
2. Builds `@a2ui/web-lib` and the Lit renderer via `npm run build`
3. Starts the Python backend using `uv run .` from the agent directory
4. Launches the Vite development server, typically serving the UI on `http://localhost:5173`

Once the terminal shows the server ready message, open your browser to `http://localhost:5173` to interact with the running A2UI demo.

## Manual Python Agent Setup (Optional)

If you need to run the Python agent separately from the web client, navigate to the agent directory and use **uv** directly:

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

```

The `uv run .` command automatically installs the **google-adk** package and any other dependencies specified in the agent's configuration the first time it executes. This approach is useful when debugging agent logic independently of the frontend, as detailed in [`docs/guides/agent-development.md`](https://github.com/google/A2UI/blob/main/docs/guides/agent-development.md).

## Verifying Your Installation with Custom Transports

To verify that `@a2ui/web-lib` is properly installed and can process messages outside the demo environment, create a minimal HTML file that imports the library and connects to a custom transport:

```javascript
import {MessageProcessor} from '@a2ui/web-lib';

const processor = MessageProcessor.getInstance();
const sse = new EventSource('/a2ui-stream');

sse.onmessage = (event) => processor.process(JSON.parse(event.data));

```

This pattern uses the `MessageProcessor` singleton defined in the core library to parse incoming A2UI JSON messages. Replace the `EventSource` URL with your agent's actual endpoint. The Lit renderer demonstrates this pattern in [`renderers/lit/README.md`](https://github.com/google/A2UI/blob/main/renderers/lit/README.md) using the `<a2ui-surface>` web component.

## Summary

- **A2UI requires Node.js ≥18, Python ≥3.10 with uv, and a `GEMINI_API_KEY` environment variable** to function.
- **The fastest way to install A2UI** is running `npm install` followed by `npm run demo:all` from `samples/client/lit/`.
- **`npm run demo:all`** handles the full setup: dependency installation, library builds, Python agent startup, and Vite dev server launch on port 5173.
- **Manual installation** allows separate control of the Python agent via `uv run .` in the specific agent directory.
- **All web renderers depend on `@a2ui/web-lib`**, which provides the `MessageProcessor` class for handling agent messages.

## Frequently Asked Questions

### What are the system requirements to install A2UI?

You need Node.js version 18 or higher, Python 3.10 or higher, and the **uv** package manager. Additionally, you must obtain a Gemini API key from Google AI Studio and export it as `GEMINI_API_KEY` before running any agent samples. These requirements are strictly enforced in the quickstart guide at [`docs/quickstart.md`](https://github.com/google/A2UI/blob/main/docs/quickstart.md).

### How do I install A2UI without using the demo script?

First, install npm dependencies manually with `npm install` in your chosen renderer directory (e.g., `samples/client/lit/`). Then build the core library with `npm run build`. Finally, start the Python agent separately using `uv run .` from within the specific agent folder (such as `samples/agent/adk/restaurant_finder/`), and launch the dev server with `npm run dev` or `npx vite`.

### Can I install A2UI with React or Angular instead of Lit?

Yes. The google/A2UI repository provides official renderers for React and Angular in the `renderers/react/` and `renderers/angular/` directories. The installation process mirrors the Lit approach: navigate to the renderer directory, run `npm install`, and follow the specific README instructions for that framework. All web renderers ultimately depend on the shared `@a2ui/web-lib` package for message processing.

### Where is the A2UI Python agent code located?

The sample Python agents are located in `samples/agent/`, with the primary restaurant finder demo residing in `samples/agent/adk/restaurant_finder/`. This directory contains the agent definition that generates A2UI JSON messages. When you run `npm run demo:all` from the Lit client directory, it automatically executes `uv run .` from this agent folder to start the backend.