はじめに:エージェントとの対話が「テキストの壁」を抜け出す

これまでのAIエージェントとの会話は、おおむね次のようなものでした。

User: 「3月のバリ島パッケージを探して」 Agent: (宿泊先・航空便・日付が並んだテキスト6件) User: 「朝食付きの5泊のやつ」 Agent: 「リンクはこちらです。予約は運営会社のサイトでどうぞ」

旅行計画は立ててくれますが、返ってくるのはテキストの塊ばかり。選択可能なリスト、地図、日付ピッカーを会話の中で描画する標準的な方法が存在しませんでした。

そこで登場するのが Generative UI です。エージェントがリクエストに応じて実行時にインターフェースを組み立て、ユーザーにインタラクティブな体験を提供するレイヤーです。実装には2つの軸が必要になります。

  1. UIを記述する方法(宣言的スキーマ)
  2. エージェントとアプリを接続しUIを描画するエージェンティックスタック

本記事では、その標準となりつつある A2UI と CopilotKit を実際のコードで解説します。根拠資料は Google Developers Blog の原文 を参照してください。

AI agent generating a rich UI with flight cards inside a chat interface Development Concept Image

A2UIのスペクトラム:制御型 vs 開放型

Generative UIには「どこまで自由にUIを作らせるか」というスペクトラムが存在します。

  • 制御型(Controlled): コンポーネントを事前にすべて用意し、エージェントは「どれを描くか」とデータだけを選びます。ブランド安全性は高い一方、ユーザー意図に沿った深いカスタマイズは困難です。
  • 開放型(Open-ended): エージェントがHTML/JS/Dartの生コードを出力し、サンドボックス化されたiframeで描画します。想定外のリクエストもカバーできますが、デザインシステムから逸脱し、モデルが書いたコードを実行するリスクを伴います。

A2UIはこのスペクトラム全体に関与します。 Typesafe社のJevのような決定モデルとも、開放型のコード生成とも組み合わせ可能です。最も人気があるのは 宣言的モード — エージェントが事前宣言されたコンポーネントと関数を組み立てる方式です。

A2UIの核心的価値は フレームワーク非依存(framework-agnostic) であること。ローカルでもリモートでも、エージェントが共通言語で既存のコンポーネントカタログを組み立てられます。フロントエンド開発者はビルディングブロックを一度デプロイすれば、エージェントがリクエストごとに合成してくれます。

Basic Catalog:18個のプリミティブ

基本カタログはレイアウト・表示・入力・コンテナにわたる18個の汎用プリミティブを提供します。この18個で全く異なるインターフェースを組み立て可能です。ただし意図的に最小限に抑えられているため、実務アプリの多くは独自のカスタムカタログを定義します。カスタムコンポーネントはフロントエンドが既に描画しているものであれば何でも構いません — エージェントが座標を埋め、レンダラーが経路を描くライブ地図のようなものも含まれます。

CopilotKit + AG-UI の連携フロー

CopilotKitは AG-UI(Agent-User Interaction Protocol) の上に構築されています。A2UIペイロードをサポートし、多数のエージェンティックバックエンド向けAgent SDKを提供します。

流れは次のとおりです。

  1. エージェントがA2UIオペレーションをemit
  2. AG-UIが型付きイベントとしてクライアントへ伝達
  3. ユーザーがアクションを起こすと、同じストリームで値が返送される

Google ADK、LangChain、Mastra、StrandsはいずれもAG-UI互換のため、どのバックエンドでもセットアップは同一です。

1) エージェントをAG-UIエンドポイントとして公開(Google ADKの例)

from fastapi import FastAPI
from google.adk.agents import LlmAgent
from ag_ui_adk import ADKAgent, add_adk_fastapi_endpoint

root_agent = LlmAgent(
    name="flight_agent",
    model="gemini-3.8-flash",
    # エージェントへの指示:結果表示時に generate_a2ui を呼び出す
    instruction="Help users find and book flights. Call generate_a2ui to show results.",
)

adk_agent = ADKAgent(
    adk_agent=root_agent,
    app_name="flights",
    user_id="demo_user",
    use_in_memory_services=True,
)

app = FastAPI()
# FastAPIアプリにAG-UIエンドポイントを登録
add_adk_fastapi_endpoint(app, adk_agent, path="/")

アプリ側ではこのエンドポイントを /api/copilotkit のCopilotKitランタイムに登録するだけ。A2UI固有の設定は不要です。

2) クライアント側でカタログを定義(React + Zod)

A2UIはクライアント側で有効化します。コンポーネントが既に存在する場所だからです。エージェントが描けるものを定義し、各定義をレンダラーにマッピングして、カタログをCopilotKit providerに渡します。

import { CopilotKit, CopilotChat } from '@copilotkit/react-core/v2';
import {
  createCatalog,
  type CatalogDefinitions,
  type CatalogRenderers,
} from '@copilotkit/a2ui-renderer';
import { z } from 'zod';

// エージェントが利用可能なコンポーネントスキーマを定義
const catalogDefinitions = {
  FlightCard: {
    description: 'A flight result with airline, times, and stops.',
    props: z.object({
      airline: z.string(),
      departs: z.string(),
      arrives: z.string(),
      stops: z.number(),
    }),
  },
} satisfies CatalogDefinitions;

const catalogRenderers = {
  FlightCard: MyFlightCard, // 実際のReactコンポーネント
} satisfies CatalogRenderers;

// カタログ生成(Basic Catalogを含める)
const catalog = createCatalog(catalogDefinitions, catalogRenderers, {
  catalogId: 'flight-catalog',
  includeBasicCatalog: true,
});

ポイントは description が エージェントのプロンプトに渡る こと。モデルが汎用カードではなく FlightCard をいつ使うべきか判断する根拠になります。Zodスキーマは返送されるpropsを検証します。

A2UI設定はサーバー側で事前に構成することも、クライアントからリクエストとともに動的に送ることも可能です。上記のADK例は動的設定のため、generate_a2ui を定義なしで使用しています。

CopilotKit経由ではなく、@ag-ui/client でイベントストリームを直接消費し、A2UIオペレーションを @a2ui/react、Flutter、Lit、Angularの各レンダラーへ渡すこともできます。

Frontend developer defining A2UI catalog components with Zod and React renderers Developer Related Image

注意点:ワンショットUIの落とし穴と双方向フロー

エージェント生成UIのほとんどは ワンショット(one-shot) です。エージェントが何かを描き、ユーザーが読み、何かが変わった瞬間に陳腐化します。

A2UIサーフェスは 双方向(bi-directional) でコンポーネントがリアクティブなため、マルチステップフローが可能です。ユーザーがインターフェース上で行うすべてのアクション(日付選択、便の選択、搭乗者情報の入力)が同じストリームで返送され、エージェントがその値でサーフェスを再emitします。

ラウンドトリップを成立させる2つの仕組み:

  1. データパスにバインドされた入力
  2. どのパスを返送するかを指定したアクション付きボタン
{ "id": "cabin", "component": "ChoicePicker", "variant": "mutuallyExclusive",
  "options": [ { "label": "Economy", "value": "eco" },
               { "label": "Business", "value": "biz" } ],
  "value": { "path": "/booking/cabin" } },
{ "id": "confirm", "component": "Button", "child": "confirm_label",
  "action": { "event": { "name": "confirmBooking",
    "context": { "cabin": { "path": "/booking/cabin" },
                 "email": { "path": "/booking/email" } } } } }

検証はクライアント側で実行されます。不正なメールアドレスはモデル呼び出しなしでインラインエラーとして表示され、ボタンが発火するまでエージェントには何も届きません。クライアントがバインドされた値を送ると、エージェントが同じ surfaceId に対して再emitします。こうして1つのサーフェス上で、航空便検索 → 結果 → 搭乗者情報 → 確定までがつながります。

実務上の注意点

  • カタログを広げすぎないこと。 Basic Catalogの18個をすべて開放すると、モデルが的外れなプリミティブを選びやすくなります。ドメインに必要なコンポーネントのみを公開する方が精度が上がります。
  • description の品質がそのまま性能になります。 モデルはdescriptionを見てコンポーネントを選ぶため、曖昧な説明は誤描画につながります。
  • 開放型モード(HTML/JS生成)はサンドボックス必須。 モデルが書いたコードを実行する構造のため、CSPとiframe隔離を必ず確認してください。
  • 日本の受託開発現場では、 社内デザインシステムのコンポーネントをカタログでラップする作業が先行します。既存コンポーネントの再利用がA2UI最大の利点なので、最初から作り直さないこと。

Multi-step booking flow UI streaming between agent and client via AG-UI protocol Programming Illustration

まとめ:一度デプロイして、あとは組み立てさせる

A2UI + CopilotKitの要点は 「フロントエンド開発者がビルディングブロックを一度デプロイすれば、エージェントがリクエストごとに組み立てる」 ことです。スターターアプリは1コマンドで生成できます。

npx copilotkit@latest create --name my-app --framework a2ui

CopilotKit Dojoには実行可能なA2UIデモが揃っています — 固定サーバーサイドスキーマ、カスタムカタログに対する動的スキーマ、そして初回レンダリングが失敗しても有効なレンダリングへ自己修復するエラーリカバリの例まで。

次の学習ステップ

  1. A2UI仕様ドキュメント を読み、宣言的メッセージフォーマットを習得する
  2. AG-UIプロトコル のイベント型を理解する(ストリーム設計の基盤)
  3. カスタムカタログ設計 — ドメインコンポーネントをZodスキーマでラップする練習
  4. エラーリカバリパターン — 誤ったレンダリングをモデル自身が修正するループ設計

あわせて読みたい記事

本コンテンツは、信頼性の高い情報源をもとにAIツールを活用して作成され、編集者によるレビューを経て公開されています。専門家によるアドバイスの代替となるものではありません。