仕様概要
HyperGenプロトコル仕様: AIエージェントがSSE経由でインタラクティブHTMLをサンドボックス化されたiframeにストリーミングする方法。
HyperGenプロトコル仕様
本ドキュメントは、HyperGenプロトコルを定義します — AIエージェントがHTMX属性付きのHTMLフラグメントをServer-Sent Events (SSE) 経由でサンドボックス化されたiframeにストリーミングすることで、インタラクティブなユーザーインターフェースを提供するための規格です。
本仕様は規範的です。適合する実装は、しなければならない (MUST) および してはならない (MUST NOT) でマークされたすべての要件を満たさなければなりません (MUST)。すべきである (SHOULD) でマークされた要件は強く推奨されます。してもよい (MAY) でマークされた要件はオプションです。
目的
HyperGenは3つの参加者間の最小限の契約を定義します:
- HTMLを生成してクライアントにストリーミングするエージェントサーバー
- iframeを埋め込み、そのライフサイクルを管理するホストアプリケーション
- ストリーミングされたHTMLを受信し、HTMXでレンダリングし、ホストにイベントをブリッジするiframeドキュメント
本仕様は、ワイヤーフォーマット、iframeブートストラップドキュメント、ホストとiframe間のpostMessageプロトコル、CSS変数によるテーマ契約、およびHTMLフラグメントを作成するエージェント向けのガイドラインを対象とします。
用語
| 用語 | 定義 |
|---|---|
| エージェント | HTMLフラグメントを生成するサーバーサイドプロセス。LLM、従来のサーバー、またはHTMLを出力する任意のシステム。 |
| エージェントサーバー | iframe内のHTMXが消費するSSEおよびPOSTエンドポイントを公開するHTTPサーバー。 |
| ホストアプリケーション | 1つ以上のHyperGen iframeを作成・管理するトップレベルWebアプリケーション。 |
| iframe | エージェント生成HTMLをレンダリングするサンドボックス化された<iframe>要素。「サンドボックス」とも呼ばれる。 |
| ブートストラップドキュメント | iframeに読み込まれる完全なHTMLドキュメント。HTMX、SSE拡張、postMessageブリッジ、基本スタイルを含む。 |
| フラグメント | エージェントがSSEイベントとして送信するHTMLの個別単位。HTMXによってiframeのDOMにスワップされる。 |
| テーマ | ホストからiframeに注入されるCSSカスタムプロパティ（--hg-*）のセット。ホストのデザインシステムとの統合に使用。 |
| ブリッジ | iframeとホスト間のpostMessageベースの通信チャネル。テーマ、リサイズ、ナビゲーション、データ交換に使用。 |
適合レベル
本仕様はRFC 2119のキーワードを使用します:
- しなければならない (MUST) / してはならない (MUST NOT) — 絶対的な要件。不適合は実装が適合していないことを意味する。
- すべきである (SHOULD) / すべきでない (SHOULD NOT) — 強い推奨。逸脱には文書化された理由が必要。
- してもよい (MAY) — 完全にオプション。実装は含めても省いてもよい。
仕様セクション
| セクション | 定義内容 |
|---|---|
| SSEメッセージフォーマット | HTMLフラグメントをストリーミングするためのServer-Sent Eventsワイヤーフォーマット。イベント名、キープアライブ、ストリームライフサイクル、必須ヘッダー。 |
| iframeブートストラップドキュメント | iframeに読み込まれる完全なHTMLドキュメント。必須要素、sandbox属性、CSP、HTMXバージョン要件。 |
| postMessageプロトコル | ホストとiframe間で交換されるすべてのメッセージタイプ。JSONシェイプ、オリジン検証、TypeScript型定義。 |
| CSS変数テーマ | --hg-* CSSカスタムプロパティ名前空間。必須および任意の変数、デフォルト、注入メカニズム。 |
| エージェント作成ガイドライン | エージェントがHTMLを生成する際のベストプラクティス。HTMX属性の使用、スタイリング、自己完結性、アクセシビリティ。 |
設計根拠
HyperGenのアーキテクチャの「なぜ」はアーキテクチャ決定記録に文書化されています:
- ADR-001 — HTMLがプロトコルである理由
- ADR-002 — 仕様 + リファレンス実装としてのスコープ
- ADR-003 — インタラクティビティにHTMXを選んだ理由
- ADR-004 — サンドボックス化されたiframeセキュリティモデル
- ADR-005 — カスタムHTMX属性ゼロ
本仕様は「何を」を定義します。ADRは「なぜ」を説明します。
バージョニング
これはHyperGenプロトコル仕様のバージョン0.1です。プロトコルは活発に開発中です。バージョン1.0以前は破壊的変更の可能性があります。