Skip to content

Type to search the docs, or jump to:

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.

Agent Prompts the LLM with the catalog
supportedCatalogIds
createSurface.catalogId
Renderer Implements the catalog natively
Catalog https://example.com/catalogs/travel/v1/catalog.json
Components "components"
Also in this catalog
Column Text Button TextField
Functions "functions"
formatCurrency

Formats a number as a currency string inside a property binding.

returns string rendererOnly
saveBoardingPass

Runs on the renderer when the agent sends callRendererFunction.

returns boolean agentOnly
Instructions "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:

  1. On the agent, the agent SDK (@a2ui/agent, a2ui-agent-sdk, a2ui_agent) reads the component schemas, function signatures, and instructions to build the LLM system prompt and validate outgoing messages.
  2. 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:

PartHow it is declaredWhat 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 onAccepts 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 ChildListPoints to child components by ID so the surface stays a flat list instead of a nested tree.
Placement rulesallowedParents, allowedChildren (v1.0)Limits where the component can appear in the layout.
Validation$ref to CheckableAdds a @checks array (checks in v0.9.1) of {condition, message} rules to an input.
Actions$ref to ActionSays 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"]
}
}

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:

  1. Renderer-side functions are declared in a catalog’s functions map 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 sending callRendererFunction and reading the returned rendererFunctionResponse.
  2. 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 @call whose name is not registered in the renderer’s local catalog, the renderer treats it as an agent-side function, dispatches callAgentFunction, and applies the returned agentFunctionResponse. In v0.9.1, function calls run only on the renderer, and components notify the agent of user interactions through action events.

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"]
}
}

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(),
);

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]);

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.

CategoryEntries
LayoutRow, Column, List, Card, Tabs, Modal, Divider
Display and mediaText, Image, Icon, Video, AudioPlayer
InputsButton, TextField, CheckBox, ChoicePicker, Slider, DateTimeInput
FunctionsformatString, 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.