A2UI

Render rich, declarative UI surfaces from your agent using the A2UI protocol.

What is this?

A2UI (Agent-to-UI) is a declarative Generative UI specification. Your agent sends a JSON schema in place of plain text. The frontend renders that schema as cards, rows, columns, badges, and price tags from a catalog of components that you (or the platform) define.

You can design and preview A2UI schemas visually using the A2UI Composer.

Free course: See this pattern built end-to-end in Build Interactive Agents with Generative UI, a free DeepLearning.AI short course taught by CopilotKit's CEO covering the full Generative UI spectrum (Controlled, Declarative, and Open-Ended).

The two approaches

CopilotKit ships two complementary A2UI approaches:

  • Dynamic Schema: a secondary LLM generates both the schema and the data. Maximum flexibility, so the agent can produce any UI for any prompt.

  • Fixed Schema: the component tree is authored ahead of time as JSON. The agent only streams data into the data model at runtime. Fastest, with no LLM schema generation.

Both approaches share the same A2UI wire protocol and the same frontend renderer. The difference is where the schema comes from and how data reaches the client.

This page uses A2UI v0.9 through the a2ui prop. For A2UI v1.0 with your own React components, in the chat and in areas of your page, see Components and surfaces.

How it works

Every A2UI surface is assembled from three operations emitted by the agent and consumed by the frontend renderer:

  1. createSurface initializes the surface with its catalog and must come first.
  2. updateComponents defines the component tree (the schema) for the surface.
  3. updateDataModel supplies the data that populates the components via JSON Pointer paths.

The CopilotKit Python SDK provides helpers for each:

from copilotkit import a2ui

a2ui.create_surface(surface_id, catalog_id=...)
a2ui.update_components(surface_id, components)
a2ui.update_data_model(surface_id, {"items": data})
a2ui.render(operations=[...])  # wraps in a2ui_operations and serializes

Setup

A2UI turns on in one of two ways. Most apps use the first.

Pass an A2UI catalog to the <CopilotKit> provider. The catalog tells the renderer which components your agent can draw, and it does two things for you automatically: it enables A2UI and it injects the A2UI tool into your agent. No a2ui block on the runtime is required.

Build myCatalog with createCatalog, as shown in Dynamic Schema.

app/page.tsx
import { CopilotKit } from "@copilotkit/react-core/v2";

<CopilotKit runtimeUrl="/api/copilotkit" a2ui={{ catalog: myCatalog }}>
  {children}
</CopilotKit>;

Enable on the runtime without a catalog

If you do not pass a catalog, enable A2UI on the runtime instead. a2ui: {} applies the middleware so the surfaces your agent emits are rendered; add injectA2UITool: true to also inject the render tool so the agent can generate surfaces dynamically:

app/api/copilotkit/[[...slug]]/route.ts
import { CopilotRuntime, InMemoryAgentRunner } from "@copilotkit/runtime/v2";

const runtime = new CopilotRuntime({
  agents: { default: myAgent },
  a2ui: { injectA2UITool: true },
  runner: new InMemoryAgentRunner(),
});

The middleware finds tool results that contain A2UI operations. It renders them as surfaces in the chat.

With neither a catalog on the provider nor a2ui on the runtime, A2UI surfaces will not render. The operations fall through as plain tool results.

What gets injected

When injection is on, the runtime adds a tool named render_a2ui to your agent. The agent's model calls it with the surface components and data, and the A2UI middleware renders the surface in the chat.

LangGraph agents that use the CopilotKit middleware (CopilotKitMiddleware in Python, copilotkitMiddleware in TypeScript) get generate_a2ui in its place. Calling generate_a2ui runs a secondary LLM, a subagent, that designs the full A2UI surface (components, layout, and data) from your catalog, then streams it into the chat. You do not write this tool yourself. See Dynamic Schema for the full flow.

Customize or opt out

To provide the tool yourself, set injectA2UITool: false. Then add the tool from the AG-UI factory: get_a2ui_tools() in Python or getA2UITools() in TypeScript. In the factory, you set the model, the default catalog id, and more. An explicit injectA2UITool: false always wins, even when a catalog is present. This is also how the Fixed Schema approach works: your agent owns a data-only tool and no subagent is injected.

Colors and dark mode

The built-in basic catalog takes its colors from CSS variables. In dark mode (.dark on an ancestor of the chat) CopilotKit's stylesheet sets them from the chat theme, so cards, chips and buttons stay readable. To use your own colors, set the variables on the surface: .a2ui-surface in React and Vue, copilot-a2ui-surface in Angular.

.a2ui-surface {
  --a2ui-color-surface: #fafafa; /* card, modal, chip and button backgrounds */
  --a2ui-color-border: #e5e5e5; /* borders, tab rule, divider */
  --a2ui-color-muted: #737373; /* captions and secondary text */
  --a2ui-color-error: #dc2626; /* validation errors */
  --a2ui-primary-color: #2563eb; /* primary buttons, selected chips, active tab */
}

Values you set on the surface apply in both light and dark mode. Scope them with .dark .a2ui-surface to set dark colors only. For fonts, image sizes, and a full theme file, see Styling.

Choose your approach

Choose your AI backend

How is this guide?