# agents

**Repository Path**: mcxia/agents

## Basic Information

- **Project Name**: agents
- **Description**: agent智能客服的项目



- **Primary Language**: Java
- **License**: AFL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-25
- **Last Updated**: 2026-04-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能客服Agent系统

## 项目简介

智能客服Agent系统是一个基于多智能体协作架构的智能客服系统，支持流式响应机制，通过工具调用、记忆管理和流程控制优化，提升复杂场景处理能力，支持并发对话会话数提升5倍。

## 技术栈

- **后端**：Python 3.10+
- **Web框架**：Flask + Flask-SocketIO
- **任务队列**：Celery
- **数据存储**：PostgreSQL, Redis
- **实时通信**：WebSocket
- **AI服务**：SiliconFlow / Azure OpenAI

## 系统架构

### 核心组件

- **接入层**：WebSocket服务，处理客户端连接和流式响应
- **业务逻辑层**：核心对话引擎，多智能体协作系统
- **数据存储层**：PostgreSQL（持久化存储）和Redis（缓存和会话管理）
- **任务处理层**：Celery任务队列，处理异步任务
- **外部服务层**：SiliconFlow API，提供智能对话能力

### 多智能体协作架构

```
┌─────────────────────────────────────────────────────────────┐
│                       客户端层                               │
│                   (test_frontend.html)                      │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                      核心引擎层                             │
│                      ChatEngine                              │
│  ┌─────────────┬─────────────┬─────────────┬───────────┐  │
│  │ Conversation│    Tool    │   Memory    │   Flow    │  │
│  │   Agent    │   Agent    │   Agent    │   Agent   │  │
│  └─────────────┴─────────────┴─────────────┴───────────┘  │
└─────────────────────────────────────────────────────────────┘
```

## 功能特性

- **流式响应**：实时返回AI生成的响应，提升用户体验
- **工具调用**：支持调用外部工具，如天气查询、计算器等
- **记忆管理**：保持会话上下文，提供连续的对话体验
- **流程控制**：根据对话内容自动调整对话流程
- **并发处理**：支持高并发对话会话
- **多AI服务**：支持SiliconFlow和Azure OpenAI两种AI服务

## 快速开始

### 环境要求

- Python 3.10+
- Redis（可选，当前支持内存存储降级）
- PostgreSQL（可选）

### 安装依赖

```bash
pip install flask flask-socketio python-dotenv openai redis
```

### 配置环境变量

复制并编辑 `.env` 文件，配置AI服务密钥：

```env
# AI服务配置
AI_PROVIDER=siliconflow

# SiliconFlow配置（当前使用）
SILICONFLOW_API_KEY=你的API密钥
SILICONFLOW_ENDPOINT=https://api.siliconflow.cn/v1
SILICONFLOW_MODEL=deepseek-ai/DeepSeek-V3

# Azure OpenAI配置（备用）
AZURE_OPENAI_KEY=你的Azure密钥
AZURE_OPENAI_ENDPOINT=https://xxx.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT_NAME=你的部署名

# WebSocket配置
WEBSOCKET_PORT=8000
```

### 启动服务

```bash
# 启动WebSocket服务
python app.py
```

服务启动后，访问 `http://localhost:8000` 或使用测试前端页面进行测试。

### 使用测试前端

1. 启动HTTP服务器（用于托管测试页面）：
   ```bash
   python -m http.server 9000
   ```

2. 在浏览器中打开：`http://localhost:9000/test_frontend.html`

## API文档

### WebSocket事件

| 事件名 | 方向 | 描述 |
|--------|------|------|
| `connect` | 客户端→服务器 | 建立WebSocket连接 |
| `disconnect` | 客户端→服务器 | 断开WebSocket连接 |
| `connected` | 服务器→客户端 | 连接成功响应 |
| `message` | 客户端→服务器 | 发送普通消息 |
| `stream_message` | 客户端→服务器 | 发送流式消息 |
| `response` | 服务器→客户端 | 接收普通响应 |
| `stream_response` | 服务器→客户端 | 接收流式响应片段 |

### 消息格式

#### 发送消息 (message)
```json
{
  "user_id": "user123",
  "message": "你好",
  "session_id": "session123"
}
```

#### 接收响应 (response)
```json
{
  "session_id": "session123",
  "response": "你好，有什么可以帮助你的吗？",
  "flow_state": {
    "current_step": "general",
    "session_id": "session123",
    "context": {}
  }
}
```

#### 流式响应片段 (stream_response)
```json
{
  "session_id": "session123",
  "chunk": "你好"
}
```

## 项目结构

```
agent/
├── agents/                     # 智能体模块
│   ├── conversation_agent.py    # 对话智能体
│   ├── tool_agent.py           # 工具调用智能体
│   ├── memory_agent.py         # 记忆管理智能体
│   └── flow_agent.py           # 流程控制智能体
├── engine/                    # 核心引擎
│   └── chat_engine.py          # 对话引擎
├── websocket/                  # WebSocket服务
│   └── handlers.py             # WebSocket事件处理
├── tasks/                      # Celery任务
│   ├── celery_config.py        # Celery配置
│   └── tasks.py                # 任务定义
├── storage/                    # 数据存储
│   ├── db.py                   # 数据库连接
│   └── models.py               # 数据库模型
├── utils/                      # 工具模块
│   ├── ai_client.py            # AI客户端
│   └── performance.py          # 性能优化
├── config/                     # 配置
│   └── config.py               # 配置管理
├── tests/                      # 测试
│   ├── test_chat_engine.py     # 单元测试
│   └── test_performance.py     # 性能测试
├── test_frontend.html          # 测试前端页面
├── test_ai_client.py           # AI客户端测试脚本
├── test_websocket.py           # WebSocket测试脚本
├── app.py                      # 应用入口
├── requirements.txt             # 依赖项
└── .env                        # 环境变量
```

## 多智能体说明

### 1. ConversationAgent（对话智能体）

负责与用户进行对话交互，生成自然语言响应。

**核心功能**：
- 构建提示词（包含历史对话、工具结果、流程状态）
- 调用AI服务生成响应
- 支持流式响应

### 2. ToolAgent（工具调用智能体）

管理和执行外部工具扩展AI能力。

**已注册工具**：
- `weather` - 查询天气信息
- `calculator` - 执行数学计算
- `faq` - 查询常见问题

### 3. MemoryAgent（记忆管理智能体）

维护会话历史和上下文信息。

**存储结构**：
- 用户ID、会话ID
- 对话历史（限制最近50条）
- 最后更新时间

**存储方式**：
- Redis优先（分布式存储）
- 内存存储降级（单机部署）

### 4. FlowAgent（流程控制智能体）

跟踪和管理对话流程状态。

**支持的流程状态**：
- `start` - 开始
- `general` - 一般对话
- `order` - 订单相关
- `refund` - 退款相关
- `complaint` - 投诉相关

## 配置说明

### AI服务配置

系统支持SiliconFlow和Azure OpenAI两种AI服务，通过`AI_PROVIDER`环境变量切换：

```env
# 使用SiliconFlow
AI_PROVIDER=siliconflow
SILICONFLOW_API_KEY=你的密钥
SILICONFLOW_MODEL=deepseek-ai/DeepSeek-V3

# 或使用Azure OpenAI
AI_PROVIDER=azure
AZURE_OPENAI_KEY=你的密钥
AZURE_OPENAI_DEPLOYMENT_NAME=你的部署名
```

### 存储配置

```env
# Redis配置（可选）
REDIS_URL=redis://localhost:6379/0

# PostgreSQL配置（可选）
DATABASE_URL=postgresql://user:pass@localhost:5432/dbname
```

### 服务配置

```env
WEBSOCKET_PORT=8000
APP_ENV=development
APP_DEBUG=True
```

## 性能测试

运行性能测试：

```bash
python tests/test_performance.py
```

## 注意事项

1. **API密钥安全**：所有密钥存储在`.env`文件中，不要提交到版本控制
2. **Redis依赖**：Redis为可选依赖，断开时会自动降级到内存存储
3. **流式响应**：在网络不稳定环境下，流式响应可能会有碎片化现象
4. **并发处理**：生产环境建议使用gunicorn或其他WSGI服务器替代Flask开发服务器