# Assistant-UI + LangGraph + FastAPI Web Chatbot

本项目成功集成了 assistant-ui 前端框架与基于 LangGraph + FastAPI 的后端服务，实现了流式 AI 对话界面，支持多步推理和工具调用。

## 项目架构

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   React Web    │    │   Next.js API    │    │  FastAPI+       │
│  (assistant-ui) │◄──►│   Route          │◄──►│  LangGraph      │
│                 │    │                  │    │  Backend        │
└─────────────────┘    └──────────────────┘    └─────────────────┘
       │                        │                        │
       ▼                        ▼                        ▼
   用户界面               API 代理/转发           AI Agent + 工具
 - Thread 组件          - /api/chat 路由        - 检索工具
 - Tool UI 显示         - Data Stream 协议      - 代码分析
 - 流式消息渲染         - 请求转发处理            - 多步推理
```

## 核心特性

### 1. 前端 (assistant-ui)

- **框架**: Next.js 15 + React 19 + TypeScript + Tailwind CSS v3
- **UI 库**: @assistant-ui/react, @assistant-ui/react-ui
- **协议**: Data Stream Protocol (SSE 流式通信)
- **组件**:
  - `Thread`: 主对话界面
  - 自定义 Tool UI: 文档检索、Web搜索、代码执行等
  - 响应式设计，支持明暗主题

### 2. 中间层 (Next.js API)

- **路由**: `/api/chat` - 转发请求到 FastAPI 后端
- **协议转换**: 确保 Data Stream Protocol 兼容性
- **headers**: 设置正确的 `x-vercel-ai-data-stream: v1` 头

### 3. 后端 (FastAPI + LangGraph)

- **框架**: FastAPI + LangGraph
- **协议**: AI SDK Data Stream Protocol
- **功能**:
  - 多步 AI 推理
  - 工具调用 (检索、搜索、代码分析等)
  - 会话状态管理
  - 流式响应

## 安装和配置

### 1. 后端服务

确保后端服务在端口 8000 运行:

```bash
cd /home/fl/code/ai-solution/agentic-rag-4
./start_service.sh
```

### 2. 前端应用

```bash
cd web
pnpm install
pnpm dev
```

访问: http://localhost:3000

## 技术实现细节

### Data Stream Protocol

实现了 AI SDK 标准的 Data Stream Protocol:

```
类型格式: TYPE_ID:CONTENT_JSON\n

支持的事件类型:
- 0: 文本流 (text)
- 2: 数据 (data)  
- 3: 错误 (error)
- 9: 工具调用 (tool call)
- a: 工具结果 (tool result)
- d: 消息完成 (finish message)
- e: 步骤完成 (finish step)
```

### 工具 UI 自定义

定义了多个工具的可视化组件:

1. **文档检索工具** (`retrieval`)
   - 显示检索到的文档
   - 相关度评分
   - 来源信息

2. **Web 搜索工具** (`web_search`)
   - 搜索结果列表
   - 链接和摘要
   - 执行时间

3. **代码执行工具** (`python`)
   - 代码高亮显示
   - stdout/stderr 输出
   - 执行状态

4. **URL 抓取工具** (`fetch_url`)
   - 页面标题和内容
   - 错误处理

### 流式集成

```typescript
// 前端运行时配置
const runtime = useDataStreamRuntime({
  api: "/api/chat",
});

// 后端事件转换
async function stream_ai_sdk_compatible(internal_stream) {
  for await (const event of internal_stream) {
    const converted = adapter.convert_event(event);
    if (converted) yield converted;
  }
}
```

## 文件结构

```
web/
├── src/
│   ├── app/
│   │   ├── page.tsx          # 主聊天界面
│   │   ├── globals.css       # 全局样式 + assistant-ui
│   │   ├── layout.tsx        # 布局配置
│   │   └── api/
│   │       └── chat/
│   │           └── route.ts  # API 路由代理
│   └── ...
├── tailwind.config.ts        # Tailwind + assistant-ui 插件
├── package.json             # 依赖配置
└── ...

service/
├── ai_sdk_adapter.py        # Data Stream Protocol 适配器
├── ai_sdk_chat.py          # AI SDK 兼容的聊天端点
├── main.py                 # FastAPI 应用入口
└── ...
```

## 使用指南

### 1. 启动对话

打开 http://localhost:3000，在输入框中输入问题，例如:
- "帮我搜索关于 Python 异步编程的资料"
- "分析一下这段代码的性能问题"
- "检索关于机器学习的文档"

### 2. 观察工具调用

AI 助手会根据问题自动调用相应工具:
- 文档检索会显示相关文档卡片
- Web 搜索会显示搜索结果列表
- 代码分析会显示执行过程和结果

### 3. 多步推理

助手支持复杂的多步推理流程，每个步骤都会实时显示进度。

## 开发和调试

### 查看后端日志

```bash
tail -f service.log
```

### 检查 Data Stream 协议

```bash
curl -N -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Hello"}],"session_id":"test"}' \
  http://localhost:8000/api/ai-sdk/chat
```

### 前端开发

```bash
cd web
pnpm dev
# 访问 http://localhost:3000
```

## 协议兼容性确认

✅ **Data Stream Protocol 兼容**
- 正确的事件格式: `TYPE_ID:JSON\n`
- 必需的 HTTP 头: `x-vercel-ai-data-stream: v1`
- 支持工具调用流式渲染
- 支持多步推理可视化

✅ **assistant-ui 集成**
- useDataStreamRuntime 正确配置
- Thread 组件正常渲染
- 自定义 Tool UI 正常显示
- 样式和主题配置正确

✅ **LangGraph + FastAPI 后端**
- 事件正确转换为 Data Stream Protocol
- 工具调用和结果正确传输
- 会话状态正确管理
- 错误处理和异常流处理

## 后续优化建议

1. **性能优化**
   - 实现消息缓存
   - 添加请求去重
   - 优化大文件传输

2. **功能扩展**
   - 添加更多工具 UI
   - 支持文件上传
   - 实现消息编辑和分支

3. **用户体验**
   - 添加加载状态指示
   - 实现消息重试机制
   - 支持键盘快捷键

4. **部署和监控**
   - 添加性能监控
   - 实现日志聚合
   - 配置生产环境部署

## 总结

本项目成功实现了 assistant-ui 与 LangGraph + FastAPI 的无缝集成，提供了完整的流式 AI 对话体验。通过标准的 Data Stream Protocol，确保了前后端的协议兼容性，同时通过自定义 Tool UI 提供了丰富的交互体验。整个架构具有良好的可扩展性和维护性，为进一步的功能开发和优化奠定了坚实基础。