A2UI

The agent assembles the UI

Tool-based rendering maps one tool to one component: the agent picks a component, you draw it. A2UI is the declarative tier of the generative-UI spectrum — instead of picking a single component, the agent assembles a surface by combining building blocks from a catalog you define.

You still own the components. The agent can only use what is in your catalog, so it can never render something you did not ship. What the agent decides is the layout and the data — how those building blocks come together into a panel, and what goes in them.

The catalog (same for every mode)

The frontend wiring is identical no matter which backend mode you use: you register a catalog on the <CopilotKit> provider with the a2ui prop.

import { CopilotKit } from "@copilotkit/react-core";
import { catalog } from "@/a2ui-catalog";

<CopilotKit runtimeUrl="/api/copilotkit" agent="assistant" a2ui={{ catalog }}>
</CopilotKit>

The catalog is your set of React components keyed by a catalog id — a FlightCard, a HotelCard, a Chart, whatever your app needs. The agent references catalog ids; CopilotKit paints your components with the data the agent supplies.

Two backend modes

A2UI backends come in two shapes. In dynamic mode the agent designs the surface; in fixed-schema mode you pre-author the layout and the agent only fills in data.

Dynamic

The Flow wires no A2UI tool. Enable A2UI on the runtime for this agent and it gains a generate_a2ui tool automatically. A sub-agent designs a surface from the conversation against your catalog, streams it to the frontend progressively, and self-heals invalid output through a validate-then-retry recovery pass. You write a normal agentic-chat Flow; the tool is injected for you.

Same as above — pass your catalog through the a2ui prop:

<CopilotKit runtimeUrl="/api/copilotkit" agent="assistant" a2ui={{ catalog }}>
</CopilotKit>

Your backend is a plain agentic-chat Flow. You do not define an A2UI tool — the runtime injects generate_a2ui when A2UI is enabled for the agent, and the sub-agent invents the layout from the conversation.

When a turn calls for UI, the agent assembles a surface from your catalog, streams the components in as it designs them, and repairs any invalid output before it reaches the screen. Your registered components render in the layout the agent chose.

Fixed-schema

When you already know the layout and only the data changes per call, pre-author the surface and let the agent fill it. The Flow wires backend tools (for example search_flights, search_hotels). Each tool returns an A2UI operations envelope as its result — createSurface -> updateComponents -> updateDataModel — which the frontend paints. There is no sub-agent, no generation, and no recovery pass: the layout JSON is authored by you, and only the data varies.

Install the toolkit that provides the envelope helpers:

pip install ag-ui-a2ui-toolkit

Build the envelope with the toolkit helpers and emit it as the tool result:

from ag_ui_a2ui_toolkit import (
    A2UI_OPERATIONS_KEY,
    create_surface,
    update_components,
    update_data_model,
)
from ag_ui_crewai.sdk import copilotkit_emit_tool_result, copilotkit_stream

The tool assembles the createSurface -> updateComponents -> updateDataModel operations into an envelope keyed by A2UI_OPERATIONS_KEY, then hands it back with copilotkit_emit_tool_result(...). Because the layout is fixed, the same tool always produces the same shape — only the values differ from call to call.

When to use which

Both modes share the same frontend: one catalog, registered once on the provider. Start with fixed-schema when your surfaces are stable, and reach for dynamic when you want the agent to design layouts you did not anticipate.

Related