a2ui

A2UI 開発スキル

このスキルは、AI エージェントがクライアントにストリーミングできる、リッチでインタラクティブなユーザーインターフェースを構築するための、A2UI（Agent to UI）プロトコル準拠のコード生成を支援します。

プロトコルバージョン

このスキルは、A2UI プロトコル v0.8（安定版リリース）を対象としています。

標準カタログ ID：https://github.com/google/A2UI/blob/main/specification/0.8/json/standard_catalog_definition.json

主な概念

1. メッセージの種類

A2UI は、JSONL ストリームで次の 4 種類のメッセージを使用します。

メッセージ	目的
surfaceUpdate	UI コンポーネントを定義または更新します
dataModelUpdate	アプリケーションの状態を設定または更新します
beginRendering	レンダリング開始をクライアントに通知します
deleteSurface	UI サーフェスを削除します

2. 隣接リストモデル

コンポーネントは、入れ子のツリーではなく、ID 参照を使ったフラットなリストとして定義します。

{"surfaceUpdate": {"surfaceId": "main", "components": [
  {"id": "root", "component": {"Column": {"children": {"explicitList": ["header", "content"]}}}},
  {"id": "header", "component": {"Text": {"text": {"literalString": "Welcome"}, "usageHint": "h1"}}},
  {"id": "content", "component": {"Text": {"text": {"path": "/user/name"}}}}
]}}

3. データバインディング（BoundValue）

値をバインドするパターンは 3 種類あります。

// Literal only - static value
{"literalString": "Hello"}

// Path only - dynamic from data model
{"path": "/user/name"}

// Both - initialization shorthand (sets default AND binds)
{"path": "/form/email", "literalString": "[email protected]"}

4. スタイル設定

beginRendering で外観をカスタマイズします。

{"beginRendering": {
  "surfaceId": "main",
  "root": "root",
  "styles": {
    "font": "Roboto",
    "primaryColor": "#1976D2"
  }
}}

プロパティ	説明
font	基本フォントファミリー
primaryColor	テーマカラー（16 進数形式 #RRGGBB）

標準カタログのコンポーネント

レイアウトコンポーネント

• Row - distribution と alignment を指定する水平コンテナー
• Column - distribution と alignment を指定する垂直コンテナー
• List - direction（垂直／水平）を指定するスクロール可能なリスト
• Card - 単一の child を持つマテリアルカードのラッパー
• Tabs - tabItems 配列を使ったタブナビゲーション
• Modal - entryPointChild と contentChild を持つダイアログ
• Divider - axis（水平／垂直）を指定する区切り線

表示コンポーネント

• Text - usageHint（h1-h5、caption、body）を指定するテキスト表示。シンプルな Markdown に対応しています。
• Image - url、fit、usageHint を指定する画像
• Icon - 標準セットのアイコン（コンポーネントリファレンスを参照）
• Video - url を指定するビデオプレーヤー
• AudioPlayer - url と description を指定するオーディオプレーヤー

入力コンポーネント

• Button - child と action を指定するクリック可能なボタン
• TextField - label と textFieldType を指定するテキスト入力フィールド
• CheckBox - label と value を指定する切り替えコントロール
• DateTimeInput - enableDate／enableTime を指定する日付／時刻ピッカー
• MultipleChoice - options と maxAllowedSelections を指定する選択コントロール
• Slider - minValue／maxValue を指定する範囲入力コントロール

コンポーネントのウェイト

Row／Column 内のコンポーネントで weight を使うと、フレックスレイアウトを設定できます。

{"id": "sidebar", "weight": 1, "component": {"Column": {...}}},
{"id": "main", "weight": 3, "component": {"Column": {...}}}

A2UI メッセージの生成

基本的な流れ

1. surfaceUpdate でコンポーネントを定義します
2. dataModelUpdate でデータを設定します
3. beginRendering でレンダリングを開始します

完全な例：シンプルなフォーム

{"surfaceUpdate": {"surfaceId": "booking", "components": [
  {"id": "root", "component": {"Column": {"children": {"explicitList": ["title", "name_field", "date_field", "submit_btn"]}}}},
  {"id": "title", "component": {"Text": {"text": {"literalString": "Book a Table"}, "usageHint": "h2"}}},
  {"id": "name_field", "component": {"TextField": {"label": {"literalString": "Your Name"}, "text": {"path": "/form/name"}}}},
  {"id": "date_field", "component": {"DateTimeInput": {"value": {"path": "/form/date"}, "enableDate": true}}},
  {"id": "submit_btn", "component": {"Button": {"child": "submit_text", "action": {"name": "submit_booking", "context": [{"key": "name", "value": {"path": "/form/name"}}, {"key": "date", "value": {"path": "/form/date"}}]}}}},
  {"id": "submit_text", "component": {"Text": {"text": {"literalString": "Confirm Booking"}}}}
]}}
{"dataModelUpdate": {"surfaceId": "booking", "contents": [{"key": "form", "valueMap": [{"key": "name", "valueString": ""}, {"key": "date", "valueString": ""}]}]}}
{"beginRendering": {"surfaceId": "booking", "root": "root"}}

イベント処理

ユーザーアクション

ユーザーが操作（ボタンのクリックなど）を行うと、クライアントは userAction を送信します。

{
  "userAction": {
    "name": "submit_booking",
    "surfaceId": "booking",
    "sourceComponentId": "submit_btn",
    "timestamp": "2025-01-01T10:00:00Z",
    "context": {"name": "John Doe", "date": "2025-01-15"}
  }
}

エラー報告

クライアントは error メッセージを使ってエラーを報告します。

{
  "error": {
    "type": "RENDER_ERROR",
    "message": "Component 'user_card' references missing child",
    "surfaceId": "main",
    "componentId": "user_card",
    "timestamp": "2025-01-01T10:30:05Z"
  }
}

ベストプラクティス

1. 一意の ID：各コンポーネントには、サーフェス内で一意の id が必要です
2. フラットな構造：親子関係には ID 参照を使用します
3. データの分離：UI 構造は surfaceUpdate に、動的な値は dataModelUpdate に保持します
4. パスの規約：パスには JSON Pointer 形式（例：/user/profile/name）を使用します
5. 段階的なレンダリング：必要なコンポーネントを定義した後に beginRendering を送信します
6. サーフェスのクリーンアップ：フローが完了したら deleteSurface を使用します

リファレンスドキュメント

基本リファレンス

• コンポーネントリファレンス - 16 個すべてのコンポーネントとそのプロパティ
• データバインディングガイド - BoundValue のパターンとテンプレート
• API 統合 - イベント処理とバックエンド接続
• スキーマリファレンス - 検証用 JSON Schema

高度なトピック

• カタログネゴシエーション - 複数のカタログのサポート
• サーフェス管理 - 複数の UI 領域
• ストリーミングとパフォーマンス - 段階的なレンダリング
• エージェントのプロンプト作成 - LLM の統合

例

基本パターン

• フォームの例 - 登録フォームと予約フォーム
• リストの例 - テンプレートを使用した動的リスト
• モーダルの例 - ダイアログとポップアップのパターン

高度なパターン

• 予約フロー - エンドツーエンドの業務フロー
• マルチサーフェス - 複数の UI 領域
• ストリーミング - 段階的なレンダリング