# Adopt from A2UI

> Move an app from the a2ui renderer to components and surfaces: the provider, the catalog, the operations, and what the agent receives.

## What is this? [#what-is-this]

The `a2ui` provider option and `@copilotkit/a2ui-renderer` render A2UI v0.9 by default, with explicit A2UI 1.0 support in React: you build a catalog with `createCatalog`, and the agent streams a fixed or a generated schema into it. Components and surfaces is a separate A2UI 1.0 engine. The idea is the same: the agent writes operations, and the browser renders your components. The engine adds typed catalogs, the [standard catalog](/generative-ui/components/standard-catalog), areas of the page as targets, two transports, dynamic values that compute in the browser, and functions the agent can call. This page maps one to the other.

## Use 1.0 with the React a2ui renderer [#use-10-with-the-react-a2ui-renderer]

You can keep the `a2ui` provider option and opt into the native 1.0 basic catalog:

```tsx
import { basicCatalogV1 } from "@copilotkit/a2ui-renderer";

<CopilotKit runtimeUrl="/api/copilotkit" a2ui={{ catalog: basicCatalogV1 }}>
  {/* Your app */}
</CopilotKit>
```

For a custom catalog, choose its protocol explicitly and use the matching binding schemas:

```tsx
import { z } from "zod";
import {
  createCatalog,
  DynamicStringSchemaV1,
} from "@copilotkit/a2ui-renderer";

const myCatalog = createCatalog(
  { Greeting: { props: z.object({ name: DynamicStringSchemaV1 }) } },
  { Greeting: ({ props }) => <p>Hello {props.name}</p> },
  {
    catalogId: "acme/greetings@1",
    protocolVersion: "1.0",
    includeBasicCatalog: true,
  },
);
```

The package also exports `DynamicNumberSchemaV1`, `DynamicBooleanSchemaV1`, `DynamicStringListSchemaV1`, `DataBindingSchemaV1`, `ChildListSchemaV1`, `ActionSchemaV1`, and `CheckRuleSchemaV1`. Bound values use `{ "@path": "/name" }` and function values use `{ "@call": "formatNumber", "args": { ... } }`. Repeating children keep the structural form `{ componentId: "row", path: "/items" }`. Omitting `protocolVersion` from `createCatalog` keeps the existing v0.9 behavior.

Default basic-catalog cards using v0.9 and 1.0 can remain in the same chat history. Each surface keeps its original protocol; create a new surface to change versions. Retaining several historical custom catalogs is not automatic. After an app upgrades its generation catalog, updating an older card may need app-side handling: the renderer forwards its actions but does not switch the agent's catalog for that run.

Your agent integration must also emit native 1.0 `a2ui_operations` through the `a2ui-surface` activity. Selecting this catalog does not upgrade backend packages or establish support in every adapter and streaming mode. This path continues to use the `a2ui` contract; migrating to the `render_ui` contract below is a separate choice.

## Before and after [#before-and-after]

The provider takes a UI instead of a catalog, and the runtime needs no A2UI option:

The examples below start from a v0.9 catalog. If your React a2ui renderer already uses 1.0, its values already use the 1.0 binding syntax; the provider and catalog migration still applies.

<Tabs groupId="frontend_framework" items={["React", "Angular", "Vue"]} persist>
  <Tab value="React">
    ```tsx title="Before"
    <CopilotKit runtimeUrl="/api/copilotkit" a2ui={{ catalog: myCatalog }}>
    ```

    ```tsx title="After"
    <CopilotKitProvider runtimeUrl="/api/copilotkit" generativeUI={{ ui: appUI }}>
    ```
  </Tab>
  <Tab value="Angular">
    ```ts title="Before"
    provideCopilotKit({ runtimeUrl: "/api/copilotkit", a2ui: { catalog: myCatalog } }),
    ```

    ```ts title="After"
    provideCopilotKit({ runtimeUrl: "/api/copilotkit" }),
    provideGenerativeUI({ ui: appUI }),
    ```
  </Tab>
  <Tab value="Vue">
    ```vue title="Before"
    <CopilotKitProvider runtime-url="/api/copilotkit" :a2ui="{ catalog: vueBasicCatalog }">
    ```

    ```vue title="After"
    <CopilotKitProvider runtime-url="/api/copilotkit" :generativeUI="{ ui: appUI }">
    ```
  </Tab>
</Tabs>

```ts title="Runtime, before"
const runtime = new CopilotRuntime({
  agents,
  a2ui: { injectA2UITool: false, agents: ["shop"] },
});
```

```ts title="Runtime, after"
// Nothing: a run that carries a catalog gets the render_ui tool and the guide.
// To force or limit it: generativeUI: true, or generativeUI: { agents: ["shop"] }.
const runtime = new CopilotRuntime({ agents });
```

The chat renders surfaces on its own. For an area of the page, mount [`<GenerativeUISurface id="...">`](/generative-ui/components/surfaces), or `<copilot-generative-ui-surface>` in Angular. For an agent that cannot call tools, use the [markdown transport](/generative-ui/components/markdown-mode). The agent keeps writing A2UI operations; see [Bindings and actions](#bindings-and-actions) for what changed in them.

## Convert a custom catalog [#convert-a-custom-catalog]

Before, a catalog was definitions plus renderers, and a bound prop had to be declared as a union with the binding object:

<Tabs groupId="frontend_framework" items={["React", "Angular", "Vue"]} persist>
  <Tab value="React">
    ```ts title="Before"
    import { createCatalog, DynamicStringSchema } from "@copilotkit/a2ui-renderer";

    const definitions = {
      Airport: {
        props: z.object({ code: DynamicStringSchema, city: DynamicStringSchema }),
      },
      Arrow: { props: z.object({}) },
    };
    const renderers = { Airport, Arrow };
    export const myCatalog = createCatalog(definitions, renderers, {
      catalogId: "acme/flights",
      includeBasicCatalog: true,
    });
    ```
  </Tab>
  <Tab value="Angular">
    ```ts title="Before"
    import { createAngularCatalog, DynamicStringSchema } from "@copilotkit/angular/a2ui";

    const definitions = {
      Airport: {
        props: z.object({ code: DynamicStringSchema, city: DynamicStringSchema }),
      },
      Arrow: { props: z.object({}) },
    };
    const renderers = { Airport, Arrow };
    export const myCatalog = createAngularCatalog(definitions, renderers, {
      catalogId: "acme/flights",
      includeBasicCatalog: true,
    });
    ```
  </Tab>
  <Tab value="Vue">
    In Vue, the `a2ui` option takes `vueBasicCatalog`. `@copilotkit/vue` has no function that builds a custom v0.9 catalog, so there is no custom catalog to convert. Declare your components as shown in the After tab.
  </Tab>
</Tabs>

After, each component is one entry, with the component, a description and plain prop types:

<Tabs groupId="frontend_framework" items={["React", "Angular", "Vue"]} persist>
  <Tab value="React">
    ```ts title="After"
    import {
      createGenerativeUI,
      standardUI,
    } from "@copilotkit/react-core/v2/generative-ui";

    export const appUI = createGenerativeUI({
      id: "acme/flights@1",
      extends: [standardUI],
      components: {
        Airport: {
          component: Airport,
          description: "An airport by IATA code, with its city under it.",
          props: z.object({ code: z.string(), city: z.string() }),
        },
        Arrow: { component: Arrow, description: "An arrow between two airports." },
      },
    });
    ```
  </Tab>
  <Tab value="Angular">
    ```ts title="After"
    import {
      createGenerativeUI,
      standardUI,
    } from "@copilotkit/angular/generative-ui";

    export const appUI = createGenerativeUI({
      id: "acme/flights@1",
      extends: [standardUI],
      components: {
        Airport: {
          component: Airport,
          description: "An airport by IATA code, with its city under it.",
          props: z.object({ code: z.string(), city: z.string() }),
        },
        Arrow: { component: Arrow, description: "An arrow between two airports." },
      },
    });
    ```
  </Tab>
  <Tab value="Vue">
    ```ts title="After"
    import {
      createGenerativeUI,
      standardUI,
    } from "@copilotkit/vue/v2/generative-ui";

    export const appUI = createGenerativeUI({
      id: "acme/flights@1",
      extends: [standardUI],
      components: {
        Airport: {
          component: Airport,
          description: "An airport by IATA code, with its city under it.",
          props: z.object({ code: z.string(), city: z.string() }),
        },
        Arrow: { component: Arrow, description: "An arrow between two airports." },
      },
    });
    ```
  </Tab>
</Tabs>

What every app changes:

- **Prop types are plain.** Drop `DynamicStringSchema` and the unions. Any prop takes a literal, a binding `{ "@path": "/x" }` or a function value `{ "@call": ... }`, and the engine resolves it before your component renders. A component never sees a binding object.
- **Every component gets a `description`.** The agent reads it to pick components.
- **The catalog id** is `id`. A surface with no `catalogId` pins to it. The run also lists the ids of the catalogs in `extends`, so an operation or a component can name `copilotkit/standard@1` or the id of any other base. Any other `catalogId` is rejected.

What to change if you use them:

- **Children** are `slots` (`{ children: "multiple" }`, `{ child: "single" }`) or `child()` / `childList()` inside the props schema, for example `tabs: z.array(z.object({ title: z.string(), child: child() }))`. See [Catalogs](/generative-ui/components/catalogs).
- **The basic catalog** is `extends: [standardUI]`. Drop components with `standardUI.omit([...])` and replace one with `overrides`; see [the standard catalog](/generative-ui/components/standard-catalog#replace-a-component).
- **Actions and app state** become `functions` with `useGenerativeUIFunction`, and `state` with `useGenerativeUIState`; in Angular, `registerGenerativeUIFunction` and `connectGenerativeUIState`. See [Connect app state and actions](/generative-ui/components/state-and-actions).

Your renderers stay as they are, apart from the props they read: a bound prop arrives resolved, and a slot or a child reference arrives as a React node, or as a `GenerativeUIChildren` handle in Angular. In Vue, a slot arrives as a named slot, and a child reference as a `VNode`.

## Bindings and actions [#bindings-and-actions]

The engine takes A2UI 1.0 operations only. A v0.9 shape is rejected with a reason that names the 1.0 form, and the agent sees the reason in the next run.

| v0.9                                              | 1.0                                                                                                                                                               |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{ "path": "/total" }`                            | `{ "@path": "/total" }`                                                                                                                                           |
| A literal only                                    | A literal, `{ "@path" }` or `{ "@call": "formatCurrency", "args": { ... } }`, at any depth                                                                        |
| `"text": "Hello"` with the value elsewhere        | `{ "@call": "formatString", "args": { "value": "Hello ${/user/name}" } }`                                                                                         |
| `"action": { "name": "buy", "context": { ... } }` | `"onClick": { "event": { "name": "buy", "userMessage": "Buy it", "context": { ... } } }` or `{ "functionCall": { "@call": "addToCart", "args": { ... } } }`       |
| `"children": ["a", "b"]`                          | The same, or a template `{ "componentId": "row", "path": "/items" }` with `{ "@call": "@index" }` inside                                                          |
| Validation in the agent                           | `"checks": [{ "condition": { "@call": "email", "args": { ... } }, "message": "..." }]`                                                                            |
| An agent tool call per function                   | Not in this version: the agent cannot call renderer functions; see [Who may call a function](/generative-ui/components/catalogs#who-may-call-a-function) |

A2UI 1.0 has no arithmetic. CopilotKit adds `calc` and `series` as catalog functions, listed like the others. Another A2UI client that does not have them rejects the call. It does not render a wrong value. See [Compute values in the browser](/generative-ui/components/state-and-actions#compute-values-in-the-browser).

## What the agent receives [#what-the-agent-receives]

A click on an `{ "event" }` action becomes a visible user message: the `userMessage`, then the context as lines. The run also carries the A2UI action message. It has `name`, `surfaceId`, `sourceComponentId`, `timestamp`, `userMessage`, and `context`. It is in `forwardedProps.copilotkit.ui.metadata.extensions.copilotkit_action`. To read it, call `envelopeToManifest` from `@copilotkit/shared` and use `action`. A second click while the agent runs is dropped, so a double click does not start two runs.

The agent cannot call renderer functions in this version: a `callRendererFunction` operation is rejected with a reason, and the prompts do not mention it. See [Who may call a function](/generative-ui/components/catalogs#who-may-call-a-function).

## What changes in markdown mode [#what-changes-in-markdown-mode]

In the tool transport, the browser renders what the agent wrote. In the markdown transport, the chat is a transcript, so the engine reshapes the surface of a fence before it renders:

- **Prose is lifted out.** A `Text` title or paragraph that only explains renders as chat markdown; the surface splits around it into parts that share one data model.
- **Informational cards lose their box.** A `Card` with no control inside it (no button, input or form) becomes a `variant: "section"`: a heading plus content. A card with a control keeps its box.
- **A new fence with the same `surfaceId`** in the same reply changes the surface in place; in a later reply it makes a new chat surface.

See [Markdown mode](/generative-ui/components/markdown-mode).

## Support matrix [#support-matrix]

The integration is experimental and implements A2UI 1.0 as of spec revision [`cbaa5ee`](https://github.com/a2ui-project/a2ui/tree/cbaa5ee62c737b50d0695c1e5794d0f648b61dca/specification/v1_0) (October 2026); upstream still calls 1.0 a candidate on [a2ui.org](https://a2ui.org/), so this table can change. This table is the supported scope. A 1.0 catalog and a complete 1.0 runtime are different claims: the catalog export is conforming, the runtime covers the rows marked Yes and nothing more.

| A2UI 1.0 | Components and surfaces |
| --- | --- |
| `createSurface`, `updateComponents`, `updateDataModel`, `deleteSurface` | Yes |
| `callRendererFunction` and `rendererFunctionResponse` | Not in this version: rejected, until results can be sent back to the model reliably |
| `callAgentFunction` and `agentFunctionResponse` | No: a user event starts a new run, with the action message in its envelope |
| The basic catalog (18 components) | Yes, with their 1.0 names, plus 51 more |
| The basic functions (14) | Yes; `calc` and `series` are CopilotKit extensions |
| Dynamic values at any depth, `formatString` with `${}`, `@index` | Yes |
| `checks` and `ValidationResult` (`code`, `severity`) | Yes |
| The action event message (`sourceComponentId`, `timestamp`) | Yes, in the envelope of the run, next to the visible user message |
| Component envelope: `catalogId`, `accessibility`, `metadata` | Yes; `catalogId` must be the id of the UI or of a catalog in its `extends` |
| Function definitions: `returnType`, `allowedCallers`, `requiresUserActivation` | Yes, written to the manifest and the export; the agent path is off regardless |
| Catalog definition JSON | Yes, `exportA2UICatalog(ui)` |
| Several catalogs in one surface | Partly: one UI per provider, and `supportedCatalogIds` lists the UI and every catalog in its `extends`. A component name comes from one catalog only, and a component is not checked against the catalog that the surface names |
| `allowedParents` and `allowedChildren` | Not enforced |
| v0.9 operations and `{ "path" }` bindings | No; rejected with a reason that names the 1.0 form |
| Agent tools built with `@ag-ui/a2ui-toolkit` 0.0.5 | No: the toolkit writes v0.9 operations. Use the `render_ui` tool that the runtime adds |
