Fixed Schema A2UI
Pre-defined A2UI schema with dynamic data. The fastest approach, with no LLM schema generation needed.
Not available for Langchain DeepAgents yet
a2ui-fixed-schema demo, and Langchain DeepAgents doesn't have it yet. See this page for CopilotKit's Built-in Agent, LangGraph (Python), LangGraph (TypeScript).Use a fixed schema when your agent always shows the same kind of card, such as a flight or an order. You design the layout once (by hand, or with the A2UI Composer) and keep it on the agent side. The agent tool supplies only the data, so the card appears as soon as the tool returns.
How the schema is delivered to the runtime is the only thing that varies between integrations:
- Schema-loading (including Strands TypeScript), the schema is saved
as a
.jsonfile next to the agent and loaded once at startup. - Schema-inline (spring-ai, ms-agent-dotnet), the schema is
declared inline as a typed literal in source. The host language
doesn't ship a
load_schemaJSON loader, so the structure is compiled in directly. - LLM-driven (Mastra and Strands Python), the agent runs a secondary LLM call to produce the operations container per-request. The catalog is still fixed; the schema is generated on demand.
The examples on this page use a flight card. Use your own components and tool.
How it works
- The schema is made available to the agent, either loaded from a JSON file at startup, declared inline, or generated per-request, depending on the integration.
- The agent's
display_flighttool receives data from the primary LLM (origin / destination / airline / price). - The tool returns an operations container with
createSurface+updateComponents+updateDataModeloperations. - The A2UI middleware intercepts the tool result and the frontend renders the surface using the matching 5-component client catalog (Title, Airport, Arrow, AirlineBadge, PriceTag, plus the built-ins).
Compositional schemas
The example below ships a flight card assembled compositionally from
small sub-components rather than one monolithic FlightCard:
Card
└─ Column
├─ Title ("Flight Details")
├─ Row (Airport → Arrow → Airport)
├─ Row (AirlineBadge · PriceTag)
└─ Button (Book)That tree lives backend-side, as a JSON file, an inline literal, or
a per-request LLM output, depending on the integration. Components
without data bindings (like Title or Arrow) carry their value
inline; components bound to the LLM's data (like Airport) reference
fields via JSON Pointer paths such as { "path": "/origin" }. The
binder resolves each path before your renderer runs. Your renderer gets
the value, not the path. To declare a bound prop, see Declare the
component definitions.
The 5-component custom catalog
The frontend catalog declares just the domain-specific primitives
(Title, Airport, Arrow, AirlineBadge, PriceTag) and merges in
CopilotKit's basic catalog (Card, Column, Row, Text, Button, …) via
includeBasicCatalog: true.
Install the renderer package
The catalog, definitions and renderers below all import from
@copilotkit/a2ui-renderer. It ships separately from
@copilotkit/react-core, and the definitions use zod for prop schemas:
npm install @copilotkit/a2ui-renderer zodDeclare the component definitions
Declare every prop that the schema binds to data as DynString (a
string or a { path } object). With a plain z.string(), the binder
does not resolve the prop, and the raw { path } object reaches your
renderer.
Plain z.string() on a bound prop crashes the render
Because the unresolved object reaches the renderer, the first thing
that renders it as text throws React's
error #31:
Objects are not valid as a React child (found: object with keys {path}).
Nothing in that message points at the schema, so it reads as a renderer
bug rather than a missing union. If you hit it, check the prop's
declared type first.
Props that are never bound (Arrow, or a variant enum) are fine as
plain types. This applies only to props the schema binds.
@copilotkit/a2ui-renderer also exports DynamicStringSchema,
DynamicNumberSchema, and DynamicBooleanSchema. Use them in place of
a hand-written union:
import { DynamicStringSchema } from "@copilotkit/a2ui-renderer";Implement the React renderers
TypeScript enforces that the renderer map's keys and prop shapes
match the definitions exactly, so refactors stay safe. The demo
renderers use the demo's own Card, Badge, Button, and Separator
components. They also call an s() helper,
(v) => (typeof v === "string" ? v : ""), that narrows a value to a
string. Use your own components in their place:
Wire the catalog
createCatalog(..., { includeBasicCatalog: true }) merges the custom
renderers with CopilotKit's built-ins so the schema can reference
Card, Column, Row, Button alongside the domain primitives:
Pass the catalog to the provider
Passing a catalog on the provider is enough to enable A2UI:
import { catalog } from "./a2ui/catalog";
<CopilotKit runtimeUrl="/api/copilotkit" a2ui={{ catalog }}>
{children}
</CopilotKit>Turn off tool injection on the runtime
Your agent owns the tool in the fixed-schema approach. A catalog
auto-injects the A2UI tool by default, so set injectA2UITool: false
on the runtime. Then your agent's own tool is the only one in play. The
middleware still finds the operations that the tool returns and renders
the surface, with no subagent involved:
const runtime = new CopilotRuntime({
agents: { "a2ui-fixed-schema": agent },
a2ui: { injectA2UITool: false, agents: ["a2ui-fixed-schema"] },
});Deep Agents has no live demo on this page yet, so the demo code above does
not show for it. On a Deep Agent, the fixed schema is a JSON file that a
LangChain tool loads with the copilotkit.a2ui helpers. This example renders
a list of flights instead of the single card above. The pattern is the same.
Save the schema as JSON
Design your schema in the A2UI Composer or write it by hand. Save it next to your agent:
apps/agent/src/a2ui/schemas/flight_schema.jsonReturn render operations from the tool
from copilotkit import a2ui
from langchain.tools import tool
from pathlib import Path
from typing import TypedDict
class Flight(TypedDict):
id: str
airline: str
airlineLogo: str
flightNumber: str
origin: str
destination: str
date: str
departureTime: str
arrivalTime: str
duration: str
status: str
statusIcon: str
price: str
SURFACE_ID = "flight-search-results"
FLIGHT_SCHEMA = a2ui.load_schema(
Path(__file__).parent / "a2ui" / "schemas" / "flight_schema.json"
)
@tool
def search_flights(flights: list[Flight]) -> str:
"""Search for flights and display results as rich cards."""
return a2ui.render(
operations=[
a2ui.create_surface(SURFACE_ID),
a2ui.update_components(SURFACE_ID, FLIGHT_SCHEMA),
a2ui.update_data_model(SURFACE_ID, {"flights": flights}),
],
)- The
FlightTypedDict is essential. LangChain turns it into the tool's JSON schema, which is what the model sees when it decides what data to generate. Without it, the model does not know which fields the schema binds to. - Button clicks go to the agent as a user action. This example has no
server-side handler for them. To handle
book_flightin the browser, see Action Handlers.
Register the tool with your Deep Agent
from deepagents import create_deep_agent
from src.a2ui_fixed_schema import search_flights
agent = create_deep_agent(
tools=[search_flights, ...],
...
)Keep injectA2UITool: false on the runtime, as shown above. The
search_flights tool owns this surface, and the A2UI middleware still
renders its a2ui.render() result.
Ask about a flight
Send Find me a flight from SFO to JFK on United for $289 in the chat.
The flight card renders in the chat with the two airports, the airline,
and the price.
Why compositional beats monolithic
A single big FlightCard component would be faster to write but would
lock the design in place. Assembling the card from Card / Column /
Row / Title / Airport / Arrow / AirlineBadge / PriceTag gives you:
- Reusable primitives the same
Airportrenderer works in search results, booking confirmations, and future seat maps. - Schema-level design iteration re-arranging rows or swapping a badge requires only a JSON edit; the renderer code is untouched.
- A2UI Composer compatibility hand-written and Composer-built schemas share the same primitive vocabulary.
Action handlers (reference)
The flight card's Book flight button declares its action in the schema:
{
"id": "bookButton",
"component": "Button",
"variant": "primary",
"child": "bookButtonLabel",
"action": {
"event": {
"name": "book_flight",
"context": {
"origin": { "path": "/origin" },
"destination": { "path": "/destination" },
"airline": { "path": "/airline" },
"price": { "path": "/price" }
}
}
}
}When the user clicks the button, CopilotKit sends the action to the agent
in a new run. To handle the click in the browser instead, pass onAction
to createA2UIMessageRenderer. See
Action Handlers.
When should I use fixed schemas?
- The surface is well-known: flight cards, product tiles, order summaries, dashboards.
- You want deterministic, designer-controlled UI. No LLM schema drift.
- You want the fastest possible first paint; no secondary LLM call.
If the UI must adapt per prompt, reach for dynamic schemas instead.
How is this guide?