ai-agent-ui-support

AI Agent 界面支持

为现有 Web 应用添加可复用的 AI Agent 界面。

Agent 应作为应用的一项辅助能力。除非 Agent 集成确有需要，否则应保留应用现有的导航、布局、工作流、设计系统、状态管理和业务界面。

在实际可行时，实现应与提供商无关。可以使用 Gemini、OpenAI、Anthropic、本地模型或其他支持 Agent 的 API。

应通过能力检测来提供特定于提供商的功能，而不是基于硬编码的假设。

---

1. 将 Agent 聊天视图接入 Web 应用

Agent 聊天视图必须提供：

1. 聊天视图
2. 文本输入
3. 用户 / Agent 消息气泡
4. Markdown 显示支持
5. 快捷回复 / 后续操作
6. Agent 加载状态
7. Agent 活动状态
8. 会话管理
9. 长任务支持
10. 任务管理面板
11. 多文件输入
12. 照片和相机输入
13. 语音转文本输入
14. 工具 / 函数调用活动显示
15. RWD 支持

聊天视图必须作为可复用功能实现，可集成到不同的 Web 应用中，而无需让应用本身变成以 Agent 为中心。

---

2. 消息视图

使用消息气泡进行对话。

Agent Bubble                        

                         User Bubble

要求：

• 用户气泡右对齐。
• Agent 气泡左对齐。
• Agent 气泡支持 Markdown。
• 长回复应保持易读。
• 代码块应正确呈现。
• 表格应支持响应式显示或水平滚动。
• 链接应可点击。
• 错误应与正常的 Agent 回复清楚区分。
• 工具执行结果可以结构化内容呈现。
• 用户发送的附件应与对应消息一同显示。

Markdown 至少应支持：

• 标题
• 粗体
• 斜体
• 有序列表
• 无序列表
• 行内代码
• 代码块
• 表格
• 引用
• 分隔线
• 链接

当 Agent 提供预定义的后续操作时，应在 Agent 消息下方显示快捷回复 / 后续操作按钮。

示例：

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

快捷回复必须对应实际可执行的操作。

---

3. 聊天滚动行为

收到新消息时：

• 如果用户当前已接近底部，则自动滚动到最新消息。
• 如果用户正在阅读之前的消息，则不要强制滚动。
• 加载较早的消息或历史记录时，保留用户当前的阅读位置。
• Agent 活动发生变化时也应遵循相同规则。

---

4. 多文件输入

支持在一条消息中输入多个文件。

Agent 界面应支持当前所选提供商和模型接受的所有文件类型。

可能的格式包括：

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

不要将支持的格式列表硬编码为唯一事实来源。

实际支持情况必须根据以下因素确定：

• 当前提供商
• 当前模型
• API 能力
• 文件大小限制
• 附件数量限制

界面必须支持：

• 多选文件
• 在一条消息中发送多个文件
• 显示文件名
• 显示文件类型
• 在有用时显示文件大小
• 上传进度
• 上传加载状态
• 移除单个附件
• 不支持的格式错误
• 文件过大错误
• 上传失败和重试

在实际可行时，发送前应预览附件。

---

5. 照片输入

支持通过以下方式输入图像：

Upload Photo
Capture with Camera

支持所选提供商 / 模型接受的所有图像格式，例如：

jpg
jpeg
png
webp
and other supported image formats

支持：

• 上传单张图像
• 上传多张图像
• 图像预览
• 发送前移除图像
• 相机拍摄
• 相机权限处理
• 上传失败
• 不支持的格式
• 不支持的模型能力

只有在当前浏览器 / 设备支持时，才应显示相机拍摄功能。

---

6. 语音转文本输入

语音转文本用于向常规聊天输入框输入文本。

这并不代表实时语音对话。

所需流程如下：

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

要求：

• 点击 [MIC] 开始录音。
• 录音必须持续进行，直到用户明确停止。
• 不得因静音而自动停止录音。
• 再次点击麦克风控件，或点击明确的“停止”控件，即可停止录音。
• 显示明显的录音状态。
• 条件允许时，显示已录制时间。
• 停止录音后，显示转录加载状态。
• 将录制的音频转换为文本。
• 将结果插入聊天输入框。
• 不要自动发送转录结果。
• 用户必须能够在发送前编辑转录文本。

处理以下情况：

• 麦克风权限被拒绝
• 取消录音
• 浏览器不受支持
• 提供方／模型不受支持
• 转录错误
• 重试

语音转文本不得影响常规文本输入行为。

---

7. 文本输入行为

文本输入必须支持：

• 单行输入
• 多行输入
• 适当时自动扩展输入框高度
• 按 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. 聊天视图响应式网页设计（RWD）

Agent 界面必须支持响应式网页设计。

主要的响应模式如下：

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. 桌面窄屏布局

在可用宽度较窄的桌面设备上，Agent 关闭时应在右下角显示为浮动操作按钮（FAB）。

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

用户可以打开或关闭聊天视图。

打开后，显示浮动 Agent 窗口。

Agent 窗口应：

• 始终显示在主应用上方。
• 尽可能避免遮挡应用的关键控件。
• 支持调整大小。
• 支持关闭。
• 关闭后保留当前会话。

---

10. 桌面宽屏布局

在可用宽度较宽的桌面设备上：

聊天视图打开时，将其显示为右侧全高面板。

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

要求：

• Agent 面板位于右侧。
• Agent 面板占用全部可用高度。
• 主应用占用剩余宽度。
• 主应用内容不得被 Agent 遮挡。
• Agent 面板必须可关闭。
• 关闭 Agent 后，恢复为紧凑／FAB 状态。
• 调整大小时，可以在浮动和停靠显示模式之间切换。

---

11. 移动端布局

关闭时：

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

在右下角显示 Agent 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. Agent 加载与活动状态

Chat View 必须在对话末尾附近包含一个常驻的 Agent 活动区域。

该区域必须动态描述 Agent 当前正在执行的操作。

最低限度的状态：

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

忙碌时：

• 显示已用秒数。
• 持续更新已用时间。
• 显示当前处理阶段。
• 如果有可用信息，则显示便于理解的 Tool／Task 名称。

空闲时：

• 以弱化的状态持续显示活动指示器。

不要为每次临时活动状态更新创建永久聊天消息。

如果用户靠近底部，活动状态变化时可以自动滚动到相应位置。

如果用户正在查看较早的消息，不要强制滚动。

---

19. Session 管理

Agent 必须支持 Session 管理。

必需功能：

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

每个 Session 应支持：

• 自动生成的标题
• 手动重命名
• 创建时间
• 上次更新时间
• 对话历史
• 必要时保存附件元数据
• 必要时保存相关的 Agent 上下文元数据

Session 历史示例：

Chat History

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

Generate monthly report
09:18

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

打开 Session 时恢复其对话。

关闭并重新打开 Agent 后，必须保留当前 Session。

开始 [New Chat] 时创建一个新的 Session。

Session 持久化可以使用应用现有的存储架构。

可能的存储方式包括：

• localStorage
• IndexedDB
• 服务端数据库
• 现有应用持久化层

如果宿主应用已经提供持久化架构，不要强行改用其他架构。

---

20. 长任务支持

Agent 必须支持不适合通过单个过长回答处理的漫长或复杂任务。

示例：

• 大型研究任务
• 多来源研究
• 大规模数据处理
• 长篇报告生成
• 涉及大量 Tool 调用的任务
• 多步骤应用操作
• 预计会超出单次响应的实际上下文／输出长度限制的任务

Agent 应能够将请求拆分为有序的子任务。

是否拆分任务应由 Agent／模型根据复杂程度和范围决定。

不要使用前端关键词匹配来判断是否属于长任务。

不得将简单问题不必要地转换为任务计划。

---

21. 长任务规划

提供内部的长任务规划机制，例如：

planLongTasks

如有需要，实现名称可以根据 Agent 框架而异，但必须具备相应功能。

任务计划包含：

Objective
Task 1
Task 2
Task 3
...

除非应用另有要求，合理的默认子任务上限约为 10 个。

每个子任务都应有独立且明确的范围。

每次任务执行都应接收：

• 总体目标
• 当前子任务
• 必要的前序任务结果
• 所需的运行时上下文
• 可用的 Tools

避免在每个子任务中反复传入不必要的完整聊天历史。

---

22. 长任务执行

长任务按顺序执行，或根据有效依赖关系执行。

每个子任务可以使用：

• 应用工具
• 函数调用
• 提供方内置工具
• Web 搜索
• 检索 / RAG
• 其他 Agent 能力

子任务失败不得自动终止其他不相关的剩余任务。

而应：

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. 快速回复和后续操作

Agent 可以为回复附加上下文相关的后续操作。

示例：

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

后续操作应根据以下内容生成：

• 工具结果
• 应用上下文
• 结构化 Agent 输出
• 明确的 UI 配置

按钮不得承诺无法执行的操作。

---

26. 聊天视图设置

Agent 必须提供设置面板。

所需的概念性设置布局为：

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 密钥 [Save]

API Key 字段必须有明确的 [Save] 按钮。

API KEY
[____________________________] [Save]

所需流程：

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

点击 [Save] 时：

1. 进入加载状态。
2. 针对所选提供方验证 API Key / 身份验证。
3. 确认提供方 API 可访问。
4. 显示成功或失败状态。
5. 仅在验证成功时保存配置。
6. 如果新密钥验证失败，则保留之前有效的配置。

可能的 UI 状态：

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

或

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

不得在以下情况下静默保存 API Key 更改：

• 失去焦点
• 字段更改
• 关闭设置面板

必须提供明确的 [Save] 操作。

保存的密钥不得完整显示。

生产环境中的凭据存储必须遵循宿主应用的安全模型。

---

28. 模型下拉列表 [Refresh]

主模型选择器必须有明确的 [Refresh] 按钮。

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

自动刷新不得移除手动 [Refresh] 按钮。

模型保留

刷新后：

• 如果当前模型仍然可用，则保持选中状态。
• 如果模型已不可用，则选择或请求一个有效的替代模型。
• 清楚显示模型列表加载错误。

---

29. 其他模型下拉列表

当不同的 Agent 能力需要使用不同模型时，应支持额外的模型选择器。

示例：

Chat Model
[Model ▼] [Refresh]

Speech-to-Text Model
[Model ▼]

Realtime Voice Model
[Model ▼]

Embedding Model
[Model ▼]

Vision Model
[Model ▼]

仅显示与当前提供方和已启用能力相关的其他模型选择器。

如果一个模型能够处理所有所需能力，则不要创建不必要的选择器。

身份验证发生变化时，应按需刷新依赖的模型列表。

---

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

对于其他提供方，显示对应的提供方原生功能。

列表必须由实际功能驱动。

不要显示不受支持的提供方工具。

提供方原生工具与应用自定义工具 / 函数调用是不同的概念。

---

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

因此，Agent UI 应对身份验证和模型变更作出响应，而不是将设置视为互不相关的静态字段。

---

34. 功能检测

Agent 控件必须反映提供方、模型和浏览器的实际功能。

可能的功能包括：

• 文本
• 流式传输
• 文件输入
• 图像输入
• 摄像头输入
• 语音转文本
• 实时语音
• 工具使用
• 函数调用
• 网页搜索
• 文件搜索
• 检索
• 代码执行
• 结构化输出
• 其他提供方原生功能

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. 工具 / 函数调用集成

在开发过程中，检查现有应用，并确定应向 Agent 暴露哪些函数作为工具 / 函数调用。

如果应用具备实用的可执行功能，Agent 应能做的不只是回答问题。

在以下情况下，如果 Agent 需要执行操作，请推荐或实现相应工具：

• 读取应用数据
• 搜索应用记录
• 获取当前应用状态
• 创建数据
• 更新数据
• 删除数据
• 生成报告
• 保存生成的结果
• 导航到特定的应用状态
• 执行现有应用操作
• 协调多项应用操作
• 执行多步骤工作流
• 运行 RAG 或内部搜索
• 通过应用触发外部服务

---

36. 不要用聊天取代简单 UI

不要将所有现有应用功能都转换为 Agent 交互。

对于以下操作，优先使用现有的传统 UI：

• 简单
• 可预测
• 高频
• 使用按钮更方便
• 使用表单更方便
• 使用菜单更方便
• 直接操作更方便

对于涉及以下内容的操作，优先使用 Agent / 工具交互：

• 自然语言意图
• 模糊请求
• 跨功能工作流
• 多步骤工作
• 数据汇总
• 依赖上下文的操作
• 复杂搜索
• 重复的管理工作流

Agent 是现有应用 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

当 Agent 调用工具时，Agent 活动区域必须反映相应操作。

示例：

⚙ Searching inventory...

而不是只显示：

running searchProducts()

使用易于理解的活动标签。

如果发生多轮工具调用，UI 应继续更新同一个 Agent 活动区域，而不是生成过多系统消息。

---

39. 工具执行完整性

除非实际工具处理程序返回成功，否则 Agent 不得声称应用操作已成功。

必需流程：

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

对于更改状态的操作，实际应用状态才是事实依据。

不要通过 Agent 文本模拟成功。

40. 应用上下文

需要时，向 Agent 提供相关的当前应用上下文。

可能的上下文包括：

• 当前路由
• 当前页面
• 当前选中项
• 当前筛选条件
• 当前表单状态
• 可见记录
• 当前用户权限
• 可用操作
• 相关业务状态

不要仅仅因为应用数据存在，就发送无关数据。

---

41. 架构分离

保持 Agent 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

层	职责
Agent 组件	视觉呈现（消息列表、气泡、标题栏、输入区、FAB、设置 UI）
Agent 状态	交互行为（处理 IME 监听器、输入区高度、状态映射、文件选择处理程序）
Agent 提供方服务	模型和 API 通信
工具服务	工具注册与执行
存储库 / 持久化	会话和设置持久化
提供方适配器	提供方专属的能力映射

复用宿主应用现有的：

• 组件系统
• 状态管理
• 样式
• 路由
• 持久化
• API 架构

不要仅仅为了支持 Agent 而引入新的应用框架。

---

42. 最低验收标准

只有以下所有适用要求均通过后，Agent UI 才算完成。

聊天 UI

• 聊天视图可以打开和关闭。
• 桌面端窄屏布局支持右下角 FAB。
• 桌面端宽屏布局支持右侧全高面板。
• 移动端打开状态支持全屏 / 近全屏聊天视图。
• 消息气泡布局正常。
• Markdown 正确渲染。
• 快捷回复正常工作。
• Agent 加载状态可见。
• Agent 活动状态可见。

输入

• 保留 [+] ___input___ [MIC][SEND] 交互。
• 文本输入支持多行。
• 按 Enter 发送。
• 按 Shift + Enter 换行。
• IME 组合输入不会意外触发发送。
• 可以选择多个文件。
• 可以单独移除多个附件。
• 可以上传照片。
• 支持时可以使用相机拍摄。

语音转文本

• [MIC] 开始录音。
• 录音不会自动停止。
• 用户手动停止录音。
• 显示转录加载状态。
• 转录内容返回到可编辑的聊天输入框。
• 不会自动发送转录内容。

会话

• [New Chat] 创建新会话。
• 可以打开会话历史记录。
• 可以切换历史会话。
• 可以重命名会话。
• 可以删除会话。
• 可以自动生成会话标题。
• 保留创建 / 更新时间。
• 关闭 Agent 后保留当前会话。

长任务

• Agent 能判断请求是否应成为长任务。
• 长任务可以拆分为子任务。
• 不会不必要地拆分简单请求。
• 单个任务失败不会自动中止无关任务。
• 执行后汇总最终结果。

任务管理面板

• 显示总体状态。
• 显示 Completed / Total。
• 显示进度条。
• 显示 Pending / Running / Done / Failed 状态。
• 可以为已完成任务显示摘要。
• 面板支持折叠 / 展开。
• 折叠状态下仍显示状态、数量和进度。

Agent 活动

• 存在空闲状态。
• 存在思考状态。
• 存在工具运行状态。
• 存在长任务状态。
• 忙碌状态显示已用时间。
• 工具 / 任务活动使用易读的名称。
• 活动更新不会污染永久聊天历史。
• 自动滚动不会影响用户阅读较早的消息。

设置

必须提供以下明确的控件：

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] 手动刷新模型列表。
• 如果支持提供方发现，模型列表应动态更新。
• 在需要时显示其他模型列表。
• 模型专属设置应反映当前能力。
• 系统提示词可编辑。
• 如果提供方提供内置工具，则可对其进行配置。

工具

• 识别适合 Agent 交互的应用程序功能。
• 将相关功能作为工具／函数调用提供。
• 工具执行使用实际的应用程序处理程序。
• 清晰显示工具错误。
• Agent 不得谎称工具执行成功。
• 在可行的情况下，聊天、长任务和其他 Agent 交互模式应复用相同的工具处理程序。

---

43. 核心设计原则

最终体验应当是：

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

而不是：

Chatbot replacing the entire application

Agent 应易于发现、易于打开、易于关闭，能感知应用程序当前的上下文，能够通过真正的工具操作应用程序，并且在工作耗时超过正常对话轮次时，能够清楚地显示当前状态。