Skip to content

独自カタログを定義する

Basic Catalog は、アプリケーションを始めたりブートストラップしたりするうえで便利ですが、ほとんどの本番アプリケーションでは、自分たちのデザインシステムを反映する独自カタログを定義します。

独自カタログを定義すると、エージェントは汎用的な入力欄やボタンではなく、アプリケーション内に実際に存在するコンポーネントと視覚言語だけを使うように制限されます。

なぜ独自カタログを定義するのか？

すべての A2UI surface は Catalog によって駆動されます。カタログは、エージェントが使用できるコンポーネント、関数、テーマを伝える JSON Schema ファイルです。

独自カタログを定義すると、次の利点があります。

  • デザインシステムとの整合: エージェントが、アプリケーションに実際に存在するコンポーネントと視覚言語だけを使うように制限できます。
  • セキュリティと型安全性: クライアントアプリケーションにカタログ全体を登録するため、信頼されたコンポーネントだけがレンダリングされます。
  • マッパー不要: Basic Catalog のような汎用カタログをアダプターで変換するよりも、クライアントのデザインシステムを直接反映するカタログを作ることが推奨されます。

Basic Catalog はあくまで一例であり、さまざまなレンダラーが実装しやすいよう意図的に最小限にされています。

仕組み

  1. カタログを定義する: アプリケーションが対応するコンポーネント、関数、スタイルを列挙したカタログ定義(JSON Schema)を作成します。
  2. カタログを登録する: カタログと、それに対応するコンポーネント実装(レンダラー)をクライアントアプリケーションに登録します。
  3. 対応状況を通知する: クライアントは対応しているカタログをエージェントに知らせます(supportedCatalogIds)。
  4. エージェントがカタログを選択する: エージェントは特定の UI surface に使うカタログを選びます(createSurface などの作成メッセージ内の catalogId)。
  5. エージェントが UI を生成する: エージェントは、そのカタログで名前付き定義されているコンポーネントを使ってコンポーネントメッセージを生成します。

実装ガイド

既存のコンポーネントライブラリに直接対応するカタログを作ることが推奨されます。

Web で独自カタログを実装するには、次を行います。

  • コンポーネント定義を含む JSON Schema を作成します。
  • 選択した Web レンダラー内で独自の Component オブジェクトと Catalog オブジェクトを作成します。
    • スキーマまたは参照 ID をエージェントに提供します。

各フレームワーク向けの詳細ガイドは近日公開予定です。

Flutter で独自カタログを実装するには、次を行います。

  • ウィジェットのプロパティを記述する JSON Schema を定義します。
  • カスタムレンダラーを使って、そのスキーマを Flutter ウィジェットにマッピングします。

詳細な Flutter 統合ガイドは近日公開予定です。

セキュリティ上の考慮事項

カタログを定義して登録するときは、次を守ってください。

  1. コンポーネントを許可リスト化する: カタログ定義には信頼できるコンポーネントだけを登録してください。任意スクリプト実行など危険な機能を提供するコンポーネントは、厳格に制御されていない限り公開しないでください。
  2. プロパティを検証する: エージェントメッセージのコンポーネントプロパティが、期待される型制約に一致するか常に検証してください。
  3. テキストをサニタイズする: 安全な境界が確立されていない場合、エージェントが提供した未サニタイズのコンテンツをそのままレンダリングしないでください。

次のステップ