aiagent/聊天智能体示例说明.md

# 智能聊天Agent完整示例说明

## 📋 概述

这是一个完整的聊天智能体示例，展示了如何使用平台的核心能力构建一个功能完善的聊天助手。该示例包含了记忆管理、意图识别、多分支路由、上下文传递等核心功能。

## 🎯 功能特性

### ✅ 核心能力展示

1. **记忆管理**
   - 使用缓存节点存储对话历史
   - 支持用户画像和上下文信息
   - 自动更新记忆内容

2. **意图识别**
   - 使用LLM节点分析用户意图
   - 识别情感状态
   - 提取关键词和话题

3. **多分支路由**
   - 使用Switch节点根据意图分发
   - 支持6种不同场景的处理分支
   - 默认分支处理未知意图

4. **上下文传递**
   - 使用Transform节点合并数据
   - 保持对话历史的连贯性
   - 支持多轮对话

5. **个性化回复**
   - 根据不同意图生成针对性回复
   - 考虑用户情感状态
   - 保持对话风格一致

## 🔄 工作流结构

```
开始节点
  ↓
查询记忆（Cache节点）
  ↓
合并上下文（Transform节点）
  ↓
意图理解（LLM节点）
  ↓
意图路由（Switch节点）
  ├─→ 问候处理（greeting）
  ├─→ 问题回答（question）
  ├─→ 情感回应（emotion）
  ├─→ 请求处理（request）
  ├─→ 告别回复（goodbye）
  └─→ 通用回复（default）
  ↓
合并回复（Merge节点）
  ↓
更新记忆（Cache节点）
  ↓
格式化回复（LLM节点）
  ↓
结束节点
```

## 📊 节点详细说明

### 1. 开始节点（start-1）
- **功能**: 接收用户输入
- **输入格式**: JSON格式，包含 `query` 字段
- **输出**: 将用户输入传递给后续节点

### 2. 查询记忆节点（cache-query）
- **类型**: Cache节点
- **操作**: `get` - 获取用户记忆
- **Key**: `user_memory_{user_id}`
- **默认值**: 空记忆结构
- **功能**: 从缓存中读取用户的对话历史和画像信息

### 3. 合并上下文节点（transform-merge）
- **类型**: Transform节点
- **模式**: `merge` - 合并模式
- **功能**: 将用户输入、记忆数据、时间戳合并为完整上下文

### 4. 意图理解节点（llm-intent）
- **类型**: LLM节点
- **模型**: DeepSeek Chat
- **功能**: 
  - 分析用户输入
  - 识别意图类型（greeting/question/emotion/request/goodbye/other）
  - 识别情感状态（positive/neutral/negative）
  - 提取关键词和话题
- **输出格式**: JSON
  ```json
  {
    "intent": "意图类型",
    "emotion": "情感状态",
    "keywords": ["关键词"],
    "topic": "话题主题",
    "needs_response": true
  }
  ```

### 5. 意图路由节点（switch-intent）
- **类型**: Switch节点
- **功能**: 根据意图类型路由到不同的处理分支
- **分支**:
  - `greeting` → 问候处理
  - `question` → 问题回答
  - `emotion` → 情感回应
  - `request` → 请求处理
  - `goodbye` → 告别回复
  - `default` → 通用回复

### 6. 各分支处理节点（llm-*）
- **类型**: LLM节点
- **功能**: 根据不同意图生成针对性的回复
- **特点**:
  - 问候分支：友好、亲切
  - 问题分支：准确、详细
  - 情感分支：共情、温暖
  - 请求分支：专业、清晰
  - 告别分支：温暖、期待
  - 通用分支：自然、连贯

### 7. 合并回复节点（merge-response）
- **类型**: Merge节点
- **模式**: `merge_first` - 合并第一个结果
- **功能**: 将各分支的回复结果合并

### 8. 更新记忆节点（cache-update）
- **类型**: Cache节点
- **操作**: `set` - 设置记忆
- **功能**: 
  - 将本次对话添加到历史记录
  - 更新用户画像（如需要）
  - 保存上下文信息
- **TTL**: 86400秒（24小时）

### 9. 格式化回复节点（llm-format）
- **类型**: LLM节点
- **功能**: 对最终回复进行格式化和优化
- **输出**: 自然、流畅的文本回复

### 10. 结束节点（end-1）
- **功能**: 返回最终回复
- **输出格式**: 纯文本

## 🚀 使用方法

### 方法一：使用生成脚本（推荐）

```bash
cd backend/scripts
python3 generate_chat_agent.py
```

脚本会自动创建Agent，包含完整的工作流配置。

### 方法二：手动创建

1. **进入Agent管理页面**
   - 点击"创建Agent"按钮
   - 填写名称和描述

2. **进入工作流编辑器**
   - 点击"设计"按钮
   - 使用节点工具箱添加节点
   - 按照工作流结构连接节点

3. **配置节点**
   - **LLM节点**: 配置API密钥、模型、Prompt
   - **Cache节点**: 配置缓存Key和操作
   - **Switch节点**: 配置路由规则
   - **Transform节点**: 配置数据映射

4. **测试Agent**
   - 点击"测试"按钮
   - 输入测试消息
   - 查看执行结果

5. **发布Agent**
   - 点击"发布"按钮
   - Agent状态变为"已发布"
   - 可以开始使用

## 📝 配置要点

### 1. LLM节点配置

- **Provider**: 选择AI模型提供商（如DeepSeek、OpenAI）
- **Model**: 选择具体模型（如deepseek-chat、gpt-3.5-turbo）
- **Temperature**: 
  - 意图识别：0.3（需要准确性）
  - 情感回应：0.8（需要创造性）
  - 问题回答：0.5（平衡准确性和灵活性）
- **Max Tokens**: 根据回复长度需求设置
- **Prompt**: 明确角色、任务、输出格式要求

### 2. Cache节点配置

- **Operation**: 
  - `get`: 查询记忆
  - `set`: 更新记忆
- **Key**: 使用用户ID确保记忆隔离
- **TTL**: 设置合适的过期时间（如24小时）

### 3. Switch节点配置

- **Field**: 指定用于路由的字段（如`intent`）
- **Cases**: 配置各分支的路由规则
- **Default**: 配置默认分支

### 4. Transform节点配置

- **Mode**: 选择合并模式（`merge`）
- **Mapping**: 配置数据映射规则
- **变量引用**: 使用`{{variable}}`引用上游数据

## 🎨 自定义扩展

### 1. 添加新的意图分支

1. 在Switch节点中添加新的case
2. 创建对应的LLM处理节点
3. 连接Switch节点和处理节点
4. 连接处理节点到Merge节点

### 2. 增强记忆功能

- 添加用户画像更新逻辑
- 实现长期记忆和短期记忆分离
- 添加记忆检索和总结功能

### 3. 添加外部工具

- 集成知识库查询
- 添加天气、新闻等外部API
- 实现文件处理功能

### 4. 优化回复质量

- 添加回复质量评估节点
- 实现多候选回复生成和选择
- 添加回复风格控制

## 🔍 测试示例

### 测试用例1：问候
```
输入: "你好"
预期: 友好的问候回复
```

### 测试用例2：问题
```
输入: "今天天气怎么样？"
预期: 尝试回答问题或说明无法获取天气信息
```

### 测试用例3：情感表达
```
输入: "我今天心情不太好"
预期: 共情、安慰的回复
```

### 测试用例4：请求
```
输入: "帮我写一首诗"
预期: 生成诗歌或说明能力范围
```

### 测试用例5：告别
```
输入: "再见"
预期: 温暖的告别回复
```

## ⚠️ 注意事项

1. **API密钥配置**
   - 确保所有LLM节点都配置了有效的API密钥
   - 检查API配额和限制

2. **记忆管理**
   - Cache节点使用内存缓存，重启后会丢失
   - 生产环境建议使用Redis等持久化缓存

3. **性能优化**
   - 减少不必要的LLM调用
   - 优化Prompt长度
   - 合理设置Token限制

4. **错误处理**
   - 添加错误处理节点
   - 配置重试机制
   - 提供友好的错误提示

## 📚 相关文档

- [创建Agent经验总结](./创建Agent经验.md)
- [工作流节点类型说明](./可新增节点类型建议.md)
- [Agent使用说明](./Agent使用说明.md)

## 🎯 适用场景

- ✅ 情感陪聊助手
- ✅ 客服机器人
- ✅ 智能问答系统
- ✅ 对话式AI应用
- ✅ 个性化聊天助手

## 💡 最佳实践

1. **Prompt设计**
   - 明确角色定位
   - 明确输出格式
   - 提供示例和上下文

2. **工作流设计**
   - 保持流程清晰
   - 合理使用分支
   - 避免过度复杂

3. **记忆管理**
   - 定期清理过期记忆
   - 控制记忆大小
   - 保护用户隐私

4. **测试验证**
   - 覆盖各种场景
   - 测试边界情况
   - 验证回复质量

---

**创建时间**: 2024年
**版本**: 1.0
**作者**: AI Agent Platform