# How to Build A2UI from Source: Complete Setup Guide

> Learn how to build A2UI from source with this complete setup guide. Install Node.js and UV, compile TypeScript, and launch the sample client and Python agent easily.

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

---

**Build A2UI from source by installing Node.js ≥20 and the UV Python package manager, then compile the TypeScript libraries with `npm install && npm run build` in `renderers/web_core` and `renderers/lit`, followed by launching the sample client with `npm run dev` and the Python agent with `uv run .`.**

A2UI is Google's multi-language framework for building agent-to-user interfaces across Web, Angular, React, and Python environments. To build A2UI from source and run the interactive demos locally, you must compile the shared TypeScript libraries, build framework-specific renderers, and configure the Python runtime for the agent SDK. The repository is organized as a monorepo with the core data model in `renderers/web_core` and framework adapters in separate directories.

## Prerequisites

Before you build A2UI from source, install the following tools:

- **Node.js** 20 or later (bundles npm)
- **npm** (included with Node) or **pnpm** 9+ (optional, used by some samples)
- **UV** 0.2 or later (Python package manager)
- **GEMINI_API_KEY** environment variable (required for agent demos)

Install UV on macOS/Linux with:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh

```

Set your API key:

```bash
export GEMINI_API_KEY="your_key_here"

```

## Building the TypeScript Libraries

A2UI uses a layered architecture where `renderers/web_core` provides the foundation, and framework-specific packages depend on it. All builds use **Wireit** as defined in each package's [`package.json`](https://github.com/google/A2UI/blob/main/package.json).

### Compile the Web Core Foundation

Navigate to the core library and run the build pipeline:

```bash
cd renderers/web_core
npm install
npm run build

```

In [`renderers/web_core/package.json`](https://github.com/google/A2UI/blob/main/renderers/web_core/package.json), the `build` script delegates to Wireit, which executes the `build:tsc` target to compile TypeScript [2†L39-L44][2†L58-L66]. This step generates the data models and base classes required by all other renderers.

### Build the Lit Renderer

The Lit renderer is the most common frontend implementation and depends on the web core:

```bash
cd renderers/lit
npm install
npm run build

```

The Lit package's [`package.json`](https://github.com/google/A2UI/blob/main/package.json) declares `@a2ui/web_core` as a dependency and uses the same Wireit-driven `build` script pattern [3†L22-L30].

### (Optional) Build Additional Renderers

To build A2UI from source with alternative frontend support:

1. **Angular**: `cd renderers/angular && npm install && npm run build` [4†L3-L5]
2. **React**: `cd renderers/react && npm install && npm run build`
3. **Markdown**: `cd renderers/markdown/markdown-it && npm install && npm run build`

All follow the identical `npm install && npm run build` pattern defined in their respective [`package.json`](https://github.com/google/A2UI/blob/main/package.json) files.

## Running the Sample Applications

Once the libraries are compiled, you can launch the reference implementation consisting of a Lit-based client and a Python agent.

### Launch the Lit Shell Client

The "shell" sample demonstrates a complete A2UI client:

```bash
cd samples/client/lit/shell
npm install
npm run dev

```

This starts a Vite development server on `http://localhost:5173` [5†L36-L55]. The `dev` script is defined in the sample's [`package.json`](https://github.com/google/A2UI/blob/main/package.json) and uses the Vite configuration in [`tools/inspector/vite.config.ts`](https://github.com/google/A2UI/blob/main/tools/inspector/vite.config.ts) [6†L1-L5].

### Start the Python Agent Backend

In a separate terminal, run the Restaurant-Finder demo agent:

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

```

This command launches the Python agent that streams A2UI JSON to the client [5†L26-L31]. The agent requires the `GEMINI_API_KEY` environment variable to communicate with the Gemini API.

## Automated Build and Run Script

For convenience, combine all steps into a single script:

```bash
#!/bin/bash
export GEMINI_API_KEY="YOUR_KEY"

# Build core and Lit renderer

cd renderers/web_core && npm i && npm run build && cd -
cd renderers/lit && npm i && npm run build && cd -

# Launch client in background

cd samples/client/lit/shell && npm i && npm run dev &
CLIENT_PID=$!

# Launch agent

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

# Cleanup

kill $CLIENT_PID

```

This script mirrors the manual steps described in the repository's README and ensures proper build order [5†L26-L55].

## Summary

- Install **Node.js ≥20**, **npm**, and **UV** before attempting to build A2UI from source.
- Always build `renderers/web_core` first, as all framework renderers depend on it.
- Use `npm run build` (powered by Wireit) in each renderer directory to compile TypeScript.
- Launch the **Lit shell client** with `npm run dev` after building the Lit renderer.
- Start Python agents with `uv run .` in the sample directories, ensuring `GEMINI_API_KEY` is set.

## Frequently Asked Questions

### What Node.js version is required to build A2UI?

You need Node.js 20 or later. The repository uses modern TypeScript features and Wireit build orchestration that rely on Node 20+ APIs. Earlier versions may fail during the `npm run build` phase with syntax or module resolution errors.

### Why does the build fail with missing TypeScript errors?

This occurs when `node_modules` is not installed in the specific package directory or when `renderers/web_core` was not built before attempting to build a dependent renderer like Lit or Angular. Always run `npm install` in the specific subdirectory (e.g., `cd renderers/lit && npm install`) before running `npm run build`, and ensure the web core build completes successfully first.

### How do I run the Python agent samples?

Navigate to a sample directory such as `samples/agent/adk/restaurant_finder` and execute `uv run .` after setting the `GEMINI_API_KEY` environment variable. The UV tool handles dependency installation and virtual environment creation automatically. You must have UV 0.2+ installed via the official installer script.

### Can I use pnpm instead of npm to build A2UI?

Yes, several samples list `pnpm i && pnpm build` as an alternative workflow. While the core libraries use npm in their documentation, pnpm 9+ is fully compatible with the monorepo structure and may offer faster installation times due to its content-addressable store.