HyperGen

ADR-001: プロジェクトコンセプト — HyperGenが存在する理由

HyperGenの創設ビジョン: 既存のGenerative UIプロトコルの批判的分析と、HTMXベースの真にエージェント非依存な代替手段の提案。

ステータス: 承認済み 日付: 2026-03-28 著者: HyperGen創設コントリビューター

コンテキスト

2026年のGenerative UIの状況は、プロトコルの乱立が起きています。AIエージェントがクライアントにUIを伝送する方法を定義しようと、複数の仕様が競合しています: AG-UI (CopilotKit)、A2UI (Google)、Open-JSON-UI (OpenAI派生)、MCP Apps (Anthropic/コミュニティ)。それぞれが「エージェント非依存」で「オープン」を標榜していますが、いずれも根本的なアーキテクチャ上の前提に欠陥があると我々は考えています。

本ADRは、これらの既存アプローチに対する批判的分析を文書化し、HyperGenの創設ビジョンを確立するものです。

問題: 偽りの非依存性

既存のGenerative UIプロトコルはすべてエージェント非依存性 — 任意のAIエージェントフレームワークで動作する能力 — を主張しています。しかし実際には、いずれも達成できていません。その理由は構造的なものです: すべてのプロトコルが中間表現（JSONスキーマ、コンポーネントカタログ、独自イベントシステム）を導入しており、プロデューサーとコンシューマーの両側でフレームワーク固有の統合コードが必要となります。

これは「古い抽象化」の思考様式です: プロデューサーとコンシューマーの間に翻訳レイヤーが必要だという信念。しかしWebにはすでにUIの普遍的な表現 — HTML — があります。仲介レイヤー全体が不要なのです。

既存アプローチの批判的分析

AG-UI (CopilotKit)

概要: AIエージェントとフロントエンドアプリケーションを接続するイベントベースのプロトコル。エージェントとUI間の「ランタイムチャネル」として位置付けられている。

正しい点:

  • 標準化されたエージェント-UI接続の必要性を認識
  • イベントベースのストリーミング設計は概念的にクリーン（約16のイベントタイプ）
  • 仕様レベルではトランスポート非依存（SSE、WebSocketなど）

問題点:

  • 実際にはGenerative UIプロトコルではない。 AG-UIはエージェントとUIがイベントを通信する方法を定義するだけで、UIの生成方法は定義しない。UI生成はA2UI、Open-JSON-UI、またはMCP-UIに委譲しており、ソリューションではなくトランスポートレイヤーに過ぎない。
  • CopilotKitへのロックイン。「オープン」を標榜しているにもかかわらず、唯一の完全なフロントエンドクライアントはCopilotKit自体。このプロジェクトはCopilotKitの内部エージェント統合レイヤーとして誕生した。コミュニティのコントリビューターは次のように指摘している: 「AG-UIは、CopilotKitが標準を使用してエージェントフレームワーク統合を追加するための内部ツールだった。」 (GitHub Issue #291)
  • SDKの増殖。 LangGraph、CrewAI、Google ADK、AWS Strands、Mastra、Pydantic AIなど向けに個別のアダプターパッケージが存在し、それぞれ独立してメンテナンスされている。これは非依存性の正反対。
  • 重い依存関係チェーン。 TypeScript SDKはRxJS、Zod、fast-json-patch、uuidに依存。Python SDKはPydantic ≥2.11.2が必要。

結論: AG-UIはGenerative UIソリューションを装った善意のトランスポートプロトコル。その真の目的は、エージェントフレームワークをCopilotKitエコシステムに誘導すること。

A2UI (Google)

概要: AIエージェントがUIコンポーネントを記述するための宣言的JSON仕様。エージェントが構造化JSONを送信し、クライアントがネイティブにレンダリングする。

正しい点:

  • UI構造、アプリケーション状態、クライアントレンダリング間のクリーンな分離
  • ID参照によるフラットなコンポーネントリストはLLMフレンドリー（インクリメンタル生成をサポート）
  • 「Surface」コンセプト（ダイアログ、サイドバー、メインビュー）は真に有用
  • トランスポート非依存 — A2A、AG-UI、SSE、WebSocket上で動作

問題点:

  • コンポーネントカタログのボトルネック。 エージェントはクライアントのカタログに定義されたコンポーネントしか使用できない。ドラッグ&ドロップウィジェットが必要？カスタムデータ可視化が必要？残念ながらカタログになければ使えない。これは「Generative」の意味を根本的に制限している。
  • プラットフォーム固有のレンダラーが必要。 プラットフォーム非依存を主張しているにもかかわらず、Web (Lit)、Flutter、Angular、および計画中のReact/SwiftUI/Jetpack Compose向けに個別のレンダラー実装が必要。各レンダラーは相当なエンジニアリング努力を要する。
  • 不安定性。 v0.8（パブリックプレビュー）で、v0.9ですでに破壊的なフォーマット変更（ネスト → フラット構造）が導入されている。v1.0は2026年Q4まで期待されていない。
  • LLMにとってのJSONオーバーヘッド。 フラット構造は助けになるが、LLMは依然として正しいコンポーネントID、データバインディングパス、構造的関係を持つ有効なJSONを生成する必要がある。JSONスキーマバリデーションラッピングが必要。
  • A2UI単体では不完全。 トランスポート、ライフサイクルイベント、双方向インタラクションセマンティクスを定義しておらず、それらにはAG-UIまたは別のプロトコルが必要。

結論: A2UIは既存の仕様の中で最も思慮深く設計されているが、そのコンポーネントカタログアプローチはshadcn/ui以前のコンポーネントライブラリの制約を再現している — 有効にするのではなく制約する固定のボキャブラリー。

Open-JSON-UI (OpenAI派生)

概要: OpenAIの内部宣言的UIスキーマのオープン標準化。JSON Schema制約下でのLLMトークン効率と生成精度に最適化。

正しい点:

  • 「生成の容易さ」を優先 — 最小限のネスト、フラットなコンテンツ配列
  • OpenAIのStructured Outputsと連携した信頼性の高いJSON生成
  • 生成の容易さとレンダリング精度の根本的なトレードオフを認識

問題点:

  • 単体でレンダリングできない。 実際に表示するにはAG-UI/CopilotKitエコシステムまたは変換レイヤー（例: SimpleA2UI）が必要。
  • 独立したエコシステムがない。 スタンドアロンのnpmパッケージ、SDK、OpenAIからの公式仕様書がない。主にCopilotKitの軌道内に存在。
  • レイアウトセマンティクスが限定的。 精密なレイアウト制御は不可能で、レンダラーが意図を推測する必要がある。
  • コアのトレードオフは行き止まり。「レンダリング精度」より「生成の容易さ」を選択することで、Open-JSON-UIはレンダラーにとって曖昧なJSONを生成する。これはクライアントが仮定を立てる必要があることを意味し、プラットフォーム間で不整合な結果をもたらす。

結論: Open-JSON-UIは、LLMに構造化UI定義を生成させることが困難であるという正直な認識だが、そのソリューション（フォーマットをシンプルにする）は複雑さを解決せずにレンダラーに転嫁しているだけ。

MCP Apps (Anthropic / コミュニティ)

概要: MCPサーバーがインタラクティブなHTMLインターフェースを返し、サンドボックス化されたiframeでレンダリングするMCP (Model Context Protocol) の拡張。

正しい点:

  • HTMLネイティブアプローチ。 サーバーが完全なHTMLを送信 — 最も普遍的なUI表現。HyperGenの哲学と一致。
  • 強力なセキュリティモデル。 4層防御: iframeサンドボックス、事前宣言テンプレート、監査可能なJSON-RPCメッセージ、ユーザー同意。
  • 幅広いクライアントサポート。 Claude、ChatGPT、VS Code GitHub Copilot、Gooseなど。
  • 実用的な設計。 リソース宣言にui:// URIスキーム、text/html;profile=mcp-app MIMEタイプを使用。

問題点:

  • ストリーミングなし。 MCP Appsは完全なHTMLペイロードを配信する。インクリメンタルレンダリングがなく、ウィジェット全体が生成されるまで表示されない。これがHyperGenがiframe内のHTMXのSSE拡張で埋める重要なギャップ。
  • 重いクライアントサイド要件。 HTMLを使用しているにもかかわらず、postMessage経由のJSON-RPC 2.0ブリッジとセキュリティインフラストラクチャにはかなりのクライアント実装努力が必要。
  • MCP結合。 MCPエコシステム内でのみ動作。MCPを話さないエージェントはMCP Appsを使用できない。
  • レンダリング後は静的。 HTMLが配信された後、インタラクティビティはiframe自身のJavaScriptに依存する。HTMXが提供するような宣言的インタラクティビティパターンがない。

結論: MCP AppsはHyperGenのビジョンに最も近い既存アプローチ — HTML + サンドボックス化されたiframeが正しい媒体であることを正しく特定している。HyperGenはこの基盤の上に、宣言的インタラクティビティのためのHTMXとストリーミングのためのSSEを追加し、MCP結合を排除して真のエージェント非依存性を実現する。

洞察: HTMLはすでに勝利している

4つのアプローチすべてが隠れた前提を共有しています: エージェントの出力はUIになる前に何かに変換される必要がある。 AG-UIはイベントをコンポーネント更新に変換。A2UIはJSONをプラットフォームネイティブウィジェットに変換。Open-JSON-UIはフラットJSONをレンダリング可能な構造に変換。MCP AppsはHTMLをiframeサンドボックスでラップ。

しかし、ClaudeがUIを生成するとき何をしているか考えてみてください: HTMLとCSSを直接書いています。 これは制約ではなく、強みです。HTMLは:

  • ユニバーサル: すべてのブラウザがレンダリングする。SDKは不要。
  • ストリーマブル: HTMLフラグメントはインクリメンタルに送信・レンダリングできる。
  • インタラクティブ（HTMXにより）: HTMX属性がJavaScriptゼロで静的HTMLをインタラクティブにする。
  • LLMネイティブ: LLMはどんなJSON UIスキーマよりもはるかに多くのHTMLで学習されている。HTML生成はより信頼性が高く、より表現力がある。
  • 検査可能: ユーザーはソースを見たり、コピーしたり、生成されたUIを修正できる。shadcn/uiのコードオーナーシップの原則が自然に適用される。

欠けていたピースは常にインタラクティビティとストリーミングでした — そしてそれこそがHTMXが提供するものです。

決定

我々はHyperGenを構築します: HTMLフラグメントをAIエージェントとクライアント間の普遍的なインターフェースとして扱う、HTMXベースのGenerative UIプロトコルです。

コア原則

  1. HTMLがプロトコルである。 エージェントはHTMX属性付きのHTMLを生成する。中間JSON表現なし。コンポーネントカタログなし。独自イベントシステムなし。

  2. 真にエージェント非依存。 HTML文字列を出力できるシステムならどれでも参加可能。SDK不要。アダプターパッケージ不要。フレームワーク固有の統合コード不要。

  3. ストリーミングファースト。 HTMLフラグメントはSSE経由でストリーミングされ、HTMXの組み込みスワップメカニズムでインクリメンタルにレンダリング。UIはエージェントが生成するにつれて段階的に表示。

  4. インタラクティビティのためのHTMX。 HTMX属性（hx-get、hx-post、hx-target、hx-swap、hx-trigger）がJavaScriptなしで宣言的インタラクティビティを提供。ユーザーインタラクションは標準HTTPリクエストとしてエージェントに流れる。

  5. スコープ(B): 仕様 + リファレンス実装。 プロトコル仕様と最小限のリファレンス実装を公開する。リファレンスは依存関係としてインストールするものではなく、コピーして適応させるもの（shadcn/uiモデル）。

  6. CSS変数ベースのテーマ。 生成されたUIはCSSカスタムプロパティを通じてホストアプリケーションのデザインシステムを継承。スタイルの競合なし、デザインシステムの結合なし。

  7. サンドボックス化されたiframeレンダリング。 生成されたUIはセキュリティ分離のためにサンドボックス化されたiframe内でレンダリング。HTMXはiframe内で動作し、エージェントサーバーと直接通信。ホストアプリケーションとの統合にはpostMessageを使用。MCP Appsのセキュリティモデルとg HTMXのインタラクティビティを組み合わせたもの — ADR-004を参照。

HyperGenが「ではないもの」

  • フレームワークではない。 npm install hypergenはなし。ビルドステップ不要。
  • コンポーネントライブラリではない。 ウィジェットの固定ボキャブラリーなし。エージェントは必要なHTMLを何でも生成する。
  • エージェントフレームワークではない。 HyperGenはエージェントの内部動作を気にしない。

結果

ポジティブ

  • エージェントの統合コストがゼロ。 HTMLを出力するエージェントならどれでもHyperGenを即座に使用可能。これは競合するどのプロトコルよりも根本的に低いハードル。
  • 馴染みのある技術。 HTML + HTMXは何百万人もの開発者が理解している。新しい概念を学ぶ必要なし。
  • プログレッシブエンハンスメント。 HyperGen UIはJavaScriptなしでも動作し（基本HTML）、HTMXでインタラクティブになり、カスタムJavaScriptでさらに拡張可能。
  • デフォルトでストリーマブル。 SSE + HTMXフラグメントスワッピングがリアルタイムのプログレッシブレンダリングを標準で提供。

ネガティブ

  • Web限定（当初は）。 HTMLはWeb技術。ネイティブモバイルやデスクトップアプリケーションにはWebViewまたはHTMLレンダリングレイヤーが必要。これは意識的なトレードオフ — まずWebプラットフォームに最適化する。
  • iframeのオーバーヘッド。 サンドボックス化されたiframeは間接レイヤーを追加する。ホストからiframeへのCSS変数注入には明示的なブリッジが必要。セキュリティのために許容可能なトレードオフ。
  • カタログベースのアプローチより精度が低い。 A2UIのコンポーネントカタログは一貫したレンダリングを保証する。HyperGenの生HTMLアプローチでは、視覚的一貫性はエージェントのCSS変数への準拠とホストのデザインシステムに依存する。

リスク

  • iframeエスケープ攻撃。 サンドボックス化されたiframeは強力な分離境界だが、sandbox属性の設定ミスはセキュリティを弱める可能性がある。軽減策: 仕様が厳格なデフォルトsandboxポリシーを定義 — ADR-004を参照。
  • HTMX依存。 HTMXは軽量（14KB）だが、依然として依存関係。軽減策: HTMXは推移的依存関係のない単一のスクリプトタグであり、HyperGenはHTMXなしの基本HTMLでも動作可能（インタラクティビティは失われる）。

参考資料

  • AG-UI Protocol — CopilotKitのエージェント-UIプロトコル
  • A2UI — Googleの宣言的エージェントUI仕様
  • Open-JSON-UI — OpenAI派生UIスキーマ
  • MCP Apps — MCPのHTML-in-iframe拡張
  • HTMX — ハイパーメディア駆動のインタラクティビティ
  • How Claude's Generative UI Works — Claudeのアプローチのアーキテクチャ分析
  • Hypermedia Systems — 思想的基盤
  • shadcn/ui — リファレンス実装において我々が従うオーナーシップモデル

エージェント作成ガイドライン

AIエージェントがHyperGen互換HTMLフラグメントを生成するためのベストプラクティス: HTMX属性、CSSテーマ、自己完結性、アクセシビリティ。

ADR-002: スコープと成果物

HyperGenのスコープを、軽量リファレンス実装付きのプロトコル仕様（スコープB）として定義。

目次

コンテキスト問題: 偽りの非依存性既存アプローチの批判的分析AG-UI (CopilotKit)A2UI (Google)Open-JSON-UI (OpenAI派生)MCP Apps (Anthropic / コミュニティ)洞察: HTMLはすでに勝利している決定コア原則HyperGenが「ではないもの」結果ポジティブネガティブリスク参考資料