Skip to content

Defining Your Own Catalog

While the Basic Catalog is useful for starting out and bootstrapping an application, most production applications will define their own catalog to reflect their specific design system.

By defining your own catalog, you restrict the agent to using exactly the components and visual language that exist in your application, rather than generic inputs or buttons.

Why Define Your Own Catalog?

Every A2UI surface is driven by a Catalog. A catalog is simply a JSON Schema file that tells the agent which components, functions, and themes are available for it to use.

  • Design System Alignment: Restrict the agent to using exactly the components and visual language that exist in your application.
  • Security and Type Safety: You register entire catalogs with your client application, ensuring that only trusted components are rendered.
  • No Mappers Needed: We recommend building catalogs that directly reflect your client's design system rather than trying to map a generic catalog (like the Basic Catalog) to it through an adapter.

The Basic Catalog is just one example and is intentionally sparse to remain easily implementable by different renderers.

How It Works

  1. Define the Catalog: Create a catalog definition (JSON Schema) listing the components, functions, and styles your application supports.
  2. Register the Catalog: Register the catalog and its corresponding component implementations (renderers) with your client application.
  3. Announce Support: The client informs the agent which catalogs it supports (via supportedCatalogIds).
  4. Agent Selects Catalog: The agent chooses a catalog for a given UI surface (via catalogId inside the creation message, like createSurface).
  5. Agent Generates UI: The agent generates component messages using the components defined in that catalog by name.

Implementation Guide

We recommend creating catalogs that directly map to your existing component library.

To implement your own catalog on the web: - Create a JSON Schema containing your component definitions. - Register your components with the @a2ui/web client. - Provide the schema or reference ID to the agent.

Detailed guides for each framework coming soon.

To implement your own catalog in Flutter: - Define a JSON Schema describing your widget properties. - Map the schema to Flutter widgets using a custom renderer.

Detailed Flutter integration guide coming soon.

Security Considerations

When defining and registering catalogs:

  1. Allowlist components: Only register components you trust in your catalog definition. Don't expose components that offer dangerous capabilities (e.g., executing arbitrary scripts) unless strictly controlled.
  2. Validate properties: Always validate component properties from agent messages to ensure they match expected type constraints.
  3. Sanitize text: Avoid rendering un-sanitized content provided by the agent unless safe bounds are established.

Next Steps