基于 DeepSeek API 的智能电商客服系统，支持订单查询、物流追踪、地址修改、退款申请。从零手写 Agent 核心逻辑，不依赖 LangChain 等框架。
- Tool Calling 双轮调用：LLM 决定工具 → 执行工具 → LLM 生成回复，完整闭环
- DSML Fallback 机制：处理 DeepSeek 非标准工具调用输出，保证可靠性
- 多用户会话隔离：每个用户独立对话历史，支持并发访问，15 分钟超时自动清理
- 数据持久化：SQLite 数据库存储订单数据，支持并发读写
- LLM 自动重试：API 超时/限流时指数退避重试，生产环境稳定性保障
- 结构化日志：JSON 格式输出，支持对接 ELK/Loki，全链路可追溯
- Token 消耗追踪：自动记录每次调用的 prompt/completion tokens，成本可控
- 输入安全过滤：Prompt Injection 基础检测，关键词/长度/特殊字符多层防护
- API 限流保护：基于 slowapi 的 per-user 限流，防止接口滥用
- 完整测试覆盖：41 个单元测试，覆盖工具函数、Agent 逻辑、API 接口、安全过滤
- 零配置部署：Docker Compose 一键启动
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Client │─────▶│ FastAPI │─────▶│ DeepSeek │
│ (CLI / HTTP)│◀─────│ Agent │◀─────│ API │
└─────────────┘ └──────┬──────┘ └─────────────┘
│
┌──────┴──────┐
│ SQLite │
│ Orders │
└─────────────┘
git clone https://github.com/yourname/customer-agent.git
cd customer-agent
cp .env.example .env
# 编辑 .env，填入你的 DEEPSEEK_API_KEY
docker-compose up服务启动后访问 http://localhost:8000/docs 查看交互式 API 文档。
# 1. 克隆项目
git clone https://github.com/yourname/customer-agent.git
cd customer-agent
# 2. 创建虚拟环境
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# 3. 安装依赖
pip install -r requirements.txt
# 4. 配置环境变量
cp .env.example .env
# 编辑 .env，填入 DEEPSEEK_API_KEY
# 5. 启动服务
# Web API 模式
uvicorn app.api:app --reload
# 或 CLI 模式
python -m app.maincurl -X POST http://localhost:8000/chat \
-H "Content-Type: application/json" \
-d '{
"user_id": "u001",
"message": "查询订单 1001"
}'响应示例：
{
"reply": "订单 1001 的商品是机械键盘，状态为已发货，收货地址是北京市朝阳区。",
"tool_called": "get_order"
}curl -X POST http://localhost:8000/reset \
-H "Content-Type: application/json" \
-d '{"user_id": "u001"}'curl http://localhost:8000/health$ python -m app.main
Agent 客服已启动！输入 quit 退出。
你: 查询订单 1001
AI: 订单 1001 的商品是机械键盘，当前状态为已发货，物流单号为 SF123456789，收货地址为北京市朝阳区。
你: 把 1002 的地址改成深圳市南山区
AI: 地址修改成功！订单 1002 的收货地址已更新为深圳市南山区。
你: 我要退款
AI: 请提供订单号
你: 1002
AI: 已为您提交退款申请，预计 1-3 个工作日到账。
你: quit
客服系统已关闭# 运行全部测试
pytest tests/ -v
# 运行特定测试文件
pytest tests/test_tools.py -v
pytest tests/test_agent.py -v
pytest tests/test_api.py -v
pytest tests/test_security.py -v| 技术 | 用途 |
|---|---|
| Python 3.11 | 编程语言 |
| DeepSeek API (OpenAI SDK) | 大语言模型 |
| FastAPI | Web API 框架 |
| SQLAlchemy + SQLite | ORM 与数据库 |
| Pydantic / Pydantic-Settings | 数据校验与配置管理 |
| Tenacity | LLM 调用自动重试 |
| python-json-logger | 结构化 JSON 日志 |
| slowapi | API 限流保护 |
| Pytest | 单元测试 |
| Docker / Docker Compose | 容器化部署 |
| GitHub Actions | CI 持续集成 |
本项目选择手写 Agent 核心逻辑，而非使用 LangChain，原因如下：
- 可控性：完全掌握 Tool Calling 的每一轮交互，便于调试和优化
- 学习价值：深入理解 Agent 的工作机制，而非依赖框架封装
- 轻量级：当前只有 4 个工具，LangChain 的抽象层反而增加复杂度
- 优势：手写 Agent 能展示对 LLM 调用链的深入理解
customer-agent/
├── app/
│ ├── __init__.py
│ ├── main.py # CLI 入口
│ ├── api.py # FastAPI Web 接口（限流、日志）
│ ├── agent.py # Agent 核心逻辑（重试、日志、Token 追踪、安全过滤）
│ ├── tools.py # 工具函数（SQLite 数据库操作）
│ ├── prompts.py # System Prompt
│ ├── state.py # 对话状态管理
│ ├── schemas.py # Tool Schema 定义
│ ├── config.py # 配置管理（Pydantic Settings）
│ ├── logger.py # 结构化 JSON 日志配置
│ └── security.py # 输入安全过滤（Prompt Injection 检测）
├── tests/
│ ├── conftest.py # Pytest fixtures（内存数据库隔离）
│ ├── test_tools.py # 工具函数测试
│ ├── test_agent.py # Agent 逻辑测试（Mock LLM、安全过滤）
│ ├── test_api.py # API 接口测试
│ └── test_security.py # 安全过滤规则测试
├── data/
│ ├── orders.json # 初始数据
│ └── orders.db # SQLite 数据库（运行时生成）
├── .github/workflows/
│ └── ci.yml # GitHub Actions CI
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── .env.example
└── README.md
本项目是从零学习 AI Agent 开发的实战记录，完整保留了迭代过程：
- 单文件原型：最初只有 400+ 行的
main.py，硬编码订单数据 - 模块化重构：拆分为 6 个模块，数据迁移到 JSON
- DSML Fallback：解决 DeepSeek 非标准工具调用输出问题
- SQLite 持久化：支持并发读写，数据不丢失
- FastAPI 服务化：支持多用户并发会话
- 测试覆盖：41 个单元测试，Mock 外部 API
- 生产级优化：重试机制、结构化日志、Token 追踪、安全过滤、API 限流
MIT License