Introduction

What is A2UI?

A2UI (Agent-to-User-Interface) is a JSON-based streaming protocol that enables AI agents and backend services to declaratively generate and update user interfaces. Instead of generating imperative code, agents emit structured JSON messages that client renderers interpret and display in real-time.

Core Philosophy

A2UI separates concerns between:

• Agent Logic: What to display and when
• UI Rendering: How to display it beautifully
• User Interaction: How users engage with the interface

This separation enables:

• Platform Independence: Same JSON works across web, mobile, and desktop
• Version Compatibility: Renderers can be updated without changing agents
• Design System Consistency: Centralized styling and theming

Key Concepts

Declarative Syntax

• Agents describe structure and data, not imperative code
• Components are defined with properties and relationships
• State changes are expressed as data updates

Separation of Concerns

• UI structure (updateComponents) is separate from application state (updateDataModel)
• Components reference data via JSON Pointer paths
• Business logic stays in the agent, presentation stays in the renderer

Flat Adjacency List

• Components are sent as a flat array with ID references for children
• Makes JSON generation simple and streaming-friendly
• LLMs can easily construct valid component structures

Transport Agnostic

• Works over WebSocket for bidirectional streaming
• Works over SSE (Server-Sent Events) for server-to-client updates
• Works with manual message ingestion for testing

What is a2ui-shadcn?

a2ui-shadcn is a production-grade React renderer that maps A2UI protocol v0.9 to shadcn/ui components. It provides:

• Full A2UI v0.9 Compliance: All message types and 30+ components
• shadcn/ui Integration: Beautiful, accessible components out of the box
• Reactive Data Binding: Zustand-powered state management
• Two-Way Binding: Input components automatically sync with data model
• RTL Support: Full right-to-left layout for international apps
• Theme Customization: Override colors, typography, and spacing
• TypeScript First: Strongly typed APIs for safety and autocomplete
• Framework Flexible: Works with Next.js and Vite

Architecture

Use Cases

AI Chat Interfaces

• Dynamic forms and data collection
• Rich media and interactive elements
• Streaming UI updates as agent processes

Admin Dashboards

• Agent-generated analytics views
• Custom data visualizations
• Dynamic filtering and sorting

Workflow Automation

• Multi-step forms and wizards
• Conditional UI based on agent logic
• Real-time status updates

Customer Support

• Interactive troubleshooting guides
• Dynamic help documentation
• Personalized UI per user context

Protocol Messages

A2UI defines four core message types:

1. createSurface - Initialize a new UI surface with catalog and theme

2. updateComponents - Add or update UI components in flat adjacency list

3. updateDataModel - Update application state at JSON Pointer paths

4. deleteSurface - Remove a surface and clean up resources

Getting Started

Ready to build? Head to the Installation guide to set up a2ui-shadcn in your project.

For a hands-on introduction, try the Interactive Playground with live code examples.