ai-agent-ui-support

AI エージェント UI サポート

既存の Web アプリケーションに、再利用可能な AI エージェントインターフェースを追加します。

エージェントは、アプリケーションを支援する機能として動作させてください。エージェントとの連携に必要な変更を除き、アプリケーション既存のナビゲーション、レイアウト、ワークフロー、デザインシステム、状態管理、ビジネス UI は維持してください。

実用上可能な限り、プロバイダーに依存しない実装にしてください。Gemini、OpenAI、Anthropic、ローカルモデル、その他のエージェント対応 API を使用できます。

プロバイダー固有の機能は、ハードコードされた前提ではなく、機能検出を通じて提供してください。

---

1. エージェントチャットビューを Web アプリケーションに追加する

エージェントチャットビューには、以下の機能が必要です。

1. チャットビュー
2. テキスト入力
3. ユーザー／エージェントのメッセージバブル
4. Markdown 表示のサポート
5. クイック返信／フォローアップアクション
6. エージェントの読み込み状態
7. エージェントのアクティビティ状態
8. セッション管理
9. 長時間タスクのサポート
10. タスク管理パネル
11. 複数ファイル入力
12. 写真およびカメラ入力
13. 音声からテキストへの入力
14. ツール／関数呼び出しのアクティビティ表示
15. レスポンシブ Web デザイン（RWD）のサポート

チャットビューは、アプリケーション自体をエージェント中心にすることなく、さまざまな Web アプリケーションに統合できる再利用可能な機能として実装してください。

---

2. メッセージビュー

会話にはメッセージバブルを使用してください。

Agent Bubble                        

                         User Bubble

要件：

• ユーザーバブルは右揃えにします。
• エージェントバブルは左揃えにします。
• エージェントバブルは Markdown をサポートします。
• 長い回答も読みやすく保ちます。
• コードブロックを正しく表示します。
• テーブルはレスポンシブ表示または横スクロールに対応させます。
• リンクはクリックできるようにします。
• エラーは通常のエージェント回答と明確に区別します。
• ツール実行結果は、構造化コンテンツとして表示できます。
• ユーザーが送信した添付ファイルは、対応するメッセージとともに表示し続けます。

Markdown は、少なくとも以下をサポートしてください。

• 見出し
• 太字
• 斜体
• 番号付きリスト
• 箇条書き
• インラインコード
• コードブロック
• テーブル
• 引用
• 区切り線
• リンク

エージェントが次に実行可能なアクションをあらかじめ提示している場合は、エージェントのメッセージの下にクイック返信／フォローアップボタンを表示してください。

例：

[Continue]
[View Details]
[Generate Report]
[Open Record]
[Retry]

クイック返信は、実際に実行できるアクションに対応していなければなりません。

---

3. チャットのスクロール動作

新しいメッセージが届いたとき：

• ユーザーがすでに下部付近にいる場合は、最新のメッセージまで自動スクロールします。
• ユーザーが過去のメッセージを読んでいる場合は、強制的にスクロールしないでください。
• 古いメッセージや履歴を読み込む際は、ユーザーの現在の閲覧位置を維持してください。
• エージェントのアクティビティが変化した場合も、同じルールに従ってください。

---

4. 複数ファイル入力

1 件のメッセージで複数のファイルを入力できるようにしてください。

エージェント UI は、現在選択されているプロバイダーとモデルが受け付けるすべてのファイル形式をサポートする必要があります。

対応形式の例：

txt
csv
pdf
xlsx
docx
ppt
pptx
json
md
and other provider-supported formats

サポート対象の形式一覧を、唯一の判断基準としてハードコードしないでください。

実際のサポート状況は、以下に基づいて判断する必要があります。

• 現在のプロバイダー
• 現在のモデル
• API の機能
• ファイルサイズの制限
• 添付ファイル数の制限

UI は以下をサポートする必要があります。

• 複数ファイルの選択
• 1 件のメッセージへの複数ファイルの添付
• ファイル名の表示
• ファイル形式の表示
• 必要に応じたファイルサイズの表示
• アップロードの進行状況
• アップロード中の状態
• 添付ファイルを個別に削除する機能
• 非対応形式のエラー
• ファイルサイズ超過のエラー
• アップロード失敗時の再試行

実用上可能な場合は、送信前に添付ファイルをプレビューできるようにしてください。

---

5. 写真入力

以下を通じた画像入力をサポートしてください。

Upload Photo
Capture with Camera

選択されているプロバイダー／モデルが受け付けるすべての画像形式をサポートしてください。例：

jpg
jpeg
png
webp
and other supported image formats

以下をサポートしてください。

• 画像のアップロード（1 枚）
• 画像のアップロード（複数枚）
• 画像プレビュー
• 送信前の画像削除
• カメラ撮影
• カメラの権限処理
• アップロード失敗
• 非対応形式
• モデルの機能が非対応の場合の処理

カメラ撮影は、現在のブラウザー／デバイスが対応している場合にのみ表示してください。

---

6. 音声からテキストへの入力

音声からテキストへの変換は、通常のチャット入力にテキストを入力する方法として使用します。

リアルタイムの音声会話が自動的に行われるわけではありません。

必要なフローは次のとおりです。

[MIC]
  ↓
Start Recording
  ↓
Recording...
  ↓
User manually stops recording
  ↓
Transcribing...
  ↓
Text inserted into Chat Input
  ↓
User reviews / edits
  ↓
[SEND]

要件：

• [MIC] をクリックして録音を開始します。
• ユーザーが明示的に停止するまで、録音を継続する必要があります。
• 無音を理由に録音を自動停止しないでください。
• マイクのコントロールをもう一度クリックするか、明示的な停止コントロールを使用して停止します。
• 録音中であることが明確にわかる状態を表示します。
• 可能な場合は、録音の経過時間を表示します。
• 録音停止後、文字起こしの読み込み状態を表示します。
• 録音した音声をテキストに変換します。
• 結果をチャット入力に挿入します。
• 文字起こし結果を自動的に送信しないでください。
• ユーザーが送信前に文字起こしを編集できるようにします。

次の状況に対応します：

• マイクの使用許可が拒否された
• 録音がキャンセルされた
• ブラウザーがサポートされていない
• プロバイダー／モデルがサポートされていない
• 文字起こしエラー
• 再試行

音声からテキストへの変換によって、通常のテキスト入力の動作が損なわれないようにしてください。

---

7. テキスト入力の動作

テキスト入力は、次の機能に対応する必要があります。

• 1 行入力
• 複数行入力
• 必要に応じた入力欄の高さの自動拡張
• Enter で送信
• Shift + Enter で改行
• 中国語 IME
• その他の入力変換方式を使用する IME
• プレースホルダー
• 送信中の状態
• エラーからの復旧
• 同じメッセージ内でのテキストと添付ファイル

IME の変換中に Enter を押しても、誤ってメッセージが送信されないようにしてください。

// Example: Composition & Keydown Handling
let isComposing = false;

inputElement.addEventListener('compositionstart', () => {
  isComposing = true;
});

inputElement.addEventListener('compositionend', () => {
  isComposing = false;
});

inputElement.addEventListener('keydown', (e) => {
  if (e.key === 'Enter') {
    // If composing in IME or composition keycode is active, do not submit
    if (isComposing || e.isComposing || e.keyCode === 229) {
      return;
    }
  
    // Send message on Enter, allow line breaks on Shift+Enter
    if (!e.shiftKey) {
      e.preventDefault();
      if (isValidMessage()) {
        sendMessage();
      }
    }
  }
});

---

8. チャットビューのレスポンシブ Web デザイン

エージェントのインターフェースは、レスポンシブ Web デザインに対応する必要があります。

主なレスポンシブ表示モードは次のとおりです。

Desktop Narrow
Desktop Wide
Mobile

graph TD
    A[Screen Size / Trigger] --> B{Screen Width}
    B -- "< 768px (Mobile)" --> C[Mobile Mode]
    B -- "768px - 1024px (Tablet / Desktop Compact)" --> D[Compact Float Window]
    B -- "> 1024px (Desktop Wide)" --> E[Wide Docked Panel]
  
    C --> C1[Full-Screen Panel / Slide-up Overlay]
    D --> D1[Floating Chat Bubble Overlay]
    E --> E1[Docked Right Side Panel / Reflows App Width]

---

9. デスクトップの狭いレイアウト

デスクトップで利用可能な幅が狭い場合、閉じているときはエージェントを右下にフローティングアクションボタンとして表示します。

┌──────────────────────────────┐
│                              │
│       Main Application       │
│                              │
│                         [AI] │
└──────────────────────────────┘

ユーザーはチャットビューを開いたり閉じたりできます。

開いたときは、フローティングエージェントウィンドウを表示します。

エージェントウィンドウは次の要件を満たす必要があります。

• メインアプリケーションより前面に表示されます。
• 可能な場合は、アプリケーションの重要なコントロールを覆わないようにします。
• サイズを変更できます。
• 閉じることができます。
• 閉じた後も現在のセッションを保持します。

---

10. デスクトップの広いレイアウト

デスクトップで利用可能な幅が広い場合、チャットビューを開くと、画面の高さ全体を使う右側のパネルとして表示します。

┌───────────────────────────────┬──────────────┐
│                               │              │
│                               │    Agent     │
│       Main Application        │    Chat      │
│                               │    View      │
│                               │              │
└───────────────────────────────┴──────────────┘

要件：

• エージェントパネルは右側に配置します。
• エージェントパネルは利用可能な高さ全体を使います。
• メインアプリケーションは残りの幅を使います。
• メインアプリケーションのコンテンツがエージェントの下に隠れないようにします。
• エージェントパネルは閉じられる状態を維持します。
• エージェントを閉じると、コンパクト／FAB 状態に戻ります。
• サイズ変更によって、フローティング表示とドッキング表示を切り替えられるようにしてもかまいません。

---

11. モバイルレイアウト

閉じているとき：

┌──────────────────┐
│                  │
│ Main Application │
│                  │
│             [AI] │
└──────────────────┘

エージェントの FAB を右下に表示します。

開いているとき：

┌──────────────────┐
│ Agent Toolbar    │
├──────────────────┤
│                  │
│                  │
│   Chat Messages  │
│                  │
│                  │
├──────────────────┤
│ Chat Input       │
└──────────────────┘

全画面または全画面に近いチャットビューを使用します。

次の項目に対応します。

• セーフエリアのインセット
• モバイルキーボード
• タッチターゲット
• カメラの使用許可
• マイクの使用許可
• 戻るナビゲーション
• 閉じる動作

---

12. チャットビューのレイアウト

チャットビューには次の要素が含まれます。

┌──────────────────────────────────────┐
│              Top Toolbar             │
├──────────────────────────────────────┤
│                                      │
│             Chat Messages            │
│                                      │
│                                      │
│           Agent Activity             │
├──────────────────────────────────────┤
│ [+]       ___input___    [MIC][SEND] │
└──────────────────────────────────────┘

全体的なレイアウトとコントロールの配置は、デスクトップとモバイルで認識しやすい一貫したものにしてください。

---

13. 上部ツールバー

上部ツールバーには次の機能が必要です。

[New Chat] [History] [Settings] [Resize] [Close]

必要な操作：

• 新しいチャット
• チャット履歴／セッション履歴
• 設定
• サイズ変更／ドッキング
• 閉じる

横幅が狭くなった場合は、優先度の低い操作をオーバーフロー／ドロップダウンメニューに移動してください。

例：

[New Chat]                  [⋮] [X]

[⋮]
 ├─ History
 ├─ Settings
 └─ Resize

スペースが限られていることだけを理由に、機能を削除しないでください。

---

14. 下部ツールバー

下部ツールバーは、次の概念的な構成を使用する必要があります。

[+]       ___input___       [MIC][SEND]

ホストアプリケーションのアクセシビリティ要件またはプラットフォーム上の制約が求める場合を除き、この操作モデルを無関係なレイアウトに置き換えないでください。

---

15. [+] 添付ファイルボタン

[+] はファイル／写真のインポートに使用します。

クリックしたときの操作には、次のようなものがあります。

[+]
 ├─ Upload File
 ├─ Upload Photo
 └─ Take Photo

要件：

• 複数ファイルを一度にインポートできるようにします。
• 複数の画像を一度にインポートできるようにします。
• 複数のインポート方法がある場合は、ドロップダウン／ポップオーバー／アクションメニューを表示します。
• サポートされていないインポート方法は非表示にします。
• 送信前に選択した添付ファイルを表示します。
• 添付ファイルを個別に削除できるようにします。

---

16. [MIC] ボタン

[MIC] は音声からテキストへの録音を開始します。

動作：

[MIC]
  ↓
Recording
  ↓
[STOP]
  ↓
Transcribing...
  ↓
Insert Text into Input

録音は自動的に停止してはいけません。

録音を終了するタイミングは、ユーザーが操作します。

文字起こしの結果は、次の場所に戻す必要があります。

___input___

これにより、ユーザーは [SEND] を押す前に誤りを修正できます。

---

17. [SEND] ボタン

[SEND] は現在のメッセージを送信します。

メッセージには次の内容を含めることができます。

• テキスト
• ファイル
• 画像
• プロバイダー／モデルがサポートする任意の組み合わせ

送信可能な有効な内容がない場合は、[SEND] を無効にしてください。

送信後は、送信中／読み込み中の状態を表示してください。

---

18. エージェントの読み込み状態とアクティビティ状態

チャットビューには、会話の末尾付近に常時表示されるエージェントアクティビティ領域を設ける必要があります。

エージェントが現在行っていることを動的に表示する必要があります。

最低限、次の状態を含めてください。

Idle
Thinking
Running Tool
Long Task
Live Voice

追加の状態として、次のようなものを含めることができます。

Uploading
Transcribing
Generating
Planning
Waiting for Tool
Consolidating
Error

表示例：

◌ Thinking... 8s

⚙ Running tool: Search products... 3s

◌ Running task 2/5:
  Compare available options... 18s

処理中の場合：

• 経過秒数を表示します。
• 経過時間を継続的に更新します。
• 現在の処理段階を表示します。
• 利用可能な場合は、人が理解できるツール名／タスク名を表示します。

アイドル状態の場合：

• アクティビティインジケーターを控えめな表示で維持します。

一時的なアクティビティ状態の更新ごとに、永続的なチャットメッセージを作成しないでください。

ユーザーが画面の下部付近にいる場合は、アクティビティの変化に応じて自動スクロールしてもかまいません。

ユーザーが過去のメッセージを読んでいる場合は、強制的にスクロールしないでください。

---

19. セッション管理

エージェントはセッション管理に対応する必要があります。

必要な機能：

New Session
Save Current Session
Session History
Switch Session
Delete Session
Rename Session

各セッションは、次の項目に対応する必要があります。

• 自動生成されるタイトル
• 手動での名前変更
• 作成日時
• 最終更新日時
• 会話履歴
• 必要に応じた添付ファイルのメタデータ
• 必要に応じたエージェント関連のコンテキストメタデータ

セッション履歴の例：

Chat History

Today
────────────────────────
Product inventory question
10:42

Generate monthly report
09:18

Yesterday
────────────────────────
Customer service analysis
16:20

セッションを開くと、その会話が復元されます。

エージェントを閉じて再度開いた場合も、現在のセッションを保持する必要があります。

[New Chat] を開始すると、新しいセッションが作成されます。

セッションの永続化には、アプリケーションの既存のストレージアーキテクチャを使用してもかまいません。

ストレージには、次のものを使用できます。

• localStorage
• IndexedDB
• サーバー側データベース
• 既存のアプリケーション永続化レイヤー

ホストアプリケーションがすでに永続化方式を提供している場合は、別のアーキテクチャを強制しないでください。

---

20. 長時間タスクのサポート

エージェントは、単一の過大な応答として処理すべきでない、長時間または複雑なタスクに対応する必要があります。

例：

• 大規模な調査タスク
• 複数の情報源を用いた調査
• 大規模なデータ処理
• 長文レポートの生成
• 多数のツール呼び出しを伴うタスク
• 複数の手順からなるアプリケーション操作
• 実用的な単一応答のコンテキスト／出力サイズを超えると予想されるタスク

エージェントは、リクエストを順序付けられたサブタスクに分割できる必要があります。

タスクを分割するかどうかは、複雑さと範囲に基づいてエージェント／モデルが判断する必要があります。

長時間タスクかどうかの判断に、フロントエンドでのキーワード照合を使用しないでください。

単純な質問を不必要にタスク計画に変換してはいけません。

---

21. 長時間タスクの計画

次のような内部の長時間タスク計画機能を用意してください。

planLongTasks

エージェントのフレームワーク上の要件により実装名を変更してもかまいませんが、この機能自体は必須です。

タスク計画には、次の内容を含めます。

Objective
Task 1
Task 2
Task 3
...

アプリケーションで別途要件がない限り、サブタスク数の妥当なデフォルト上限は約10件です。

各サブタスクは、個別に範囲が定められている必要があります。

各タスクの実行には、次の情報を渡します。

• 全体の目標
• 現在のサブタスク
• 必要な前のタスクの結果
• 必要な実行時コンテキスト
• 利用可能なツール

各サブタスクに不要な完全なチャット履歴を繰り返し送信することは避けてください。

---

22. 長時間タスクの実行

長時間タスクは、順次、または有効な依存関係に従って実行されます。

各サブタスクでは、次を使用できます。

• アプリケーションツール
• 関数呼び出し
• プロバイダー組み込みツール
• ウェブ検索
• 検索／RAG
• その他のエージェント機能

サブタスクが失敗しても、無関係な残りのタスクを自動的に終了してはなりません。

代わりに、次のようにします。

Task 1  ✓
Task 2  ✓
Task 3  ✕
Task 4  ✓

可能な場合は続行します。

すべてのタスクが終了したら、次のようにします。

1. 成功した結果を統合します。
2. 失敗したタスクや未完了のタスクを明確に示します。
3. 最終回答を作成します。
4. 最終回答をチャットビューに追加します。

---

23. タスク管理パネル

長時間タスクが存在する場合、チャットビューにタスク管理パネルを表示する必要があります。

例：

┌──────────────────────────────────┐
│ Research competitor products     │
│ Running              2 / 5       │
│ ████████░░░░░░░░ 40%             │
├──────────────────────────────────┤
│ ✓ Search available products      │
│ ✓ Collect pricing                │
│ ◌ Compare specifications         │
│ ○ Analyze differences            │
│ ○ Generate final report          │
└──────────────────────────────────┘

必須の全体状態：

Running
Consolidating
Completed
Partially Failed

各タスクには状態を表示する必要があります。

Pending
Running
Done
Failed

推奨される視覚的な対応付け：

○ Pending
◌ Running
✓ Done
✕ Failed

完了したタスクには、有用な場合、短い結果の要約を含めてください。

---

24. タスクパネルの折りたたみ／展開

タスク管理パネルは、次をサポートする必要があります。

[Collapse]
[Expand]

展開時：

Research competitor products
Running 2 / 5
████████░░░░░░ 40%

✓ Search products
✓ Collect prices
◌ Compare products
○ Analyze differences
○ Generate report

折りたたみ時：

Research competitor products
Running 2 / 5
████████░░░░░░ 40%

折りたたんだ状態でも、次の情報を保持します。

• 状態
• 完了数／合計数
• 進捗バー

完了後も、確認できるようにタスクパネルを保持します。

次の独立したユーザーリクエストまたはタスク計画が始まるときに、クリアしてもかまいません。

---

25. クイック返信とフォローアップアクション

エージェントは、応答にコンテキストに応じたフォローアップアクションを付加できます。

例：

[Continue]
[Retry]
[View Result]
[Open Page]
[Apply Changes]
[Generate Report]

フォローアップアクションは、次の情報から生成してください。

• ツールの結果
• アプリケーションのコンテキスト
• 構造化されたエージェント出力
• 明示的な UI 設定

利用できないアクションを実行できるとボタンで約束してはなりません。

---

26. チャットビューの設定

エージェントは設定パネルを提供する必要があります。

必須の概念的な設定レイアウトは次のとおりです。

API KEY
[____________________________] [Save]

Model
[Model Drop Down List        ] [Refresh]

Other Model
[Other Model Drop Down List  ]

Other Model Settings
[...]

System Prompt
[                              ]
[                              ]
[                              ]

Built-in Tools
[✓] Web / Google Search
[ ] Code Execution
[ ] Other Provider Tool

これらの明示的なアクションを抽象化してはなりません。

---

27. API KEY [保存]

API Key フィールドには、明示的な [保存] ボタンが必要です。

API KEY
[____________________________] [Save]

必須のフロー：

Enter API Key
      ↓
    [Save]
      ↓
Checking availability...
      ↓
 ┌───────────────┐
 │ Valid         │
 │ Invalid       │
 └───────────────┘

[保存] をクリックしたとき：

1. 読み込み状態にします。
2. 選択したプロバイダーに対して API Key／認証情報を検証します。
3. プロバイダー API に接続できることを確認します。
4. 成功または失敗を表示します。
5. 検証に成功した場合に限り、設定を保存します。
6. 新しいキーの検証に失敗した場合は、以前の有効な設定を保持します。

UI の状態の例：

API KEY
[****************************] [Save]
✓ Connected

または

API KEY
[____________________________] [Save]
✕ Invalid API Key

次のタイミングで API Key の変更を通知せずに保存してはなりません。

• フォーカスが外れたとき
• フィールドが変更されたとき
• 設定パネルを閉じたとき

明示的な [保存] アクションが必要です。

保存したシークレットを全体表示してはなりません。

本番環境の認証情報の保存は、ホストアプリケーションのセキュリティモデルに従う必要があります。

---

28. モデルのドロップダウンリスト [更新]

プライマリモデルのセレクターには、明示的な [更新] ボタンが必要です。

Model
[Model Drop Down List ▼] [Refresh]

モデルの検出にプロバイダー API が対応している場合、モデルリストはプロバイダーから動的に読み込む必要があります。

ハードコードされたモデル名だけに依存してはなりません。

必須の動作：

手動更新

最新のモデルリストを取得するには、次をクリックします。

[Refresh]

更新中：

Model
[Loading models...      ] [Refresh]

API Key の変更

新しい API Key の保存に成功した後：

API Key Changed
      ↓
Validate API Key
      ↓
Validation Success
      ↓
Automatically Refresh Model List

自動更新を行う場合も、手動の [更新] ボタンを削除してはなりません。

モデルの保持

更新後：

• 現在のモデルが引き続き利用可能な場合は、選択状態を維持します。
• モデルが利用できなくなった場合は、有効な代替モデルを選択するか、選択を求めます。
• モデルリストの読み込みエラーを明確に表示します。

---

29. その他のモデルのドロップダウンリスト

異なるエージェント機能で異なるモデルが必要な場合は、追加のモデルセレクターをサポートします。

例：

Chat Model
[Model ▼] [Refresh]

Speech-to-Text Model
[Model ▼]

Realtime Voice Model
[Model ▼]

Embedding Model
[Model ▼]

Vision Model
[Model ▼]

現在のプロバイダーと有効な機能に関連する追加モデルセレクターのみを表示します。

1 つのモデルですべての必須機能に対応できる場合は、不要なセレクターを作成しないでください。

認証情報が変更されたときは、必要に応じて依存するモデルリストを更新します。

---

30. その他のモデル設定

選択したモデル／プロバイダーがサポートするモデル設定を提供します。

設定の例：

Temperature
Maximum Output Tokens
Reasoning Level
Top P
Streaming
Structured Output
Voice
Response Modality
Other Provider-Specific Settings

実際にサポートされている設定のみを表示します。

選択したモデルが変更されたときは、モデル設定を更新します。

---

31. システムプロンプト

編集可能なシステムプロンプトフィールドを用意します。

System Prompt

┌──────────────────────────────────┐
│                                  │
│                                  │
│                                  │
└──────────────────────────────────┘

システムプロンプトの設定は、自動的に注入される実行時のアプリケーションコンテキストとは分けておく必要があります。

実装では、次のように組み合わせることができます。

Base Agent Instructions
+
User-configurable System Prompt
+
Runtime Application Context

ユーザーが現在のアプリケーションの状態を手動でシステムプロンプトにコピーする必要がないようにします。

---

32. 組み込みプロバイダーツール

サポートされているプロバイダー標準のツールを有効または無効にできるようにします。

例：

Built-in Tools

[✓] Google Search
[ ] Code Execution
[ ] File Search
[ ] URL Context

Gemini の場合、次のような機能が含まれることがあります。

Google Search
Code Execution
URL Context

その他のプロバイダーでは、同等のプロバイダー標準機能を表示します。

リストは機能に応じて決定する必要があります。

サポートされていないプロバイダーツールは表示しないでください。

プロバイダー標準のツールと、アプリケーションで定義するカスタムツール／Function Call は別の概念です。

---

33. 設定の依存関係フロー

設定を変更したら、依存する機能も自動的に更新する必要があります。

API KEY
  ↓
[Save]
  ↓
Validate
  ↓
Connected
  ↓
Refresh Models
  ↓
Select Model
  ↓
Detect Model Capabilities
  ↓
Refresh:
- Other Models
- Model Settings
- Built-in Tools
- File Support
- Image Support
- Speech Support
- Other Agent Capabilities

そのため、エージェント UI は設定を無関係な静的フィールドとして扱うのではなく、認証やモデルの変更に応じて反応する必要があります。

---

34. 機能の検出

エージェントのコントロールには、プロバイダー、モデル、ブラウザーで実際に利用できる機能を反映する必要があります。

利用可能な機能の例：

• テキスト
• ストリーミング
• ファイル入力
• 画像入力
• カメラ入力
• 音声認識
• リアルタイム音声
• ツールの使用
• Function Calling
• ウェブ検索
• ファイル検索
• 検索拡張
• コード実行
• 構造化出力
• その他のプロバイダー標準機能

interface ModelCapabilities {
  supportsStreaming: boolean;
  supportsImageInput: boolean;
  supportsFileInput: boolean; // CSV, PDF, XLSX, etc.
  supportsAudioInput: boolean;
  supportsRealtimeVoice: boolean;
  supportsToolUse: boolean;
  supportedFileExtensions: string[];
}

interface ProviderAdapter {
  getCapabilities(modelName: string): ModelCapabilities;
  generateContentStream(request: GenerateRequest): AsyncIterable<GenerateResponse>;
  executeTool(name: string, args: Record<string, any>): Promise<any>;
}

サポートされていない場合：

• 関連性がなければ、その機能を非表示にします。
• ユーザーが機能の存在を知っておくべき場合は、説明を添えて無効にします。
• 実用的であれば、代替動作を提供します。

---

35. ツール／Function Calling の統合

開発中に既存のアプリケーションを調査し、エージェントにツール／Function Call として公開するべき関数を特定します。

アプリケーションに実用的な実行機能がある場合、エージェントには質問に答える以上のことが期待されます。

エージェントが次の操作を行う必要がある場合は、ツールの追加を推奨するか、実装してください。

• アプリケーションのデータを読み取る
• アプリケーションのレコードを検索する
• 現在のアプリケーションの状態を取得する
• データを作成する
• データを更新する
• データを削除する
• レポートを生成する
• 生成した結果を保存する
• 特定のアプリケーション状態に移動する
• 既存のアプリケーション操作を実行する
• 複数のアプリケーション操作を調整する
• 複数ステップのワークフローを実行する
• RAG または内部検索を実行する
• アプリケーションを通じて外部サービスを呼び出す

---

36. シンプルな UI をチャットに置き換えない

既存のアプリケーション機能をすべてエージェントとの対話に置き換えないでください。

次のような操作では、既存の従来型 UI を優先します。

• シンプルな操作
• 予測しやすい操作
• 高頻度の操作
• ボタンのほうが簡単な操作
• フォームのほうが簡単な操作
• メニューのほうが簡単な操作
• 直接操作のほうが簡単な操作

次のような操作では、エージェント／ツールとの対話を優先します。

• 自然言語で意図を伝える操作
• 曖昧なリクエスト
• 複数の機能にまたがるワークフロー
• 複数ステップの作業
• データの集計
• コンテキストに応じて変わる操作
• 複雑な検索
• 繰り返し行う管理ワークフロー

エージェントは既存のアプリケーション UI を補完するものです。

アプリケーションの主要な操作モデルに取って代わるものではありません。

---

37. ツールの定義

アプリケーションの各ツールでは、次の項目を定義します。

name
description
parameters / input schema
return type / output schema
handler
error handling

推奨される追加メタデータ：

user-facing label
activity label
permission requirement
confirmation requirement

ツール名には通常、動詞を使用します。

例：

searchProducts
getProductDetails
createReport
updateTask
deleteItem
navigateToRecord
saveDocument

---

38. ツール実行 UI

エージェントがツールを呼び出したときは、エージェントのアクティビティに操作内容を反映する必要があります。

例：

⚙ Searching inventory...

次の内容だけを表示するのではなく、

running searchProducts()

人が理解しやすいアクティビティラベルを使用します。

ツール呼び出しが複数回行われる場合、過剰なシステムメッセージを生成せず、同じエージェントアクティビティ領域を更新し続ける必要があります。

---

39. ツール実行の完全性

実際のツールハンドラーが成功を返さない限り、エージェントはアプリケーションの操作が成功したと主張してはなりません。

必須のフロー：

Agent decides to execute action
        ↓
Call Tool
        ↓
Application handler executes
        ↓
Tool returns result
        ↓
Application state updates
        ↓
Agent reports confirmed result

状態を変更する操作では、実際のアプリケーションの状態を信頼できる唯一の情報源とします。

エージェントのテキストで成功を装わないでください。

40. アプリケーションコンテキスト

必要に応じて、現在のアプリケーションに関連するコンテキストをエージェントに提供します。

コンテキストには、以下のような情報が含まれます。

• 現在のルート
• 現在のページ
• 現在選択されている項目
• 現在のフィルター
• 現在のフォームの状態
• 表示されているレコード
• 現在のユーザー権限
• 利用可能なアクション
• 関連するビジネスの状態

存在するというだけの理由で、関連性のないアプリケーションデータを送信しないでください。

---

41. アーキテクチャの分離

エージェント UI は再利用可能にしてください。

推奨する責務の分離：

Agent Components
    ↓
Agent UI / interaction

Agent State
    ↓
Chat / Session / Task / Activity state

Agent Provider Service
    ↓
Model API communication

Tool Service
    ↓
Function registration and execution

Repository / Persistence
    ↓
Session and settings persistence

Provider Adapter
    ↓
Provider-specific capability mapping

レイヤー	責務
エージェントコンポーネント	視覚的な表示（視覚的なメッセージリスト、バブル、ヘッダー、入力欄、FAB、設定 UI）
エージェント状態	インタラクションの動作（IME リスナー、入力欄の高さ、状態のマッピング、ファイル選択ハンドラーを処理）
エージェントプロバイダーサービス	モデルおよび API との通信
ツールサービス	ツールの登録と実行
リポジトリ／永続化	セッションおよび設定の永続化
プロバイダーアダプター	プロバイダー固有の機能のマッピング

ホストアプリケーションにすでにある以下の要素を再利用します。

• コンポーネントシステム
• 状態管理
• スタイリング
• ルーティング
• 永続化
• API アーキテクチャ

エージェントをサポートすることだけを目的として、新しいアプリケーションフレームワークを導入しないでください。

---

42. 最低限の受け入れ基準

エージェント UI は、以下の該当する要件をすべて満たした場合にのみ完成です。

チャット UI

• チャットビューを開閉できる。
• デスクトップの狭いレイアウトでは、右下の FAB に対応している。
• デスクトップの広いレイアウトでは、右側の全高パネルに対応している。
• モバイルのオープン状態では、全画面／ほぼ全画面のチャットビューに対応している。
• メッセージバブルのレイアウトが機能する。
• Markdown が正しく表示される。
• クイック返信が機能する。
• エージェントの読み込み状態が表示される。
• エージェントのアクティビティが表示される。

入力

• [+] ___input___ [MIC][SEND] の操作が維持されている。
• テキスト入力は複数行に対応している。
• Enter で送信する。
• Shift + Enter で改行する。
• IME の変換中に誤って送信されない。
• 複数のファイルを選択できる。
• 複数の添付ファイルを個別に削除できる。
• 写真をアップロードできる。
• 対応している場合は、カメラ撮影が機能する。

音声からテキストへの変換

• [MIC] で録音を開始する。
• 録音が自動的に停止しない。
• ユーザーが手動で録音を停止する。
• 文字起こしの読み込み状態が表示される。
• 文字起こし結果が編集可能なチャット入力欄に戻る。
• 文字起こし結果が自動的に送信されない。

セッション

• [New Chat] で新しいセッションを作成する。
• セッション履歴を開ける。
• 過去のセッションに切り替えられる。
• セッション名を変更できる。
• セッションを削除できる。
• セッションタイトルを自動生成できる。
• 作成日時／更新日時が保持される。
• エージェントを閉じても現在のセッションが保持される。

長時間タスク

• エージェントが、リクエストを長時間タスクにするべきか判断できる。
• 長時間タスクをサブタスクに分割できる。
• 単純なリクエストを不必要に分割しない。
• 個別のタスクの失敗によって、無関係なタスクが自動的に中止されない。
• 実行後に最終結果を統合する。

タスク管理パネル

• 全体の状態が表示される。
• Completed / Total が表示される。
• 進行状況バーが表示される。
• Pending / Running / Done / Failed の各状態が表示される。
• 完了したタスクには要約を表示できる。
• パネルを折りたたみ／展開できる。
• 折りたたんだ状態でも、状態、件数、進行状況が表示される。

エージェントのアクティビティ

• 待機状態がある。
• 思考中状態がある。
• ツール実行中状態がある。
• 長時間タスクの状態がある。
• ビジー状態では経過時間が表示される。
• ツール／タスクのアクティビティには、わかりやすい名前が使われる。
• アクティビティの更新が、永続的なチャット履歴を汚さない。
• 自動スクロールによって、古いメッセージを読んでいるユーザーの操作を妨げない。

設定

以下の明示的なコントロールが必要です。

API KEY [Save]

Model Drop Down List [Refresh]

Other Model Drop Down Lists

Other Model Settings

System Prompt

Enable / Disable Built-in Tools

• [Save] は、新しい API Key を受け入れる前に API が利用可能かどうかを検証します。
• 無効なキーは、有効な認証情報として保存されたものと見なされません。
• API Key の変更に成功すると、モデルの選択肢が自動的に更新されます。
• [Refresh] はモデル一覧を手動で更新します。
• プロバイダーの検出機能がある場合、モデル一覧は動的に更新されます。
• 必要に応じて、他のモデル一覧も表示されます。
• モデル固有の設定には、現在の機能が反映されます。
• システムプロンプトを編集できます。
• プロバイダーが組み込みツールを公開している場合、それらを設定できます。

ツール

• エージェントとの対話に適したアプリケーション機能が特定されています。
• 関連する機能がツール／関数呼び出しとして公開されています。
• ツールの実行には、実際のアプリケーションハンドラーが使用されます。
• ツールのエラーが明確に表示されます。
• エージェントがツールの成功を誤って主張することはありません。
• チャット、長時間のタスク、その他のエージェント対話モードでは、可能な限り同じツールハンドラーを再利用します。

---

43. 中核となる設計原則

実現される操作感は、次のようなものです。

Existing Web Application
        +
Reusable AI Agent Assistance
        +
Application-aware Tools

次のようなものではありません。

Chatbot replacing the entire application

エージェントは見つけやすく、開きやすく、閉じやすいものであるべきです。また、アプリケーションの現在のコンテキストを把握し、実際のツールを通じてアプリケーションを操作でき、通常の会話の1ターンを超える作業では現在の状態を明確に示せるものであるべきです。