# nuts-consumer-service-agent

**Repository Path**: emproof/nuts-consumer-service-agent

## Basic Information

- **Project Name**: nuts-consumer-service-agent
- **Description**: 一个智能客服系统
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-14
- **Last Updated**: 2026-06-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Nuts Consumer Service Agent

> 🥜 开箱即用的企业级智能客服Agent
> 配置API Key → 启动 → 可用的完整智能客服系统

## 快速开始

```bash
# 1. 安装
pip install -r requirements.txt

# 2. 配置你的LLM API Key
cp .env.example .env
# 编辑.env，填入你的API Key（支持任意OpenAI兼容API）

# 3. 启动
python src/main.py

# 4. 测试
curl http://localhost:8000/api/chat?message=帮我查一下OD-202606-001订单

# 或者打开浏览器访问：
# http://localhost:8000/api/chat?message=你好
```

## 支持的LLM

| 平台 | 配置示例 |
|------|---------|
| DeepSeek | `LLM_BASE_URL=https://api.deepseek.com` |
| 阿里云通义千问 | `LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1` |
| 智谱GLM | `LLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4` |
| OpenAI | `LLM_BASE_URL=https://api.openai.com/v1` |

## 项目架构

```
nuts-consumer-service-agent/
├── src/
│   ├── main.py              # FastAPI服务入口
│   ├── config.py             # 配置管理
│   ├── llm_client.py         # LLM调用客户端
│   ├── gateway/              # API网关（路由+安全前置）
│   ├── security/             # Prompt注入检测+权限控制
│   ├── agents/               # Agent核心（客服Agent+质检Agent+编排器）
│   ├── a2a/                  # A2A协议（Agent间通信）
│   ├── tools/                # 工具层（订单查询/FAQ/工单/转接）
│   ├── memory/               # 上下文与记忆管理
│   └── observability/        # 可观测性（可选）
├── deploy/                   # Docker部署
└── tests/                    # 测试
```

## 能力

- ✅ 智能对话：理解用户意图，回答常见问题
- ✅ 订单查询：根据订单号查物流状态
- ✅ 售后工单：创建退换货/维修工单
- ✅ 人工转接：无法处理时转接人工客服
- ✅ 质检评估：系统自动评估回复质量
- ✅ 安全防护：检测Prompt注入和越狱攻击
- ✅ 上下文记忆：多轮对话保持上下文
- ✅ 开箱即用：下载→配Key→启动，3步跑起来
- 🆕 MCP 协议：订单工具已封装为 MCP Server，任何 AI Agent 可即插即用

## 🆕 MCP Server 集成

从 Skills+MCP 系列第 09 篇开始，本项目的工具函数已封装为标准 MCP Server。
MCP Server 不是替代原有 Agent，而是作为**协议适配层**——原 `src/tools/` 模块保持不动，`order_service_mcp.py` 调用它们并暴露为标准 MCP 协议。

### 启动 MCP Server

```bash
# 1. 安装 MCP 依赖
pip install mcp>=1.0.0

# 2. stdio 模式（本地开发 / 单 Agent 接入）
python order_service_mcp.py

# 3. HTTP 模式（生产环境 / 多 Agent 共享）
MCP_MODE=http MCP_PORT=8080 python order_service_mcp.py
```

### 在 OpenClaw 中注册

```
mcporter: register stdio://order-service python order_service_mcp.py
```

### MCP 工具列表

| 工具名 | 参数 | 说明 |
|--------|------|------|
| `query_order` | `order_id: str` | 查询订单物流状态和商品信息 |
| `search_faq` | `query: str` | 搜索 FAQ 知识库（退货/发货/退款等） |
| `create_ticket` | `ticket_type: str, description: str` | 创建售后工单 |
| `transfer_human` | `reason: str` | 转接人工客服 |

### 与传统 Agent 的区别

| 维度 | 原 Agent（customer_service.py） | MCP Server（order_service_mcp.py） |
|------|------|------|
| 定位 | 完整智能客服（含 LLM 推理） | 纯工具服务（不含 LLM） |
| 调用方式 | Prompt 描述工具 → LLM 猜参数 | MCP 协议自动发现 → 类型安全的 function calling |
| 复用性 | 绑定在此项目内 | 任何 MCP 兼容 Agent 即插即用 |
| 部署 | FastAPI HTTP 服务 | 同时支持 stdio / HTTP |

## 配置项

参见 `.env.example`：

| 配置 | 说明 | 默认值 |
|------|------|--------|
| LLM_API_KEY | API Key | - |
| LLM_BASE_URL | API地址 | https://api.deepseek.com |
| LLM_MODEL | 模型名 | deepseek-chat |
| PORT | 服务端口 | 8000 |

## 关联系列文章

Agent开发实战系列（公众号「AI-Agent实战笔记」01-15篇）：
- 01-06：Agent基础与Multi-Agent编排
- 07-08：工具调用与Skill工程
- 10：上下文工程与记忆管理
- 11-12：A2A协议与Agent间通信
- 13/15：安全防护
- 14：可观测性

---

*知识星球「跟着坚果学AI」完整实战项目*