Main Components of A2UI: The Complete Architecture Guide

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, 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, 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, this tool performs spec validation and optional asset bundling.

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

# 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 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. 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. 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 demonstrates initializing the Lit renderer within a React shell:

// 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, 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 demonstrates how agents send function responses that trigger UI updates:

# 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 and 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 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) defining UI message structure and data binding.
• Composer: TypeScript library (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) 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) 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. 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. This CLI utility accepts a directory of TypeScript widget files, validates them against the specification, and outputs a 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. The Lit renderer (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) 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.

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