[!info] related notes

• 所属 MOC: AI Agent Application MOC
• 子组件: Chat UI, Tool Call UI, Human Approval UI, Artifact UI
• 框架: [[assistant-ui|assistant-ui]], Vercel AI SDK UI

Agent Interaction UI

一句话定义

Agent Interaction UI 是 AI Agent 应用中所有用户交互界面的总称。它不只是一个聊天框，而是包含消息流、工具调用状态、审批弹窗、产物查看器、进度指示器和错误提示的完整交互系统。

它解决什么问题

传统聊天 UI 只需要处理文本消息的发送和接收。但 AI Agent 的交互复杂得多：

• Agent 在执行过程中需要实时反馈（正在搜索、正在分析）
• 高风险操作需要人类审批（确认删除、确认支付）
• Agent 生成的不只是文字，还有结构化产物（图表、代码、文件）
• 执行可能出错，需要错误恢复（重试、取消）
• 长时间执行需要进度指示（步骤数、预计时间）

核心原理

UI 组件全景

Agent Interaction UI
├── Chat UI (聊天界面)
│   ├── MessageList (消息列表)
│   ├── Composer (输入区)
│   └── ScrollAnchor (自动滚动)
├── Tool Call UI (工具调用状态)
│   ├── ToolCallCard (调用卡片)
│   └── ToolTimeline (执行时间线)
├── Approval UI (审批界面)
│   ├── ApprovalCard (审批卡片)
│   └── ParameterEditor (参数编辑)
├── Artifact UI (产物查看器)
│   ├── ChartViewer (图表)
│   ├── CodeViewer (代码)
│   ├── DataTable (表格)
│   └── FileViewer (文件)
├── Status UI (状态指示)
│   ├── StreamingIndicator (流式指示)
│   ├── ProgressIndicator (进度)
│   └── ErrorBoundary (错误边界)
└── Controls (控制)
    ├── StopButton (停止按钮)
    ├── RetryButton (重试按钮)
    └── RegenerateButton (重新生成)

交互状态机

idle → user_input → streaming → done
                              → tool_calling → streaming
                              → waiting_approval → streaming
                              → error → retry → streaming
                              → cancelled

典型工程实现

组件组合示例

function AgentChat() {
  const { messages, status, sendMessage, stop, retry } = useChat();

  return (
    <div className="agent-chat">
      <MessageList>
        {messages.map(msg => (
          <Message key={msg.id}>
            {msg.role === 'assistant' && msg.toolCalls?.map(tc => (
              <ToolCallCard key={tc.id} toolCall={tc} />
            ))}
            <TextContent content={msg.content} />
            {msg.artifacts?.map(a => (
              <ArtifactViewer key={a.id} artifact={a} />
            ))}
          </Message>
        ))}
      </MessageList>

      {status === 'streaming' && <StreamingIndicator />}
      {status === 'waiting_approval' && <ApprovalCard />}
      {status === 'error' && <ErrorBanner onRetry={retry} />}

      <Composer onSend={sendMessage}>
        {status === 'streaming' && <StopButton onClick={stop} />}
      </Composer>
    </div>
  );
}

常见设计模式

1. 渐进式披露

默认只显示摘要，用户点击展开详情。

2. 上下文感知

根据 Agent 当前状态动态显示/隐藏组件。

3. 响应式布局

桌面端左右分栏，移动端上下排列。

常见坑

1. 只做聊天框: 忽略了工具调用、审批、产物等交互需求
2. 状态不同步: UI 状态和 Agent 实际状态不一致
3. 不做错误边界: 一个组件崩溃导致整个界面不可用
4. 移动端适配差: 审批卡片、产物查看器在手机上显示不全

参考资料

• assistant-ui
• Vercel AI SDK UI
• AI Chat UI Design