|
| 1 | +--- |
| 2 | +title: A2UI |
| 3 | +description: The declarative tier of generative UI — the agent assembles a surface from a catalog of components you own. |
| 4 | +icon: table-cells |
| 5 | +mode: "wide" |
| 6 | +--- |
| 7 | + |
| 8 | +## The agent assembles the UI |
| 9 | + |
| 10 | +[Tool-based rendering](/en/guides/frontend/tool-based-generative-ui) maps one tool to one component: the agent picks a component, you draw it. A2UI is the **declarative** tier of the [generative-UI spectrum](/en/guides/frontend/generative-ui#declarative) — instead of picking a single component, the agent **assembles a surface** by combining building blocks from a catalog you define. |
| 11 | + |
| 12 | +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. |
| 13 | + |
| 14 | +<Note> |
| 15 | +A2UI works with [Flows](/en/concepts/flows). Both modes below — dynamic and fixed-schema — run as Flows served over AG-UI, exactly like the rest of this section. |
| 16 | +</Note> |
| 17 | + |
| 18 | +## The catalog (same for every mode) |
| 19 | + |
| 20 | +The frontend wiring is identical no matter which backend mode you use: you register a **catalog** on the `<CopilotKit>` provider with the `a2ui` prop. |
| 21 | + |
| 22 | +```tsx |
| 23 | +import { CopilotKit } from "@copilotkit/react-core"; |
| 24 | +import { catalog } from "@/a2ui-catalog"; |
| 25 | + |
| 26 | +<CopilotKit runtimeUrl="/api/copilotkit" agent="assistant" a2ui={{ catalog }}> |
| 27 | + {/* ... */} |
| 28 | +</CopilotKit> |
| 29 | +``` |
| 30 | + |
| 31 | +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. |
| 32 | + |
| 33 | +<Note> |
| 34 | +Authoring the catalog itself — the id schema, prop mapping, and composition rules — is deeper than this page covers. See the [CopilotKit A2UI docs](https://docs.copilotkit.ai) for the full authoring reference. Here we focus on the two backend modes and when to reach for each. |
| 35 | +</Note> |
| 36 | + |
| 37 | +## Two backend modes |
| 38 | + |
| 39 | +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. |
| 40 | + |
| 41 | +| Mode | Who designs the layout | Backend | Predictability | |
| 42 | +| --- | --- | --- | --- | |
| 43 | +| **[Dynamic](#dynamic)** | The agent, from the conversation | No A2UI tool — auto-injected | Novel layouts, LLM layout step | |
| 44 | +| **[Fixed-schema](#fixed-schema)** | You, up front | Backend tools return an envelope | Deterministic, no layout step | |
| 45 | + |
| 46 | +### Dynamic |
| 47 | + |
| 48 | +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. |
| 49 | + |
| 50 | +<Steps> |
| 51 | + |
| 52 | +<Step title="Register the catalog on the provider"> |
| 53 | + |
| 54 | +Same as above — pass your catalog through the `a2ui` prop: |
| 55 | + |
| 56 | +```tsx |
| 57 | +<CopilotKit runtimeUrl="/api/copilotkit" agent="assistant" a2ui={{ catalog }}> |
| 58 | + {/* ... */} |
| 59 | +</CopilotKit> |
| 60 | +``` |
| 61 | + |
| 62 | +</Step> |
| 63 | + |
| 64 | +<Step title="Serve a normal Flow"> |
| 65 | + |
| 66 | +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. |
| 67 | + |
| 68 | +</Step> |
| 69 | + |
| 70 | +<Step title="Let the agent compose"> |
| 71 | + |
| 72 | +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. |
| 73 | + |
| 74 | +</Step> |
| 75 | + |
| 76 | +</Steps> |
| 77 | + |
| 78 | +### Fixed-schema |
| 79 | + |
| 80 | +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. |
| 81 | + |
| 82 | +Install the toolkit that provides the envelope helpers: |
| 83 | + |
| 84 | +```bash |
| 85 | +pip install ag-ui-a2ui-toolkit |
| 86 | +``` |
| 87 | + |
| 88 | +Build the envelope with the toolkit helpers and emit it as the tool result: |
| 89 | + |
| 90 | +```python |
| 91 | +from ag_ui_a2ui_toolkit import ( |
| 92 | + A2UI_OPERATIONS_KEY, |
| 93 | + create_surface, |
| 94 | + update_components, |
| 95 | + update_data_model, |
| 96 | +) |
| 97 | +from ag_ui_crewai.sdk import copilotkit_emit_tool_result, copilotkit_stream |
| 98 | +``` |
| 99 | + |
| 100 | +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. |
| 101 | + |
| 102 | +## When to use which |
| 103 | + |
| 104 | +<CardGroup cols={2}> |
| 105 | + <Card title="Dynamic" icon="wand-magic-sparkles"> |
| 106 | + The layout is not known ahead of time and you want the agent to compose novel surfaces from your primitives. You gain flexibility and pay for an LLM layout step. |
| 107 | + </Card> |
| 108 | + <Card title="Fixed-schema" icon="table-cells"> |
| 109 | + The layout is known and only the data varies. More predictable and deterministic — no generation, no recovery, no LLM in the layout path. |
| 110 | + </Card> |
| 111 | +</CardGroup> |
| 112 | + |
| 113 | +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. |
| 114 | + |
| 115 | +## Related |
| 116 | + |
| 117 | +<CardGroup cols={3}> |
| 118 | + <Card title="Generative UI" icon="wand-magic-sparkles" href="/en/guides/frontend/generative-ui"> |
| 119 | + The full spectrum — A2UI is its declarative tier. |
| 120 | + </Card> |
| 121 | + <Card title="Tool-Based Generative UI" icon="puzzle-piece" href="/en/guides/frontend/tool-based-generative-ui"> |
| 122 | + Map one tool to one component (controlled). |
| 123 | + </Card> |
| 124 | + <Card title="Agentic Generative UI" icon="list-check" href="/en/guides/frontend/agentic-generative-ui"> |
| 125 | + Render live agent state (controlled). |
| 126 | + </Card> |
| 127 | +</CardGroup> |
0 commit comments