ReACT 智能助手
一个基于 OpenAI Agents SDK 的智能助手系统，实现了 ReACT 推理模式（Reasoning and Acting），支持多轮工具调用、对话历史管理、流式响应、MCP 工具集成以及现代化的 Web 用户界面。
📋 目录
✨ 功能特性
核心功能
- 🧠 ReACT 推理模式
- 观察 (Observe)：仔细分析用户问题和当前可用信息 - 思考 (Think)：推理需要采取什么行动来解决问题 - 行动 (Act)：使用可用工具执行必要操作 - 记忆 (Memory)：记住之前的对话和操作结果
- 🔧 多轮工具调用
- 支持复杂任务的多步骤工具调用 - 自动整合多次工具调用的结果 - 智能决策何时需要继续调用工具
- 💾 对话历史管理
- 使用 Redis 存储对话历史 - 自动保存和加载对话历史 - 保持多次会话的上下文连续性 - 多会话管理：支持创建、切换、删除多个独立会话
- ⚡ 流式响应
- 实时输出生成内容 - 打字机效果的交互体验 - 降低首字节响应时间
- 🔌 自定义模型提供者
- 灵活配置 OpenAI 或兼容服务的 API - 支持自定义 base URL - 支持多种模型选择
- 🛠️ MCP 工具集成
- 支持 stdio 协议（标准输入输出） - 支持 SSE 协议（Server-Sent Events） - 支持 StreamableHTTP 协议 - 支持 SSE 和 StreamableHTTP 的超时配置 - 动态加载和管理工具服务器
- 🌐 Web 界面
- 现代化的 Web 用户界面（类似 ChatGPT） - 多会话管理（创建、切换、删除） - 实时流式响应展示 - 工具调用和输出的可视化 - WebSocket 实时通信 - Markdown 渲染：助手消息支持完整的 Markdown 格式渲染 - 标题、段落、列表等基本格式 - 代码块语法高亮（支持多种编程语言） - 表格、引用、链接等高级格式 - GitHub Flavored Markdown 支持 - 流式 Markdown 渲染（实时更新）
技术亮点
- ✅ 异步 IO 设计，高效处理并发操作
- ✅ 模块化架构，易于扩展和维护
- ✅ 完善的错误处理和资源清理机制
- ✅ 优雅的命令行交互界面
- ✅ 现代化的 Web 用户界面（React + TypeScript + Tailwind CSS）
- ✅ 完整的单元测试覆盖
- ✅ 类型注解和文档字符串
🛠️ 技术栈
后端
- Python 3.8+
- OpenAI Agents SDK - Agent 框架和工具集成
- FastAPI/WebSockets - WebSocket 服务器
- Redis - 会话存储（必需）
- Pydantic - 配置验证
- python-dotenv - 环境变量管理
前端
- React 18 - UI 框架
- TypeScript - 类型安全
- Tailwind CSS - 样式框架
- Vite - 构建工具
- react-markdown - Markdown 渲染
- remark-gfm - GitHub Flavored Markdown 支持
- react-syntax-highlighter - 代码块语法高亮
🏗️ 系统架构
┌─────────────────────────────────────────────────────────────┐
│ 用户交互层 │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ 命令行界面 CLI │ │ Web 界面 │ │
│ │ (main.py) │ │ (React + TS) │ │
│ └──────────────────┘ └──────────────────┘ │
└────────────────────────┬───────────────────────────────────┘
│
┌───────────────┼───────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ WebSocket │ │ CLI 接口 │ │ Web API │
│ 服务器 │ │ │ │ (web_api) │
└─────────────┘ └─────────────┘ └─────────────┘
│ │ │
└───────────────┼───────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Agent 核心层 │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ ReACT 推理 │ │ 工具调用 │ │ 流式输出 │ │
│ │ 引擎 │ │ 管理器 │ │ 处理器 │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└────────────────────────┬────────────────────────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 模型提供者 │ │ 会话管理 │ │ MCP 工具集成│
│ (Custom │ │ (Redis) │ │ (stdio/sse/ │
│ Provider) │ │ │ │ http) │
└─────────────┘ └─────────────┘ └─────────────┘
│ │ │
└───────────────┼───────────────┘
▼
┌─────────────────────────────────────────────────────────────┐
│ 配置管理层 │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ .env 配置 │ │ mcp_config │ │
│ │ 加载器 │ │ .json 加载器 │ │
│ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘🚀 快速开始
环境要求
- Python 3.8+
- Redis（必需，用于会话存储）
- Node.js 16+（仅 Web 界面需要）
- npm 或 yarn（仅 Web 界面需要）
安装步骤
- 克隆项目
git clone
cd react-agent-assistant- 安装和启动 Redis
# Windows (使用 Chocolatey)
choco install redis-64
# macOS (使用 Homebrew)
brew install redis
brew services start redis
# Linux (Ubuntu/Debian)
sudo apt-get install redis-server
sudo systemctl start redis-server
# 验证 Redis 是否运行
redis-cli ping
# 应该返回: PONG- 安装后端依赖
# 创建虚拟环境（推荐）
python -m venv .venv
# 激活虚拟环境
# Windows:
.venv\Scripts\activate
# Linux/Mac:
source .venv/bin/activate
# 安装依赖
pip install -r requirements.txt- 安装前端依赖（仅 Web 界面需要）
cd web
npm install
cd ..- 配置环境变量
# 复制示例配置文件
cp .env.example .env
# 编辑 .env 文件，设置您的 API 密钥和配置- 配置 MCP 工具（可选）
# 复制示例配置文件
cp mcp_config.example.json mcp_config.json
# 编辑 mcp_config.json，配置您的 MCP 服务器运行程序
方式一：命令行界面（CLI）
python main.py方式二：Web 界面
- 启动后端 WebSocket 服务器：
python web_main.py服务器默认运行在 ws://localhost:8000
- 启动前端开发服务器（新终端窗口）：
cd web
npm run dev前端默认运行在 http://localhost:5173（Vite 默认端口）
- 访问 Web 界面：
打开浏览器访问 http://localhost:5173
⚙️ 配置指南
1. 环境变量配置
创建 .env 文件（从 .env.example 复制）：
# OpenAI API 配置
OPENAI_API_KEY=your_api_key_here # 必需：您的 API 密钥
OPENAI_BASE_URL=https://api.openai.com/v1 # 必需：API 基础 URL
OPENAI_MODEL=gpt-4 # 必需：使用的模型名称
# Redis 配置（必需）
REDIS_URL=redis://localhost:6379/0 # 必需：Redis 连接 URL
# Web 服务配置（可选）
WEB_PORT=8000 # WebSocket 服务器端口（默认 8000）
WEB_HOST=localhost # WebSocket 服务器主机（默认 localhost）配置说明：
| 配置项 | 说明 | 示例 |
|---|---|---|
OPENAI_API_KEY | OpenAI API 密钥或兼容服务的密钥 | sk-... |
OPENAI_BASE_URL | API 端点 URL | https://api.openai.com/v1 |
OPENAI_MODEL | 模型名称 | gpt-4, gpt-4-turbo, gpt-3.5-turbo |
REDIS_URL | 必需 Redis 连接 URL | redis://localhost:6379/0 |
WEB_PORT | （可选）WebSocket 服务器端口 | 8000 |
WEB_HOST | （可选）WebSocket 服务器主机 | localhost |
使用其他 API 服务：
如果您使用的是兼容 OpenAI 接口的其他服务，只需修改 OPENAI_BASE_URL：
OPENAI_BASE_URL=https://your-api-service.com/v12. MCP 工具配置
创建 mcp_config.json 文件（从 mcp_config.example.json 复制）：
{
"servers": [
{
"name": "filesystem",
"protocol": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
},
{
"name": "weather",
"protocol": "sse",
"url": "http://localhost:8000/sse",
"timeout": 30
},
{
"name": "calculator",
"protocol": "streamablehttp",
"url": "http://localhost:8000/mcp",
"timeout": 30
}
]
}协议说明：
| 协议 | 说明 | 必需字段 | 可选字段 | 适用场景 |
|---|---|---|---|---|
stdio | 通过标准输入输出通信 | command, args | env | 本地命令行工具 |
sse | 通过 Server-Sent Events 通信 | url | timeout, env | 支持 SSE 的 HTTP 服务 |
streamablehttp | 通过 HTTP 流式请求通信 | url | timeout, env | 标准 HTTP API 服务 |
超时配置：
timeout：超时时间（秒），仅对 SSE 和 StreamableHTTP 协议有效- 如果未配置，将使用默认超时或无限等待（取决于协议实现）
注意： 如果不需要 MCP 工具，可以删除 mcp_config.json 文件或将 servers 数组设为空 []。
📖 使用指南
CLI 界面使用
启动后，您将看到欢迎界面：
============================================================
欢迎使用 ReACT 智能助手！
============================================================
这是一个基于 ReACT 推理模式的智能助手，能够：
• 观察和理解您的问题
• 思考解决方案
• 使用工具执行操作
• 记住对话历史
输入 'exit' 或 'quit' 退出程序
输入 Ctrl+C 也可以随时退出
============================================================
您: Web 界面使用
会话管理
- 创建新会话：点击左侧"新建会话"按钮
- 切换会话：点击左侧会话列表中的任意会话
- 删除会话：点击会话右侧的删除按钮（会同时删除该会话的所有聊天记录）
- 默认会话：首次访问时自动创建一个默认会话
发送消息
- 在底部输入框中输入您的问题
- 按
Enter键或点击"发送"按钮发送消息 - AI 助手会实时流式返回响应，呈现打字机效果
消息显示
- 用户消息：显示在右侧，蓝色背景
- 助手消息：显示在左侧，白色背景
- 支持完整的 Markdown 格式渲染 - 代码块自动语法高亮 - 表格、列表、链接等格式友好显示
- 工具调用：显示为独立卡片
- 工具调用卡片：显示工具名称和调用参数（默认折叠） - 工具输出卡片：显示工具执行结果（默认折叠） - 状态指示：显示"执行中..."或"已完成"
Markdown 渲染功能
助手消息支持以下 Markdown 格式：
- 标题：
# H1,## H2,### H3 - 列表：有序列表和无序列表
- 代码块：自动语法高亮（支持多种编程语言）
- 使用三个反引号包裹代码块 - 指定语言类型：\\\`python
- 内联代码：使用单个反引号包裹
- 链接：自动识别并渲染为可点击链接
- 表格：支持 GitHub Flavored Markdown 表格
- 引用：使用
>标记引用内容 - 粗体/斜体：
**粗体**,*斜体*
📁 项目结构
react-agent-assistant/
├── src/ # 后端源代码
│ ├── agent_core.py # Agent 核心逻辑（ReACT 推理）
│ ├── cli.py # CLI 交互界面
│ ├── config.py # 配置管理
│ ├── mcp_manager.py # MCP 工具管理器
│ ├── model_provider.py # 模型提供者
│ ├── session_manager.py # 会话管理器
│ └── web_api.py # WebSocket API 服务
├── web/ # 前端源代码
│ ├── src/
│ │ ├── components/ # React 组件
│ │ │ ├── ChatWindow.tsx # 聊天窗口组件
│ │ │ ├── MessageInput.tsx # 消息输入组件
│ │ │ └── SessionList.tsx # 会话列表组件
│ │ ├── services/ # 服务层
│ │ │ └── websocket.ts # WebSocket 客户端
│ │ ├── types/ # TypeScript 类型定义
│ │ ├── App.tsx # 主应用组件
│ │ └── main.tsx # 入口文件
│ ├── package.json # 前端依赖配置
│ └── vite.config.ts # Vite 构建配置
├── tests/ # 单元测试
├── openspec/ # OpenSpec 规范文档
├── main.py # CLI 入口
├── web_main.py # Web 服务入口
├── requirements.txt # Python 依赖
├── mcp_config.json # MCP 工具配置
└── README.md # 项目文档🛠️ 开发指南
后端开发
- 运行测试：
pytest- 代码格式：
项目使用 Python 标准代码风格，建议使用 black 或 autopep8 格式化代码。
前端开发
- 开发模式：
cd web
npm run dev- 构建生产版本：
cd web
npm run build- 预览生产构建：
cd web
npm run preview- 代码检查：
cd web
npm run lint添加新的 MCP 工具
- 在
mcp_config.json中添加服务器配置 - 根据协议类型配置相应字段
- 重启服务即可使用新工具
自定义 Markdown 样式
Markdown 样式定义在 web/src/components/ChatWindow.tsx 中的 ReactMarkdown 组件的 components 属性中。您可以修改 Tailwind CSS 类来自定义样式。
❓ 常见问题
Web 界面无法连接
- 确保后端 WebSocket 服务器正在运行（
python web_main.py） - 检查
WEB_PORT环境变量是否与前端配置一致 - 检查浏览器控制台是否有错误信息
MCP 工具无法加载
- 检查
mcp_config.json文件格式是否正确 - 对于 stdio 协议，确保命令和参数正确
- 对于 SSE/StreamableHTTP 协议，确保 URL 可访问且超时配置合理
- 查看后端日志了解详细错误信息
会话历史丢失
- 确保 Redis 服务正在运行
- 检查 Redis 连接 URL 是否正确（
REDIS_URL环境变量） - 检查 Redis 服务是否可访问
- 查看后端日志了解详细错误信息
Markdown 渲染问题
- 确保前端依赖已正确安装（
npm install） - 检查浏览器控制台是否有 JavaScript 错误
- 代码块语法高亮需要指定语言类型
📄 许可证
[本开源软件遵循 MIT 许可证]