本文へスキップ
Material 3 Expressivev1.3.0-rc.1

React向けA2UI

Google A2UIをMaterial 3 Expressiveで描画します。

Material 3 Expressive for A2UIは、GoogleのA2UIプロトコルに対応するReactレンダラーです。A2UI基本カタログのすべてのコンポーネントをGoogleのMaterial 3 Expressiveデザインシステムに対応付けるため、エージェントが生成するインターフェースにもアプリ全体と同じテーマを適用できます。

メッセージの到着に合わせてサーフェスをストリーミングし、入力をデータモデルにバインドして検証し、アクションをエージェントに返します。

ここで試す

エージェントのサーフェスをストリーミングする

スクリプトによるデモです。LLMやAPIキーは必要ありません。

シナリオを選択

すべてのメッセージはスクリプトで定義されています。再生はいつでも停止できます。

サーフェスをストリーミング

エージェントはコンテンツを送る前にカード名を指定するため、まずプレースホルダーが表示されます。データバインディング、書式設定関数、後続の値の更新によって内容が表示されます。

リスボン旅行の予定を見せてください。

シナリオを再生すると、サーフェスがストリーミングされます。

仕組み

メッセージストリームからMaterialコンポーネントへ

レンダラーはGoogleのプロトコルランタイムとデザインシステムの間で動作します。ランタイム依存関係や通信機能は追加しません。

  1. メッセージの到着

    エージェントはA2A、HTTP、またはWebSocket経由でA2UIのJSONメッセージをストリーミングします。各行を解析してprocessMessagesに渡します。

  2. web_coreがモデルを管理

    Googleの@a2ui/web_coreが各メッセージを検証し、サーフェスとデータモデルを管理して、バインディングとカタログ関数を評価します。

  3. サーフェスの描画

    A2uiSurfaceは各コンポーネントを購読し、Material 3 Expressiveのコンポーネントで描画します。到着前に名前が指定された子要素はプレースホルダーとして表示されます。

  4. アクションを返す

    入力値はデータモデルに書き込まれます。ボタンは解決済みのコンテキストとともにイベントをonActionコールバックに渡すため、エージェントに送信できます。

対応コンポーネント

A2UI基本カタログのすべてに対応

v0.9.1基本カタログの18コンポーネントすべてを、Material 3 Expressiveのコンポーネントとトークンで描画します。色、文字スタイル、角の形、モーションの値は、ライトモードとダークモードのどちらでもテーマに従います。

A2UIコンポーネント描画結果備考
TextTexth1からh5はheadlineとtitleのロールに対応します。Markdownの対応範囲:太字、斜体、コード、リンク、見出し、リスト。
Imageサイズバリアント付きImageicon、avatar、smallFeature、mediumFeature、largeFeature、header。
IconIconカタログ内の名前は埋め込みグリフとして描画されます。アイコンフォントは不要です。
Videoネイティブ動画プレーヤーコントロールを有効にします。
AudioPlayerネイティブ音声プレーヤーコントロールを有効にします。
RowFlex行justify、align、子要素のweightに対応します。
ColumnFlex列justify、align、子要素のweightに対応します。
ListList縦または横に配置できます。静的な子要素とテンプレートに対応します。
CardCardアウトライン付きの非インタラクティブなコンテナーです。
TabsTabsキーボードで操作できます。
ModalDialogトリガーでダイアログを開き、アクションもディスパッチします。
DividerDivider水平または垂直に配置できます。
ButtonButtonprimaryは塗りつぶし、defaultはトーナル、textは枠線なしです。チェックに失敗すると無効になります。
TextFieldTextFieldまたはTextAreashortText、longText、obscured、numberに対応します。
CheckBoxCheckboxラベルを表示します。
ChoicePickerRadio、Checkbox、またはfilter Chip単一選択または複数選択に対応し、任意でフィルターフィールドを表示します。
SliderSlider小数点以下の精度は範囲に応じて決まります。
DateTimeInputDatePicker、TimePicker、またはDateTimePicker1.3.0-rc.1のMaterialピッカー機能を使い、1.2のpeer依存バージョンではネイティブ入力にフォールバックします。
コンポーネントと描画ルールを読む

互換性

バージョンと制限

このパッケージはコミュニティによる独立した実装です。Googleとは提携していません。A2UIとMaterial DesignはGoogleのプロジェクトです。

対応バージョン
A2UIプロトコルv0.9.1(v0.9を受け付けます)。基本カタログ。
@a2ui/web_core^0.10.7。0.10.7でテスト済みです。
@language-lit/material3-expressive1.3.0-rc.1。
ReactとReact DOM18 or 19。
@a2ui/react0.11.0でカタログをテストしています。依存パッケージではありませんが、React 19自体が必要です。

既知の制限

  • 既定では基本カタログのみを使います。createMaterial3Catalogでほかのカタログを登録できます。
  • カタログにないアイコン名はMaterial Symbolsの合字にフォールバックするため、そのフォントが必要です。
  • Markdownの対応範囲にテーブル、画像、生HTML、入れ子のリストは含まれません。
  • DateTimeInputは1.3.0-rc.1のMaterialピッカーのエクスポートを使い、互換性のある1.2のpeer依存バージョンではプラットフォームの入力欄にフォールバックします。
  • エージェントのprimaryColorはカスタムプロパティとして公開されます。サーフェスのテーマは変更しません。
  • 通信、認証、永続化、オーケストレーションはアプリケーション側で管理します。

開発を始める

ReactアプリにA2UIを追加する

React 18または19のアプリにレンダラーとpeer依存パッケージをインストールします。

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

2つのスタイルシートをこの順番で読み込みます。次にuseA2uiでプロセッサーを管理し、各サーフェスをMaterial3Provider内で描画します。

import '@language-lit/material3-expressive/styles.css'
import '@language-lit/material3-expressive-a2ui/styles.css'
import { Material3Provider } from '@language-lit/material3-expressive'
import { A2uiSurface, useA2ui } from '@language-lit/material3-expressive-a2ui'

export function AgentPanel({ send }) {
  const { surfaces, processMessages } = useA2ui({
    onAction: (action) => send(action),
  })
  // Call processMessages(messages) with each batch your agent delivers.
  return (
    <Material3Provider>
      {surfaces.map((surface) => (
        <A2uiSurface key={surface.id} surface={surface} />
      ))}
    </Material3Provider>
  )
}

すでにGoogleのReactサーフェスで描画していますか?

material3Catalog(@language-lit/material3-expressive-a2uiからエクスポート)は、@a2ui/reactが利用する描画専用形式のweb_coreカタログです。既存のプロセッサーに登録すれば、サーフェス、通信、フォールバックの方針はそのまま管理できます。

カタログの登録方法を読む

独自のエージェントサーフェスを作る

まずセットアップガイドを読み、各コンポーネントの描画方法とカタログの拡張方法を確認してください。プロトコル自体についてはA2UIプロジェクト。

A2UIを使い始める

レンダラーをインストールし、A2UIメッセージをサーフェスにストリーム配信して、アクションをエージェントに返します。

A2UIコンポーネントとレンダリング規則

基本カタログの各コンポーネントのレンダリング方法に加え、バインディング、検証、テンプレート、テーマ設定、カタログの拡張方法を説明します。