A2UIを使い始める

@language-lit/material3-expressive-a2uiは、Google A2UIのサーフェスをMaterial 3 Expressiveで表示します。A2UIは、エージェントがデータバインディングを持つカタログコンポーネントのツリーとしてUIを記述し、それをJSONメッセージとしてストリーミングするプロトコルです。この連携パッケージはA2UI basic catalogのすべてのコンポーネントをMaterial 3 Expressiveのコンポーネントに対応づけるため、エージェントが生成したUIもアプリの他の部分と同じテーマを使います。

このガイドはReact 18または19、@language-lit/material3-expressive 1.2.x、@a2ui/web_core 0.10.xを通じたA2UIプロトコルv0.9.1を対象とします。この連携パッケージは独立したコミュニティ実装であり、Googleとは提携していません。

エージェントに接続する前に試す

インタラクティブデモはすべてブラウザー内で動作します。スクリプトで用意したA2UIメッセージを一つずつレンダラーにストリーミングするため、プレースホルダーが埋まる様子、バインドしたフィールドの編集、検証の通過、エージェントに返されるアクションを確認できます。LLMは呼び出されず、APIキーも必要ありません。

インストール

既存のReactアプリに連携パッケージと必須peer依存関係をインストールします。

npm install @language-lit/material3-expressive-a2ui @language-lit/material3-expressive @a2ui/web_core

@a2ui/web_coreはGoogleのプロトコルランタイムです。メッセージを検証し、サーフェスとデータモデルを管理して、バインディングとカタログ関数を評価します。この連携パッケージ自体にランタイム依存関係はありません。

スタイルを読み込む

アプリケーションのルートで、次の順に両方のスタイルシートを一度だけ読み込みます。

import '@language-lit/material3-expressive/styles.css'
import '@language-lit/material3-expressive-a2ui/styles.css'

両パッケージは同じMaterialテーマを使います。既存のMaterial3Providerで、アプリの他の部分とエージェントのサーフェスをまとめて囲めます。カスタムカラーとネストしたスコープについてはテーマガイドをご覧ください。

サーフェスをレンダリングする

useA2uiでメッセージプロセッサを管理し、エージェントから届くメッセージを渡して、各サーフェスをA2uiSurfaceでレンダリングします。

'use client'

import { Material3Provider } from '@language-lit/material3-expressive'
import { A2uiSurface, useA2ui } from '@language-lit/material3-expressive-a2ui'
import type { A2uiClientAction, A2uiMessage } from '@a2ui/web_core/v0_9'

export function AgentPanel({ send }: { send: (action: A2uiClientAction) => void }) {
  const { surfaces, processMessages } = useA2ui({
    onAction: (action) => send(action),
    onError: (error, surfaceId) => console.warn(surfaceId, error),
  })

  // Call this with each batch your transport delivers.
  const receive = (messages: A2uiMessage[]) => processMessages(messages)

  return (
    <Material3Provider>
      {surfaces.map((surface) => (
        <A2uiSurface key={surface.id} surface={surface} />
      ))}
    </Material3Provider>
  )
}

この連携パッケージはトランスポートを提供しません。エージェントのフレームワークからA2A、HTTP、WebSocketなどの経路でA2UIメッセージを届けてください。JSONの各行を解析し、1件ずつ、またはまとめてprocessMessagesに渡します。createSurfaceメッセージの到着時にサーフェスが表示され、deleteSurfaceで削除されます。

useA2uiは安定した関数と、サーフェスに変更があるたびに変わるsurfaces配列を返します。結果オブジェクト全体ではなく、関数をエフェクトの依存関係にしてください。

レンダリング可能な内容をエージェントに伝える

最初のリクエストとともにクライアントの対応機能を送信し、エージェントがbasic catalogを選べるようにします。

const { getClientCapabilities, getClientDataModel } = useA2ui()

const capabilities = getClientCapabilities()
// { 'v0.9.1': { supportedCatalogIds: ['https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json'] } }

const dataModel = getClientDataModel()
// The data model of every surface created with sendDataModel, or undefined.

アクションを返す

actionを持つButtonを押すと、クライアントアクションが送信されます。アクションには、サーフェス、送信元コンポーネント、タイムスタンプ、エージェントが要求した解決済みのcontextが含まれます。これをエージェントに送信します。

{
  "name": "reserve",
  "surfaceId": "table",
  "sourceComponentId": "reserve-button",
  "timestamp": "2026-09-11T10:00:00.000Z",
  "context": { "name": "Ada", "guests": 2 }
}

checksを持つボタンは、すべてのチェックに合格するまで無効です。そのため、アクションは有効なデータでのみ送信されます。デモには送信される各アクションが表示されます。

表示されるエラー

onErrorは2種類の報告を受け取ります。検証に失敗したメッセージはプロセッサエラーであり、エージェントがプロトコルで許可されていない内容を送信したことを示します。サーフェスからのEXPRESSION_ERRORは、formatCurrencyやrequiredなどのカタログ関数が、必要な値がまだない状態で実行されたことを示します。サーフェスのストリーミング中や必須フィールドが未入力の間に起きる通常の現象で、データが届くと解消されます。2つ目は診断情報として扱ってください。onErrorがない場合、プロセッサエラーはprocessMessagesからスローされます。

次のステップ

• コンポーネントとレンダリング規則：各カタログコンポーネントの表示、バインディングと検証、テンプレート、テーマ設定、カタログの拡張方法、Google独自のReactサーフェスでの利用方法を説明します。
• A2UI仕様：プロトコル、basic catalog、メッセージ形式を確認できます。