# smart-support-agent

**Repository Path**: yunmeng-dev/smart-support-agent

## Basic Information

- **Project Name**: smart-support-agent
- **Description**: 基于 LangGraph、FastAPI 的智能客服与工单 Agent
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-09-16
- **Last Updated**: 2026-11-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Python

## README

# SmartSupport Agent

SmartSupport 是一个基于 LangGraph 与 FastAPI 的智能客服和工单 Agent。系统通过 State、Node 与 Conditional Edge 编排客户请求，结合 Embedding 召回、Rerank 精排、Structured Output、Guardrail、Fallback、Checkpoint 和人工升级，形成可控制、可恢复的业务工作流。

项目的目标不是把所有判断都交给大模型，而是让模型负责适合概率判断的分类与表达，业务操作继续由可测试的规则、数据库事务和人工审批控制。

> 本仓库主要展示项目架构、核心流程与关键模块，部分业务实现及知识库数据未完整公开。

**核心看点：** LangGraph 状态编排 · Embedding 召回与 Rerank 精排 · 结构化输出 · 安全护栏与降级 · Checkpoint 与 Human-in-the-loop

## 运行效果

客服请求经过 Agent 工作流完成分类、工单创建和员工分配，并同步展示节点执行时间线。

![SmartSupport 客服对话与工单流转](docs/images/smartsupport-agent-ticket.jpg)

管理端集中展示工单状态、负责人和客服团队工作量。

![SmartSupport 工单管理后台](docs/images/smartsupport-admin.jpg)

## 技术栈

- Agent：Python 3.11、LangGraph、LangChain、OpenAI-compatible Chat API
- 检索链路：Embedding 语义召回、Rerank 精排；公开版保留可独立运行的关键词检索与降级链路
- API 与数据：FastAPI、Pydantic、SQLAlchemy、SQLite
- 状态与可观测性：LangGraph SQLite Checkpoint、Loguru、可选 LangSmith tracing
- 前端：React 19、Vite
- 测试：Pytest、内存 SQLite

## LangGraph 工作流

```mermaid
flowchart TD
    START --> INTAKE[Intake Node]
    INTAKE --> GUARD[Policy Guardrail Node]
    GUARD -->|blocked| FINAL[Final Response Node]
    GUARD -->|allowed| CLASSIFY[Classifier Node]
    CLASSIFY -->|general question| RECALL[Embedding Recall]
    RECALL --> RERANK[Rerank]
    RERANK --> KNOWLEDGE[Policy Knowledge Node]
    KNOWLEDGE --> RESPONSE[Response Node]
    RESPONSE --> FINAL
    CLASSIFY -->|ticket required| TICKET[Ticket Creation Node]
    TICKET --> ASSIGN[Assignment Node]
    ASSIGN -->|normal and assigned| FINAL
    ASSIGN -->|urgent / sensitive / unassigned| HITL{{interrupt: Human Review}}
    HITL -->|Command resume| ESCALATE[Escalation Node resumes]
    ESCALATE --> FINAL
    FINAL --> END
```

## 关键实现

### State、Node 与 Conditional Edge

`SupportAgentState` 统一保存会话标识、分类结果、策略判断、工单、分配结果、审计事件、时间线和最终回复。每个 Node 只处理一个职责，路由函数根据 `allowed`、`requires_ticket`、优先级、人员可用性和人工审核要求选择下一条边，避免在一个超长 Agent Prompt 中混合所有业务逻辑。

### Structured Output

模型分类通过 `ChatOpenAI.with_structured_output()` 输出 `ClassificationResult`。Pydantic 将 `category` 和 `priority` 约束为固定枚举，并校验 `requires_ticket` 与类别是否一致。模型返回格式不合法或接口不可用时，不会把未经验证的数据带入工单流程。

### Embedding 召回与 Rerank 精排

完整项目的知识检索链路先通过 Embedding 进行语义召回，再使用 Rerank 对候选内容精排，将更相关的知识片段交给回复节点。求职展示版未完整公开向量库配置、知识库数据和精排模型接入代码，仓库中的 `policy_tools.py` 保留了可离线运行的关键词检索与 Fallback，便于复现工作流主链路。

### Guardrail

`policy_guardrail_node` 在分类和工具调用前运行。确定性规则会拦截密钥索取、系统提示词探测、命令执行和越权访问等请求；涉及退款、折扣、合同、法律或明确时限承诺的请求会被标记为需要人工审核。每次判断都会写入审计日志。

### Fallback

项目在两个关键位置提供降级：

- 未配置模型密钥、模型调用失败或结构化输出校验失败时，分类器退回到确定性关键词规则。
- SQLite Checkpoint 初始化失败时，工作流退回到 `MemorySaver`，保证本地演示仍可运行。

LLM 只润色已经生成的回复；润色失败时直接返回确定性草稿，不改变分类、派单或审批结论。

### Checkpoint

工作流以 `thread_id` 作为 checkpoint key，默认写入 `data/langgraph_checkpoints.sqlite`。这既支持读取流程状态，也为人工审核期间的暂停与恢复提供持久化基础。本地数据库和 checkpoint 文件都在 `.gitignore` 中，不会进入仓库。

### Human-in-the-loop / 人工升级

紧急、敏感、涉及承诺或暂时无人可分配的工单会进入 `escalation_node`。节点调用 LangGraph `interrupt()` 真正暂停工作流；管理员通过 `POST /api/chat/resume` 提交审核结果，接口使用 `Command(resume=...)` 从 checkpoint 恢复同一条执行链。审核结果会更新工单状态并写入审计日志，然后才生成最终回复。

### 工单与分配规则

工单创建后，分配器按问题类别筛选角色，再按当前工作量、资历和姓名稳定排序。没有满足条件的员工时，工单进入等待分配并升级人工处理。写操作集中在工具层，便于独立测试。

## FastAPI 核心接口

| 方法 | 路径 | 作用 |
| --- | --- | --- |
| `GET` | `/health` | 服务与数据库健康检查 |
| `POST` | `/api/chat/start` | 创建 `thread_id` |
| `POST` | `/api/chat/message` | 执行或暂停客服工作流 |
| `POST` | `/api/chat/resume` | 提交人工审核结果并恢复工作流 |
| `GET` | `/api/tickets` | 查询工单列表 |
| `GET` | `/api/tickets/{tracking_id}` | 查询单个工单状态 |
| `GET/POST/PATCH` | `/api/employees` | 查看与维护客服人员 |
| `GET` | `/api/audit-logs` | 查看最近的策略和业务审计事件 |

交互式接口文档：`http://127.0.0.1:8000/docs`。

## 项目结构

```text
backend/app/
├── api/routes.py          # FastAPI 路由、暂停状态响应与 Command 恢复
├── graph/
│   ├── builder.py         # StateGraph、Node、Edge、Checkpointer
│   ├── nodes.py           # 工作流节点与 interrupt
│   ├── policies.py        # Guardrail 与人工审核规则
│   ├── routing.py         # Conditional Edge 路由
│   └── state.py           # SupportAgentState
├── tools/                 # 分类、知识查询、工单与员工分配
├── models.py              # SQLAlchemy 数据模型
├── schemas.py             # FastAPI 请求/响应模型
└── llm.py                 # 可选的回复润色与降级
frontend/src/              # React 客户端与管理端
tests/                     # 图、策略、派单和工具测试
```

## 本地运行

依赖 Python 3.11+ 和 Node.js 18+。

```bash
git clone https://gitee.com/yunmeng-dev/smart-support-agent.git
cd smart-support-agent

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
# OPENAI_API_KEY 可留空；此时自动使用确定性分类和回复
python scripts/setup_db.py
uvicorn backend.app.main:app --reload
```

前端另开终端启动：

```bash
cd frontend
npm ci
npm run dev
```

测试命令：

```bash
pytest -q
```

公开版整理完成后测试结果为 `17 passed`。测试环境使用内存 SQLite，且不调用外部模型 API。

## 后续扩展


后续可扩展：

- 关键词与向量混合召回策略优化
- 检索、Rerank 与回复质量的离线评测
- 审核台的待办队列、身份认证与权限控制
- PostgreSQL、Redis 和分布式任务队列
- 基于离线数据集的分类质量评测