Fixed Schema A2UI

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

A2UI Fixed Schema

Waking up the demo

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 .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 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

  1. 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.
  2. The agent's display_flight tool receives data from the primary LLM (origin / destination / airline / price).
  3. The tool returns an operations container with createSurface + updateComponents + updateDataModel operations.
  4. 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 zod

Declare 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";
definitions.ts
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 definitions = {
  /**
   * Card override: gives the outer flight-card container a ShadCN look
   * (rounded-xl, neutral-200 border, soft shadow). The basic catalog's
   * Card uses inline styles; overriding here lets the demo's renderer
   * adopt the demo's Tailwind aesthetic without touching the schema JSON.
   */
  Card: {
    description: "A container card with a single child.",
    props: z.object({
      child: z.string(),
    }),
  },
  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. 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:

renderers.tsx
export const renderers: CatalogRenderers<Definitions> = {
  /**
   * Card override: ShadCN-style outer container. The basic catalog's Card
   * uses inline styles; overriding here keeps the demo's tailwind aesthetic.
   * The flight schema renders Card > Column > [Title, Row, …]; the inner
   * Column adds the vertical spacing.
   */
  Card: ({ props, children }) => (
    <Card className="w-full max-w-md p-5" data-testid="a2ui-fixed-card">
      {props.child ? children(props.child) : null}
    </Card>
  ),
  Title: ({ props }) => (
    <div className="flex items-center justify-between">
      <div className="space-y-1">
        <p className="text-[11px] font-medium uppercase tracking-[0.14em] text-neutral-500 dark:text-muted-foreground">
          Itinerary
        </p>
        <h3 className="text-base font-semibold leading-none tracking-tight text-neutral-900 dark:text-foreground">
          {s(props.text)}
        </h3>
      </div>
      <Badge variant="outline" className="font-mono">
        1-stop · economy
      </Badge>
    </div>
  ),
  Airport: ({ props }) => (
    <div className="flex flex-col items-center">
      <span className="font-mono text-2xl font-semibold tracking-wider text-neutral-900 dark:text-foreground">
        {s(props.code)}
      </span>
    </div>
  ),
  Arrow: () => (
    <div className="flex flex-1 items-center px-3">
      <Separator className="flex-1 bg-neutral-200 dark:bg-border" />
      <svg
        width="16"
        height="16"
        viewBox="0 0 24 24"
        fill="none"
        stroke="currentColor"
        strokeWidth="2"
        strokeLinecap="round"
        strokeLinejoin="round"
        className="mx-1 text-neutral-400 dark:text-muted-foreground"
        aria-hidden
      >
        <line x1="5" y1="12" x2="19" y2="12" />
        <polyline points="12 5 19 12 12 19" />
      </svg>
      <Separator className="flex-1 bg-neutral-200 dark:bg-border" />
    </div>
  ),
  AirlineBadge: ({ props }) => (
    <Badge variant="secondary" className="uppercase tracking-[0.08em]">
      {s(props.name)}
    </Badge>
  ),
  PriceTag: ({ props }) => (
    <div className="flex items-baseline gap-1">
      <span className="text-[11px] font-medium uppercase tracking-[0.14em] text-neutral-500 dark:text-muted-foreground">
        Total
      </span>
      <span className="font-mono text-base font-semibold text-neutral-900 dark:text-foreground">
        {s(props.amount)}
      </span>
    </div>
  ),
  /**
   * Button override: wires the schema `action` to the click and shows a
   * "Booked" confirmation after click (see ActionButton above). Mirrors the
   * built-in-agent a2ui-fixed-schema renderer.
   */
  Button: ({ props, children }) => (
    <ActionButton action={(props as { action?: unknown }).action}>
      {props.child ? children(props.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:

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

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

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

export const catalog = createCatalog(definitions, renderers, {
  catalogId: CATALOG_ID,
  includeBasicCatalog: true,
});

Generate the schema dynamically

Mastra and Strands Python take a different route: the agent tool runs a secondary LLM call with a forced tool choice that produces the operations container per-request. The frontend catalog is still fixed (same Title/Airport/Arrow/AirlineBadge/PriceTag primitives), but the schema is built on the fly. Schema construction and render emission happen in the same tool call.

Neither SDK ships an a2ui.render(...) equivalent here, so the tool assembles the a2ui_operations envelope itself. In Mastra, the operation builder is in the snippet below. In Strands Python, the snippet imports the builder (build_a2ui_operations_from_tool_call) and the catalog helpers from the demo's shared tools package. Copy those functions with the tool. Note the operations are nested ({ createSurface: {...} }): a consumer dispatches on the operation key, so a flat { type: "create_surface" } shape is ignored and the surface never paints.

a2ui-generate.ts
import { createTool } from "@mastra/core/tools";
import { z } from "zod";
import { generateText, tool as aiTool } from "ai";
// In your own app this is `import { openai } from "@ai-sdk/openai"`. The
// showcase wraps it so this backend tool's own LLM call carries the inbound
// request's aimock headers — see `_header_forwarding.ts`.
import { openai } from "@/mastra/_header_forwarding";
// Reads the catalog schema + generation guidelines the AG-UI bridge forwards
// onto Mastra's request context, and flattens them into the inner call's system
// prompt. In your own app, hand the inner call whatever description of your
// catalog you want it to render against. Copy the required a2ui-context.ts
// companion from the example's Code tab when using this implementation.
import { readForwardedA2uiContext, systemPromptFrom } from "./a2ui-context";

/** Catalog the surface is pinned to when the model omits `catalogId`. */
const DEFAULT_CATALOG_ID = "copilotkit://app-dashboard-catalog";
const DEFAULT_SURFACE_ID = "dynamic-surface";

/**
 * A2UI v0.9 operations are NESTED (`{ createSurface: {...} }`), not flat
 * (`{ type: "create_surface", ... }`): a consumer dispatches on the operation
 * key, so a flat shape is silently ignored and the surface never paints.
 */
type A2UIOperation =
  | { version: "v0.9"; createSurface: { surfaceId: string; catalogId: string } }
  | {
      version: "v0.9";
      updateComponents: {
        surfaceId: string;
        components: Array<Record<string, unknown>>;
      };
    }
  | {
      version: "v0.9";
      updateDataModel: {
        surfaceId: string;
        path: string;
        value: Record<string, unknown>;
      };
    };

/**
 * Turn the inner model's `render_a2ui` arguments into the `a2ui_operations`
 * container the A2UI middleware detects in a tool result.
 */
function buildA2uiOperations(args: Record<string, unknown>): {
  a2ui_operations: A2UIOperation[];
} {
  const surfaceId = (args.surfaceId as string) ?? DEFAULT_SURFACE_ID;
  const catalogId = (args.catalogId as string) ?? DEFAULT_CATALOG_ID;
  const components = (args.components as Array<Record<string, unknown>>) ?? [];
  const data = args.data as Record<string, unknown> | undefined;

  if (components.length === 0) {
    console.warn("generate-a2ui: empty components for surface", surfaceId);
  }

  const operations: A2UIOperation[] = [
    { version: "v0.9", createSurface: { surfaceId, catalogId } },
    { version: "v0.9", updateComponents: { surfaceId, components } },
  ];

  // Emit `updateDataModel` only when there is data to seed. An empty object is
  // truthy in JS, so guard on key count to stay in step with the Python
  // reference (`if data:`), which skips the op for `{}`.
  if (
    data != null &&
    typeof data === "object" &&
    Object.keys(data).length > 0
  ) {
    operations.push({
      version: "v0.9",
      updateDataModel: { surfaceId, path: "/", value: data },
    });
  }

  return { a2ui_operations: operations };
}

/**
 * Normalize an incoming message role to the `user`/`assistant` pair
 * `generateText` accepts. An unsound `as "user" | "assistant"` cast would let a
 * `system`/`tool` role slip through mis-typed (a `??` only guards
 * null/undefined), so map explicitly: anything that is not `assistant`
 * collapses to `user`.
 */
function toRole(role: unknown): "user" | "assistant" {
  return role === "assistant" ? "assistant" : "user";
}

// The `generate-a2ui` tool runs a secondary LLM call with a forced
// `render_a2ui` tool, then converts that tool call's args into the
// A2UI `a2ui_operations` container that the middleware forwards to
// the frontend renderer. Mastra returns the operations as a JSON
// string from the tool body; the catalog resolves component names to
// React renderers on the client.
export const generateA2uiTool = createTool({
  id: "generate-a2ui",
  description: "Generate dynamic A2UI surface components",
  inputSchema: z.object({
    messages: z.array(z.record(z.unknown())).describe("Chat messages"),
    contextEntries: z
      .array(z.record(z.unknown()))
      .optional()
      .describe("Context entries"),
  }),
  execute: async ({ messages, contextEntries }, executionContext) => {
    // The outer model leaves `contextEntries` empty — it has no basis to hand
    // the catalog schema back through a tool arg — so on a live LLM the inner
    // `render_a2ui` subagent would run with an EMPTY system prompt: ungrounded,
    // it emits invalid/misnamed components (or none), and the surface fails to
    // render, varying run to run. (aimock hides it: the recorded fixture
    // returns a valid envelope regardless of the empty context.) The bridge
    // already forwards the catalog schema + generation guidelines onto the
    // request context, so read them server-side and ground the render there
    // rather than trusting the model-supplied arg.
    const forwardedContext = readForwardedA2uiContext(executionContext);
    const systemPrompt = systemPromptFrom(
      forwardedContext.length > 0 ? forwardedContext : contextEntries,
    );

    const result = await generateText({
      model: openai("gpt-6-luna"),
      system: systemPrompt,
      messages: messages.map((m) => ({
        role: toRole(m.role),
        content: (m.content as string) ?? "",
      })),
      tools: {
        render_a2ui: aiTool({
          description: "Render a dynamic A2UI v0.9 surface.",
          // AI SDK v5 renamed the tool schema key from `parameters` to
          // `inputSchema`; under v5 a `parameters` key is ignored, so the
          // render_a2ui schema would never reach the model.
          inputSchema: z.object({
            surfaceId: z.string().describe("Unique surface identifier."),
            catalogId: z.string().describe("The catalog ID."),
            components: z
              .array(z.record(z.unknown()))
              .describe("A2UI v0.9 component array."),
            data: z
              .record(z.unknown())
              .optional()
              .describe("Optional initial data model."),
          }),
        }),
      },
      toolChoice: { type: "tool", toolName: "render_a2ui" },
    });

    const toolCall = result.toolCalls?.[0];
    if (!toolCall) {
      // The forced `render_a2ui` tool was not called, so there are no
      // operations to forward. Returning a `{ error }` JSON string would look
      // like a successful tool result to the frontend/runtime, which cannot
      // then distinguish it from a real A2UI payload. Throw instead so the
      // Mastra runtime surfaces this as a genuine tool error.
      const message = "generate-a2ui: LLM did not call render_a2ui";
      console.error(message, { finishReason: result.finishReason });
      throw new Error(message);
    }

    // AI SDK v5 renamed the typed tool-call arguments from `.args` to
    // `.input` (the `ai` v4 shape was `toolCall.args`). Read `.input` so the
    // a2ui builder gets the render_a2ui arguments instead of `undefined`.
    return JSON.stringify(
      buildA2uiOperations(toolCall.input as Record<string, unknown>),
    );
  },
});

Pass the catalog to the provider

Passing a catalog on the provider is enough to enable A2UI:

app/page.tsx
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:

app/api/copilotkit/route.ts
const runtime = new CopilotRuntime({
  agents: { "a2ui-fixed-schema": agent },
  a2ui: { injectA2UITool: false, agents: ["a2ui-fixed-schema"] },
});

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 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.

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?