Let's be honest: the first time you hear "the agent builds the UI", the reaction is a mix of curiosity and alarm. Curiosity because a form that appears exactly when the conversation needs it is a genuinely new kind of interface. Alarm because the same sentence sounds like "a model decides what runs in my app".
With A2UI it doesn't. The agent never sends HTML or code, it sends a description of a UI made of components you wrote (here's one real message, next to the Angular component it becomes), and the thing that keeps that promise is the catalog. In this article I'll walk through the catalog of my AngularDay demo: one Zod schema per component, read by the model, by the agent's validation and by the Angular component itself.
⚠️ Version note: A2UI 1.0 was announced on 11 November as the first stable version of the protocol. Everything here is still v0.9, on purpose: the demo pins
@a2ui/angular0.13 and@a2ui/web_core(written in Zod 3), and the published packages are still 0.x, behind the final 1.0 spec. On the wire, 1.0 mostly renames: bindings and calls become@pathand@call, and client and server become renderer and agent (evolution guide). The catalog, the validation and the policy below work the same way. Pin your versions.
🧩 Where the catalog sits
A quick map of the demo, because the catalog only makes sense in context (if MCP, A2A, AG-UI and A2UI blur together, this post sorts the four layers):
| Step | What happens | Who owns it |
|---|---|---|
| 1 | The Angular app sends the prompt plus the catalogs it supports | your own API (POST, SSE reply) |
| 2 | The app's server forwards it to the agent | A2A |
| 3 | The agent composes the UI from the catalog and validates it | A2UI + your code |
| 4 |
createSurface / updateComponents messages stream back |
A2A, then your SSE |
| 5 |
<a2ui-v09-surface> renders them with your Angular components |
@a2ui/angular |
The renderer declares what it can draw with supportedCatalogIds. The agent may only answer with components from those catalogs, so the catalog is the contract between the two sides.
🔧 One schema per component
Nothing is better than seeing some code in order to understand something. This is the PriorityBadge from the demo's ticket catalog:
export const PRIORITIES = ['low', 'medium', 'high', 'urgent'] as const;
export const PriorityBadgeApi = {
name: 'PriorityBadge',
schema: z
.object({
priority: z
.union([z.enum(PRIORITIES), DataBindingSchema])
.describe("The ticket's priority, or a binding to it."),
})
.strict()
.describe("A coloured badge showing a ticket's priority."),
} satisfies ComponentApi;
Three details matter. z.enum limits the value to four strings. DataBindingSchema lets the agent bind the badge to the data model instead of hardcoding a value. And .strict() rejects any prop the schema doesn't name.
The components are then assembled with @a2ui/web_core's own Catalog class, and toJson() produces the JSON Schema document the model reads:
export const ticketCatalog = new Catalog<ComponentApi>(
TICKET_CATALOG_ID,
'v0.9',
[...TICKET_BASIC_COMPONENTS, ...TICKET_CUSTOM_COMPONENTS],
[],
{ themeSchema: BasicCatalogThemeSchema, title: 'Support ticket catalog' /* … */ },
);
export function ticketCatalogDocument(): Record<string, unknown> {
return ticketCatalog.toJson();
}
The .describe() strings aren't decoration: they end up in that document, so they're the only documentation the model gets.
⚛️ The Angular side reads the same object
Here is the part I like most as an Angular developer. The component that draws the badge is typed from the very same PriorityBadgeApi:
@Component({
selector: 'app-priority-badge',
changeDetection: ChangeDetectionStrategy.OnPush,
template: `<span class="priority-badge" [attr.data-priority]="priority()">{{ priority() }}</span>`,
})
export class PriorityBadgeComponent extends CatalogComponent<typeof PriorityBadgeApi> {
/** 'low' | 'medium' | 'high' | 'urgent', inferred from the Zod enum. */
protected readonly priority = computed(() => this.props().priority?.value());
}
CatalogComponent exposes the props as signals, so the resolved value drops straight into a computed(). Registration pairs each ComponentApi with its component:
new AngularCatalog(TICKET_CATALOG_ID, 'v0.9', [
...BASIC_COMPONENTS.filter((impl) => basicNames.has(impl.name)),
createComponentImplementation(PriorityBadgeApi, PriorityBadgeComponent),
// …
], [], BasicCatalogThemeSchema);
Add a fifth priority to the enum and the model's prompt, the agent's validation and the component's types all change together. There is no second list to forget.
🔍 What "rejected" looks like
The demo has a stub mode (STUB_LLM=true, no API key) and a flag, STUB_INVALID_FIRST=true, that makes the first answer use a priority outside the enum. This is the agent's log, verbatim:
--- RestaurantExecutor: Attempt 1/2 ---
--- A2UI validation failed:
Validation failed for component 'PriorityBadge'
(ticket_priority): priority: Invalid enum value.
Expected low | medium | high | urgent,
received 'critical' … (Attempt 1) ---
--- RestaurantExecutor: Attempt 2/2 ---
The agent validates each message against the catalog before publishing it, and on failure retries once with the error in the prompt, as the official A2UI restaurant sample does. If both attempts fail, the user gets a text apology instead of a broken surface. A component outside the catalog fails the same way (Unknown component type 'Image' not found in catalog …), and so does an extra prop (Unrecognized key(s) in object: 'color').
One honest caveat: validation runs per message, while streaming. If the first message of attempt 1 was valid, it has already reached the browser when a later one fails. Design the retry so it replaces the surface rather than appending to it.
💡 The trap: two copies of "the same" schema
Here's the bug that taught me the title of this article (the short version is on LinkedIn). The agent first loaded the basic catalog from its published JSON document, while the renderer validated with web_core's Zod objects. They describe the same components, but they're not equally strict: rebuilt from JSON Schema, a Button action's context comes back as Record<unknown>.
So a data binding cut at a chunk boundary streamed out as {}. The agent's copy accepted it, the renderer's Zod rejected it, and the form broke in the browser.
The fix was to register the Zod Catalog object on the agent too. The model still reads toJson() in its prompt, so nothing changed for it, but now both sides validate with the same object. A schema is only as strong as the copy each side holds.
🧠 Valid isn't the same as allowed
The catalog answers one question: is this a valid UI? It can't answer the next one: may this user see it? In the demo, each ticket carries internal_notes for the support team, and the detail view can offer a Delete ticket button. A Text bound to /ticket/internal_notes is a perfectly valid component, and so is a Button whose action is delete_ticket. Validation lets both through.
So the agent runs a second, deployment-specific check after validation and before anything is published:
export const DEMO_POLICY: Policy = {
forbiddenDataPaths: ['/tickets/*/internal_notes', '/ticket/internal_notes'],
disabledActions: ['delete_ticket'],
};
applyPolicy is pure and works per message. It deletes forbidden paths from every updateDataModel value, and it removes every component that binds one of them or carries a disabled action, together with its subtree. Then it mends the tree so the surface stays valid against the catalog: a parent drops the id from its children, a Card whose only child is gone goes too, and a template pointing at a removed row becomes an empty list. Removing a component rather than blanking one of its props is deliberate, because a required prop like Text.text can't simply be emptied.
The reason it's per message is streaming. In Direct JSON mode, the agent re-sends a message whole every time it grows, and each re-send goes straight to the browser. In my tests, the raw stream carried internal_notes in re-sends well before the last one, so filtering only the final message would come too late: the filter has to clean every re-send on its own.
One honest limit: a denylist only covers the shapes you anticipated. My first policy listed /tickets/*/internal_notes and missed the detail view, which binds /ticket/internal_notes. That's why the deny-by-default version of this, an allowlist of what each view may show, is the one I'd reach for in production.
🎯 Swap the transport, keep the catalog
A2UI doesn't care how its messages travel: its roadmap lists A2A, AG-UI, MCP, REST and WebSockets. In the demo the browser never speaks A2A: it POSTs to the app's own server, and server.ts is the A2A client. It unwraps the A2UI messages from the A2A parts and streams them back as plain SSE, { messages, sessionId }, so the Angular app doesn't contain a single A2A type.
That makes the transport a single file. Swap A2A for AG-UI (CopilotKit's runtime) and steps 1, 2 and 4 change, while the catalog, the validation and the Angular components stay exactly as they are. The architecture does care, though: A2A gives you agent-to-agent delegation that an agent-to-app protocol doesn't.
✅ Closing thoughts
- Define each component once, as a Zod
ComponentApi, and derive everything else from it: the prompt viatoJson(), the agent's validation, the Angular types. - Make schemas
.strict()and enums explicit: anything the catalog doesn't name is something the agent can't render. - Never let the agent and the renderer validate with different copies.
- Validation says what's valid; a policy after it says what's allowed for this user, and it has to run on every streamed message.
Neither the catalog nor a denylist can catch everything, though. A2UI 1.0 narrows the gap a little: a catalog can now declare allowedParents and allowedChildren, so a component in the wrong place gets rejected too. Where the line still sits is one of the things I'll talk about at AngularDay on 20 November. The demo is public and stub mode needs no key: github.com/giorgiogalassi/talk-a2ui.
If you liked it, follow me on LinkedIn and Medium for more Angular deep dives.
See you in the next one! 🤙🏻
— G.
Top comments (0)