A2UIとCopilotKitで生成UIを実装｜AG-UI接続と双方向フォームの設計

Googleは2026年10月29日、A2UIとCopilotKitを組み合わせ、AIエージェントが生成する宣言的な画面をWebアプリへ組み込む実装方法を公開しました。対象は、Google ADK、LangGraph、Mastra、Strandsなどでエージェントを作り、ReactやAngularを含むフロントエンドへフォーム、カード、一覧、グラフを動的に表示したい開発者です。今回の要点は、A2UIの画面記述をAG-UIのイベントストリームで運び、CopilotKit側で許可済みコンポーネントへ変換する接続が具体化されたことです。

導入時は、まず固定画面で足りる処理と生成UIが必要な処理を分け、フロントエンドが受け入れるコンポーネントカタログを小さく定義します。そのうえで、入力値の結合、操作イベント、検証失敗、再生成、セッション復元を一つずつ確認します。本稿は公式発表とドキュメントに基づく実装整理であり、性能の実測結果ではありません。

A2UIの画面記述とAG-UIの通信を分けて考える

A2UIは、エージェントが任意のHTMLやJavaScriptを返す方式ではありません。入力欄、ボタン、カードなど、クライアント側が用意した部品を使い、画面構造、データ、操作を宣言的なメッセージで表します。転送方式には依存しないため、A2UIだけではエージェントとブラウザーを結ぶAPIやセッション管理まで決まりません。

今回の構成では、その通信をAG-UIが担います。エージェントが出したA2UIの操作を型付きイベントとしてCopilotKit Runtimeへ送り、フロントエンドのA2UIレンダラーが登録済み部品へ変換します。利用者がフォームを変更したりボタンを押したりした結果も同じストリームでエージェントへ戻ります。つまり、A2UIは「何を描くか」、AG-UIは「状態と操作をどう往復させるか」、CopilotKitは「Webアプリでどう接続し描画するか」を受け持ちます。

層	主な役割	実装時に固定するもの
エージェント	要求を解釈し、A2UI操作を生成する	モデル、ツール、生成指示、失敗時の戻り先
AG-UI	イベント、状態、操作を双方向に運ぶ	エンドポイント、セッション、イベント順序
CopilotKit Runtime	フロントエンドとエージェントを中継する	runtimeUrl、利用するアダプター
A2UIカタログ	生成可能な部品と属性を制限する	スキーマ、説明、描画関数、版

既存記事「A2UI Expressで生成UIを高速化」は、モデルが出力する推論形式とトークン量の比較が主題です。本稿は、生成後のメッセージをWebアプリへ接続し、利用者の入力をエージェントへ返す境界を扱います。Expressへ移行しなくても、この接続構成は検討できます。

カタログを小さく始め、部品の説明まで契約に含める

公式記事によると、A2UIのBasic Catalogには18個の汎用プリミティブがあります。試作ではBasic Catalogから始められますが、本番では自社のデザインシステムや業務部品に合わせたカスタムカタログを定義できます。重要なのは、部品名だけでなく、各プロパティの型、必須条件、説明、フロントエンドの描画関数を同じ契約として管理することです。

CopilotKitの例では、catalogDefinitionsへZodスキーマとrendererを登録し、createCatalogでカタログを作ります。スキーマは受信したプロパティを検証し、説明文はモデルが部品を選ぶ際の判断材料になります。似た用途の部品を大量に登録すると選択が曖昧になるため、最初は「検索条件」「結果一覧」「確認」「完了」など、画面の目的ごとに必要な部品だけを公開する方が評価しやすくなります。

const catalog = createCatalog({
  components: {
    ResultCard: {
      schema: z.object({
        title: z.string(),
        summary: z.string(),
        score: z.number().min(0).max(100),
      }),
      renderer: ResultCard,
    },
  },
});

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

上記は公式構成を簡略化した設計例で、動作を実測したコードではありません。実際には利用中のCopilotKit版に合うAPIを公式ドキュメントで確認してください。A2UIの公式ガイドは、CopilotKit 1.61.2以降ではカタログを渡すことでA2UIが有効になり、エージェントへ生成ツールが提示されると説明しています。

エージェント基盤ごとにAG-UIへの接続点を確認する

Google ADKの公式例では、A2UI対応エージェントをag_ui_adkで包み、FastAPIから公開します。LangGraphはCopilotKitのミドルウェアを組み込み、StrandsはAG-UIアダプターで包む構成です。Mastraも対応候補に含まれます。どの基盤でも、モデルやツールの実装をブラウザーから直接呼び出すのではなく、AG-UI準拠の境界へ変換してからCopilotKit Runtimeへ接続します。

基盤	接続方法の要点	導入前の確認
Google ADK	ag_ui_adkでラップしFastAPIから提供	Python依存関係、ストリーム、セッションID
LangGraph	CopilotKitミドルウェアを組み込む	グラフ状態とUI状態の対応、再開位置
Strands	AG-UIアダプターで公開する	ツール結果からA2UI操作への変換
独自基盤	AG-UIクライアントと互換レンダラーを直接接続	イベント型、順序、終了条件、エラー表現

カタログはサーバー側で固定プリセットを選ぶ方法と、クライアントから動的に送る方法があります。複数ブランドや複数画面を同じエージェントで扱う場合、クライアントが現在使える部品を通知する方式は柔軟です。一方で、画面ごとにカタログが変わると再現条件が増えます。障害調査のため、カタログ名、版、ハッシュ、フロントエンドのビルド番号を会話ログとは別に記録できる設計が必要です。

双方向フォームは入力・操作・検証を分離する

A2UIの双方向画面では、入力部品をデータパスへ結合し、ボタンのactionにエージェントへ返すコンテキストを指定できます。たとえばメールアドレスを入力した時点ではローカル状態だけを更新し、「確認」操作で必要な値をまとめてエージェントへ渡せます。すべてのキー入力をモデル呼び出しへ変換する必要はありません。

形式チェック、必須入力、数値範囲など、クライアントだけで判定できる条件は送信前に検証します。公式記事も、不正なメール形式をモデルへ送らずクライアント側で拒否できる例を示しています。モデルへ渡すのは、自然言語の解釈、候補生成、外部ツール実行など、エージェントが必要な処理に限定します。これにより、入力のたびに画面が再生成される揺れと、不要な待ち時間や費用を抑えられます。

送信後は、action名、対象surface、データの版、画面を生成した応答IDを一組で扱います。古い画面を開いたまま操作された場合、現在のエージェント状態と一致しないことがあります。更新を拒否して再描画するのか、入力を引き継いで新しいsurfaceへ移すのかを先に決めておくと、二重送信や途中状態の消失を切り分けやすくなります。

再試行を前提に、失敗を画面状態として設計する

公式記事は、AG-UIを使う利点として、生成UIを専用サブエージェントへ任せる構成、無効な生成の自己修正、再試行を使い切った後の段階的な失敗処理を挙げています。ただし、再試行回数や成功率が一律に保証されるわけではありません。本番では、スキーマ違反、未知の部品、欠けた必須値、イベント順序の不整合を別の失敗として記録します。

再生成する場合も、同じ入力を無制限にモデルへ戻してはいけません。1回目は検証エラーを構造化して返し、2回目で直らなければ定型画面へ戻すなど、上限と代替表示を決めます。既存の静的フォームや結果一覧をフォールバックとして残せば、生成UIの失敗が業務全体の停止に直結しません。利用者には「再試行中」「入力は保持済み」「定型画面へ切り替えた」を区別して示します。

本番導入前に評価する7項目

1. 部品選択：要求に対して意図したカタログ部品が選ばれるか。
2. スキーマ適合：必須値、型、範囲違反を検出し、修正または代替表示へ進めるか。
3. 初回表示：要求開始から最初の有用なsurfaceが見えるまでの時間を測れるか。
4. 操作往復：actionと必要なコンテキストだけがエージェントへ届くか。
5. 状態復元：再読込、切断、会話再開で入力と表示の対応が崩れないか。
6. 失敗上限：再試行終了後に定型画面や案内へ確実に移れるか。
7. 版管理：モデル、プロンプト、カタログ、レンダラー、アダプターの組み合わせを追跡できるか。

評価用データは、正常系だけでなく、入力不足、長文、曖昧な依頼、途中キャンセル、連続クリック、古いsurfaceからの操作を含めます。見た目の正しさだけでなく、次の操作を完了できた割合、定型画面へ戻った割合、再試行回数、利用者が入力し直した項目数を記録します。モデルの出力トークンが減っても、操作のやり直しが増えれば導入効果は小さくなります。

採用判断：変化する作業画面に限定して始める

A2UIとCopilotKitの組み合わせは、検索条件や結果、確認手順が要求によって変わる業務画面に向きます。質問への回答が文章だけで済むチャットや、法定項目が固定された申請画面、ピクセル単位で配置が決まる画面では、生成UIを使う利点が小さい場合があります。まず一つの作業フローへ限定し、カタログとフォールバックを固定して比較してください。

2026年11月1日の確認時点で、A2UIはv0.9.1が現行の本番向け仕様として案内され、v1.0は候補段階です。v1.0を安定版として前提にせず、採用する仕様版とライブラリー版を固定します。接続が動いたことだけを完了条件にせず、双方向操作、再試行、復元、代替画面まで通して初めて、本番導入の判断材料がそろいます。

参考資料

• Google Developers Blog「Build Generative UI Apps with A2UI & CopilotKit Agents」
• A2UI公式サイト・仕様案内
• A2UI公式ガイド「Build with any framework」

関連記事

• A2UI Expressで生成UIを高速化｜Direct JSONから移す手順と比較検証