# Dynamic Schema A2UI

> LLM-generated A2UI. A secondary LLM creates both the schema and data from any prompt.

> **Not available for a2a yet.** The code on this page comes from the showcase's `declarative-gen-ui` demo, and a2a doesn't have it yet. See this page for [CopilotKit's Built-in Agent](/generative-ui/a2ui/dynamic-schema), [LangGraph (Python)](/langgraph-python/generative-ui/a2ui/dynamic-schema), [LangGraph (TypeScript)](/langgraph-typescript/generative-ui/a2ui/dynamic-schema).

Use a dynamic schema when you cannot know the UI shape ahead of time,
for example a dashboard whose layout changes per question. Your agent
composes the surface (schema, data, and layout) from your components
on each turn.

## How it works [#how-it-works]

1. The agent calls the A2UI tool to draw a surface, made available
   when `injectA2UITool: true`.
2. The runtime serializes your client-side catalog (component names +
   Zod prop schemas) into the agent's `copilotkit.context` so the LLM
   knows which components it may emit.
3. The tool call streams from the agent as `TOOL_CALL_ARGS` events.
4. The A2UI middleware intercepts the stream and renders cards
   progressively as data items arrive.

## The 3-file split [#the-3-file-split]

The canonical Bring-Your-Own-Catalog (BYOC) layout keeps three files
side-by-side under `frontend/src/app/a2ui/`:

| File | What lives there |
|---|---|
| `definitions.ts` | Zod props schema + human-readable descriptions for each custom component. Platform-agnostic, so the runtime can serialise it to the LLM. |
| `renderers.tsx` | React implementations keyed by the same names. TypeScript enforces that every definition has a renderer. |
| `catalog.ts` | `createCatalog(definitions, renderers, { includeBasicCatalog: true })`: merges your custom components with CopilotKit's built-in primitives. |

<Steps>
<Step>
### Declare your custom component definitions [#declare-your-custom-component-definitions]

Each entry pairs a Zod prop schema with a description. The description
matters, because the LLM reads it to decide which component to emit. The
example below is a dashboard catalog with cards (`Card`, `StatusBadge`,
`Metric`, `InfoRow`, `DataTable`, `PrimaryButton`) and charts
(`PieChart`, `BarChart`):

</Step>

<Step>
### Implement the React renderers [#implement-the-react-renderers]

Every key in `myDefinitions` must have a matching renderer. Props are
statically typed against the Zod schema, so refactors stay safe.
The demo renderers use the demo's own `Badge` and `Button` components,
its theme tokens, and `recharts` for the charts. Use your own
components in their place:

</Step>

<Step>
### Wire definitions and renderers into a catalog [#wire-definitions-and-renderers-into-a-catalog]

`createCatalog` is what you hand to the provider. Flip
`includeBasicCatalog: true` to merge CopilotKit's built-ins
(Column, Row, Text, Image, Card, Button, List, Tabs, …), so the LLM
can compose custom + basic components interchangeably:

</Step>

<Step>
### Pass the catalog to the provider [#pass-the-catalog-to-the-provider]

A single prop (`a2ui={{ catalog }}`) is all the frontend needs; the
provider registers the catalog and wires up the built-in A2UI
activity-message renderer:

In your app, use your own runtime URL and your own chat in place of the
demo's `Chat` component.

That is all the default path needs. The catalog auto-enables A2UI and
injects the `generate_a2ui` tool, so the runtime needs no `a2ui` block,
unless your agent brings its own A2UI tool (see [Agent setup](#agent-setup)).
(No catalog? Turn it on from the runtime instead with
`a2ui: { injectA2UITool: true }`.)
</Step>

<Step>
### Ask for a dashboard [#ask-for-a-dashboard]

Ask the agent for a dashboard. For example, send `Show me my sales
dashboard for this quarter`. The dashboard renders in the chat with the
components from your catalog.
</Step>
</Steps>

## Agent setup [#agent-setup]

Tell the model in its instructions when to call `generate_a2ui`, for example
for any answer that needs a dashboard, a card layout, or a chart. A model with
no instruction about the tool answers in prose and never calls it.

## I opted out of auto-inject, now what? [#i-opted-out-of-auto-inject-now-what]

When the runtime does not inject the `generate_a2ui` tool, what you add
depends on your setup:

- **The runtime has an `a2ui` block, or the provider passes a catalog.**
  The runtime still attaches the `A2UIMiddleware`. Add only the A2UI
  agent tool below.
- **No catalog and no `a2ui` block.** A2UI is off. Add both the
  `A2UIMiddleware` and the A2UI agent tool below.

<Steps>
<Step>
### The `A2UIMiddleware` [#the-a2uimiddleware]

The `A2UIMiddleware` is what turns the agent's `a2ui_operations` into
rendered surfaces. Without it, the agent's output never becomes UI; it
falls through as a plain tool result. The middleware can also add a
`render_a2ui` tool to the agent. To do this, set `injectA2UITool: true`
and skip the next step. Attach it to the AG-UI agent:

```typescript
import { A2UIMiddleware } from "@ag-ui/a2ui-middleware";

agent.use(new A2UIMiddleware({ injectA2UITool: false }));
```
</Step>

<Step>
### The A2UI agent tool [#the-a2ui-agent-tool]

The `generate_a2ui` tool runs a secondary LLM (a subagent) that designs
the surface, which is why you hand it a model. With LangGraph Python,
build it with the AG-UI factory and add it to your agent's tools:

```python title="agent.py"
from ag_ui_langgraph import get_a2ui_tools
from langchain_openai import ChatOpenAI

generate_a2ui = get_a2ui_tools({
    "model": ChatOpenAI(model="gpt-6-luna", reasoning_effort="none"),
    "default_catalog_id": "declarative-gen-ui-catalog",  # the catalogId you pass to createCatalog
})

tools = [my_other_tool, generate_a2ui]
```

With other agents, define a `generate_a2ui` tool that calls a second
model and returns an `a2ui_operations` container. The
[Built-in Agent example](https://github.com/CopilotKit/CopilotKit/blob/main/showcase/integrations/built-in-agent/src/lib/factory/a2ui-factory.ts)
shows this in TypeScript.
</Step>
</Steps>

## Progressive streaming [#progressive-streaming]

The secondary LLM's `render_a2ui` tool call streams from the agent
as `TOOL_CALL_ARGS` events. The A2UI middleware:

1. Waits for the full `components` array before emitting anything;
   the schema must be complete before rendering starts.
2. Extracts `surfaceId` + `root` from the partial JSON.
3. Emits `createSurface` + `updateComponents` once the schema is
   complete.
4. Extracts complete `items` objects progressively and emits an
   `updateDataModel` for each, so cards appear one by one as data
   streams in.

A built-in progress indicator shows while the schema is still
generating and hides automatically once data items start arriving.

## When should I use dynamic schemas? [#when-should-i-use-dynamic-schemas]

- You don't know the UI shape ahead of time; the agent decides what
  to show based on the user's request.
- You want to prototype A2UI without committing to a schema file yet.
- You're building a conversational dashboard where the layout varies
  per turn.

If the surface is well-known (e.g. a product card, a flight result),
prefer a **[fixed schema](./fixed-schema)**; it's faster, cheaper,
and the UI is deterministic.

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