Catalogs
An A2UI catalog defines the UI components, the functions that populate data or handle user events, and the prompt instructions that an agent and a renderer agree on. Because both sides work from the same catalog contract, the agent only sends component types and properties that the renderer knows how to build natively, never raw HTML, CSS, or executable scripts.
In the diagram below, the renderer advertises the catalogs it supports through supportedCatalogIds, and the agent selects a default catalog for a surface by setting catalogId in createSurface. The shared catalog document has three sections: components such as FlightStatusCard and Column, functions such as formatCurrency and saveBoardingPass, and Markdown instructions that the agent SDK adds to the LLM system prompt.
supportedCatalogIds createSurface.catalogId https://example.com/catalogs/travel/v1/catalog.json "components" FlightStatusCard Shows a flight's number, fare, and action buttons.
-
flightNumberDynamicString required -
fareAmountDynamicNumber -
actionsChildList
["Column", "List"] Column Text Button TextField "functions" formatCurrency Formats a number as a currency string inside a property binding.
saveBoardingPass
Runs on the renderer when the agent sends callRendererFunction.
"instructions" Markdown guidance that the agent SDK adds to the LLM system prompt.
"Place FlightStatusCard inside a Column. Format fares with formatCurrency." Catalogs
A catalog is a collection of components and functions that acts as a contract between an agent and a renderer. Both agents and renderers can support one or more catalogs at the same time: a renderer advertises its supportedCatalogIds when a session starts, and an agent can create surfaces against any of those catalogs or, in v1.0, combine components and functions from multiple catalogs on the same surface by setting @catalogId on individual components and catalogId on individual function calls.
Every catalog has a catalogId string, conventionally formatted as a URI such as https://a2ui.org/specification/v1_0/catalogs/basic/catalog.json or https://example.com/catalogs/travel/v1/catalog.json, along with optional instructions, components, and functions. Both sides of the connection read from that contract:
- On the agent, the agent SDK (
@a2ui/agent,a2ui-agent-sdk,a2ui_agent) reads the component schemas, function signatures, andinstructionsto build the LLM system prompt and validate outgoing messages. - On the renderer, the core and framework SDKs (
@a2ui/web_core,a2ui_core,A2UICore,androidx.a2ui) pair each component schema with a native widget and each local function signature with code that runs on the client.
Components
A component is a UI component that is rendered natively on the client, such as a Flutter widget, a React, Lit, or Angular component, a SwiftUI view, or a Jetpack Compose composable, and composed with other components to form rich UIs. Instead of nesting JSON objects deeply, an A2UI surface stores component instances in a flat list where parent components reference child IDs, making layouts straightforward for an LLM to stream incrementally.
Each entry in a catalog’s components map is a JSON Schema that describes one component type:
| Part | How it is declared | What it does |
|---|---|---|
| Component type | "component": { "const": "FlightStatusCard" } | Names the component type in the surface’s flat component list. |
| Dynamic properties | $ref to DynamicString, DynamicNumber, DynamicBoolean, and so on | Accepts a literal value, a data binding (@path in v1.0, path in v0.9.1), or a function call (@call / call). |
| Children | $ref to ComponentId or ChildList | Points to child components by ID so the surface stays a flat list instead of a nested tree. |
| Placement rules | allowedParents, allowedChildren (v1.0) | Limits where the component can appear in the layout. |
| Validation | $ref to Checkable | Adds a @checks array (checks in v0.9.1) of {condition, message} rules to an input. |
| Actions | $ref to Action | Says what happens when the user interacts with the component: send an event to the agent or call a function. |
In v1.0, the optional envelope keys that any component instance can carry (@catalogId, @accessibility, @metadata, and @checks on Checkable components) take the @ prefix, so a custom component can declare its own catalogId, accessibility, metadata, or checks property as an ordinary property. In v0.9.1, the accessibility and checks envelope keys are bare.
Here is a custom FlightStatusCard component schema in a catalog:
{ "FlightStatusCard": { "type": "object", "description": "Shows a flight's number, fare, and action buttons.", "allowedParents": ["Column", "List"], "properties": { "component": {"const": "FlightStatusCard"}, "flightNumber": { "$ref": "common_types.json#/$defs/DynamicString", "description": "IATA flight designator, such as 'NH 105'." }, "fareAmount": { "$ref": "common_types.json#/$defs/DynamicNumber", "description": "Ticket fare in the booking currency." }, "actions": { "$ref": "common_types.json#/$defs/ChildList", "description": "Buttons shown in the card footer." } }, "required": ["component", "flightNumber"] }}{ "FlightStatusCard": { "type": "object", "description": "Shows a flight's number, fare, and action buttons.", "allOf": [ { "$ref": "https://a2ui.org/specification/v0_9/common_types.json#/$defs/ComponentCommon" }, { "type": "object", "properties": { "component": {"const": "FlightStatusCard"}, "flightNumber": { "$ref": "https://a2ui.org/specification/v0_9/common_types.json#/$defs/DynamicString", "description": "IATA flight designator, such as 'NH 105'." }, "fareAmount": { "$ref": "https://a2ui.org/specification/v0_9/common_types.json#/$defs/DynamicNumber", "description": "Ticket fare in the booking currency." }, "actions": { "$ref": "https://a2ui.org/specification/v0_9/common_types.json#/$defs/ChildList", "description": "Buttons shown in the card footer." } }, "required": ["component", "flightNumber"] } ], "unevaluatedProperties": false }}Functions
A function is named logic used to populate data in the UI, such as formatting a bound property or checking an input rule, or to handle user events when someone interacts with a component.
A2UI supports both renderer-side and agent-side functions:
- Renderer-side functions are declared in a catalog’s
functionsmap and run locally on the client. They handle formatting, input validation, boolean logic, and client side effects such as opening a URL. In v1.0, the agent can also invoke an authorized renderer-side function remotely by sendingcallRendererFunctionand reading the returnedrendererFunctionResponse. - Agent-side functions, introduced in v1.0, run on the server, such as checking live seat inventory or verifying a booking code. When a component evaluates a
@callwhose name is not registered in the renderer’s local catalog, the renderer treats it as an agent-side function, dispatchescallAgentFunction, and applies the returnedagentFunctionResponse. In v0.9.1, function calls run only on the renderer, and components notify the agent of user interactions throughactionevents.
Each entry in a catalog’s functions map declares a returnType ("string", "number", "boolean", "array", "object", "any", "void", or, in v1.0, "validationResult") and an args schema for its arguments:
{ "formatCurrency": { "type": "object", "description": "Formats a number as a currency string.", "returnType": "string", "properties": { "@call": {"const": "formatCurrency"}, "args": { "type": "object", "properties": { "value": { "$ref": "common_types.json#/$defs/DynamicNumber", "description": "The monetary amount." }, "currency": { "$ref": "common_types.json#/$defs/DynamicString", "description": "The ISO 4217 currency code (e.g., 'USD', 'EUR')." } }, "required": ["currency", "value"], "unevaluatedProperties": false } }, "required": ["@call", "args"] }}{ "formatCurrency": { "type": "object", "description": "Formats a number as a currency string.", "properties": { "call": {"const": "formatCurrency"}, "args": { "type": "object", "properties": { "value": { "$ref": "https://a2ui.org/specification/v0_9/common_types.json#/$defs/DynamicNumber", "description": "The monetary amount." }, "currency": { "$ref": "https://a2ui.org/specification/v0_9/common_types.json#/$defs/DynamicString", "description": "The ISO 4217 currency code (e.g., 'USD', 'EUR')." } }, "required": ["currency", "value"], "unevaluatedProperties": false }, "returnType": {"const": "string"} }, "required": ["call", "args"], "unevaluatedProperties": false }}Using a catalog in an agent
An agent loads a catalog from its JSON document and passes it to A2uiGenerator through a CatalogConfig. The generator uses the catalog to build the LLM system prompt and to validate the messages the LLM produces.
import {readFileSync} from 'node:fs';
import {A2uiGenerator, CatalogConfig, ExpressFormatFactory} from '@a2ui/agent';import {Catalog} from '@a2ui/web_core';
const travelCatalog = Catalog.fromJson(JSON.parse(readFileSync('./catalogs/travel.json', 'utf8')));
const generator = new A2uiGenerator( [new CatalogConfig(travelCatalog)], undefined, new ExpressFormatFactory(),);import jsonfrom pathlib import Path
from a2ui.core import Catalogfrom a2ui.inference_formats import ExpressFormatFactoryfrom a2ui.processor import A2uiGenerator, CatalogConfig
travel_catalog = Catalog.from_json( json.loads(Path("./catalogs/travel.json").read_text(encoding="utf-8")))
generator = A2uiGenerator( catalogs=[CatalogConfig(catalog=travel_catalog)], inference_format_factory=ExpressFormatFactory(),)import 'dart:convert';import 'dart:io';
import 'package:a2ui_agent/a2ui_agent.dart';import 'package:a2ui_core/a2ui_core.dart';
void main() { final travelCatalog = Catalog.fromJson( jsonDecode(File('./catalogs/travel.json').readAsStringSync()) as Map<String, Object?>, );
final generator = A2uiGenerator( catalogs: [CatalogConfig(travelCatalog)], inferenceFormatFactory: const ExpressFormatFactory(), );}Swift (A2UISwiftCore, A2UISwiftUI) and Kotlin (androidx.a2ui, androidx.a2ui.compose) target client-side rendering; see SDKs for server-side Agent SDK packages.
Registering a catalog in a renderer
A renderer builds a Catalog that pairs each component schema with a native widget (ComponentImplementation) and each local function signature with code that runs it (FunctionImplementation). It then passes the catalog to its message processor or framework provider.
import 'package:a2ui_core/a2ui_core.dart';import 'package:a2ui_flutter/a2ui_flutter.dart';import 'package:flutter/material.dart';import 'package:json_schema_builder/json_schema_builder.dart';
final flightStatusCard = ComponentImplementation( name: 'FlightStatusCard', allowedParents: ['Column', 'List'], schema: Schema.object( properties: { 'component': Schema.string(enumValues: ['FlightStatusCard']), 'flightNumber': CommonSchemasV1.dynamicString, 'fareAmount': CommonSchemasV1.dynamicNumber, }, required: ['component', 'flightNumber'], ), builder: (context, node, props, buildChild) { final flightNumber = props.string('flightNumber') ?? ''; final fare = props.number('fareAmount');
return Card( child: ListTile( leading: const Icon(Icons.flight_takeoff), title: Text('Flight $flightNumber'), trailing: fare != null ? Text('\$${fare.toStringAsFixed(2)}') : null, ), ); },);
final travelCatalog = Catalog<ComponentImplementation, FunctionImplementation>( id: 'https://example.com/catalogs/travel/v1/catalog.json', protocolVersion: A2uiProtocolVersion.v1_0, components: [flightStatusCard], functions: BasicCatalog.v1_0().functions.values.toList(),);
final processor = MessageProcessor(catalogs: [travelCatalog]);import {z} from 'zod';
import {createComponentImplementation} from '@a2ui/react';import {Catalog, type ComponentApi, MessageProcessor} from '@a2ui/web_core';import {BASIC_FUNCTIONS, DynamicNumberSchema, DynamicStringSchema} from '@a2ui/web_core/v1_0';
const FlightStatusCardApi = { name: 'FlightStatusCard', allowedParents: ['Column', 'List'], schema: z.object({ flightNumber: DynamicStringSchema, fareAmount: DynamicNumberSchema.optional(), }),} satisfies ComponentApi;
const FlightStatusCard = createComponentImplementation(FlightStatusCardApi, ({props}) => { const flightNumber = typeof props.flightNumber === 'string' ? props.flightNumber : ''; const fareAmount = typeof props.fareAmount === 'number' ? props.fareAmount : undefined;
return ( <div className="flight-card"> <strong>Flight {flightNumber}</strong> {fareAmount !== undefined && <span>${fareAmount.toFixed(2)}</span>} </div> );});
export const travelCatalog = new Catalog( 'https://example.com/catalogs/travel/v1/catalog.json', '1.0', [FlightStatusCard], BASIC_FUNCTIONS,);
const processor = new MessageProcessor([travelCatalog]);import {html, nothing} from 'lit';import {customElement} from 'lit/decorators.js';import {z} from 'zod';
import {A2uiLitElement, type LitComponentApi} from '@a2ui/lit';import {Catalog, type ComponentApi, MessageProcessor} from '@a2ui/web_core';import {BASIC_FUNCTIONS, DynamicNumberSchema, DynamicStringSchema} from '@a2ui/web_core/v1_0';
const FlightStatusCardApi = { name: 'FlightStatusCard', allowedParents: ['Column', 'List'], schema: z.object({ flightNumber: DynamicStringSchema, fareAmount: DynamicNumberSchema.optional(), }),} satisfies ComponentApi;
@customElement('flight-status-card')export class FlightStatusCardElement extends A2uiLitElement<typeof FlightStatusCardApi> { static readonly tagName = 'flight-status-card'; protected override readonly api = FlightStatusCardApi;
override render() { const rawFlight = this.controller?.props?.flightNumber; const rawFare = this.controller?.props?.fareAmount; const flightNumber = typeof rawFlight === 'string' ? rawFlight : ''; const fareAmount = typeof rawFare === 'number' ? rawFare : undefined;
return html` <div class="flight-card"> <strong>Flight ${flightNumber}</strong> ${fareAmount !== undefined ? html`<span>$${fareAmount.toFixed(2)}</span>` : nothing} </div> `; }}
const FlightStatusCard = { ...FlightStatusCardApi, tagName: FlightStatusCardElement.tagName, element: FlightStatusCardElement,} satisfies LitComponentApi;
export const travelCatalog = new Catalog( 'https://example.com/catalogs/travel/v1/catalog.json', '1.0', [FlightStatusCard], BASIC_FUNCTIONS,);
const processor = new MessageProcessor([travelCatalog]);import {Component, computed} from '@angular/core';import {z} from 'zod';
import { AngularCatalog, BASIC_FUNCTIONS, CatalogComponent, createComponentImplementation, provideA2UI,} from '@a2ui/angular';import {type ComponentApi} from '@a2ui/web_core';import {DynamicNumberSchema, DynamicStringSchema} from '@a2ui/web_core/v1_0';
const FlightStatusCardApi = { name: 'FlightStatusCard', allowedParents: ['Column', 'List'], schema: z.object({ flightNumber: DynamicStringSchema, fareAmount: DynamicNumberSchema.optional(), }),} satisfies ComponentApi;
@Component({ selector: 'app-flight-status-card', template: ` <div class="flight-card"> <strong>Flight {{ flightNumber() }}</strong> @if (formattedFare(); as fare) { <span>\${{ fare }}</span> } </div> `,})export class FlightStatusCardComponent extends CatalogComponent<typeof FlightStatusCardApi> { readonly flightNumber = computed(() => { const flight = this.props().flightNumber?.value(); return typeof flight === 'string' ? flight : ''; }); readonly formattedFare = computed(() => { const fare = this.props().fareAmount?.value(); return typeof fare === 'number' ? fare.toFixed(2) : undefined; });}
export const travelCatalog = new AngularCatalog( 'https://example.com/catalogs/travel/v1/catalog.json', '1.0', [createComponentImplementation(FlightStatusCardApi, FlightStatusCardComponent)], BASIC_FUNCTIONS,);
export const appA2uiProviders = provideA2UI({catalogs: [travelCatalog]});import A2UICoreimport A2UISwiftUIimport BasicCatalogimport JSONSchemaimport SwiftUI
let flightStatusCard = ComponentImplementation( name: "FlightStatusCard", schema: try! Schema( instance: """ { "type": "object", "properties": { "component": { "const": "FlightStatusCard" }, "flightNumber": { "$ref": "common_types.json#/$defs/DynamicString" }, "fareAmount": { "$ref": "common_types.json#/$defs/DynamicNumber" } }, "required": ["component", "flightNumber"] } """, remoteSchemas: A2UICommonSchema.allSchemas ), allowedParents: ["Column", "List"]) { node in HStack { Image(systemName: "airplane.departure") Text("Flight \(node.string(for: "flightNumber") ?? "")") .font(.headline) Spacer() if let fare = node.double(for: "fareAmount") { Text(String(format: "$%.2f", fare)) } } .padding()}
let travelCatalog = Catalog( id: "https://example.com/catalogs/travel/v1/catalog.json", protocolVersion: "1.0", components: [flightStatusCard], functions: V10BasicFunctions.allFunctions)
let processor = MessageProcessor(catalogs: [travelCatalog])import android.content.Contextimport java.util.Locale
import androidx.a2ui.compose.runtime.A2uiComponentPropertiesimport androidx.a2ui.compose.runtime.A2uiComponentScopeimport androidx.a2ui.compose.runtime.A2uiMessageProcessorimport androidx.a2ui.compose.runtime.A2uiPropertyimport androidx.a2ui.compose.ui.A2uiCatalogimport androidx.a2ui.compose.ui.A2uiComponentimport androidx.a2ui.compose.ui.catalog.A2uiBasicCatalogV1import androidx.a2ui.model.processor.A2uiMessageProcessorimport androidx.compose.foundation.layout.Arrangementimport androidx.compose.foundation.layout.Rowimport androidx.compose.foundation.layout.fillMaxWidthimport androidx.compose.foundation.layout.paddingimport androidx.compose.material3.Cardimport androidx.compose.material3.Textimport androidx.compose.material3.a2ui.catalog.MaterialA2uiBasicCatalogV1Defaultsimport androidx.compose.material3.a2ui.catalog.materialA2uiBasicCatalogV1import androidx.compose.runtime.Composableimport androidx.compose.ui.Modifierimport androidx.compose.ui.unit.dp
private val FlightNumberProp = A2uiProperty.dynamicString("flightNumber", required = true)private val FareAmountProp = A2uiProperty.dynamicNumber("fareAmount")
val FlightStatusCard: A2uiComponent = object : A2uiComponent { override val name = "FlightStatusCard" override val description = "Shows a flight's number and fare." override val properties = listOf(FlightNumberProp, FareAmountProp)
@Composable override fun A2uiComponentScope.isReady(properties: A2uiComponentProperties): Boolean = properties.bind(FlightNumberProp) != null
@Composable override fun A2uiComponentScope.Content( properties: A2uiComponentProperties, modifier: Modifier, ) { val flightNumber = properties.bind(FlightNumberProp) ?: return val fare = properties.bind(FareAmountProp)?.toDouble()
Card(modifier = modifier.fillMaxWidth()) { Row( modifier = Modifier.fillMaxWidth().padding(16.dp), horizontalArrangement = Arrangement.SpaceBetween, ) { Text(text = "Flight $flightNumber") if (fare != null) { Text(text = String.format(Locale.US, "$%.2f", fare)) } } } } }
// androidx.a2ui implements v0.9.1, where each surface binds to a single catalogId.fun createTravelProcessor(context: Context): A2uiMessageProcessor { val basicCatalog = materialA2uiBasicCatalogV1( image = MaterialA2uiBasicCatalogV1Defaults.image { _, _, _, _, _ -> }, video = MaterialA2uiBasicCatalogV1Defaults.video { _, _, _ -> }, audioPlayer = MaterialA2uiBasicCatalogV1Defaults.audioPlayer { _, _, _, _ -> }, functions = A2uiBasicCatalogV1.Functions(context), ) val travelCatalog = A2uiCatalog( catalogId = "https://example.com/catalogs/travel/v1/catalog.json", components = basicCatalog.components + FlightStatusCard, functions = basicCatalog.functions, themeSchema = basicCatalog.themeSchema, ) // Launch processor.collectMessages() in a background coroutine scope // (such as viewModelScope) to process queued messages: val processor = A2uiMessageProcessor(catalogs = listOf(travelCatalog)) return processor}The basic catalog
A2UI publishes a basic catalog with 18 general-purpose components and 14 functions. The v1.0 schema lives at catalogs/basic/v1/catalog.json, and the v0.9.1 schema lives at specification/v0_9_1/catalogs/basic/catalog.json.
| Category | Entries |
|---|---|
| Layout | Row, Column, List, Card, Tabs, Modal, Divider |
| Display and media | Text, Image, Icon, Video, AudioPlayer |
| Inputs | Button, TextField, CheckBox, ChoicePicker, Slider, DateTimeInput |
| Functions | formatString, formatNumber, formatCurrency, formatDate, pluralize, required, regex, length, numeric, email, openUrl, and, or, not |
You do not have to use the basic catalog. You can adopt it as is, restyle its components to match your design system, combine it with domain-specific catalogs on the same surface, or replace it altogether.
For an example of a domain catalog built on the basic catalog, see the experimental Google Maps Platform Agentic UI toolkit. Its catalog, a2ui://maps-agentic-ui-catalog.json, adds GoogleMap and PlaceDetailsCompact components to the basic catalog’s components and functions. The toolkit ships renderers for web (Lit), Android, and iOS, so agents can show maps, routes, and place details next to standard layout widgets.
Catalog negotiation and multi-catalog surfaces
When a session starts, the renderer sends supportedCatalogIds to list the catalogs it supports. When creating a surface, the agent picks from that list (or sends no UI if none match).
Set catalogId in createSurface to choose the surface’s default catalog, then add @catalogId on any component in updateComponents (or catalogId on any function call, @call) that comes from another supported catalog.
In this example, salesDashboard uses the basic catalog by default, and chart comes from a custom charts catalog:
[ { "version": "1.0", "createSurface": { "surfaceId": "salesDashboard", "catalogId": "https://a2ui.org/specification/v1_0/catalogs/basic/catalog.json" } }, { "version": "1.0", "updateComponents": { "surfaceId": "salesDashboard", "components": [ {"id": "root", "component": "Column", "children": ["title", "chart"]}, {"id": "title", "component": "Text", "text": "Quarterly sales"}, { "id": "chart", "component": "BarChart", "@catalogId": "https://example.com/catalogs/charts/v1/catalog.json", "data": {"@path": "/sales"} } ] } }]Edge cases when createSurface.catalogId is omitted
catalogId in createSurface is optional. If a surface omits createSurface.catalogId, every component must set its own @catalogId and every function call its own catalogId. If an entry omits its catalog ID and the surface has no default catalogId either, the renderer rejects that component or function call rather than falling back to supportedCatalogIds. See Mixable catalogs and component resolution logic for the full resolution rules.
The agent selects a single catalogId in createSurface, locked for the lifetime of that surface:
{ "version": "v0.9", "createSurface": { "surfaceId": "salesDashboard", "catalogId": "https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json" }}