# Markdown mode

> Let the agent write UI inside its markdown reply, in a2ui code blocks, with no tool call.

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

Your agent streams text well, but tool calls are a pain: the framework does not pass client tools, or you build the prompt yourself. You still want the reply to contain real UI.

In markdown mode, the agent writes the UI inside its reply, in a code block tagged `a2ui`. The chat renders each block as a live surface, and the text around it as normal markdown:

````markdown
Here is an estimate you can play with:

```a2ui
{"version":"1.0","createSurface":{"surfaceId":"plan-estimator","dataModel":{"seats":10,"price":"$290 / month"},"components":[{"id":"root","component":"Card","children":["seats","price"]}]}}
{"version":"1.0","updateComponents":{"surfaceId":"plan-estimator","components":[{"id":"seats","component":"Slider","label":"Seats","min":1,"max":50,"value":{"@path":"/seats"}},{"id":"price","component":"Text","text":{"@path":"/price"}}]}}
```

Move the slider to change the seat count.
````

Each line is one [A2UI v1.0](https://a2ui.org) operation. The UI is plain text, so this works with any AG-UI agent that streams text.

<Callout type="info" title="React Native">
  Markdown mode is not available on React Native yet. `GenerativeUIProvider` from `@copilotkit/react-native/generative-ui` uses the [tool transport](/generative-ui/components/transports#tool-transport) only: `transport: "markdown"` is a type error, and passed from JavaScript it is dropped, with a warning in development.
</Callout>

## Turn it on [#turn-it-on]

Set the markdown transport on the provider:

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

    <CopilotKitProvider runtimeUrl="/api/copilotkit" generativeUI={{ ui: standardUI, transport: "markdown" }}>
      {children}
    </CopilotKitProvider>;
    ```
  </Tab>
  <Tab value="Angular">
    ```ts title="src/app/app.config.ts"
    import { provideCopilotKit } from "@copilotkit/angular";
    import { provideGenerativeUI, standardUI } from "@copilotkit/angular/generative-ui";

    providers: [
      provideCopilotKit({ runtimeUrl: "/api/copilotkit" }),
      provideGenerativeUI({ ui: standardUI, transport: "markdown" }),
    ],
    ```

    `provideGenerativeUI` then renders each assistant message with the blocks replaced by their surfaces, unless the app gives `<copilot-chat-assistant-message>` its own markdown renderer.
  </Tab>
  <Tab value="Vue">
    ```vue title="src/App.vue"
    <script setup lang="ts">
    import { CopilotKitProvider } from "@copilotkit/vue/v2";
    import { standardUI } from "@copilotkit/vue/v2/generative-ui";
    </script>

    <template>
      <CopilotKitProvider runtime-url="/api/copilotkit" :generativeUI="{ ui: standardUI, transport: 'markdown' }">
        <slot />
      </CopilotKitProvider>
    </template>
    ```

    The chat then renders each assistant message with the blocks replaced by their surfaces. If you fill the `message-renderer` slot of the assistant message, render the content with `<MarkdownSurfaces :content="content" :message-id="message.id" />` to keep the surfaces.
  </Tab>
</Tabs>

On every run, the provider then sends the agent two context entries:

- A compact schema of the components: their names, props, events, and slots.
- A guide on how to write the code blocks. It has only the rules that your catalog needs, and it leaves out the advice that names a standard component your catalog does not have.

The runtime adds no `render_ui` tool to these runs. The built-in agent puts the context entries into its system prompt. For a LangGraph Python agent, add `CopilotKitMiddleware`. Any other agent needs one thing: put the run's context entries into its system prompt.

## How it streams [#how-it-streams]

The UI paints while the reply is still streaming:

- Each component renders as soon as its line has fully arrived, so a surface fills in one component at a time.
- A child that has not arrived yet takes no space. There is no placeholder.
- Components fade in once, when they appear.
- If the stream stops halfway, the surface keeps what already painted.

## Where the UI renders [#where-the-ui-renders]

- **In the reply.** A code block renders where it is in the text.
- **In the same surface again.** A later block in the same reply with the same `surfaceId` updates that surface instead of adding a second one.
- **On the page.** A block with a target, ```` ```a2ui target=featured ````, renders in `<GenerativeUISurface id="featured">`, or `<copilot-generative-ui-surface id="featured">` in Angular. A later reply can update it. See [Surfaces](/generative-ui/components/surfaces).

If the agent leaves out `createSurface`, CopilotKit adds one.

## Text inside a block [#text-inside-a-block]

The agent sometimes puts a title or a paragraph inside a block. That text is lifted out and renders as chat markdown, so only real UI ends up in a surface. The surface splits around the text into parts. The parts share their values, so a slider in one part still updates a value in another.

## Build your own prompt [#build-your-own-prompt]

Some backends build the prompt themselves. Turn the context entries off, and read the same data from the run instead:

<Tabs groupId="frontend_framework" items={["React", "Angular", "Vue"]} persist>
  <Tab value="React">
    ```tsx
    <CopilotKitProvider
      runtimeUrl="/api/copilotkit"
      generativeUI={{ ui: standardUI, transport: "markdown", sendContext: false }}
    >
    ```
  </Tab>
  <Tab value="Angular">
    ```ts
    provideGenerativeUI({ ui: standardUI, transport: "markdown", sendContext: false }),
    ```
  </Tab>
  <Tab value="Vue">
    ```vue
    <CopilotKitProvider
      runtime-url="/api/copilotkit"
      :generativeUI="{ ui: standardUI, transport: 'markdown', sendContext: false }"
    >
    ```
  </Tab>
</Tabs>

Every run carries it at `forwardedProps.copilotkit.ui`, in the A2UI v1.0 renderer capabilities shape:

```json
{
  "1.0": {
    "supportedCatalogIds": ["copilotkit/standard@1"],
    "inlineCatalogs": [
      {
        "catalogId": "copilotkit/standard@1",
        "protocolVersion": "1.0",
        "components": { "Card": { "props": { "type": "object" } } },
        "functions": {},
        "instructions": "You can show interactive UI in your reply ..."
      }
    ]
  },
  "metadata": {
    "extensions": {
      "copilotkit_format": 3,
      "copilotkit_transport": "markdown",
      "copilotkit_targets": [{ "id": "chat", "kind": "chat" }],
      "copilotkit_surfaces": {},
      "copilotkit_contextSent": false
    }
  }
}
```

```python
ui = input.forwarded_props["copilotkit"]["ui"]
catalog = ui["1.0"]["inlineCatalogs"][0]
system = f"{MY_PROMPT}\n\n{catalog['instructions']}\n\nComponents:\n{json.dumps(catalog['components'])}"
```

What the parts hold:

- `components`: the JSON Schema of each component, with its events and slots.
- `instructions`: the guide text.
- `copilotkit_targets`: the targets on screen.
- `copilotkit_surfaces`: the surfaces of the thread, with the values the user typed and the operations the browser rejected. A surface that was deleted has `"status": "deleted"`, and its id cannot be used again. A surface whose `createSurface` the browser rejected has `"status": "failed"`.
- `copilotkit_contextSent`: `true` when the context entries were also sent, so a backend never adds the schema twice.

Two more options for these backends:

- `includeCatalog: false` leaves `components` out, for a backend that already has them.
- `agentIds: ["chat"]` sends the context and this data to those agents only.

## The v1 chat [#the-v1-chat]

The v1 chat components in `@copilotkit/react-ui` (`CopilotChat`, `CopilotSidebar`, `CopilotPopup`) render `a2ui` blocks too. Give the v1 `<CopilotKit>` provider the same `generativeUI` prop. Without it, a block renders as plain code.

## Limits [#limits]

- A block must start at the beginning of a line. A block that is indented inside a list item renders as code.
- Values are literals, bindings (`{"@path": "/seats"}`) or function values (`{"@call": "calc", "args": { "expression": "seats * 29", "seats": {"@path": "/seats"} }}`); see [function values](/generative-ui/components/state-and-actions#compute-values-in-the-browser). There are no operators outside `calc`, and no function that maps over a list.
- A `surfaceId` is never used twice, also after `deleteSurface`.

To run it, start [`examples/v2/a2ui-markdown`](https://github.com/CopilotKit/CopilotKit/tree/main/examples/v2/a2ui-markdown) with the built-in agent or the LangGraph Python agent, and open `/?transport=markdown`.
