How to Build A2UI from Source: Complete Setup Guide

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:

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

Set your API key:

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.

Compile the Web Core Foundation

Navigate to the core library and run the build pipeline:

cd renderers/web_core
npm install
npm run build

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

cd renderers/lit
npm install
npm run build

The Lit package's 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 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:

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 and uses the Vite configuration in tools/inspector/vite.config.ts [6†L1-L5].

Start the Python Agent Backend

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

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:

#!/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.

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