citu_vanna/test/custom_react_agent/doc/QUICKSTART.md

Custom React Agent - 快速开始指南

🚀 5分钟快速启动

1. 启动API服务

cd test/custom_react_agent
python api.py

服务将在 http://localhost:8000 启动

2. 验证服务状态

curl http://localhost:8000/health

3. 开始对话

curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"question": "请问哪个高速服务区的档口数量最多？", "user_id": "doudou"}'

4. 查看对话历史 ⭐ 新功能

# 查看用户的对话列表
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用法

智能问答

# 普通对话
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"}'

对话历史管理 ⭐ 新功能

# 获取用户对话列表
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 客户端示例

基础对话

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']}")

对话历史查询 ⭐ 新功能

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/前端示例

基础对话

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);

对话历史管理 ⭐ 新功能

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);
}

🧪 测试工具

运行完整测试

cd test/custom_react_agent
python test_api.py

测试新的对话历史功能 ⭐

cd test/custom_react_agent
python test_conversation_api.py

单独测试问题

python test_api.py "查询服务区收入排名"

🎯 典型应用场景

1. 聊天机器人界面

# 获取用户的历史对话，显示对话列表
conversations = get_user_conversations("user123", limit=20)

for conv in conversations['data']['conversations']:
    print(f"[{conv['formatted_time']}] {conv['conversation_preview']}")

2. 客服系统

# 客服查看用户的完整对话历史
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. 对话分析

# 分析用户的对话模式
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日志和性能指标

🔍 故障排除

常见问题

# 检查服务状态
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文档