a2ui-renderer

このスキルは、copilotkit/react-core（CopilotKit プロバイダーの基本）と copilotkit/runtime（CopilotRuntime の基本）を基盤としています。まずそちらをお読みください。

セットアップ

A2UI は 2 つの要素で構成されます。ランタイムで a2ui ミドルウェアを宣言し、クライアントでプロバイダーの a2ui プロパティを有効にします。両方を設定すると、/info が A2UI を通知し、クライアントが createA2UIMessageRenderer を自動的にマウントします。renderActivityMessages を自分で設定する必要はありません。

ランタイム側（app/routes/api.copilotkit.$.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);
}

クライアント側（app/root.tsx またはアプリシェル）

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

export default function App() {
  return (
    <CopilotKit
      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" />
    </CopilotKit>
  );
}

基本パターン

カスタムカタログ

カスタムカタログを渡すことで、組み込みコンポーネントセットを拡張できます。createCatalog と extractSchema を使うと、エージェントがレンダリング可能なコンポーネントを把握できます。

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 },
);

<CopilotKit runtimeUrl="/api/copilotkit" a2ui={{ theme, catalog }}>
  <CopilotChat agentId="default" />
</CopilotKit>;

extractSchema(definitions) は、定義の JSON シリアライズ可能なビューをランタイムの a2ui.schema 設定に渡すために利用できます。汎用的な型ヘルパーではありません。型パラメーターは実行時に消去されるため、エージェントには実際のランタイムスキーマ値（Zod）が必要です。

読み込み中のスケルトンをオーバーライドする

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

よくある間違い

重大：runtime.a2ui の設定忘れ

誤り：

// server
new CopilotRuntime({ agents: { default: agent } });
// client
<CopilotKit runtimeUrl="/api/copilotkit" a2ui={{ theme }} />;

正しい例：

// server
new CopilotRuntime({ agents: { default: agent }, a2ui: {} });
// client
<CopilotKit runtimeUrl="/api/copilotkit" a2ui={{ theme }} />;

runtime.a2ui がないと、/info は A2UI を通知せず、プロバイダーの a2ui プロパティは何もせずに無視されます。そのため、レンダラーはマウントされません。

出典：packages/runtime/src/v2/runtime/core/runtime.ts:55-58,217,242

重要：A2UI 用の renderActivityMessages を手動で設定する

誤り：

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

<CopilotKit
  runtimeUrl="/api/copilotkit"
  renderActivityMessages={[createA2UIMessageRenderer({ theme })]}
/>;

正しい例：

<CopilotKit runtimeUrl="/api/copilotkit" a2ui={{ theme }} />

CopilotKit プロバイダーは /info を通じてランタイムの A2UI を自動検出し、組み込みレンダラーを注入します。renderActivityMessages を通じて渡すと、レンダラーが重複し、自動注入されたレンダラーと競合する可能性があります。

出典：packages/react-core/src/v2/providers/CopilotKitProvider.tsx:188-222,294-296

注意：スナップショットごとに createSurface を再出力する

誤り：

# Pseudocode — inside your agent generator. Exact API names/kwargs vary by
# 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(...)

正しい例：

# Pseudocode — inside your agent generator.
# Emit createSurface once per surfaceId; use 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", ...)

MessageProcessor は surfaceId に基づいて重複を排除しますが、再出力はエージェント側のバグです。クライアントで不要な調整処理が再実行され、ちらつきが発生します。

出典：packages/react-core/src/v2/a2ui/A2UIMessageRenderer.tsx:218-226

注意：a2uiAction のクリーンアップを行わないカスタムアクションブリッジ

誤り：

copilotkit.setProperties({ ...copilotkit.properties, a2uiAction: msg });
await copilotkit.runAgent({ agent });
// no finally — a2uiAction leaks into the next run's properties

正しい例：

try {
  copilotkit.setProperties({ ...copilotkit.properties, a2uiAction: msg });
  await copilotkit.runAgent({ agent });
} finally {
  if (copilotkit.properties) {
    const { a2uiAction, ...rest } = copilotkit.properties;
    copilotkit.setProperties(rest);
  }
}

組み込みブリッジは常に finally で a2uiAction を削除します。また、copilotkit.properties が null でないことを確認してから処理するため、分割代入中の TypeError によって元の runAgent エラーが隠されることはありません。クリーンアップを省略すると、以前のアクションが後続の実行にも残ります。

出典：packages/react-core/src/v2/a2ui/A2UIMessageRenderer.tsx:146-167

注意：@copilotkitnext/a2ui-renderer をインストールする

誤り：

import { createA2UIMessageRenderer } from "@copilotkitnext/a2ui-renderer";

正しい例：

// Low-level primitives (rarely needed — the CopilotKit provider's 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";

このパッケージは @copilotkitnext/a2ui-renderer ではなく、@copilotkit/a2ui-renderer として提供されています。@copilotkitnext/ スコープは、別途そのスコープで提供される他のパッケージ用です。このパッケージにも適用されると思い込まないでください。

出典：packages/a2ui-renderer/package.json