Fixed Schema A2UI

Pre-defined A2UI schema with dynamic data. The fastest approach — no LLM schema generation needed.

In the fixed-schema approach, you design the UI schema once (by hand, or using the A2UI Composer) and keep it on the agent side. The agent tool only provides the data; the surface appears instantly when the tool returns because nothing has to be generated at runtime.

How the schema is delivered to the runtime is the only thing that varies between integrations:

Schema-loading (langgraph-python, langgraph-typescript, langgraph-fastapi, llamaindex, crewai-crews, pydantic-ai, ms-agent-python, google-adk) — the schema is saved as a .json file 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_schema JSON loader, so the structure is compiled in directly.
LLM-driven (mastra, strands) — 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.

Ask about a flight and the agent renders a fully structured card from a pre-defined schema:

Live Demo: Built-in Agent (TanStack AI) — a2ui-fixed-schemaOpen full demo →

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_flight tool receives data from the primary LLM (origin / destination / airline / price).
The tool returns a2ui.render(...) with createSurface + updateComponents + updateDataModel operations.
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 A2UI binder resolves those paths before the React renderer runs, so renderer props are typed as their resolved values (plain z.string(), not a path-or-literal union).

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.

Declare the component definitions#

Each component declares its props as a Zod schema. Props are the resolved values, never the path expressions:

src/app/demos/a2ui-fixed-schema/a2ui/definitions.ts

L19–89

import { z } from "zod";
import type { CatalogDefinitions } from "@copilotkit/a2ui-renderer";

/**
 * Dynamic string: literal OR a data-model path binding. The GenericBinder
 * resolves path bindings to the actual value at render time.
 */
const DynString = z.union([z.string(), z.object({ path: z.string() })]);

export const flightDefinitions = {
  Title: {
    description: "A prominent heading for the flight card.",
    props: z.object({
      text: DynString,
    }),
  },
  Airport: {
    description: "A 3-letter airport code, displayed large.",
    props: z.object({
      code: DynString,
    }),
  },
  Arrow: {
    description: "A right-pointing arrow used between airports.",
    props: z.object({}),
  },
  AirlineBadge: {
    description: "A pill-styled airline name tag.",
    props: z.object({
      name: DynString,
    }),
  },
  PriceTag: {
    description: "A stylized price display (e.g. '$289').",
    props: z.object({
      amount: DynString,
    }),
  },
  /**
   * Button override: swaps in an ActionButton renderer that tracks
   * its own `done` state so clicking "Book flight" visually updates to
   * a "Booked ✓" confirmation. The basic catalog's Button is stateless,
   * so without this override the click fires the action but the button
   * looks unchanged. Mirrors the pattern in beautiful-chat
   * (src/app/demos/beautiful-chat/declarative-generative-ui/renderers.tsx).
   */
  Button: {
    description:
      "An interactive button with an action event. Use 'child' with a Text component ID for the label. After click, the button shows a confirmation state.",
    props: z.object({
      child: z
        .string()
        .describe(
          "The ID of the child component (e.g. a Text component for the label).",
        ),
      variant: z.enum(["primary", "secondary", "ghost"]).optional(),
      // Union with { event } so GenericBinder resolves this as ACTION → callable () => void.
      action: z
        .union([
          z.object({
            event: z.object({
              name: z.string(),
              context: z.record(z.any()).optional(),
            }),
          }),
          z.null(),
        ])
        .optional(),
    }),
  },
} satisfies CatalogDefinitions;

Implement the React renderers#

TypeScript enforces that the renderer map's keys and prop shapes match the definitions exactly, so refactors stay safe:

src/app/demos/a2ui-fixed-schema/a2ui/renderers.tsx

L88–174

export const flightRenderers: CatalogRenderers<FlightDefinitions> = {
  Title: ({ props: rawProps }) => {
    const props = rawProps as Record<string, any>;
    return (
      <div
        style={{
          fontSize: "1.15rem",
          fontWeight: 600,
          color: "#010507",
        }}
      >
        {props.text}
      </div>
    );
  },
  Airport: ({ props: rawProps }) => {
    const props = rawProps as Record<string, any>;
    return (
      <span
        style={{
          fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
          fontSize: "1.5rem",
          fontWeight: 600,
          letterSpacing: "0.05em",
          color: "#010507",
        }}
      >
        {props.code}
      </span>
    );
  },
  Arrow: () => <span style={{ color: "#AFAFB7", fontSize: "1.5rem" }}>→</span>,
  AirlineBadge: ({ props: rawProps }) => {
    const props = rawProps as Record<string, any>;
    return (
      <span
        style={{
          display: "inline-block",
          padding: "2px 10px",
          background: "rgba(190, 194, 255, 0.15)",
          color: "#010507",
          border: "1px solid #BEC2FF",
          borderRadius: 999,
          fontSize: "0.75rem",
          fontWeight: 600,
          letterSpacing: "0.08em",
          textTransform: "uppercase",
        }}
      >
        {props.name}
      </span>
    );
  },
  PriceTag: ({ props: rawProps }) => {
    const props = rawProps as Record<string, any>;
    return (
      <span
        style={{
          fontWeight: 600,
          fontSize: "1.1rem",
          color: "#189370",
          fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
        }}
      >
        {props.amount}
      </span>
    );
  },
  /**
   * Button override: the basic catalog's Button is stateless. This
   * stateful version lets clicking "Book flight" transition to
   * "Booked ✓" without a round-trip to the agent.
   */
  Button: ({ props, children }) => {
    return (
      <ActionButton
        label="Book flight"
        doneLabel="Booked"
        action={(props as Record<string, any>).action}
      >
        {(props as Record<string, any>).child
          ? children((props as Record<string, any>).child)
          : null}
      </ActionButton>
    );
  },
};

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:

src/app/demos/a2ui-fixed-schema/a2ui/catalog.ts

L11–21

import { createCatalog } from "@copilotkit/a2ui-renderer";

import { flightDefinitions } from "./definitions";
import { flightRenderers } from "./renderers";

export const CATALOG_ID = "copilotkit://flight-fixed-catalog";

export const fixedCatalog = createCatalog(flightDefinitions, flightRenderers, {
  catalogId: CATALOG_ID,
  includeBasicCatalog: true,
});

Define the schema inline#

Spring AI / .NET don't ship a load_schema JSON helper, so the component tree is declared inline as a typed literal in source — equivalent to deserialising a flight_schema.json but compiled into the agent class. The structure is identical to the JSON form; only the surface syntax changes:

src/app/demos/a2ui-fixed-schema/a2ui-backend.snippet.ts

L11–44

declare const a2ui: {
  createSurface: (id: string, opts: { catalogId: string }) => unknown;
  updateComponents: (id: string, schema: unknown) => unknown;
  updateDataModel: (id: string, data: Record<string, unknown>) => unknown;
  render: (args: { operations: unknown[] }) => unknown;
};
const SURFACE_ID = "flight-fixed-schema";
const CATALOG_ID = "flight-catalog";

// In the schema-inline pattern, the schema is declared as a typed literal
// in source rather than loaded from JSON at startup. Same shape as the
// schema-loading variant; just no file I/O.
const FLIGHT_SCHEMA = [
  {
    type: "Card",
    children: [
      { type: "Title", text: "Flight" },
      {
        type: "Row",
        children: [
          { type: "Label", bind: "origin" },
          { type: "Label", bind: "destination" },
        ],
      },
      {
        type: "Row",
        children: [
          { type: "Label", bind: "airline" },
          { type: "Label", bind: "price" },
        ],
      },
    ],
  },
];

Return render operations from the tool#

The agent tool builds the same createSurface + updateComponents + updateDataModel operations container and returns it. The A2UI middleware detects the operations in the tool result and forwards them to the frontend renderer; the LLM only supplies the four data fields:

src/app/demos/a2ui-fixed-schema/a2ui-backend.snippet.ts

L11–66

declare const a2ui: {
  createSurface: (id: string, opts: { catalogId: string }) => unknown;
  updateComponents: (id: string, schema: unknown) => unknown;
  updateDataModel: (id: string, data: Record<string, unknown>) => unknown;
  render: (args: { operations: unknown[] }) => unknown;
};
const SURFACE_ID = "flight-fixed-schema";
const CATALOG_ID = "flight-catalog";

// In the schema-inline pattern, the schema is declared as a typed literal
// in source rather than loaded from JSON at startup. Same shape as the
// schema-loading variant; just no file I/O.
const FLIGHT_SCHEMA = [
  {
    type: "Card",
    children: [
      { type: "Title", text: "Flight" },
      {
        type: "Row",
        children: [
          { type: "Label", bind: "origin" },
          { type: "Label", bind: "destination" },
        ],
      },
      {
        type: "Row",
        children: [
          { type: "Label", bind: "airline" },
          { type: "Label", bind: "price" },
        ],
      },
    ],
  },
];

export function emitRenderOperations(args: {
  origin: string;
  destination: string;
  airline: string;
  price: number;
}) {
  // The a2ui middleware detects the `a2ui_operations` container in this
  // tool result and forwards the ops to the frontend renderer. The
  // frontend catalog resolves component names to local React components.
  return a2ui.render({
    operations: [
      a2ui.createSurface(SURFACE_ID, { catalogId: CATALOG_ID }),
      a2ui.updateComponents(SURFACE_ID, FLIGHT_SCHEMA),
      a2ui.updateDataModel(SURFACE_ID, {
        origin: args.origin,
        destination: args.destination,
        airline: args.airline,
        price: args.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 Airport renderer 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.

Registering the runtime#

On the TypeScript side, A2UI's middleware auto-detects the operations in any tool result, so even with a fixed schema, the minimum setup is a2ui: {}. The a2ui-fixed-schema cell happens to also keep injectA2UITool: true so the same agent can be pointed at dynamic-schema workflows later without re-configuring.

app/api/copilotkit/route.ts

typescript

const runtime = new CopilotRuntime({
  agents: { "a2ui-fixed-schema": agent },
  a2ui: { injectA2UITool: true, agents: ["a2ui-fixed-schema"] },
});

Action handlers (reference)#

The canonical reference pairs fixed schemas with action_handlers={...} to declare optimistic UI swaps (e.g. replacing the flight schema with BOOKED_SCHEMA when the user clicks "Book"). The Python SDK's a2ui.render does not yet accept action_handlers, so the cell omits them; the booked_schema.json sibling is retained so the swap can be wired up the moment the SDK exposes the handler kwarg.

When available, a button declares its action like this:

{
  "Button": {
    "label": "Book",
    "action": {
      "name": "book_flight",
      "context": [
        { "key": "flightNumber", "value": { "path": "/flightNumber" } },
        { "key": "price", "value": { "path": "/price" } }
      ]
    }
  }
}

And the Python tool matches it with a handler keyed by the action name (plus a "*" catch-all). Until the SDK lands, see the reference fixed-schema guide for the full pattern.

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.

Fixed Schema A2UI

Pre-defined A2UI schema with dynamic data. The fastest approach — no LLM schema generation needed.

How the schema is delivered to the runtime is the only thing that varies between integrations:

Schema-loading (langgraph-python, langgraph-typescript, langgraph-fastapi, llamaindex, crewai-crews, pydantic-ai, ms-agent-python, google-adk) — the schema is saved as a .json file 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_schema JSON loader, so the structure is compiled in directly.
LLM-driven (mastra, strands) — 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.

Ask about a flight and the agent renders a fully structured card from a pre-defined schema:

Live Demo: Built-in Agent (TanStack AI) — a2ui-fixed-schemaOpen full demo →

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_flight tool receives data from the primary LLM (origin / destination / airline / price).
The tool returns a2ui.render(...) with createSurface + updateComponents + updateDataModel operations.
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)

The 5-component custom catalog#

Declare the component definitions#

Each component declares its props as a Zod schema. Props are the resolved values, never the path expressions:

src/app/demos/a2ui-fixed-schema/a2ui/definitions.ts

L19–89

import { z } from "zod";
import type { CatalogDefinitions } from "@copilotkit/a2ui-renderer";

/**
 * Dynamic string: literal OR a data-model path binding. The GenericBinder
 * resolves path bindings to the actual value at render time.
 */
const DynString = z.union([z.string(), z.object({ path: z.string() })]);

export const flightDefinitions = {
  Title: {
    description: "A prominent heading for the flight card.",
    props: z.object({
      text: DynString,
    }),
  },
  Airport: {
    description: "A 3-letter airport code, displayed large.",
    props: z.object({
      code: DynString,
    }),
  },
  Arrow: {
    description: "A right-pointing arrow used between airports.",
    props: z.object({}),
  },
  AirlineBadge: {
    description: "A pill-styled airline name tag.",
    props: z.object({
      name: DynString,
    }),
  },
  PriceTag: {
    description: "A stylized price display (e.g. '$289').",
    props: z.object({
      amount: DynString,
    }),
  },
  /**
   * Button override: swaps in an ActionButton renderer that tracks
   * its own `done` state so clicking "Book flight" visually updates to
   * a "Booked ✓" confirmation. The basic catalog's Button is stateless,
   * so without this override the click fires the action but the button
   * looks unchanged. Mirrors the pattern in beautiful-chat
   * (src/app/demos/beautiful-chat/declarative-generative-ui/renderers.tsx).
   */
  Button: {
    description:
      "An interactive button with an action event. Use 'child' with a Text component ID for the label. After click, the button shows a confirmation state.",
    props: z.object({
      child: z
        .string()
        .describe(
          "The ID of the child component (e.g. a Text component for the label).",
        ),
      variant: z.enum(["primary", "secondary", "ghost"]).optional(),
      // Union with { event } so GenericBinder resolves this as ACTION → callable () => void.
      action: z
        .union([
          z.object({
            event: z.object({
              name: z.string(),
              context: z.record(z.any()).optional(),
            }),
          }),
          z.null(),
        ])
        .optional(),
    }),
  },
} satisfies CatalogDefinitions;

Implement the React renderers#

TypeScript enforces that the renderer map's keys and prop shapes match the definitions exactly, so refactors stay safe:

src/app/demos/a2ui-fixed-schema/a2ui/renderers.tsx

L88–174

export const flightRenderers: CatalogRenderers<FlightDefinitions> = {
  Title: ({ props: rawProps }) => {
    const props = rawProps as Record<string, any>;
    return (
      <div
        style={{
          fontSize: "1.15rem",
          fontWeight: 600,
          color: "#010507",
        }}
      >
        {props.text}
      </div>
    );
  },
  Airport: ({ props: rawProps }) => {
    const props = rawProps as Record<string, any>;
    return (
      <span
        style={{
          fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
          fontSize: "1.5rem",
          fontWeight: 600,
          letterSpacing: "0.05em",
          color: "#010507",
        }}
      >
        {props.code}
      </span>
    );
  },
  Arrow: () => <span style={{ color: "#AFAFB7", fontSize: "1.5rem" }}>→</span>,
  AirlineBadge: ({ props: rawProps }) => {
    const props = rawProps as Record<string, any>;
    return (
      <span
        style={{
          display: "inline-block",
          padding: "2px 10px",
          background: "rgba(190, 194, 255, 0.15)",
          color: "#010507",
          border: "1px solid #BEC2FF",
          borderRadius: 999,
          fontSize: "0.75rem",
          fontWeight: 600,
          letterSpacing: "0.08em",
          textTransform: "uppercase",
        }}
      >
        {props.name}
      </span>
    );
  },
  PriceTag: ({ props: rawProps }) => {
    const props = rawProps as Record<string, any>;
    return (
      <span
        style={{
          fontWeight: 600,
          fontSize: "1.1rem",
          color: "#189370",
          fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
        }}
      >
        {props.amount}
      </span>
    );
  },
  /**
   * Button override: the basic catalog's Button is stateless. This
   * stateful version lets clicking "Book flight" transition to
   * "Booked ✓" without a round-trip to the agent.
   */
  Button: ({ props, children }) => {
    return (
      <ActionButton
        label="Book flight"
        doneLabel="Booked"
        action={(props as Record<string, any>).action}
      >
        {(props as Record<string, any>).child
          ? children((props as Record<string, any>).child)
          : null}
      </ActionButton>
    );
  },
};

Wire the catalog#

src/app/demos/a2ui-fixed-schema/a2ui/catalog.ts

L11–21

import { createCatalog } from "@copilotkit/a2ui-renderer";

import { flightDefinitions } from "./definitions";
import { flightRenderers } from "./renderers";

export const CATALOG_ID = "copilotkit://flight-fixed-catalog";

export const fixedCatalog = createCatalog(flightDefinitions, flightRenderers, {
  catalogId: CATALOG_ID,
  includeBasicCatalog: true,
});

Define the schema inline#

src/app/demos/a2ui-fixed-schema/a2ui-backend.snippet.ts

L11–44

declare const a2ui: {
  createSurface: (id: string, opts: { catalogId: string }) => unknown;
  updateComponents: (id: string, schema: unknown) => unknown;
  updateDataModel: (id: string, data: Record<string, unknown>) => unknown;
  render: (args: { operations: unknown[] }) => unknown;
};
const SURFACE_ID = "flight-fixed-schema";
const CATALOG_ID = "flight-catalog";

// In the schema-inline pattern, the schema is declared as a typed literal
// in source rather than loaded from JSON at startup. Same shape as the
// schema-loading variant; just no file I/O.
const FLIGHT_SCHEMA = [
  {
    type: "Card",
    children: [
      { type: "Title", text: "Flight" },
      {
        type: "Row",
        children: [
          { type: "Label", bind: "origin" },
          { type: "Label", bind: "destination" },
        ],
      },
      {
        type: "Row",
        children: [
          { type: "Label", bind: "airline" },
          { type: "Label", bind: "price" },
        ],
      },
    ],
  },
];

Return render operations from the tool#

src/app/demos/a2ui-fixed-schema/a2ui-backend.snippet.ts

L11–66

declare const a2ui: {
  createSurface: (id: string, opts: { catalogId: string }) => unknown;
  updateComponents: (id: string, schema: unknown) => unknown;
  updateDataModel: (id: string, data: Record<string, unknown>) => unknown;
  render: (args: { operations: unknown[] }) => unknown;
};
const SURFACE_ID = "flight-fixed-schema";
const CATALOG_ID = "flight-catalog";

// In the schema-inline pattern, the schema is declared as a typed literal
// in source rather than loaded from JSON at startup. Same shape as the
// schema-loading variant; just no file I/O.
const FLIGHT_SCHEMA = [
  {
    type: "Card",
    children: [
      { type: "Title", text: "Flight" },
      {
        type: "Row",
        children: [
          { type: "Label", bind: "origin" },
          { type: "Label", bind: "destination" },
        ],
      },
      {
        type: "Row",
        children: [
          { type: "Label", bind: "airline" },
          { type: "Label", bind: "price" },
        ],
      },
    ],
  },
];

export function emitRenderOperations(args: {
  origin: string;
  destination: string;
  airline: string;
  price: number;
}) {
  // The a2ui middleware detects the `a2ui_operations` container in this
  // tool result and forwards the ops to the frontend renderer. The
  // frontend catalog resolves component names to local React components.
  return a2ui.render({
    operations: [
      a2ui.createSurface(SURFACE_ID, { catalogId: CATALOG_ID }),
      a2ui.updateComponents(SURFACE_ID, FLIGHT_SCHEMA),
      a2ui.updateDataModel(SURFACE_ID, {
        origin: args.origin,
        destination: args.destination,
        airline: args.airline,
        price: args.price,
      }),
    ],
  });

Why compositional beats monolithic#

Reusable primitives — the same Airport renderer 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.

Registering the runtime#

app/api/copilotkit/route.ts

typescript

const runtime = new CopilotRuntime({
  agents: { "a2ui-fixed-schema": agent },
  a2ui: { injectA2UITool: true, agents: ["a2ui-fixed-schema"] },
});

Action handlers (reference)#

When available, a button declares its action like this:

{
  "Button": {
    "label": "Book",
    "action": {
      "name": "book_flight",
      "context": [
        { "key": "flightNumber", "value": { "path": "/flightNumber" } },
        { "key": "price", "value": { "path": "/price" } }
      ]
    }
  }
}

And the Python tool matches it with a handler keyed by the action name (plus a "*" catch-all). Until the SDK lands, see the reference fixed-schema guide for the full pattern.

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.