Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/a2ui-project/a2ui/llms.txt

Use this file to discover all available pages before exploring further.

The Basic Catalog that ships with A2UI is intentionally minimal — it is designed to be quickly implementable across many different renderers. Most production applications will outgrow it fast and benefit from defining a catalog that reflects their own design system. When you control the catalog, the agent generates UI from exactly the components you already trust, with no translation layer in between.

​
Why Define Your Own Catalog?

Every A2UI surface is driven by a Catalog: a JSON Schema file that tells the agent which components, functions, and themes it is allowed to use. Replacing or extending the Basic Catalog with your own offers three concrete benefits:

Design System Alignment

Restrict the agent to your application’s exact visual language — your buttons, your typography, your spacing — rather than generic placeholders.

Security and Type Safety

You register entire catalogs with your client application. Only trusted, validated components can ever be rendered.

No Mappers Needed

Build catalogs that directly reflect your client’s design system. You never need an adapter that maps a generic catalog to your components.

Agent Precision

A narrower, well-described catalog gives the agent better signal about when and how to use each component, improving output quality.
The Basic Catalog is just one example implementation. It is intentionally sparse so that it is easy to support across many renderers and platforms.

​
How It Works

The lifecycle from catalog definition to rendered UI has five stages:
1

Define the Catalog

Create a catalog definition — a JSON Schema listing the components, functions, and themes your application supports. This is the contract between the agent and your renderer.
2

Register the Catalog

Register the catalog and its corresponding component implementations (renderers) with your client application via the renderer’s configuration API (e.g., A2UI_RENDERER_CONFIG in Angular, or the provider catalog prop in React/CopilotKit).
3

Announce Support

The client informs the agent which catalogs it supports via the supportedCatalogIds field in the initial handshake. The agent will only generate components from catalogs it knows the client can render.
4

Agent Selects Catalog

For each UI surface, the agent chooses one of the announced catalogs and declares it via the catalogId field inside the surface-creation message (e.g., createSurface in v0.9).
5

Agent Generates UI

The agent generates component messages using only the components defined in the selected catalog, referred to by name. The renderer looks up each component name in its registered catalog and mounts the matching implementation.

​
Catalog JSON Schema Structure

A catalog definition is a JSON Schema document. At minimum it contains a stable identifier, a list of component definitions, optional function definitions, and optional theme fields. 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "catalogId": "my-app-catalog",
  "components": {
    "StatusBadge": {
      "description": "A colored status badge for conveying task or entity state.",
      "properties": {
        "text": {
          "type": "string",
          "description": "Label displayed inside the badge."
        },
        "variant": {
          "type": "string",
          "enum": ["success", "warning", "error"],
          "description": "Visual style of the badge."
        }
      },
      "required": ["text"]
    },
    "Metric": {
      "description": "A key metric card with a label, value, and optional trend indicator.",
      "properties": {
        "label": { "type": "string" },
        "value": { "type": "string" },
        "trend": {
          "type": "string",
          "enum": ["up", "down"]
        }
      },
      "required": ["label", "value"]
    }
  },
  "functions": {
    "openDetailPanel": {
      "description": "Opens the detail panel for a given entity ID.",
      "parameters": {
        "entityId": { "type": "string" }
      }
    }
  }
}
Key fields:
FieldRequiredDescription
catalogId✅A stable, unique handle the agent uses to target this catalog.
components✅Map of component names to their JSON Schema definitions.
functionsOptionalClient-side functions the agent can invoke (e.g., open a panel, trigger navigation).
Theme fieldsOptionalArbitrary theme data passed through createSurface. See Theming.

​
Implementation Guide

To implement your own catalog on the web:
  1. Create a JSON Schema containing your component definitions (see structure above).
  2. Create Component objects — one per component definition — that map the schema name to a framework-specific renderer (a Lit element, an Angular component, or a React component).
  3. Create a Catalog object that groups the component objects, the schema, and any action handlers together.
  4. Register the catalog with the renderer’s configuration:
Angular (@a2ui/angular/v0_9):
import { ApplicationConfig } from '@angular/core';
import { A2UI_RENDERER_CONFIG, A2uiRendererService } from '@a2ui/angular/v0_9';
import { myAppCatalog } from './catalogs/my-app-catalog';

export const appConfig: ApplicationConfig = {
  providers: [
    {
      provide: A2UI_RENDERER_CONFIG,
      useValue: {
        catalogs: [myAppCatalog],
        actionHandler: action => {
          console.log('Action dispatched:', action);
        },
      },
    },
    A2uiRendererService,
  ],
};
React (@a2ui/react/v0_9) with CopilotKit:
import { CopilotKitProvider } from '@copilotkit/react-core/v2';
import { myCatalog } from '@/lib/a2ui/renderers';

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <CopilotKitProvider runtimeUrl="/api/copilotkit" a2ui={{ catalog: myCatalog }}>
      {children}
    </CopilotKitProvider>
  );
}
Detailed per-framework implementation guides for standalone (non-CopilotKit) usage are coming soon. For CopilotKit-based React flows, see the A2UI with Any Agent Framework guide.

​
Security Considerations

Because the agent produces the component names and properties that your renderer will mount, treat catalog registration as a security boundary.
Only register components you fully trust. An agent-controlled component name should never be able to escape the boundaries defined by your catalog.
Follow these three practices:
1

Allowlist components

Register only the components your application explicitly supports. Do not expose components that offer dangerous capabilities (for example, components that execute arbitrary scripts or make unauthenticated network requests) unless strictly controlled.
2

Validate properties

Always validate component properties from agent messages against expected type constraints before passing them to your renderer. The Zod schemas generated from your catalog definition are a natural place to do this.
3

Sanitize text content

Avoid rendering un-sanitized strings provided by the agent unless safe bounds are established. Treat agent-provided text as untrusted input and apply the same sanitization you would apply to any user-generated content.

​
Next Steps

Theming & Styling

Customize the look and feel of your catalog’s components.

Component Reference

Explore standard component types available for reuse in the Basic Catalog.

A2UI with Any Agent Framework

Wire your catalog to an agent using CopilotKit and AG-UI.

Client Setup

Install and configure the renderer for your platform.

Build docs developers (and LLMs) love

Get started for freeTalk to us