Back to Details

a2ui-renderer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
This skill builds on copilotkit/react-core (for CopilotKitProvider fundamentals) and copilotkit/runtime (for CopilotRuntime fundamentals). Read those first.
本技能基于copilotkit/react-core（用于CopilotKitProvider基础功能）和copilotkit/runtime（用于CopilotRuntime基础功能）构建。请先阅读这些内容。

Setup

设置

A2UI has two halves. The runtime declares a2ui middleware; the client enables the a2ui prop on the provider. Once both are set, 
/info
flags A2UI and the client auto-mounts 
createA2UIMessageRenderer
— you do NOT wire 
renderActivityMessages
yourself.
A2UI分为两部分。运行时声明a2ui中间件；客户端在提供者上启用a2ui属性。两者设置完成后，
/info
会标记A2UI，客户端会自动挂载
createA2UIMessageRenderer
——您无需自行配置
renderActivityMessages
。

Runtime side (
app/routes/api.copilotkit.$.tsx
)

运行时端（
app/routes/api.copilotkit.$.tsx
）

tsx
import type { Route } from "./+types/api.copilotkit.$";
import {
  CopilotRuntime,
  createCopilotRuntimeHandler,
  BuiltInAgent,
  convertInputToTanStackAI,
} from "@copilotkit/runtime/v2";
import { chat } from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai";

const agent = new BuiltInAgent({
  type: "tanstack",
  factory: ({ input, abortController }) => {
    const { messages, systemPrompts } = convertInputToTanStackAI(input);
    return chat({
      adapter: openaiText("gpt-4o"),
      messages,
      systemPrompts,
      abortController,
    });
  },
});

const runtime = new CopilotRuntime({
  agents: { default: agent },
  // Enabling this key causes /info to advertise A2UI to the client.
  a2ui: {},
});

const handler = createCopilotRuntimeHandler({
  runtime,
  basePath: "/api/copilotkit",
});

export async function loader({ request }: Route.LoaderArgs) {
  return handler(request);
}
export async function action({ request }: Route.ActionArgs) {
  return handler(request);
}
tsx
import type { Route } from "./+types/api.copilotkit.$";
import {
  CopilotRuntime,
  createCopilotRuntimeHandler,
  BuiltInAgent,
  convertInputToTanStackAI,
} from "@copilotkit/runtime/v2";
import { chat } from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai";

const agent = new BuiltInAgent({
  type: "tanstack",
  factory: ({ input, abortController }) => {
    const { messages, systemPrompts } = convertInputToTanStackAI(input);
    return chat({
      adapter: openaiText("gpt-4o"),
      messages,
      systemPrompts,
      abortController,
    });
  },
});

const runtime = new CopilotRuntime({
  agents: { default: agent },
  // 启用此键会让/info向客户端宣告A2UI支持
  a2ui: {},
});

const handler = createCopilotRuntimeHandler({
  runtime,
  basePath: "/api/copilotkit",
});

export async function loader({ request }: Route.LoaderArgs) {
  return handler(request);
}
export async function action({ request }: Route.ActionArgs) {
  return handler(request);
}

Client side (
app/root.tsx
or the app shell)

客户端（
app/root.tsx
或应用壳层）

tsx
import { CopilotKitProvider, CopilotChat } from "@copilotkit/react-core/v2";
import "@copilotkit/react-core/v2/styles.css";

export default function App() {
  return (
    <CopilotKitProvider
      runtimeUrl="/api/copilotkit"
      a2ui={{
        theme: {
          // Theme object forwarded to A2UIProvider → ThemeProvider.
          // Tokens map to A2UI's basic catalog CSS vars.
          colors: { primary: "#0ea5e9" },
        },
      }}
    >
      <CopilotChat agentId="default" className="h-full" />
    </CopilotKitProvider>
  );
}
tsx
import { CopilotKitProvider, CopilotChat } from "@copilotkit/react-core/v2";
import "@copilotkit/react-core/v2/styles.css";

export default function App() {
  return (
    <CopilotKitProvider
      runtimeUrl="/api/copilotkit"
      a2ui={{
        theme: {
          // 主题对象会传递给A2UIProvider → ThemeProvider
          // 令牌映射到A2UI基础组件库的CSS变量
          colors: { primary: "#0ea5e9" },
        },
      }}
    >
      <CopilotChat agentId="default" className="h-full" />
    </CopilotKitProvider>
  );
}

Core Patterns

核心模式

Custom catalog

自定义组件库

Pass a custom catalog to extend the built-in component set. 
createCatalog
and 
extractSchema
let the agent see what components it may render.
tsx
import { createCatalog } from "@copilotkit/a2ui-renderer";
import { z } from "zod";

const theme = { colors: { primary: "#0ea5e9" } };

// Definitions are platform-agnostic (Zod schemas + descriptions).
// Renderers are platform-specific (React components).
// TypeScript enforces that renderer keys match definition keys exactly.
const definitions = {
  ProductCard: {
    description: "A product card with title and price",
    props: z.object({ title: z.string(), price: z.number() }),
  },
};

const catalog = createCatalog(
  definitions,
  {
    ProductCard: ({ props }) => (
      <div className="rounded-xl border p-3">
        <div className="font-medium">{props.title}</div>
        <div className="text-sm text-muted-foreground">${props.price}</div>
      </div>
    ),
  },
  { includeBasicCatalog: true },
);

<CopilotKitProvider runtimeUrl="/api/copilotkit" a2ui={{ theme, catalog }}>
  <CopilotChat agentId="default" />
</CopilotKitProvider>;
extractSchema(definitions)
is available for passing a JSON-serializable view of the definitions to the runtime's 
a2ui.schema
config — it is not a generic type helper. Type parameters erase at runtime; the agent needs a real runtime schema value (Zod).
传入自定义组件库以扩展内置组件集。
createCatalog
和
extractSchema
可让Agent了解它能渲染的组件。
tsx
import { createCatalog } from "@copilotkit/a2ui-renderer";
import { z } from "zod";

const theme = { colors: { primary: "#0ea5e9" } };

// 定义是平台无关的（Zod模式 + 描述）
// 渲染器是平台特定的（React组件）
// TypeScript会强制渲染器键与定义键完全匹配
const definitions = {
  ProductCard: {
    description: "包含标题和价格的产品卡片",
    props: z.object({ title: z.string(), price: z.number() }),
  },
};

const catalog = createCatalog(
  definitions,
  {
    ProductCard: ({ props }) => (
      <div className="rounded-xl border p-3">
        <div className="font-medium">{props.title}</div>
        <div className="text-sm text-muted-foreground">${props.price}</div>
      </div>
    ),
  },
  { includeBasicCatalog: true },
);

<CopilotKitProvider runtimeUrl="/api/copilotkit" a2ui={{ theme, catalog }}>
  <CopilotChat agentId="default" />
</CopilotKitProvider>;
extractSchema(definitions)
可用于将定义的JSON可序列化视图传递给运行时的
a2ui.schema
配置——它不是通用类型助手。类型参数在运行时会被擦除；Agent需要真实的运行时模式值（Zod）。

Override the loading skeleton

覆盖加载骨架

tsx
<CopilotKitProvider
  runtimeUrl="/api/copilotkit"
  a2ui={{
    theme,
    loadingComponent: () => <div className="animate-pulse">Building UI…</div>,
  }}
>
  <CopilotChat agentId="default" />
</CopilotKitProvider>
tsx
<CopilotKitProvider
  runtimeUrl="/api/copilotkit"
  a2ui={{
    theme,
    loadingComponent: () => <div className="animate-pulse">Building UI…</div>,
  }}
>
  <CopilotChat agentId="default" />
</CopilotKitProvider>

Common Mistakes

常见错误

CRITICAL forgetting runtime.a2ui

严重：忘记设置runtime.a2ui

Wrong:
tsx
// server
new CopilotRuntime({ agents: { default: agent } });
// client
<CopilotKitProvider runtimeUrl="/api/copilotkit" a2ui={{ theme }} />;
Correct:
tsx
// server
new CopilotRuntime({ agents: { default: agent }, a2ui: {} });
// client
<CopilotKitProvider runtimeUrl="/api/copilotkit" a2ui={{ theme }} />;
Without 
runtime.a2ui
, 
/info
never flags A2UI and the provider's a2ui prop silently no-ops — the renderer never mounts.
Source: packages/runtime/src/v2/runtime/core/runtime.ts:55-58,217,242
错误示例：
tsx
// 服务端
new CopilotRuntime({ agents: { default: agent } });
// 客户端
<CopilotKitProvider runtimeUrl="/api/copilotkit" a2ui={{ theme }} />;
正确示例：
tsx
// 服务端
new CopilotRuntime({ agents: { default: agent }, a2ui: {} });
// 客户端
<CopilotKitProvider runtimeUrl="/api/copilotkit" a2ui={{ theme }} />;
如果没有
runtime.a2ui
，
/info
永远不会标记A2UI，提供者的a2ui属性会静默失效——渲染器永远不会挂载。
来源：packages/runtime/src/v2/runtime/core/runtime.ts:55-58,217,242

HIGH manually wiring renderActivityMessages for A2UI

高风险：手动为A2UI配置renderActivityMessages

Wrong:
tsx
import { createA2UIMessageRenderer } from "@copilotkit/react-core/v2";

<CopilotKitProvider
  runtimeUrl="/api/copilotkit"
  renderActivityMessages={[createA2UIMessageRenderer({ theme })]}
/>;
Correct:
tsx
<CopilotKitProvider runtimeUrl="/api/copilotkit" a2ui={{ theme }} />
CopilotKitProvider auto-detects runtime A2UI via 
/info
and injects the built-in renderer. Passing it through 
renderActivityMessages
duplicates the renderer and can race with the auto-injected one.
Source: packages/react-core/src/v2/providers/CopilotKitProvider.tsx:188-222,294-296
错误示例：
tsx
import { createA2UIMessageRenderer } from "@copilotkit/react-core/v2";

<CopilotKitProvider
  runtimeUrl="/api/copilotkit"
  renderActivityMessages={[createA2UIMessageRenderer({ theme })]}
/>;
正确示例：
tsx
<CopilotKitProvider runtimeUrl="/api/copilotkit" a2ui={{ theme }} />
CopilotKitProvider会通过
/info
自动检测运行时的A2UI支持并注入内置渲染器。通过
renderActivityMessages
传入会导致渲染器重复，可能与自动注入的渲染器产生冲突。
来源：packages/react-core/src/v2/providers/CopilotKitProvider.tsx:188-222,294-296

MEDIUM re-emitting createSurface on every snapshot

中风险：每次快照都重新发送createSurface

Wrong:
python
undefined
错误示例：
python
undefined

Pseudocode — inside your agent generator. Exact API names/kwargs vary by

伪代码——在你的Agent生成器内部。具体API名称/参数会因A2UI SDK版本而异；请查阅SDK文档获取真实调用格式。

A2UI SDK version; consult your SDK's docs for real call shapes.

—
async def agent_generator(): # agent re-emits createSurface operation on every state delta async for update in stream: yield a2ui.create_surface(surface_id="main", ...) # every tick yield a2ui.update_components(...)

Correct:

```python
async def agent_generator(): # Agent在每个状态增量时都重新发送createSurface操作 async for update in stream: yield a2ui.create_surface(surface_id="main", ...) # 每次触发都发送 yield a2ui.update_components(...)

正确示例：

```python

Pseudocode — inside your agent generator.

伪代码——在你的Agent生成器内部。

Emit createSurface once per surfaceId; use updateComponents / updateDataModel

每个surfaceId只发送一次createSurface；使用updateComponents / updateDataModel处理变更。

for changes.

—
async def agent_generator(): yield a2ui.create_surface(surface_id="main", ...) # once async for update in stream: yield a2ui.update_components(surface_id="main", ...)

The MessageProcessor dedups on `surfaceId` but re-emitting is an agent-side
bug — the client re-runs reconciliation logic for nothing and flickers.

Source: packages/react-core/src/v2/a2ui/A2UIMessageRenderer.tsx:218-226
async def agent_generator(): yield a2ui.create_surface(surface_id="main", ...) # 只发送一次 async for update in stream: yield a2ui.update_components(surface_id="main", ...)

MessageProcessor会根据`surfaceId`去重，但重复发送是Agent端的bug——客户端会无意义地重新运行协调逻辑并导致界面闪烁。

来源：packages/react-core/src/v2/a2ui/A2UIMessageRenderer.tsx:218-226

MEDIUM custom action bridge without a2uiAction cleanup

中风险：自定义action bridge但未清理a2uiAction

Wrong:
ts
copilotkit.setProperties({ ...copilotkit.properties, a2uiAction: msg });
await copilotkit.runAgent({ agent });
// no finally — a2uiAction leaks into the next run's properties
Correct:
ts
try {
  copilotkit.setProperties({ ...copilotkit.properties, a2uiAction: msg });
  await copilotkit.runAgent({ agent });
} finally {
  if (copilotkit.properties) {
    const { a2uiAction, ...rest } = copilotkit.properties;
    copilotkit.setProperties(rest);
  }
}
The built-in bridge always strips 
a2uiAction
in 
finally
, guarded by a 
copilotkit.properties
null-check so it can't mask the original 
runAgent
error with a 
TypeError
during destructuring. Skipping cleanup keeps the previous action attached to subsequent runs.
Source: packages/react-core/src/v2/a2ui/A2UIMessageRenderer.tsx:146-167
错误示例：
ts
copilotkit.setProperties({ ...copilotkit.properties, a2uiAction: msg });
await copilotkit.runAgent({ agent });
// 没有finally——a2uiAction会泄漏到下一次运行的属性中
正确示例：
ts
try {
  copilotkit.setProperties({ ...copilotkit.properties, a2uiAction: msg });
  await copilotkit.runAgent({ agent });
} finally {
  if (copilotkit.properties) {
    const { a2uiAction, ...rest } = copilotkit.properties;
    copilotkit.setProperties(rest);
  }
}
内置bridge总会在
finally
中移除
a2uiAction
，并通过
copilotkit.properties
空值检查进行保护，避免在解构时因
TypeError
掩盖原始
runAgent
错误。跳过清理会让之前的操作附加到后续运行中。
来源：packages/react-core/src/v2/a2ui/A2UIMessageRenderer.tsx:146-167

MEDIUM installing @copilotkitnext/a2ui-renderer

中风险：安装@copilotkitnext/a2ui-renderer

Wrong:
ts
import { createA2UIMessageRenderer } from "@copilotkitnext/a2ui-renderer";
Correct:
ts
// Low-level primitives (rarely needed — CopilotKitProvider a2ui prop is the default path):
import {
  A2UIProvider,
  A2UIRenderer,
  createCatalog,
} from "@copilotkit/a2ui-renderer";
// Auto-mounted renderer lives in react-core/v2:
import { createA2UIMessageRenderer } from "@copilotkit/react-core/v2";
This package ships as 
@copilotkit/a2ui-renderer
, not 
@copilotkitnext/a2ui-renderer
. The 
@copilotkitnext/
scope is reserved for other packages that ship under it separately — do not assume it applies here.
Source: packages/a2ui-renderer/package.json
错误示例：
ts
import { createA2UIMessageRenderer } from "@copilotkitnext/a2ui-renderer";
正确示例：
ts
// 底层原语（很少需要——CopilotKitProvider的a2ui属性是默认路径）：
import {
  A2UIProvider,
  A2UIRenderer,
  createCatalog,
} from "@copilotkit/a2ui-renderer";
// 自动挂载的渲染器位于react-core/v2：
import { createA2UIMessageRenderer } from "@copilotkit/react-core/v2";
该包的正确名称是
@copilotkit/a2ui-renderer
，而非
@copilotkitnext/a2ui-renderer
。
@copilotkitnext/
作用域是为其他单独发布的包保留的——请勿假设它适用于此。
来源：packages/a2ui-renderer/package.json