citu_vanna/test/custom_react_agent/doc/README_API.md

Custom React Agent API 文档

Flask API服务，提供与Custom React Agent进行交互的RESTful接口。

🚀 快速开始

启动服务

cd test/custom_react_agent
python api.py

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

📋 API 端点

1. 健康检查

GET /health

检查API服务状态

响应示例:

{
  "status": "healthy",
  "agent_initialized": true,
  "timestamp": "2025-01-15T10:30:00"
}

2. 聊天接口

POST /api/chat

与Agent进行对话

请求参数:

{
  "question": "请问哪个高速服务区的档口数量最多？",
  "user_id": "doudou",
  "thread_id": "doudou:20250115103000001"  // 可选，不提供则自动生成
}

响应示例:

{
  "success": true,
  "data": {
    "records": {...},      // SQL查询结果
    "response": "...",     // Agent回答
    "sql": "...",         // 执行的SQL
    "react_agent_meta": {...}
  },
  "thread_id": "doudou:20250115103000001",
  "timestamp": "2025-01-15T10:30:00"
}

3. 获取用户对话列表 ⭐ 新增

GET /api/v0/react/users/{user_id}/conversations

获取指定用户的最近聊天记录列表

路径参数:

• user_id: 用户ID

查询参数:

• limit: 返回数量限制 (默认10，最大50)

请求示例:

curl "http://localhost:8000/api/v0/react/users/doudou/conversations?limit=5"

响应示例:

{
  "success": true,
  "data": {
    "user_id": "doudou",
    "conversations": [
      {
        "thread_id": "doudou:20250115103000001",
        "user_id": "doudou",
        "timestamp": "20250115103000001",
        "message_count": 4,
        "last_message": "南城服务区的档口数量最多，共有39个档口。",
        "last_updated": "2025-01-15T10:30:00",
        "conversation_preview": "请问哪个高速服务区的档口数量最多？",
        "formatted_time": "2025-01-15 10:30:00"
      },
      {
        "thread_id": "doudou:20250115102500002", 
        "user_id": "doudou",
        "timestamp": "20250115102500002",
        "message_count": 6,
        "last_message": "共有6个餐饮档口。",
        "last_updated": "2025-01-15T10:25:00",
        "conversation_preview": "南城服务区有多少个餐饮档口？",
        "formatted_time": "2025-01-15 10:25:00"
      }
    ],
    "total_count": 2,
    "limit": 5
  },
  "timestamp": "2025-01-15T10:35:00"
}

4. 获取对话详情 ⭐ 新增

GET /api/v0/react/users/{user_id}/conversations/{thread_id}

获取特定对话的详细历史记录

路径参数:

• user_id: 用户ID
• thread_id: 对话线程ID (必须以 user_id: 开头)

请求示例:

curl "http://localhost:8000/api/v0/react/users/doudou/conversations/doudou:20250115103000001"

响应示例:

{
  "success": true,
  "data": {
    "user_id": "doudou",
    "thread_id": "doudou:20250115103000001",
    "message_count": 4,
    "messages": [
      {
        "type": "human",
        "content": "请问哪个高速服务区的档口数量最多？",
        "tool_calls": null
      },
      {
        "type": "ai", 
        "content": "我来帮您查询一下高速服务区的档口数量信息。",
        "tool_calls": [...]
      },
      {
        "type": "tool",
        "content": "[{\"service_area\": \"南城服务区\", \"booth_count\": 39}, ...]",
        "tool_calls": null
      },
      {
        "type": "ai",
        "content": "南城服务区的档口数量最多，共有39个档口。",
        "tool_calls": null
      }
    ]
  },
  "timestamp": "2025-01-15T10:35:00"
}

🔧 技术特性

Thread ID 设计

• 格式：{user_id}:{timestamp}
• 示例：doudou:20250115103000001
• 自动按时间戳排序
• 无需额外映射表

数据持久化

• 使用 AsyncRedisSaver 存储对话状态
• 支持跨会话的对话历史查询
• Redis pattern匹配高效查询用户数据

错误处理

• 统一的JSON错误格式
• 详细的错误日志
• 优雅的异常处理

📊 使用场景

1. 聊天机器人界面: 显示用户的历史对话列表
2. 对话管理: 查看和管理特定对话的详细内容
3. 数据分析: 分析用户的对话模式和频率
4. 客服系统: 客服人员查看用户历史对话记录

🔍 测试示例

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

# 2. 查看对话列表  
curl "http://localhost:8000/api/v0/react/users/doudou/conversations?limit=5"

# 3. 查看特定对话详情
curl "http://localhost:8000/api/v0/react/users/doudou/conversations/doudou:20250115103000001"

📝 注意事项

• user_id 和 thread_id 的格式验证
• limit 参数范围限制 (1-50)
• 异步操作的错误处理
• Redis连接的健壮性