Skip to content

client-setup.md

Latest commit

 

History

History
171 lines (114 loc) · 6.91 KB

client-setup.md

File metadata and controls

171 lines (114 loc) · 6.91 KB

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
Jetpack Compose Android — — 🚧 Planned Q2 2026

For more see all A2UI Renderers and Community A2UI Renderers.

Component Catalogs

A component catalog is any collection of components. A2UI provides a "Basic Catalog" but we expect you will add your own components, or shared libraries or fully replace the basic components with your own.

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 Defining Your Own Catalog for how to define a catalog that matches your design system.

Shared Web Library

All web renderers (Lit, Angular, React) share a common foundation: @a2ui/web_core. 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.

The shared web_core library provides:

  • Message Processor: Manages A2UI state and processes incoming messages.

Web Components (Lit)

npm install @a2ui/lit @a2ui/web_core

Once installed, you can use the renderer in your app. The Lit renderer uses:

  • Message Processor: Wraps the A2UI message processor.
  • <a2ui-surface> component: Renders surfaces in your app.
  • Lit Signals: Provides reactive state management for automatic UI updates.

See working example: Lit shell sample — Check its README for detailed run instructions.

Angular

npm install @a2ui/angular @a2ui/web_core

Once installed, you can use the renderer in your app. The Angular renderer provides:

  • A2uiRendererService: A service that manages the A2UI message processor and reactive model.
  • a2ui-v09-component-host component: A dynamic component host that renders A2UI components from a surface.
  • A2UI_RENDERER_CONFIG token: Used to configure the renderer with catalogs and action handlers.

Setup Example (v0.9)

A2UI uses versioned imports for its protocol-specific implementations. For v0.9, configure your application providers as follows:

import { ApplicationConfig } from '@angular/core';
import { 
  A2UI_RENDERER_CONFIG, 
  A2uiRendererService, 
  minimalCatalog 
} from '@a2ui/angular/v0_9';

export const appConfig: ApplicationConfig = {
  providers: [
    {
      provide: A2UI_RENDERER_CONFIG,
      useValue: {
        catalogs: [minimalCatalog],
        actionHandler: (action) => {
          console.log('Action dispatched:', action);
        }
      }
    },
    A2uiRendererService
  ]
};

See working example: Angular samples

Streaming

By default, the Angular client uses the non-streaming API. To enable streaming, set the ENABLE_STREAMING environment variable to true before starting the app:

export ENABLE_STREAMING=true
npm start -- restaurant

React

npm install @a2ui/react @a2ui/web_core

The React renderer provides:

  • MessageProcessor class: A class that manages the A2UI message processor and reactive model.
  • <A2UISurface> component: Renders A2UI surfaces in your React app
  • useA2UI() hook: Accesses the message processor from any component

See working example: React shell

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

See samples/client/lit/shell/client.ts for an example of using the A2A protocol client.

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

See the @a2uiaction event handler in #maybeRenderData in samples/client/lit/shell/app.ts for an example of handling button clicks and form submissions.

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.

See try...catch blocks in #sendMessage in samples/client/lit/shell/app.ts for examples of handling communication errors.

Next Steps