Installation

@flabbergasted-ai/react and @flabbergasted-ai/tokens come along as dependencies; add them explicitly only if you also use Flab directly. React and react-dom are peer dependencies.

pnpm add @flabbergasted-ai/a2ui# npm i / yarn add / bun add all work too

In your global stylesheet, after Tailwind. The token import must follow Tailwind so its @theme registration can extend it. Point @source at both Flab and the A2UI renderer's shipped files, so Tailwind generates the utilities the adapters use (the renderer adds a few layout classes of its own).

/* app/globals.css */@import 'tailwindcss';@import '@flabbergasted-ai/tokens/css';
@source '../node_modules/@flabbergasted-ai/react/dist';@source '../node_modules/@flabbergasted-ai/a2ui/dist';

A2UI renders Flab components, so the theme setup is identical: wrap your app in FlabThemeProvider and run themeInitScript in the document head so the light/dark class is set before first paint. Visual styling is owned by the Flab theme — the agent never sends colours.

// app/layout.tsx (Next.js App Router)import { FlabThemeProvider } from '@flabbergasted-ai/react';import { themeInitScript } from '@flabbergasted-ai/react/theme-script';import './globals.css';
export default function RootLayout({ children }: { children: React.ReactNode }) {  return (    <html lang="en" suppressHydrationWarning>      <head>        <script dangerouslySetInnerHTML={{ __html: themeInitScript() }} />      </head>      <body data-flab-root className="bg-canvas text-primary">        <FlabThemeProvider>{children}</FlabThemeProvider>      </body>    </html>  );}

An A2uiClient consumes a transport, parses the agent's message stream, and maintains a store of surfaces. Subscribe to that store, then hand a surface to <A2UISurface>. Pass client.onAction so user interactions travel back to the agent. This example uses the in-memory transport for a local demo.

'use client';
import {  FLAB_CATALOG_ID,  A2uiClient,  A2UISurface,  createMemoryTransport,  type RendererAction,} from '@flabbergasted-ai/a2ui';import { useEffect, useMemo, useSyncExternalStore } from 'react';
export function AgentView() {  const transport = useMemo(() => createMemoryTransport(), []);  const client = useMemo(() => new A2uiClient(transport), [transport]);
  useEffect(() => {    const disconnect = client.connect();    // Demo: push a stream. In production this arrives from the agent.    transport.push({      version: 'v1.0',      createSurface: { surfaceId: 'main', catalogId: FLAB_CATALOG_ID },    });    transport.push({      version: 'v1.0',      updateComponents: {        surfaceId: 'main',        components: [{ id: 'root', component: 'Text', text: 'Hello from the agent' }],      },    });    return disconnect;  }, [client, transport]);
  const surfaces = useSyncExternalStore(    client.surfaces.subscribe,    client.surfaces.getSnapshot,    client.surfaces.getSnapshot,  );  const surface = surfaces.get('main');  const handleAction = (action: RendererAction) => {    void client.onAction(action).catch((error) => console.error('A2UI action failed', error));  };
  return surface ? <A2UISurface surface={surface} onAction={handleAction} /> : null;}

A2UI is transport-agnostic. The AG-UI binding follows the a2ui-surface convention emitted by @ag-ui/a2ui-middleware: surface operations arrive inside ACTIVITY_SNAPSHOT events (activityType: "a2ui-surface", operations under content.a2ui_operations), and user actions travel back as the A2UI userAction. Inject your AG-UI client as a bridge — a subscribe over the event stream plus a sendAction that triggers a run carrying forwardedProps.a2uiAction.userAction.

import { A2uiClient, createAgUiTransport } from '@flabbergasted-ai/a2ui';
const client = new A2uiClient(  createAgUiTransport({    // Forward the raw AG-UI event stream (RunStarted, ActivitySnapshot, …).    subscribe: (handler) => agUiClient.subscribe(handler),    // Send the A2UI user action back to the agent (middleware logs it).    sendAction: (userAction) =>      agUiClient.runAgent({ forwardedProps: { a2uiAction: { userAction } } }),  }),);client.connect();

Or connect a raw Server-Sent Events endpoint directly. The agent streams A2UI envelopes as SSE data: frames; createSseTransport reads them with fetch (so it can carry auth headers and a request body) and POSTs user actions back to sendUrl. It reconnects if the stream drops.

import { A2uiClient, createSseTransport } from '@flabbergasted-ai/a2ui';
const client = new A2uiClient(  createSseTransport('/api/agent/stream', {    headers: { Authorization: `Bearer ${token}` },    sendUrl: '/api/agent/action', // where user actions are POSTed  }),);client.connect();

Local functions the agent (or UI) may call. Each declares who can invoke it via allowedCallers; the renderer enforces that at runtime and never executes arbitrary code.

import { A2uiClient, FunctionRegistry } from '@flabbergasted-ai/a2ui';
const functions = new FunctionRegistry().register({  name: 'getScreenResolution',  allowedCallers: 'agentOnly',  handler: () => [window.innerWidth, window.innerHeight],});
const client = new A2uiClient(transport, { functions });