Dynamic Schema A2UI

LLM-generated A2UI — a secondary LLM creates both the schema and data from any prompt.

"""LangGraph agent for the Declarative Generative UI (A2UI — Dynamic Schema) demo.Pattern (ported from the canonical`examples/integrations/langgraph-python/agent/src/a2ui_dynamic_schema.py`):- The agent binds an explicit `generate_a2ui` tool. When called, `generate_a2ui`  invokes a secondary LLM bound to `_design_a2ui_surface` (tool_choice forced)  with the registered client catalog injected as `copilotkit.context`. The  internal tool is intentionally NOT named `render_a2ui` to avoid the A2UI  middleware's default tool-call intercept (`a2uiToolNames`).- The tool result returns an `a2ui_operations` container which the A2UI  middleware detects in the tool-call result and forwards to the frontend  renderer.- The runtime (see `src/app/api/copilotkit-declarative-gen-ui/route.ts`) uses  `injectA2UITool: false` because the tool binding is owned by the agent here  (double-injection would duplicate the tool slot).This mirrors `beautiful_chat.py` which exercises the same pattern for theflagship combined cell — the pattern is confirmed working there (Pie Chartclick renders a real styled doughnut).Reference:    examples/integrations/langgraph-python/agent/src/a2ui_dynamic_schema.py"""from __future__ import annotationsimport jsonfrom typing import Anyfrom copilotkit import CopilotKitMiddleware, a2uifrom langchain.agents import create_agentfrom langchain.tools import ToolRuntime, toolfrom langchain_core.messages import SystemMessagefrom langchain_core.tools import tool as lc_toolfrom langchain_openai import ChatOpenAIfrom src.agents._a2ui_utils import has_root_component, sanitize_a2ui_componentsCUSTOM_CATALOG_ID = "declarative-gen-ui-catalog"# Internal tool bound only to the secondary LLM inside `generate_a2ui` for# structured output. Intentionally NOT named `render_a2ui` because the A2UI# middleware default-intercepts tool calls by that name from the run's event# stream and synthesises ACTIVITY_SNAPSHOT events from the LLM's RAW streaming# args (catalogId + components, before our Python code can validate). That# bypass is what surfaced the "Cannot create component root without a type"# infinite-loop on the deployed declarative-gen-ui demo. Renaming sidesteps# the middleware's intercept list (`a2uiToolNames`).@lc_tooldef _design_a2ui_surface(    surfaceId: str,    catalogId: str,    components: list[dict],    data: dict | None = None,) -> str:    """Design a dynamic A2UI v0.9 surface.    Args:        surfaceId: Unique surface identifier.        catalogId: The catalog ID (use "declarative-gen-ui-catalog").        components: A2UI v0.9 component array (flat format). The root            component must have id "root".        data: Optional initial data model for the surface.    """    return "designed"_GENERATE_A2UI_PROMPT_HEADER = f"""\You are designing a dynamic A2UI v0.9 surface. Call the `_design_a2ui_surface`tool with a flat component array.Hard requirements (failing any of these breaks the renderer — be strict):- `catalogId` MUST be exactly: "{CUSTOM_CATALOG_ID}"- `surfaceId` is a short kebab-case identifier (e.g. "kpi-dashboard").- `components` is a FLAT array. Every entry MUST include both an `id` (unique  string) AND a `component` (string — the catalog component name). The root  entry MUST have `id: "root"` AND a valid `component` field — never emit  a root entry without a component type.- Container components (Row, Column, Card) reference children by id via their  `children` (array of strings) or `child` (single string) prop. Do NOT inline  children objects. Define each child as its own entry in the flat array and  reference its id.- Use only catalog component names listed in the schema below."""@tool()def generate_a2ui(runtime: ToolRuntime[Any]) -> str:    """Generate dynamic A2UI components based on the conversation.    A secondary LLM designs the UI schema and data. The result is returned as    an `a2ui_operations` container for the A2UI middleware to detect and    forward to the frontend renderer.    """    messages = runtime.state["messages"][:-1]    # Pull the A2UI component schema + usage guidelines from the runtime's    # `copilotkit.context` (the runtime injects them automatically when the    # frontend registers a catalog via `<CopilotKit a2ui={{ catalog }}>`).    # We prepend an explicit instruction header because the runtime context    # alone leaves room for the LLM to hallucinate catalog IDs or emit a root    # component without a `component` field — both surface as "Cannot create    # component root without a type" infinite-loops in the renderer.    context_entries = runtime.state.get("copilotkit", {}).get("context", [])    context_text = "\n\n".join(        entry.get("value", "")        for entry in context_entries        if isinstance(entry, dict) and entry.get("value")    )    prompt = f"{_GENERATE_A2UI_PROMPT_HEADER}\n\n{context_text}".strip()    # `streaming=True` so aimock's record/replay (which only intercepts    # SSE streams) sees this secondary LLM call. Without it the call    # bypasses fixture matching in replay mode, surfacing as    # "An internal error occurred" on the demo page.    model = ChatOpenAI(model="gpt-5.4", streaming=True)    model_with_tool = model.bind_tools(        [_design_a2ui_surface],        tool_choice="_design_a2ui_surface",    )    response = model_with_tool.invoke(        [SystemMessage(content=prompt), *messages],    )    if not response.tool_calls:        return json.dumps({"error": "LLM did not call _design_a2ui_surface"})    tool_call = response.tool_calls[0]    args = tool_call["args"]    surface_id = args.get("surfaceId", "dynamic-surface")    # Force the canonical catalog ID — the secondary LLM has been observed    # hallucinating IDs from sibling demos when context is sparse.    catalog_id = CUSTOM_CATALOG_ID    components = sanitize_a2ui_components(args.get("components", []))    data = args.get("data", {})    if not has_root_component(components):        return json.dumps(            {"error": "LLM produced no valid root component for the A2UI surface."}        )    ops = [        a2ui.create_surface(surface_id, catalog_id=catalog_id),        a2ui.update_components(surface_id, components),    ]    if data:        ops.append(a2ui.update_data_model(surface_id, data))    return a2ui.render(operations=ops)SYSTEM_PROMPT = (    "You are a demo assistant for Declarative Generative UI (A2UI — Dynamic "    "Schema). Whenever a response would benefit from a rich visual — a "    "dashboard, status report, KPI summary, card layout, info grid, a "    "pie/donut chart of part-of-whole breakdowns, a bar chart comparing "    "values across categories, or anything more structured than plain text — "    "call `generate_a2ui` to draw it. The registered catalog includes "    "`Card`, `StatusBadge`, `Metric`, `InfoRow`, `PrimaryButton`, `PieChart`, "    "and `BarChart` (in addition to the basic A2UI primitives). Prefer "    "`PieChart` for part-of-whole breakdowns (sales by region, traffic "    "sources, portfolio allocation) and `BarChart` for comparisons across "    "categories (quarterly revenue, headcount by team, signups per month). "    "`generate_a2ui` takes no arguments and handles the rendering "    "automatically. Keep chat replies to one short sentence; let the UI do "    "the talking.")graph = create_agent(    model=ChatOpenAI(model="gpt-5.4"),    tools=[generate_a2ui],    middleware=[CopilotKitMiddleware()],    system_prompt=SYSTEM_PROMPT,)

In the dynamic-schema approach, a secondary LLM generates the entire UI (schema, data, and layout) based on the conversation context. It's the most flexible A2UI flavor; the agent can render any UI for any request without pre-defined schemas.

How it works#

The primary LLM decides to call render_a2ui (the tool the runtime auto-injects when injectA2UITool: true).
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.
The tool call streams through LangGraph as TOOL_CALL_ARGS events.
The A2UI middleware intercepts the stream and renders cards progressively as data items arrive.

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.

Declare your custom component definitions#

Each entry pairs a Zod prop schema with a description. The description is crucial; the LLM reads it to decide which component to emit. The example below ships a small dashboard catalog (Card / StatusBadge / Metric / InfoRow / PrimaryButton):

definitions.ts

import { z } from "zod";import type { CatalogDefinitions } from "@copilotkit/a2ui-renderer";export const myDefinitions = {  Card: {    description:      "A titled card container with an optional subtitle and a single child slot. Use it to group related content (metrics, rows, buttons).",    props: z.object({      title: z.string(),      subtitle: z.string().optional(),      child: z.string().optional(),    }),  },  StatusBadge: {    description:      "A small coloured pill communicating the state of something (healthy/degraded/down, online/offline, open/closed). Choose `variant` to match the intent.",    props: z.object({      text: z.string(),      variant: z.enum(["success", "warning", "error", "info"]).optional(),    }),  },  Metric: {    description:      "A key/value KPI display with an optional trend indicator. Ideal for dashboards (e.g. 'Revenue • $12.4k • up').",    props: z.object({      label: z.string(),      value: z.string(),      trend: z.enum(["up", "down", "neutral"]).optional(),    }),  },  InfoRow: {    description:      "A compact two-column 'label: value' row. Good for stacks of facts inside a Card (owner, region, last updated, etc.).",    props: z.object({      label: z.string(),      value: z.string(),    }),  },  PrimaryButton: {    description:      "A styled primary call-to-action button. Attach an optional `action` that will be dispatched back to the agent when the user clicks it.",    props: z.object({      label: z.string(),      action: z.any().optional(),    }),  },  PieChart: {    description:      "A pie/donut chart with a brand-coloured legend. Provide `title`, `description`, and `data` as an array of `{ label, value }` objects. Great for part-of-whole breakdowns (sales by region, traffic sources, portfolio allocation).",    props: z.object({      title: z.string(),      description: z.string(),      data: z.array(        z.object({          label: z.string(),          value: z.number(),        }),      ),    }),  },  BarChart: {    description:      "A vertical bar chart built on Recharts. Provide `title`, `description`, and `data` as an array of `{ label, value }` objects. Great for comparing series across categories (quarterly revenue, headcount by team, signups per month).",    props: z.object({      title: z.string(),      description: z.string(),      data: z.array(        z.object({          label: z.string(),          value: z.number(),        }),      ),    }),  },} satisfies CatalogDefinitions;

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:

renderers.tsx

export const myRenderers: CatalogRenderers<MyDefinitions> = {  Card: ({ props, children }) => (    <Card      className="w-full min-w-0 overflow-hidden"      data-testid="declarative-card"    >      <CardHeader>        <CardTitle>{props.title}</CardTitle>        {props.subtitle && <CardDescription>{props.subtitle}</CardDescription>}      </CardHeader>      {props.child && (        <CardContent className="flex flex-col gap-4">          {children(props.child)}        </CardContent>      )}    </Card>  ),  StatusBadge: ({ props }) => (    <Badge      variant={props.variant ?? "info"}      data-testid="declarative-status-badge"    >      {props.text}    </Badge>  ),  Metric: ({ props }) => {    const trend = props.trend ?? "neutral";    const arrow = trend === "up" ? "↑" : trend === "down" ? "↓" : "";    const trendClass =      trend === "up"        ? "text-emerald-600"        : trend === "down"          ? "text-rose-600"          : "text-[var(--foreground)]";    return (      // `flex-1 min-w-[120px]` lets a row of Metrics distribute evenly      // inside the basic catalog's gap-less Row — 3 metrics in a 600px      // card column get ~200px each instead of squishing to content width.      <div        data-testid="declarative-metric"        className="flex flex-1 min-w-[120px] flex-col gap-1"      >        <div className="text-xs font-medium uppercase tracking-wider text-[var(--muted-foreground)]">          {props.label}        </div>        <div          className={`flex items-baseline gap-1.5 text-2xl font-semibold tabular-nums ${trendClass}`}        >          <span>{props.value}</span>          {arrow && <span className="text-base">{arrow}</span>}        </div>      </div>    );  },  InfoRow: ({ props }) => (    // Divider via `border-b last:border-b-0` so the final row doesn't dangle    // a trailing line, regardless of whether the agent wraps these in a    // Column or drops them directly into a Card's child slot.    <div className="flex items-baseline justify-between gap-4 py-2 border-b border-[var(--border)] last:border-b-0 last:pb-0 first:pt-0">      <span className="text-sm text-[var(--muted-foreground)]">        {props.label}      </span>      <span className="text-sm font-medium text-[var(--foreground)] text-right tabular-nums">        {props.value}      </span>    </div>  ),  PrimaryButton: ({ props, dispatch }) => (    <Button      onClick={() => {        if (props.action && dispatch) dispatch(props.action);      }}    >      {props.label}    </Button>  ),  PieChart: ({ props }) => {    const data = props.data ?? [];    const safeData = Array.isArray(data) ? data : [];    const total = safeData.reduce((sum, d) => sum + (Number(d.value) || 0), 0);    return (      // `flex-1 min-w-0` so multiple charts in a basic-catalog Row      // distribute the available width evenly instead of each insisting      // on its content size and overflowing.      <Card        className="w-full flex-1 min-w-0 overflow-hidden"        data-testid="declarative-pie-chart"      >        <CardHeader>          <CardTitle>{props.title}</CardTitle>          <CardDescription>{props.description}</CardDescription>        </CardHeader>        <CardContent className="flex flex-col gap-4">          {safeData.length === 0 ? (            <div className="py-8 text-center text-sm text-[var(--muted-foreground)]">              No data available            </div>          ) : (            <>              <DonutChart data={safeData} />              <div className="flex flex-col gap-2 pt-2">                {safeData.map((item, index) => {                  const val = Number(item.value) || 0;                  const pct =                    total > 0 ? ((val / total) * 100).toFixed(0) : "0";                  return (                    <div                      key={index}                      className="flex items-center gap-3 text-sm"                    >                      <span                        className="inline-block h-2.5 w-2.5 shrink-0 rounded-sm"                        style={{                          backgroundColor:                            CHART_COLORS[index % CHART_COLORS.length],                        }}                      />                      <span className="flex-1 truncate text-[var(--foreground)]">                        {item.label}                      </span>                      <span className="tabular-nums text-[var(--muted-foreground)]">                        {val.toLocaleString()}                      </span>                      <span className="w-10 text-right tabular-nums text-[var(--muted-foreground)]">                        {pct}%                      </span>                    </div>                  );                })}              </div>            </>          )}        </CardContent>      </Card>    );  },  BarChart: ({ props }) => {    const { isNew } = useSeenIndices();    const data = props.data ?? [];    const safeData = Array.isArray(data) ? data : [];    return (      <Card        className="w-full flex-1 min-w-0 overflow-hidden"        data-testid="declarative-bar-chart"      >        {/* Scoped keyframe — no globals.css needed */}        <style>{`          @keyframes barSlideIn {            from { transform: translateY(40px); opacity: 0; }            20% { opacity: 1; }            to { transform: translateY(0); opacity: 1; }          }        `}</style>        <CardHeader>          <CardTitle>{props.title}</CardTitle>          <CardDescription>{props.description}</CardDescription>        </CardHeader>        <CardContent>          {safeData.length === 0 ? (            <div className="py-8 text-center text-sm text-[var(--muted-foreground)]">              No data available            </div>          ) : (            <ResponsiveContainer width="100%" height={260}>              <RechartsBarChart                data={safeData}                margin={{ top: 12, right: 12, bottom: 4, left: -8 }}              >                <CartesianGrid                  strokeDasharray="3 3"                  stroke="var(--border)"                  vertical={false}                />                <XAxis                  dataKey="label"                  tick={{ fontSize: 12, fill: "var(--muted-foreground)" }}                  stroke="var(--border)"                  tickLine={false}                  axisLine={false}                />                <YAxis                  tick={{ fontSize: 12, fill: "var(--muted-foreground)" }}                  stroke="var(--border)"                  tickLine={false}                  axisLine={false}                />                <Tooltip                  contentStyle={CHART_TOOLTIP_STYLE}                  cursor={{ fill: "var(--muted)", opacity: 0.5 }}                />                <Bar                  isAnimationActive={false}                  dataKey="value"                  radius={[6, 6, 0, 0]}                  maxBarSize={48}                  // eslint-disable-next-line @typescript-eslint/no-explicit-any                  shape={                    ((barProps: any) => (                      <AnimatedBar                        {...barProps}                        isNew={isNew(barProps.index as number)}                      />                      // eslint-disable-next-line @typescript-eslint/no-explicit-any                    )) as any                  }                >                  {safeData.map((_, index) => (                    <Cell                      key={index}                      fill={CHART_COLORS[index % CHART_COLORS.length]}                    />                  ))}                </Bar>              </RechartsBarChart>            </ResponsiveContainer>          )}        </CardContent>      </Card>    );  },};

Wire definitions × 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:

catalog.ts

import { createCatalog } from "@copilotkit/a2ui-renderer";import { myDefinitions } from "./definitions";import { myRenderers } from "./renderers";export const myCatalog = createCatalog(myDefinitions, myRenderers, {  catalogId: "declarative-gen-ui-catalog",  includeBasicCatalog: true,});

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:

page.tsx

import React from "react";import { CopilotKit } from "@copilotkit/react-core/v2";import { myCatalog } from "./a2ui/catalog";import { Chat } from "./chat";export default function DeclarativeGenUIDemo() {  return (    <CopilotKit      runtimeUrl="/api/copilotkit-declarative-gen-ui"      agent="declarative-gen-ui"      a2ui={{ catalog: myCatalog }}    >      <div className="flex justify-center items-center h-screen w-full">        <div className="h-full w-full max-w-4xl">          <Chat />        </div>      </div>    </CopilotKit>

Inject the render tool on the runtime#

On the TypeScript runtime, injectA2UITool: true tells CopilotKit to add the render_a2ui tool to the agent's tool list at request time and serialise your client catalog into the agent's copilotkit.context. No backend code to write; the agent can be an empty create_agent(tools=[]):

app/api/copilotkit/route.ts

const runtime = new CopilotRuntime({
  agents: { default: myAgent },
  a2ui: {
    injectA2UITool: true,
  },
});

Progressive streaming#

The secondary LLM's render_a2ui tool call streams through LangGraph as TOOL_CALL_ARGS events. The A2UI middleware:

Waits for the full components array before emitting anything — the schema must be complete before rendering starts.
Extracts surfaceId + root from the partial JSON.
Emits surfaceUpdate + beginRendering once the schema is complete.
Extracts complete items objects progressively and emits a dataModelUpdate 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?#

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; it's faster, cheaper, and the UI is deterministic.