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

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.

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

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:

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:

cd samples/client/lit
npm install

This command installs three key packages defined in 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.

Run the Demo Launcher

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

npm run demo:all

As implemented in 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:

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.

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:

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

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.

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