# Fixed Schema A2UI

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

<!-- interactive demo: a2ui-fixed-schema -->

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](https://a2ui-composer.ag-ui.com/)) 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 [#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 [#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](#declare-the-component-definitions).

## The 5-component custom catalog [#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`.

<Steps>
<Step>
### Install the renderer package [#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
npm install @copilotkit/a2ui-renderer zod
```
</Step>

<Step>
### Declare the component definitions [#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.

<Callout type="warn" title="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](https://react.dev/errors/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.
</Callout>

`@copilotkit/a2ui-renderer` also exports `DynamicStringSchema`,
`DynamicNumberSchema`, and `DynamicBooleanSchema`. Use them in place of
a hand-written union:

```ts
import { DynamicStringSchema } from "@copilotkit/a2ui-renderer";
```

```typescript title="src/app/demos/a2ui-fixed-schema/a2ui/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;
```
</Step>

<Step>
### Implement the React renderers [#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:

```typescript title="src/app/demos/a2ui-fixed-schema/a2ui/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: this is a pure-presentation demo, so the button just
   * renders its label. The schema declares an `action` for visual fidelity,
   * but the click handler is inert until the Python SDK exposes
   * `action_handlers=` on `a2ui.render` (see `src/agents/a2ui_fixed.py`).
   */
  Button: ({ props, children }) => (
    <UIButton className="w-full">
      {props.child ? children(props.child) : null}
    </UIButton>
  ),
};
```
</Step>

<Step>
### Wire the catalog [#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:

```typescript title="src/app/demos/a2ui-fixed-schema/a2ui/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,
});
```
</Step>

<Step>
### Load the schema JSON at startup [#load-the-schema-json-at-startup]

Save the component tree as `a2ui_schemas/flight_schema.json` next to the
agent. Each `{ "path": ... }` value binds a prop to the data model:

```json title="a2ui_schemas/flight_schema.json"
[
  { "id": "root", "component": "Card", "child": "content" },
  {
    "id": "content",
    "component": "Column",
    "children": ["title", "route", "meta", "bookButton"]
  },
  { "id": "title", "component": "Title", "text": "Flight Details" },
  {
    "id": "route",
    "component": "Row",
    "justify": "spaceBetween",
    "align": "center",
    "children": ["from", "arrow", "to"]
  },
  { "id": "from", "component": "Airport", "code": { "path": "/origin" } },
  { "id": "arrow", "component": "Arrow" },
  { "id": "to", "component": "Airport", "code": { "path": "/destination" } },
  {
    "id": "meta",
    "component": "Row",
    "justify": "spaceBetween",
    "align": "center",
    "children": ["airline", "price"]
  },
  { "id": "airline", "component": "AirlineBadge", "name": { "path": "/airline" } },
  { "id": "price", "component": "PriceTag", "amount": { "path": "/price" } },
  {
    "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" }
        }
      }
    }
  },
  { "id": "bookButtonLabel", "component": "Text", "text": "Book flight" }
]
```

The integration parses the pre-authored JSON schema once at startup.
The agent then reuses that component tree for every tool call:

```typescript title="src/agent/a2ui-fixed-prompt.ts"
import flightSchema from "./a2ui_schemas/flight_schema.json";

export const A2UI_FIXED_CATALOG_ID = "copilotkit://flight-fixed-catalog";
export const A2UI_FIXED_SURFACE_ID = "flight-fixed-schema";

export const FLIGHT_SCHEMA: unknown[] = flightSchema as unknown[];
```
</Step>

<Step>
### Return render operations from the tool [#return-render-operations-from-the-tool]

The agent tool returns an A2UI operations container. The A2UI middleware
detects it in the tool result and forwards it to the frontend renderer.
The LLM only supplies the four data fields (`origin`, `destination`,
`airline`, `price`); the pre-authored schema defines the component tree:

```typescript title="src/agent/a2ui-fixed-prompt.ts"
import flightSchema from "./a2ui_schemas/flight_schema.json";

export const A2UI_FIXED_CATALOG_ID = "copilotkit://flight-fixed-catalog";
export const A2UI_FIXED_SURFACE_ID = "flight-fixed-schema";

export const FLIGHT_SCHEMA: unknown[] = flightSchema as unknown[];

export const A2UI_FIXED_SYSTEM_PROMPT =
  "You help users find flights. When asked about a flight, call " +
  "display_flight with origin (3-letter code), destination (3-letter " +
  "code), airline, and price (e.g. '$289'). Keep any chat reply to one " +
  "short sentence.";

export const DISPLAY_FLIGHT_TOOL_SCHEMA: Anthropic.Tool = {
  name: "display_flight",
  description:
    "Show a flight card for the given trip. Emits an a2ui_operations " +
    "container the frontend renders into a flight card via the fixed " +
    "schema catalog.",
  input_schema: {
    type: "object",
    properties: {
      origin: {
        type: "string",
        description: "Origin airport code, e.g. 'SFO'",
      },
      destination: {
        type: "string",
        description: "Destination airport code, e.g. 'JFK'",
      },
      airline: { type: "string", description: "Airline name, e.g. 'United'" },
      price: { type: "string", description: "Price string, e.g. '$289'" },
    },
    required: ["origin", "destination", "airline", "price"],
  },
};

/**
 * Build the `a2ui_operations` payload the A2UI runtime middleware
 * detects in tool results and forwards to the frontend renderer.
 *
 * Ops MUST use the v0.9 NESTED operation shape
 * (`{ version, createSurface: {...} }` / `updateComponents` /
 * `updateDataModel`) that `@ag-ui/a2ui-middleware`'s
 * `getOperationSurfaceId` and the React A2UI renderer walk. The legacy
 * flat shape (`{ type: "create_surface", surfaceId, ... }`) looks
 * plausible but the middleware's matcher never recognizes it — every op
 * lands on the fallback "default" surface and the renderer never
 * receives the schema, so the `a2ui-fixed-card` never mounts. See the
 * identical fix note in `showcase/shared/python/tools/generate_a2ui.py`
 * (`build_a2ui_operations_from_tool_call`).
 */
export function buildDisplayFlightOperations(input: {
  origin: string;
  destination: string;
  airline: string;
  price: string;
}): { a2ui_operations: unknown[] } {
  return {
    a2ui_operations: [
      {
        version: "v0.9",
        createSurface: {
          surfaceId: A2UI_FIXED_SURFACE_ID,
          catalogId: A2UI_FIXED_CATALOG_ID,
        },
      },
      {
        version: "v0.9",
        updateComponents: {
          surfaceId: A2UI_FIXED_SURFACE_ID,
          components: FLIGHT_SCHEMA,
        },
      },
      {
        version: "v0.9",
        updateDataModel: {
          surfaceId: A2UI_FIXED_SURFACE_ID,
          path: "/",
          value: input,
        },
      },
    ],
  };
}
```

Nothing about A2UI depends on how the agent itself is built. The operations
container is just the tool's return value, so the tool drops into whatever agent
you already have.
</Step>

<Step>
### Pass the catalog to the provider [#pass-the-catalog-to-the-provider]

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

```tsx title="app/page.tsx"
import { catalog } from "./a2ui/catalog";

<CopilotKit runtimeUrl="/api/copilotkit" a2ui={{ catalog }}>
  {children}
</CopilotKit>
```
</Step>

<Step>
### Turn off tool injection on the runtime [#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:

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

<Steps>
  <Step>
    ### Register the fixed-schema tool at the endpoint

    The dedicated endpoint supplies `DISPLAY_FLIGHT_TOOL_SCHEMA` to the shared
    agent loop. This is the first connection between the schema shown above and
    the executable backend tool.

~~~~typescript title="agent_server.ts"
app.post(
  "/a2ui-fixed-schema",
  async (req: Request, res: Response): Promise<void> => {
    await runAgenticLoop(req, res, {
      systemPrompt: A2UI_FIXED_SYSTEM_PROMPT,
      toolSchemas: [DISPLAY_FLIGHT_TOOL_SCHEMA] as Anthropic.Tool[],
      initialState: {},
    });
  },
);
~~~~

  </Step>

  <Step>
    ### Select the Claude Agent SDK path

    A normal request has no runtime-provided tools, structured input, extended
    thinking, or aimock headers, so `shouldUseClaudeAgentSdk` selects the
    production `ClaudeAgentAdapter` path. The direct Anthropic Messages API
    loop remains a compatibility fallback for those excluded request shapes.

~~~~typescript title="claude-agent-sdk-adapter.ts"
export function shouldUseClaudeAgentSdk({
  input,
  forwardedHeaders,
  runtimeToolCount,
  enableThinking,
}: {
  input: RunAgentInput;
  forwardedHeaders: Record<string, string>;
  runtimeToolCount: number;
  enableThinking?: boolean;
}): boolean {
  if ((process.env.ANTHROPIC_BASE_URL ?? "").includes("aimock")) {
    return false;
  }
  // The official adapter keeps a `headers` property for forward compatibility,
  // but the Claude Agent SDK cannot forward per-request HTTP headers today.
  if (hasHeader(forwardedHeaders, "x-aimock-context")) {
    return false;
  }
  if (enableThinking) {
    return false;
  }
  // The official Claude Agent SDK path can execute backend MCP tools, but it
  // does not yet bridge CopilotKit frontend/runtime tools back through AG-UI.
  if (runtimeToolCount > 0) {
    return false;
  }
  if (hasStructuredUserContent(input)) {
    return false;
  }
  return true;
}
~~~~

~~~~typescript title="agent_server.ts"
  if (
    shouldUseClaudeAgentSdk({
      input,
      forwardedHeaders,
      runtimeToolCount: runtimeTools.length,
      enableThinking: config.enableThinking,
    })
  ) {
    await runWithClaudeAgentSdk({
      input,
      emit,
      runId,
      threadId,
      systemPrompt,
      toolSchemas: config.toolSchemas,
      initialState: state,
      model: config.model ?? CLAUDE_MODEL,
      forwardedHeaders,
      executeTool: (toolName, toolInput, currentState, toolEmit) =>
        executeBackendTool(
          toolName,
          toolInput,
          currentState,
          toolEmit,
          forwardedHeaders,
          contextString,
        ),
    });
    res.end();
    return;
  }
~~~~

  </Step>

  <Step>
    ### Expose `display_flight` through an SDK MCP server

    `runWithClaudeAgentSdk` converts the Anthropic tool schema into an
    in-process Claude SDK MCP tool, registers the server on
    `ClaudeAgentAdapter`, and adds the fully-qualified
    `mcp__copilotkit__display_flight` name to `allowedTools`.

~~~~typescript title="claude-agent-sdk-adapter.ts"
function createClaudeAgentAdapter({
  toolSchemas,
  emit,
  getState,
  setState,
  executeTool,
  model,
  systemPrompt,
}: {
  toolSchemas: Anthropic.Tool[];
  emit: Emit;
  getState: () => Record<string, unknown>;
  setState: (state: Record<string, unknown>) => void;
  executeTool: ExecuteTool;
  model: string;
  systemPrompt: string;
}) {
  const backendToolServer = buildBackendToolServer({
    toolSchemas,
    emit,
    getState,
    setState,
    executeTool,
  });

  return new ClaudeAgentAdapter({
    agentId: "claude-sdk-typescript",
    model: normalizeClaudeAgentSdkModel(model),
    systemPrompt,
    tools: [],
    mcpServers: backendToolServer.mcpServers,
    allowedTools: backendToolServer.allowedTools,
    permissionMode: "dontAsk",
    maxTurns: 10,
  });
}
~~~~

~~~~typescript title="claude-agent-sdk-adapter.ts"
const COPILOTKIT_MCP_SERVER_NAME = "copilotkit";
const COPILOTKIT_TOOL_PREFIX = `mcp__${COPILOTKIT_MCP_SERVER_NAME}__`;

function buildBackendToolServer({
  toolSchemas,
  emit,
  getState,
  setState,
  executeTool,
}: {
  toolSchemas: Anthropic.Tool[];
  emit: Emit;
  getState: () => Record<string, unknown>;
  setState: (state: Record<string, unknown>) => void;
  executeTool: ExecuteTool;
}): {
  mcpServers?: Record<string, McpServerConfig>;
  allowedTools: string[];
} {
  if (toolSchemas.length === 0) {
    return { allowedTools: [] };
  }

  const tools = toolSchemas.map((schema) =>
    sdkTool(
      schema.name,
      schema.description ?? "",
      zodShapeFromJsonSchema(schema.input_schema),
      async (args) => {
        try {
          const result = await executeTool(
            schema.name,
            args as Record<string, unknown>,
            getState(),
            emit,
          );
          if (result.state) {
            setState(result.state);
          }
          return {
            content: [{ type: "text" as const, text: result.resultText }],
          };
        } catch (error) {
          const message =
            error instanceof Error ? error.message : String(error);
          return {
            content: [{ type: "text" as const, text: message }],
            isError: true,
          };
        }
      },
    ),
  );

  return {
    mcpServers: {
      [COPILOTKIT_MCP_SERVER_NAME]: createSdkMcpServer({
        name: COPILOTKIT_MCP_SERVER_NAME,
        version: "1.0.0",
        tools,
      }),
    },
    allowedTools: toolSchemas.map(
      (schema) => `${COPILOTKIT_TOOL_PREFIX}${schema.name}`,
    ),
  };
}
~~~~

  </Step>

  <Step>
    ### Execute the tool and return A2UI operations

    When the MCP tool invokes `display_flight`, the backend dispatches to the
    canonical handler, builds the fixed schema's A2UI operations, and returns
    them as the tool result for the middleware to render.

~~~~typescript title="agent_server.ts"
  if (toolName === "display_flight") {
    const origin = typeof toolInput.origin === "string" ? toolInput.origin : "";
    const destination =
      typeof toolInput.destination === "string" ? toolInput.destination : "";
    const airline =
      typeof toolInput.airline === "string" ? toolInput.airline : "";
    const price = typeof toolInput.price === "string" ? toolInput.price : "";
    const ops = buildDisplayFlightOperations({
      origin,
      destination,
      airline,
      price,
    });
    return {
      resultText: JSON.stringify(ops),
      state: null,
    };
  }
~~~~

  </Step>
</Steps>
</Step>

<Step>
### Ask about a flight [#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.
</Step>
</Steps>

## Why compositional beats monolithic [#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) [#action-handlers-reference]

The flight card's **Book flight** button declares its action in the schema:

```json
{
  "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](/claude-sdk-typescript/generative-ui/a2ui/advanced#action-handlers).

## When should I use fixed schemas? [#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](./dynamic-schema)** instead.

<IntegrationGrid path="generative-ui/a2ui" />
