# A2UI

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

## What is this? [#what-is-this]

[A2UI](https://a2ui.org) (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](https://a2ui-composer.ag-ui.com/).

<Callout type="info">
  **Free course:** See this pattern built end-to-end in [Build Interactive Agents with Generative UI](https://www.deeplearning.ai/short-courses/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).
</Callout>

## The two approaches [#the-two-approaches]

CopilotKit ships two complementary A2UI approaches:

- **[Dynamic Schema](./a2ui/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](./a2ui/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*.

<Callout type="info">
  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](/generative-ui/components).
</Callout>

## How it works [#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:

```python
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 [#setup]

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

### Pass a catalog on the provider (recommended) [#pass-a-catalog-on-the-provider-recommended]

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](./a2ui/dynamic-schema).

```tsx title="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 [#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:

```typescript title="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.

<Callout type="warn">
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.
</Callout>

### What gets injected [#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](./a2ui/dynamic-schema) for the full flow.

### Customize or opt out [#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](./a2ui/fixed-schema) approach
works: your agent owns a data-only tool and no subagent is injected.

## Colors and dark mode [#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.

```css
.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](/generative-ui/a2ui/styling).

## Choose your approach [#choose-your-approach]

<Cards>
  <Card
    title="Dynamic Schema"
    href="./a2ui/dynamic-schema"
    description="A secondary LLM generates both the schema and data. Any UI from any prompt."
  />
  <Card
    title="Fixed Schema"
    href="./a2ui/fixed-schema"
    description="Pre-authored JSON schema, agent streams data. Fastest path to production-quality UI."
  />
</Cards>

<IntegrationGrid path="generative-ui/a2ui" />
