# Custom React Agent - 快速开始指南 ## 🚀 5分钟快速启动 ### 1. 启动API服务 ```bash cd test/custom_react_agent python api.py ``` 服务将在 http://localhost:8000 启动 ### 2. 验证服务状态 ```bash curl http://localhost:8000/health ``` ### 3. 开始对话 ```bash curl -X POST http://localhost:8000/api/chat \ -H "Content-Type: application/json" \ -d '{"question": "请问哪个高速服务区的档口数量最多？", "user_id": "doudou"}' ``` ### 4. 查看对话历史 ⭐ 新功能 ```bash # 查看用户的对话列表 curl "http://localhost:8000/api/v0/react/users/doudou/conversations?limit=5" # 查看特定对话的详细内容 curl "http://localhost:8000/api/v0/react/users/doudou/conversations/doudou:20250115103000001" ``` ## 📋 基本API用法 ### 智能问答 ```bash # 普通对话 curl -X POST http://localhost:8000/api/chat \ -H "Content-Type: application/json" \ -d '{"question": "你好", "user_id": "alice"}' # SQL查询 curl -X POST http://localhost:8000/api/chat \ -H "Content-Type: application/json" \ -d '{"question": "查询收入最高的服务区", "user_id": "alice"}' # 继续对话 (使用相同thread_id) curl -X POST http://localhost:8000/api/chat \ -H "Content-Type: application/json" \ -d '{"question": "详细说明一下", "user_id": "alice", "thread_id": "alice:20250115103000001"}' ``` ### 对话历史管理 ⭐ 新功能 ```bash # 获取用户对话列表 curl "http://localhost:8000/api/v0/react/users/alice/conversations" # 限制返回数量 curl "http://localhost:8000/api/v0/react/users/alice/conversations?limit=10" # 获取特定对话详情 curl "http://localhost:8000/api/v0/react/users/alice/conversations/alice:20250115103000001" ``` ## 💻 Python 客户端示例 ### 基础对话 ```python import requests def chat_with_agent(question, user_id, thread_id=None): url = "http://localhost:8000/api/chat" payload = { "question": question, "user_id": user_id } if thread_id: payload["thread_id"] = thread_id response = requests.post(url, json=payload) return response.json() # 使用示例 result = chat_with_agent("请问服务区数据查询", "alice") print(f"回答: {result['data']['response']}") ``` ### 对话历史查询 ⭐ 新功能 ```python import requests def get_user_conversations(user_id, limit=10): """获取用户对话列表""" url = f"http://localhost:8000/api/v0/react/users/{user_id}/conversations" params = {"limit": limit} response = requests.get(url, params=params) return response.json() def get_conversation_detail(user_id, thread_id): """获取对话详情""" url = f"http://localhost:8000/api/v0/react/users/{user_id}/conversations/{thread_id}" response = requests.get(url) return response.json() # 使用示例 conversations = get_user_conversations("alice", limit=5) print(f"找到 {len(conversations['data']['conversations'])} 个对话") if conversations['data']['conversations']: thread_id = conversations['data']['conversations'][0]['thread_id'] detail = get_conversation_detail("alice", thread_id) print(f"对话包含 {detail['data']['message_count']} 条消息") ``` ## 🌐 JavaScript/前端示例 ### 基础对话 ```javascript async function chatWithAgent(question, userId, threadId = null) { const response = await fetch('http://localhost:8000/api/chat', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ question: question, user_id: userId, ...(threadId && { thread_id: threadId }) }) }); return await response.json(); } // 使用示例 const result = await chatWithAgent("查询服务区信息", "alice"); console.log("回答:", result.data.response); ``` ### 对话历史管理 ⭐ 新功能 ```javascript async function getUserConversations(userId, limit = 10) { const response = await fetch( `http://localhost:8000/api/v0/react/users/${userId}/conversations?limit=${limit}` ); return await response.json(); } async function getConversationDetail(userId, threadId) { const response = await fetch( `http://localhost:8000/api/v0/react/users/${userId}/conversations/${threadId}` ); return await response.json(); } // 使用示例 const conversations = await getUserConversations("alice", 5); console.log(`找到 ${conversations.data.conversations.length} 个对话`); if (conversations.data.conversations.length > 0) { const firstConv = conversations.data.conversations[0]; const detail = await getConversationDetail("alice", firstConv.thread_id); console.log(`对话详情:`, detail.data); } ``` ## 🧪 测试工具 ### 运行完整测试 ```bash cd test/custom_react_agent python test_api.py ``` ### 测试新的对话历史功能 ⭐ ```bash cd test/custom_react_agent python test_conversation_api.py ``` ### 单独测试问题 ```bash python test_api.py "查询服务区收入排名" ``` ## 🎯 典型应用场景 ### 1. 聊天机器人界面 ```python # 获取用户的历史对话，显示对话列表 conversations = get_user_conversations("user123", limit=20) for conv in conversations['data']['conversations']: print(f"[{conv['formatted_time']}] {conv['conversation_preview']}") ``` ### 2. 客服系统 ```python # 客服查看用户的完整对话历史 user_id = "customer_456" conversations = get_user_conversations(user_id) for conv in conversations['data']['conversations']: thread_id = conv['thread_id'] detail = get_conversation_detail(user_id, thread_id) print(f"对话时间: {conv['formatted_time']}") print(f"消息数量: {detail['data']['message_count']}") # 显示详细消息... ``` ### 3. 对话分析 ```python # 分析用户的对话模式 conversations = get_user_conversations("analyst_user") total_messages = sum(conv['message_count'] for conv in conversations['data']['conversations']) avg_messages = total_messages / len(conversations['data']['conversations']) print(f"平均每个对话 {avg_messages:.1f} 条消息") ``` ## 🔧 Thread ID 设计说明 ### 格式规则 - **格式**: `{user_id}:{timestamp}` - **示例**: `doudou:20250115103000001` - **优势**: - 自然包含用户信息 - 支持时间排序 - 无需额外映射表 ### 时间戳格式 ``` 20250115103000001 │ │ │ │ │ │ │ │ │ │ │ │ │ └── 毫秒 (001) │ │ │ │ │ └──── 秒 (30) │ │ │ │ └────── 分钟 (30) │ │ │ └──────── 小时 (10) │ │ └────────── 日 (15) │ └───────────── 月 (01) └─────────────── 年 (2025) ``` ## ⚠️ 注意事项 1. **服务依赖**: 确保Redis服务可用 2. **数据库连接**: 确认业务数据库连接正常 3. **并发限制**: API有并发和频率限制 4. **数据安全**: 生产环境需要添加认证授权 5. **监控日志**: 注意观察API日志和性能指标 ## 🔍 故障排除 ### 常见问题 ```bash # 检查服务状态 curl http://localhost:8000/health # 查看详细日志 python api.py # 查看启动日志 # 测试基础功能 python test_api.py "你好" # 测试新功能 python test_conversation_api.py ``` ### 性能优化 - 对话列表查询使用Redis SCAN，支持大量数据 - 合理设置limit参数避免过大响应 - 生产环境建议添加缓存层 --- 🎉 现在你已经掌握了Custom React Agent API的基本用法和新的对话历史管理功能！ 📚 更多详细信息请参考: [完整API文档](./README_API.md)