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:
createSurfaceinitializes the surface with its catalog and must come first.updateComponentsdefines the component tree (the schema) for the surface.updateDataModelsupplies 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 serializesSetup
A2UI turns on in one of two ways. Most apps use the first.
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.
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:
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
Dynamic Schema
A secondary LLM generates both the schema and data. Any UI from any prompt.
Fixed Schema
Pre-authored JSON schema, agent streams data. Fastest path to production-quality UI.
Choose your AI backend
LangGraph (Python)
LangGraph (TypeScript)
LangGraph (FastAPI)
Langchain DeepAgents
Google ADK
Mastra
CrewAI Flows
PydanticAI
Google Antigravity
OpenAI Agents SDK (Python)
Claude Agent SDK (Python)
Claude Agent SDK (TypeScript)
Agno
AG2
LlamaIndex
AWS Strands (Python)
AWS Strands (TypeScript)
MS Agent Framework (Python)
MS Agent Framework (.NET)
MS Agent Harness (.NET)
How is this guide?