Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/a2ui-project/a2ui/llms.txt

Use this file to discover all available pages before exploring further.

A2UI is a declarative UI format that describes what to render. AG-UI is the transport layer that carries those descriptions between an agent and your application. CopilotKit’s AG-UI implementation is the fastest path to putting A2UI in front of users today: any agent framework CopilotKit supports can emit A2UI and have it rendered in a supported app surface with no custom transport code.
Source of truth: This guide mirrors the key steps from CopilotKit’s A2UI docs. For Google ADK-specific setup, see the Google ADK + A2UI guide. Always refer to the CopilotKit docs for the latest API surface.

​
Supported Agent Frameworks

CopilotKit’s AG-UI implementation supports every major agent framework out of the box:

Google ADK

Native ADK agents with A2UI surface rendering

LangGraph

LangGraph agents and stateful graph workflows

CrewAI

Multi-agent CrewAI pipelines

Mastra

Mastra agent and workflow runtime

Custom Python Services

Any Python service that can emit A2UI operations

Custom TypeScript Services

Any TypeScript/Node.js service that emits A2UI operations

​
Setup in Three Steps

1

Set up CopilotKit

Install CopilotKit into your application with the agent framework of your choice. The CopilotKit init command scaffolds everything you need:
npx copilotkit@latest init
Alternatively, follow the CopilotKit quickstart to wire it into an existing project. This is standard CopilotKit setup — there is nothing A2UI-specific about this step.
The npx copilotkit@latest init command supports ADK, LangGraph, CrewAI, Mastra, and plain Python/TypeScript backends. Choose the option that matches your agent framework during the interactive setup.
2

Enable A2UI

​
Backend

Turn on A2UI in CopilotRuntime. For dynamic-schema flows, inject the render_a2ui tool so your agent can produce A2UI surfaces:
app/api/copilotkit/route.ts
import { CopilotRuntime } from '@copilotkit/runtime';

const runtime = new CopilotRuntime({
  agents: { default: myAgent },
  a2ui: { injectA2UITool: true },
});
To scope A2UI to specific agents rather than all agents, pass the agents array:
a2ui: { injectA2UITool: true, agents: ['my-agent'] }
For fixed-schema flows where your agent already returns a2ui_operations directly (rather than using the injected tool), a minimal config is enough:
a2ui: true
// or
a2ui: {}

​
Frontend

The A2UI renderer activates automatically once you add a2ui configuration to CopilotKitProvider. This guide uses React/Next.js snippets; CopilotKit also supports A2UI through Vue, Angular, and React Native/headless clients.To add an optional theme:
app/layout.tsx
import { CopilotKitProvider } from '@copilotkit/react-core/v2';
import '@copilotkit/react-core/v2/styles.css';
import { myCustomTheme } from '@copilotkit/a2ui-renderer';

<CopilotKitProvider runtimeUrl="/api/copilotkit" a2ui={{ theme: myCustomTheme }}>
  {children}
</CopilotKitProvider>
If you do not need a custom theme, omit the theme prop — A2UI will render using the Basic Catalog’s default styles.
3

Add custom components (optional)

A2UI ships with a built-in Basic Catalog (Text, Image, Card, and more) that gives you a working surface immediately. The real power is extending it with your own React components from your design system, so the agent can compose interfaces from primitives you already trust.A catalog has three pieces:
  1. Definitions — Zod schemas with natural-language descriptions. This is what the agent reads in its system prompt. Note that for client-side functions, the client determines the function’s execution boundary (such as clientOnly status) at runtime by reading its configuration from the active catalog definition.
  2. Renderers — Typed React components, one per definition. This is what the user sees.
  3. Registration — Pass the catalog through the provider so the A2UI renderer knows how to draw your components.

​
1. Define component schemas

Create platform-agnostic definitions using Zod. The description field is injected into the agent’s system prompt so the LLM knows when to reach for each component:
lib/a2ui/definitions.ts
import { z } from 'zod';

export const myDefinitions = {
  StatusBadge: {
    description: 'A colored status badge.',
    props: z.object({
      text: z.string(),
      variant: z.enum(['success', 'warning', 'error']).optional(),
    }),
  },
  Metric: {
    description: 'A key metric with label and value.',
    props: z.object({
      label: z.string(),
      value: z.string(),
      trend: z.enum(['up', 'down']).optional(),
    }),
  },
};

export type MyDefinitions = typeof myDefinitions;

​
2. Create React renderers

Map each definition to a React component. createCatalog is generic over the definitions type, so the props your renderer receives are type-checked against the Zod schema — a typo in props.text is a compile error:
lib/a2ui/renderers.tsx
'use client';

import { createCatalog, type CatalogRenderers } from '@copilotkit/a2ui-renderer';
import { myDefinitions, type MyDefinitions } from './definitions';

const myRenderers: CatalogRenderers<MyDefinitions> = {
  StatusBadge: ({ props }) => {
    const colors = {
      success: { bg: '#dcfce7', text: '#166534' },
      warning: { bg: '#fef3c7', text: '#92400e' },
      error:   { bg: '#fee2e2', text: '#991b1b' },
    };
    const c = colors[props.variant ?? 'success'];
    return (
      <span
        style={{
          padding: '2px 8px',
          borderRadius: 9999,
          fontSize: '0.75rem',
          background: c.bg,
          color: c.text,
        }}
      >
        {props.text}
      </span>
    );
  },

  Metric: ({ props }) => (
    <div>
      <div style={{ fontSize: '0.75rem', color: '#6b7280' }}>{props.label}</div>
      <div style={{ fontSize: '1.5rem', fontWeight: 700 }}>
        {props.value}{' '}
        {props.trend === 'up' ? '↑' : props.trend === 'down' ? '↓' : ''}
      </div>
    </div>
  ),
};

export const myCatalog = createCatalog(myDefinitions, myRenderers, {
  catalogId: 'my-app-catalog',
  includeBasicCatalog: true, // merges with built-in components
});
catalogId is the stable handle the agent uses to target this catalog. Set includeBasicCatalog: true to keep the built-in components available alongside yours, or omit it to render only your components.

​
3. Pass the catalog to CopilotKit

app/layout.tsx
'use client';

import { CopilotKitProvider } from '@copilotkit/react-core/v2';
import '@copilotkit/react-core/v2/styles.css';
import { myCatalog } from '@/lib/a2ui/renderers';

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <CopilotKitProvider runtimeUrl="/api/copilotkit" a2ui={{ catalog: myCatalog }}>
      {children}
    </CopilotKitProvider>
  );
}
Agents will now see your custom components alongside the built-ins and can use them in any A2UI surface they emit.

​
Advanced Usage

For the full A2UI integration surface — multiple catalogs, fine-grained agent scoping, theming hooks, and advanced patterns — refer to CopilotKit’s official documentation:

​
Next Steps

A2UI Composer

Build widgets visually in the A2UI Composer playground.

Transports Reference

Understand how A2UI messages map onto AG-UI transport events.

Defining Your Own Catalog

Go deeper on catalog structure and security considerations.

v0.9.1 Specification

Read the full underlying A2UI protocol specification.

Build docs developers (and LLMs) love

Get started for freeTalk to us