agent-ui-design

Agent-UI-Design

チャットインターフェース、エージェントの UX、ストリーミング UI、ツールの可視化に関するデザインパターンです。21st.dev Agents SDK と、数々の賞を受賞したエージェント製品を参考にしています。

対象範囲

以下の場合にこのスキルを使用します。

• AI アプリケーションのチャットインターフェースを設計する場合
• エージェントのツール呼び出しを視覚的に表現する必要がある場合
• リアルタイムのテキスト出力に対応するストリーミング表示を実装する場合
• サンドボックスの状態や実行環境を可視化する場合
• エージェントのダッシュボード向けに 3 パネルレイアウトを設計する場合

原則

1. エージェント対応の設計

コンポーネントは、ストリーミングコンテンツ、ツール呼び出し、非同期の状態遷移を標準でサポートする必要があります。チャット UI は付け足しではなく、中心的なパターンです。

2. 魔法より透明性を重視

システムが何をしているのか、ユーザーが常に把握できるようにする必要があります。バックグラウンドで黙って処理してはいけません。エージェントの各ステップをすべて可視化します。

3. 段階的な複雑さ

デフォルトの表示では重要な情報を示します。詳細（ツールのパラメーター、生データ、ログ）は、必要に応じて確認できるようにします。

4. 体験としてのストリーミング

リアルタイムのテキスト出力は技術的な詳細ではなく、意図的に設計する UX 要素です。テキストが表示される速度は、知的さの印象に影響します。

5. エラーを設計上のケースとして扱う

ツールのエラー、タイムアウト、予期しない結果は、例外ではなく通常の状態です。それぞれに専用のビジュアルデザインが必要です。

ルール

チャットの構成

• 必須：21st.dev のパターンに沿った 3 カラムのチャット構成にします。
  • スレッドサイドバー（左）：過去の会話を一覧表示します。スクロールと検索に対応させます。
  • チャットパネル（中央）：メッセージストリームと入力欄を配置します。主な操作領域です。
  • コンテキストパネル（右）：結果、プレビュー、フォーム用の任意のパネルです。
• 必須：メッセージ履歴を遅延読み込みします。最初は直近の N 件のみを読み込み、上方向にスクロールしたときに古いメッセージを読み込みます。
• 禁止：メッセージ履歴全体をクライアントの状態に保持しないでください。サーバーサイドで永続化します。
• 禁止：入力欄が見えないチャットパネルを作らないでください。どこに入力すればよいか、常に明確にする必要があります。

メッセージの種類

• 必須：役割ごとにメッセージを区別します。
  • ユーザーメッセージ：右揃え、アクセントカラー、コンパクトなレイアウトにします。
  • アシスタントメッセージ：左揃えでニュートラルなデザインにし、ツールの結果を展開できるようにします。
  • システムメッセージ：中央揃えで控えめにし、情報を伝えます。
  • ツール呼び出し：ステータスインジケーターを付け、視覚的に区別します。
• 必須：アシスタントメッセージでは Markdown（見出し、リスト、コードブロック）を表示します。
• 必須：コードブロックにはシンタックスハイライトとコピー ボタンを付けます。
• 禁止：すべてのメッセージを同じスタイルにしないでください。視覚的な区別によって、ユーザーが状況を把握しやすくなります。

ストリーミング表示

• 必須：カーソルインジケーターを表示しながら、テキストを文字単位または単語単位で表示します。
• 必須：リアルタイム表示には、AI SDK の useChat フックまたは SSE ストリーミングを使用します。
• 必須：ストリーミング中は自動で最下部までスクロールし、停止ボタンを表示します。
• 禁止：生成中に表示をブロックしないでください。ユーザーがいつでもスクロールできるようにします。
• 禁止：視覚的なカーソルなしでストリーミングしないでください。ユーザーが続きのテキストが表示されるとわかるようにします。

ツールの可視化

• 必須：チャットストリーム内にツール呼び出しを表示します。
  • ツール名：結果の前にラベルまたはバッジとして表示します。
  • 入力パラメーター：折りたたみ可能にし、上級ユーザーが確認できるようにします。
  • 結果：種類（テキスト、テーブル、コード、画像）に応じて整形します。
  • ステータス：読み込みスピナー ＞ 成功チェックマーク ＞ エラーアイコンの順に表示します。
• 必須：ツールの結果を、メッセージストリーム内に埋め込みカードとして表示します。
• 必須：エラー状態を明示し、何が問題だったのか、ユーザーが何をできるのかを伝えます。
• 禁止：視覚的なフィードバックなしでツールを呼び出さないでください。黙って実行してはいけません。
• 禁止：生の JSON 出力を表示しないでください。常に人が読みやすい形式に整えます。

サンドボックス UI

• DO: サンドボックスの状態を視覚的に伝えます。
  • Created: 環境の準備が整ったことを示すインジケーター。
  • Active: 緑色のステータスドット。
  • Executing: 進捗を示すアニメーション状態。
  • Terminated: 結果の概要を示す最終状態。
• DO: ファイルツリーは、ファイルプレビュー付きのインタラクティブなツリー構造にします。
• DON'T: デフォルトビューにサンドボックスの詳細を表示しません。段階的開示を使用します。

拡張ルールと例については、references/implementation.md を参照してください。

パターン

パターン	用途	基本的な考え方
ストリーミングチャットメッセージ	すべての AI チャットアプリ	SSE ストリーム、カーソル、Markdown レンダリング
ツール実行カード	エージェントがアクションを実行	バッジ＋折りたたみ可能なパラメーター＋ステータス
3 パネルレイアウト	エージェントダッシュボード	スレッド＋チャット＋コンテキスト
フォームとエージェントのハイブリッド	フォームアシスタント	フォーム＋チャット、エージェントがフィールドに入力
リアルタイムステータスダッシュボード	エージェントの監視	ライブ更新、色分けされたタイル

パターンの詳細については、references/patterns.md を参照してください。

アンチパターン

1. コンテキストパネルのないチャットボット -- 結果がチャット内にのみ表示されます。複雑な出力には専用のスペースが必要です。
2. JSON ダンプとしてのツール結果 -- 生の API レスポンスです。必ず人が読みやすい形式で表示します。
3. 見えないエージェントの作業 -- ツール実行中にフィードバックがありません。ユーザーはシステムがフリーズしたと思ってしまいます。
4. 単一メッセージデザイン -- すべてのメッセージが同じスタイルで表示されます。役割の区別は必須です。
5. 停止できない延々と続くストリーミング -- 生成中にキャンセルボタンがありません。
6. モーダルでのツール結果表示 -- ツールの出力をインラインではなくモーダルで表示します。会話の流れを妨げます。
7. 検索機能のないスレッドサイドバー -- 会話が 10 件を超えると、検索とフィルターが不可欠です。
8. 再試行オプションの欠如 -- ツールエラーが発生しても、再試行できません。

チェックリスト

• チャットメッセージが役割（ユーザー、アシスタント、システム、ツール）ごとに区別されている
• カーソルが見えるストリーミングレンダリングが実装されている
• 生成中に停止ボタンが表示される
• ツール呼び出しに読み込み／成功／エラー状態がある
• ツール結果が生の JSON 出力ではなく、整形されている
• ツールのパラメーターを折りたたみ可能な状態で確認できる
• 3 パネルレイアウト：スレッド＋チャット＋コンテキスト
• メッセージ履歴が遅延読み込みされる（すべてをクライアントに読み込まない）
• コードブロックにシンタックスハイライトとコピーボタンがある
• アシスタントメッセージで Markdown がレンダリングされる
• サンドボックスの状態が視覚的に伝わる
• ツールエラー時に再試行ボタンがある
• モバイル：チャットパネルは全画面表示、サイドバーはドロワー表示
• キーボードショートカット：Enter で送信、Shift+Enter で改行

関連項目

• component-patterns -- 基本的なコンポーネントアーキテクチャとトークンシステム
• design-trends -- 現在のトレンドとしての AI ネイティブインターフェース
• ui-patterns -- コマンドパレットと一般的な UI パターン
• visual-direction -- エージェントインターフェース向けのカラーパレットとタイポグラフィ
• usability -- チャットインターフェースのユーザビリティの基本
• accessibility -- チャット UI のスクリーンリーダー互換性
• responsive-design -- 3 パネルレイアウトのモバイル対応策