# 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](/ag2/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.

### Serve A2UI from an AG2 agent

AG2 has an A2UI module, `ag2.a2ui`. Wrap a plain `Agent` in an `A2UIServer`
with the `AgUiTransport`. The server streams validated A2UI output to
CopilotKit over the AG-UI protocol, so you write no bridge code.

Install AG2 with the A2UI, AG-UI and OpenAI extras:

```bash
pip install "ag2[a2ui,ag-ui,openai]>=1.1.2" uvicorn
```

Build a plain agent and wrap it in `A2UIServer`:

- The `A2UIServer` instance is the ASGI app.
- `AgUiTransport` serves the AG-UI endpoint.
- A function with `@a2ui_action` becomes a button. Its handler runs on the
  server.

```python title="server.py"
import uvicorn

from ag2 import Agent
from ag2.a2ui import A2UIServer, a2ui_action
from ag2.a2ui.transports import AgUiTransport
from ag2.config import OpenAIResponsesConfig

@a2ui_action(description="Book the selected dinner reservation")
def book_table(time: str, party_size: int) -> str:
    return f"booked a table for {party_size} at {time}"

agent = Agent(
    name="ui_agent",
    prompt=(
        "Answer with an A2UI surface whenever a list, a choice, or a "
        "confirmation would help the user."
    ),
    config=OpenAIResponsesConfig(model="gpt-6-luna"),
)

app = A2UIServer(
    agent,
    transport=AgUiTransport(),  # AG-UI endpoint at POST /
    actions=[book_table],
    protocol_version="v0.9",
)

if __name__ == "__main__":
    uvicorn.run(app, host="127.0.0.1", port=8000)
```

`A2UIServer` validates every A2UI message the agent produces against the
component catalog, and retries on validation errors, so malformed UI never
reaches the client. The `AgUiTransport` then emits the validated messages as an
AG-UI activity snapshot (`activityType: "a2ui-surface"`), which is the wire
contract the CopilotKit A2UI renderer consumes.

Register the AG2 endpoint in your Copilot Runtime and enable A2UI:

```ts title="app/api/copilotkit/route.ts"
import { HttpAgent } from "@ag-ui/client";
import {
  CopilotRuntime,
  createCopilotRuntimeHandler,
} from "@copilotkit/runtime/v2";

const runtime = new CopilotRuntime({
  agents: {
    default: new HttpAgent({ url: "http://localhost:8000/" }),
  },
  a2ui: {},
});

const handler = createCopilotRuntimeHandler({
  runtime,
  basePath: "/api/copilotkit",
  mode: "single-route",
});

export { handler as POST };
```

A2UI surfaces from your AG2 agent now render in the chat, and button clicks
travel back to your `@a2ui_action` handlers through the same connection.

<Callout type="info">
  AG2's A2UI transports support protocol versions <code>v0.9</code> (default),
  <code>v0.9.1</code>, and <code>v1.0</code> through the
  <code>protocol_version</code> parameter. See the
  <a href="https://docs.ag2.ai/docs/user-guide/ag-ui/" target="_blank">AG2 AG-UI integration docs</a>
  for the underlying protocol bridge.
</Callout>

## 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](/ag2/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" />
