Skip to content

Client Setup Guide

Integrate A2UI into your application using the renderer for your platform.

Renderers

Renderer Platform v0.8 v0.9 Status
React Web ✅ ❌ ✅ Stable
Lit (Web Components) Web ✅ ✅ ✅ Stable
Angular Web ✅ ✅ ✅ Stable
Flutter (GenUI SDK) Mobile/Desktop/Web ✅ ✅ ✅ Stable
SwiftUI iOS/macOS — — 🚧 Planned Q2 2026
Jetpack Compose Android — — 🚧 Planned Q2 2026

Component Catalogs

A component catalog is any collection of components — standard ones, your custom components, or shared libraries. Your design system is what matters. You can register any collection of components and functions, and A2UI will work with them. The catalog is just the contract between your agent and your renderer.

See Custom Components for how to extend or replace the standard catalog.

Shared Web Library

All web renderers (Lit, Angular, React) share a common foundation: @a2ui/web-lib. This library provides the message processor, state management, and data binding logic that every web renderer needs. Each framework-specific renderer builds on top of it, adding only the rendering layer for its framework.

This means core protocol handling is consistent across web platforms — only the component rendering differs.

Web Components (Lit)

⚠️ Attention

The Lit client library is not yet published to NPM. Check back in the coming days.

npm install @a2ui/web-lib lit @lit-labs/signals

The Lit renderer uses:

  • Message Processor: Manages A2UI state and processes incoming messages
  • <a2ui-surface> component: Renders surfaces in your app
  • Lit Signals: Provides reactive state management for automatic UI updates

TODO: Add verified setup example.

See working example: Lit shell sample

Angular

⚠️ Attention

The Angular client library is not yet published to NPM. Check back in the coming days.

npm install @a2ui/angular @a2ui/web-lib

The Angular renderer provides:

  • provideA2UI() function: Configures A2UI in your app config
  • Surface component: Renders A2UI surfaces
  • MessageProcessor service: Handles incoming A2UI messages

TODO: Add verified setup example.

See working example: Angular restaurant sample

Flutter (GenUI SDK)

flutter pub add flutter_genui

Flutter uses the GenUI SDK which provides native A2UI rendering.

Docs: GenUI SDK | GitHub | README in GenUI Flutter Package

Connecting to Agents

Your client application needs to: 1. Receive A2UI messages from the agent (via transport) 2. Process messages using the Message Processor 3. Send user actions back to the agent

Common transport options: - Server-Sent Events (SSE): One-way streaming from server to client - WebSockets: Bidirectional real-time communication - A2A Protocol: Standardized agent-to-agent communication with A2UI support

TODO: Add transport implementation examples.

See: Transports guide

Handling User Actions

When users interact with A2UI components (clicking buttons, submitting forms, etc.), the client: 1. Captures the action event from the component 2. Resolves any data context needed for the action 3. Sends the action to the agent 4. Processes the agent's response messages

TODO: Add action handling examples.

Error Handling

Common errors to handle: - Invalid Surface ID: Surface referenced before beginRendering (v0.8) or createSurface (v0.9) was received - Invalid Component ID: Component IDs must be unique within a surface - Invalid Data Path: Check data model structure and JSON Pointer syntax - Schema Validation Failed: Verify message format matches A2UI specification

TODO: Add error handling examples.

Next Steps