# Main Components of A2UI: The Complete Architecture Guide

> Explore the main components of A2UI: Specification, Composer, Renderers, and more. Understand how this architecture allows LLM agents to declare UIs with JSON schema for type-safe rendering.

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

---

**A2UI consists of eight integrated components—Specification, Composer, Build Catalog Tool, Renderers, Inspector UI, Agent SDKs, Samples, and Documentation—that enable LLM agents to declare user interfaces via JSON schema and render them through type-safe client libraries.**

The google/A2UI repository provides a modular Agent-to-UI (A2UI) framework that bridges large language model outputs with interactive web interfaces. Understanding the main components of A2UI is essential for developers building agent-driven applications, as each module handles a specific stage in the pipeline from LLM function response to rendered DOM elements.

## Specification

The **Specification** defines the canonical JSON schema that governs all agent-to-client communication. Located at [`specification/v0_10/json/server_to_client.json`](https://github.com/google/A2UI/blob/main/specification/v0_10/json/server_to_client.json), this versioned schema establishes the structure for catalogs, components, data binding, and server-to-client actions.

According to the google/A2UI source code, agents generate UI by emitting messages that strictly conform to this specification. The schema ensures that widget definitions, data streams, and interaction handlers remain consistent across different agent implementations and rendering targets.

## Composer

The **Composer** is a TypeScript library found in `tools/composer` that provides type-safe helpers for defining widgets. Developers use the Composer API to write widget definitions that serve as the building blocks of a catalog.

Key source files include [`tools/composer/src/types/widget.ts`](https://github.com/google/A2UI/blob/main/tools/composer/src/types/widget.ts), which exports TypeScript interfaces for widget properties and event handlers. The Composer also includes a command-line interface that validates widget definitions against the specification schema before they enter the build pipeline.

## Build Catalog Tool

The **Build Catalog Tool** is a Python utility that compiles widget definitions into a deployable catalog. Implemented in [`tools/build_catalog/build_catalog.py`](https://github.com/google/A2UI/blob/main/tools/build_catalog/build_catalog.py), this tool performs spec validation and optional asset bundling.

The following example demonstrates how to generate a catalog from TypeScript widget definitions:

```python

# tools/build_catalog/build_catalog.py

from pathlib import Path
from build_catalog import build_catalog

# Directory containing widget definition .ts files

widget_dir = Path("tools/composer/src/widgets")

# Output catalog file

output = Path("specification/v0_10/json/catalog.json")

build_catalog(widget_dir, output, spec_version="0.10")

```

This Python CLI accepts a directory of widget files and outputs a validated [`catalog.json`](https://github.com/google/A2UI/blob/main/catalog.json) file that renderers consume at runtime.

## Renderers

**Renderers** are front-end libraries that transform catalog definitions into live DOM elements. The google/A2UI repository ships two official renderer implementations:

### Web-Core

The **Web-Core** renderer is a framework-agnostic implementation written in vanilla TypeScript, configured via [`renderers/web_core/tsconfig.json`](https://github.com/google/A2UI/blob/main/renderers/web_core/tsconfig.json). This renderer suits applications requiring minimal dependencies or custom framework integrations.

### Lit

The **Lit** renderer is built on the Lit web-components library, with its entry point at [`renderers/lit/src/index.ts`](https://github.com/google/A2UI/blob/main/renderers/lit/src/index.ts). This is the renderer used by the sample React wrapper to mount A2UI components in React applications.

Both renderers ingest the catalog JSON, create the corresponding UI elements, and establish data binding to agent streams. The React sample at [`samples/client/react/shell/src/theme/default-theme.ts`](https://github.com/google/A2UI/blob/main/samples/client/react/shell/src/theme/default-theme.ts) demonstrates initializing the Lit renderer within a React shell:

```tsx
// samples/client/react/shell/src/App.tsx
import React, { useEffect } from "react";
import { renderA2UI } from "@a2ui/lit-renderer";
import catalog from "./catalog.json";

export default function App() {
  useEffect(() => {
    // Initialise the Lit renderer with the catalog and a WebSocket URL
    renderA2UI({
      catalog,
      wsUrl: "wss://my-agent.example.com/stream",
      root: document.getElementById("a2ui-root")!,
    });
  }, []);

  return <div id="a2ui-root" />;
}

```

## Inspector UI

The **Inspector UI** provides a developer-tool interface for debugging running catalogs. Located in [`tools/inspector/ui/ui.ts`](https://github.com/google/A2UI/blob/main/tools/inspector/ui/ui.ts), this component visualizes the catalog tree, displays real-time data flow, and supports hot-reloading of widgets during development.

Developers can launch the Inspector alongside a client application to inspect widget state and verify that agent messages correctly propagate through the UI layer.

## Agent SDKs

**Agent SDKs** handle the transport layer between LLM backends and the UI client. The repository currently maintains a **Python SDK** that formats messages, loads catalogs, and manages WebSocket or HTTP streaming.

The SDK implementation in [`agent_sdks/python/tests/test_a2a.py`](https://github.com/google/A2UI/blob/main/agent_sdks/python/tests/test_a2a.py) demonstrates how agents send function responses that trigger UI updates:

```python

# agent_sdks/python/example_agent.py

from a2ui_sdk import A2UIClient

client = A2UIClient(ws_url="ws://localhost:8080")
client.send_function_response(
    function_name="show_quiz",
    arguments={"question": "What is the capital of France?"},
)

```

As implemented in the google/A2UI source code, the Python SDK manages connection lifecycle and message serialization according to the specification schema.

## Samples and Documentation

The **Samples** directory contains end-to-end integrations demonstrating React, Angular, Lit, and personalized-learning implementations. The React sample illustrates how to configure themes and initialize the Lit renderer within a React application.

**Documentation** includes architectural guides such as [`docs/concepts/overview.md`](https://github.com/google/A2UI/blob/main/docs/concepts/overview.md) and [`docs/guides/renderer-development.md`](https://github.com/google/A2UI/blob/main/docs/guides/renderer-development.md), which explain data-flow patterns and provide steps for building custom renderers.

## How the Components Fit Together

The main components of A2UI operate in a sequential pipeline:

1. An **Agent** generates a function response conforming to the **Specification** schema.
2. Developers use the **Composer** to define widgets, then the **Build Catalog Tool** compiles these into a [`catalog.json`](https://github.com/google/A2UI/blob/main/catalog.json) file.
3. The **Renderer** (Web-Core or Lit) loads the catalog and instantiates UI elements in the browser.
4. The **Agent SDK** maintains the WebSocket connection, streaming data updates to the rendered components.
5. The **Inspector UI** attaches to the client for debugging and hot-reload capabilities.

## Summary

- **Specification**: Versioned JSON schema ([`specification/v0_10/json/server_to_client.json`](https://github.com/google/A2UI/blob/main/specification/v0_10/json/server_to_client.json)) defining UI message structure and data binding.
- **Composer**: TypeScript library ([`tools/composer/src/types/widget.ts`](https://github.com/google/A2UI/blob/main/tools/composer/src/types/widget.ts)) for type-safe widget definition and CLI validation.
- **Build Catalog Tool**: Python utility ([`tools/build_catalog/build_catalog.py`](https://github.com/google/A2UI/blob/main/tools/build_catalog/build_catalog.py)) that compiles widgets into validated catalog files.
- **Renderers**: Web-Core (vanilla TypeScript) and Lit (web components) libraries that render catalogs to the DOM.
- **Inspector UI**: Developer tool ([`tools/inspector/ui/ui.ts`](https://github.com/google/A2UI/blob/main/tools/inspector/ui/ui.ts)) for visualizing catalog state and data flow.
- **Agent SDKs**: Python SDK (`agent_sdks/python`) that handles transport and message formatting for LLM agents.
- **Samples**: Working React, Angular, and Lit integrations demonstrating end-to-end usage.
- **Documentation**: Guides for architecture, theming, and custom renderer development.

## Frequently Asked Questions

### What file defines the canonical schema for A2UI messages?

The canonical schema is defined in [`specification/v0_10/json/server_to_client.json`](https://github.com/google/A2UI/blob/main/specification/v0_10/json/server_to_client.json). This file establishes the JSON structure that all agents must use when generating UI descriptions, including field definitions for catalogs, components, and action handlers.

### How do I compile widget definitions into a catalog?

Use the Python Build Catalog Tool located at [`tools/build_catalog/build_catalog.py`](https://github.com/google/A2UI/blob/main/tools/build_catalog/build_catalog.py). This CLI utility accepts a directory of TypeScript widget files, validates them against the specification, and outputs a [`catalog.json`](https://github.com/google/A2UI/blob/main/catalog.json) file that renderers consume at runtime.

### Which renderer should I use for a React application?

Use the **Lit renderer** via the React wrapper demonstrated in [`samples/client/react/shell/src/theme/default-theme.ts`](https://github.com/google/A2UI/blob/main/samples/client/react/shell/src/theme/default-theme.ts). The Lit renderer ([`renderers/lit/src/index.ts`](https://github.com/google/A2UI/blob/main/renderers/lit/src/index.ts)) provides web components that integrate cleanly with React's component lifecycle, while the framework-agnostic **Web-Core** renderer suits vanilla TypeScript projects.

### How does the Inspector UI help during development?

The Inspector UI ([`tools/inspector/ui/ui.ts`](https://github.com/google/A2UI/blob/main/tools/inspector/ui/ui.ts)) visualizes the live catalog tree, displays real-time data bindings between agents and components, and enables hot-reloading of widgets without restarting the client application. This accelerates debugging of agent-to-UI data flows.