smart-cs-multi-agent

🤖 智能客服多Agent系统

企业级面试项目全攻略 — 面向金融/电商场景，包含 Python / Java / Go 三语言完整实现 + 配套面试材料，从零到面试一站搞定。

📋 目录

• 项目简介
• 系统架构
• 核心功能
• 技术栈
• 三语言实现对比
• 快速开始
• 项目结构
• 核心代码解析
• 面试准备材料
• 参考项目
• 安全说明

🎯 项目简介

本项目是一个企业级多Agent智能客服系统，模拟真实金融/电商公司的客服场景。系统由多个专业AI Agent协同工作，自动处理用户咨询、工单创建、知识检索等任务。

这个项目能帮你做什么？

• ✅ 面试加分项：拥有一个真实完整的多Agent项目，不再只是CRUD
• ✅ 三语言实现：Python/Java/Go均有完整代码，适配不同岗位需求
• ✅ 面试材料齐全：简历模板、STAR话术、八股文题库一应俱全
• ✅ 学习参考：代码有详细注释，架构文档有图文说明

适合人群：

• 准备AI/后端岗位面试的同学
• 想了解多Agent系统架构的开发者
• 对LangGraph/Spring AI/Eino感兴趣的工程师

🏗️ 系统架构

整体架构图

用户 (Web/App/API)
        │  HTTP/SSE
        ▼
┌──────────────────────┐
│   API Gateway        │  ← 认证、限流、日志
│   (FastAPI / Spring) │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────────────────────────────────┐
│              Supervisor 编排 Agent                │
│  ┌─────────────┐         ┌────────────────────┐  │
│  │  分层记忆系统  │         │  全链路追踪          │  │
│  │ • 工作记忆    │         │  (OpenTelemetry)   │  │
│  │ • 短期(Redis) │         │  Agent调用链可视化  │  │
│  │ • 长期(向量库) │         └────────────────────┘  │
│  └─────────────┘                                  │
└──────┬──────────┬──────────┬──────────┬───────────┘
       │          │          │          │
       ▼          ▼          ▼          ▼
  ┌─────────┐┌─────────┐┌─────────┐┌─────────┐
  │ 意图路由  ││ 知识检索  ││ 工单处理  ││ 合规审查  │
  │  Agent   ││  Agent   ││  Agent   ││  Agent   │
  │ (分类)   ││ (RAG)    ││ (CRUD)   ││ (规则+LLM)│
  └─────────┘└─────────┘└─────────┘└─────────┘
                  │              │
                  ▼              ▼
           ┌──────────────────────────────┐
           │         MCP 工具协议层         │
           │  订单查询 | 工单CRUD | 风控接口  │
           │  知识库搜索 | 用户画像查询       │
           └──────────────────────────────┘

请求处理流程

① 用户发送消息："我的订单什么时候到？"
        ↓
② Supervisor 分析意图 → 路由决策
        ↓
③ 意图路由 Agent 识别意图: "order_query"
        ↓
④ 知识检索 Agent → 调用MCP工具查询订单
        ↓
⑤ 合规审查 Agent → 检查回复内容合规性
        ↓
⑥ Supervisor 汇总结果 → 返回最终回复

✨ 核心功能

1. Supervisor 编排模式

什么是Supervisor？ 就像一个项目经理，接到需求后分配给不同专家处理，最后汇总结果。

2. 分层记忆系统

为什么需要三层记忆？ 类似人类记忆：工作桌(工作记忆) + 笔记本(短期) + 大脑长期记忆。

3. MCP 工具协议

什么是MCP？ Model Context Protocol，AI模型调用外部工具的标准协议，类似HTTP规范了Web通信。

{
  "name": "order_query",
  "description": "查询订单信息",
  "inputSchema": {
    "type": "object",
    "properties": {
      "order_id": {"type": "string", "description": "订单ID"}
    },
    "required": ["order_id"]
  }
}

已实现的MCP工具：

• order_query — 查询订单状态、物流信息
• ticket_create / ticket_update — 工单创建和更新
• risk_check — 金融风控接口
• kb_search — 知识库全文搜索
• user_profile — 用户画像查询

4. RAG 知识检索

什么是RAG？ Retrieval-Augmented Generation，先从知识库检索相关内容，再让AI生成回答，避免AI"瞎编"。

用户问题: "怎么退款？"
    ↓ Query改写（扩展关键词）
"退款 政策 申请 流程 时限"
    ↓ 向量化（转为1536维数字）
    ↓ 向量检索（找最相似的Top-5文档）
    ↓ 重排序（LLM评估相关性 → Top-3）
    ↓ 上下文注入（文档内容 + 用户问题）
    ↓ LLM生成（基于文档的准确回答）
最终回答 + 引用来源标注

5. 全链路追踪 (OpenTelemetry)

可以清楚地看到每次请求经过哪些Agent、每个步骤耗时多少、消耗了多少Token：

[Root] user_request (总耗时: 2.8s, 总Token: 1850)
  ├── [Span] supervisor.route_decision     → 800ms, 150 tokens
  ├── [Span] knowledge_rag.process         → 1.9s
  │     ├── rag.query_rewrite              → 200ms
  │     ├── rag.vector_search              → 15ms
  │     ├── rag.rerank                     → 500ms
  │     └── rag.generate_answer            → 1200ms, 1200 tokens
  ├── [Span] compliance_checker.process    → 600ms, 400 tokens
  └── [Span] supervisor.synthesize         → 50ms

6. 合规审查

专为金融场景设计：

• 敏感词检测：自动识别违规词汇
• PII保护：过滤身份证、银行卡等隐私信息
• 越权访问治理：防止用户绕过权限限制
• 双重审查：规则引擎（快，<2ms）+ LLM审查（准，~600ms）

🛠️ 技术栈

🔀 三语言实现对比

🚀 快速开始

前置条件

• 一个 OpenAI API Key（或其他LLM的Key）
• Docker（可选，用于一键启动）

方式一：Docker 一键启动（推荐新手）

# 1. 克隆项目
git clone https://github.com/bcefghj/smart-cs-multi-agent.git
cd smart-cs-multi-agent

# 2. 配置API Key
cp python-impl/.env.example python-impl/.env
# 编辑 .env 文件，填入你的 OPENAI_API_KEY

# 3. 一键启动所有服务
docker-compose up -d

# 4. 访问接口
# API文档: http://localhost:8000/docs
# 追踪UI:  http://localhost:16686 (Jaeger)

方式二：Python 版本（直接运行）

# 进入Python实现目录
cd python-impl

# 安装依赖
pip install -r requirements.txt

# 配置环境变量
cp .env.example .env
# 编辑 .env，至少填写：
# OPENAI_API_KEY=你的key
# OPENAI_BASE_URL=https://api.openai.com/v1

# 启动服务
python -m api.main

# 测试接口（新开终端）
curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user_001", "message": "我想查询订单状态"}'

方式三：Java 版本

cd java-impl

# 需要 Java 17+ 和 Maven 3.8+
mvn clean package -DskipTests

# 运行
java -jar target/smart-cs-agent-1.0.0.jar

# 或者直接用Maven运行
mvn spring-boot:run

方式四：Go 版本

cd go-impl

# 需要 Go 1.22+
go mod tidy

# 运行
go run main.go

# 或者编译后运行
go build -o smart-cs-agent .
./smart-cs-agent

📁 项目结构

smart-cs-multi-agent/
│
├── 📄 README.md                    ← 你现在看的这个文件
├── 📄 docker-compose.yml           ← 一键启动所有服务
├── 📄 LICENSE                      ← MIT开源协议
│
├── 📂 docs/                        ← 文档目录
│   ├── 📄 architecture.md          ← 架构设计文档（含流程图）
│   ├── 📄 code-walkthrough.md      ← 核心代码逐行解析
│   ├── 📄 deployment.md            ← 生产环境部署指南
│   └── 📂 interview/               ← 面试准备材料
│       ├── 📄 resume-template.md   ← 简历模板（STAR格式）
│       ├── 📄 star-method.md       ← 面试话术（含多场景）
│       ├── 📄 baguwen.md           ← 30+八股文题库+详细答案
│       └── 📄 project-qa.md        ← 20+项目深度追问+应对策略
│
├── 📂 python-impl/                 ← Python实现 (LangGraph + FastAPI)
│   ├── 📄 requirements.txt         ← Python依赖包
│   ├── 📄 Dockerfile
│   ├── 📂 agents/                  ← 核心Agent代码
│   │   ├── supervisor.py           ← Supervisor编排Agent（核心）
│   │   ├── intent_router.py        ← 意图识别Agent
│   │   ├── knowledge_rag.py        ← RAG知识检索Agent
│   │   ├── ticket_handler.py       ← 工单处理Agent
│   │   └── compliance_checker.py   ← 合规审查Agent
│   ├── 📂 memory/                  ← 三层记忆系统
│   ├── 📂 mcp/                     ← MCP工具协议实现
│   ├── 📂 tracing/                 ← OpenTelemetry追踪
│   └── 📂 api/                     ← FastAPI接口层
│
├── 📂 java-impl/                   ← Java实现 (Spring AI + Spring Boot)
│   ├── 📄 pom.xml                  ← Maven依赖配置
│   ├── 📄 Dockerfile
│   └── 📂 src/main/java/com/smartcs/
│
└── 📂 go-impl/                     ← Go实现 (Eino框架)
    ├── 📄 go.mod                   ← Go依赖管理
    ├── 📄 main.go                  ← 程序入口
    ├── 📄 Dockerfile
    ├── 📂 agent/                   ← Agent实现
    ├── 📂 memory/                  ← 记忆系统
    ├── 📂 mcp/                     ← MCP协议
    └── 📂 tracing/                 ← 链路追踪

💻 核心代码解析

Supervisor 编排核心逻辑（Python）

这是整个系统最重要的部分，理解了这个代码，面试时就能讲清楚多Agent协作原理：

# python-impl/agents/supervisor.py

# 1. 定义全局状态（类似"黑板"，所有Agent共享）
class AgentState(TypedDict):
    messages: list[BaseMessage]    # 对话历史
    user_id: str                   # 用户ID
    intent: str                    # 识别到的意图
    sub_results: dict[str, Any]    # 各Agent处理结果
    compliance_passed: bool        # 合规是否通过
    final_response: str            # 最终回复

# 2. 构建有向图（定义Agent之间的流转关系）
def create_supervisor_graph():
    graph = StateGraph(AgentState)
    
    # 添加节点（每个Agent是一个节点）
    graph.add_node("supervisor_route", supervisor.route_decision)
    graph.add_node("knowledge_rag", knowledge_agent.process)
    graph.add_node("ticket_handler", ticket_agent.process)
    graph.add_node("compliance_check", compliance_agent.process)
    graph.add_node("synthesize", supervisor.synthesize_response)
    
    # 设置入口
    graph.set_entry_point("supervisor_route")
    
    # 条件路由（根据意图决定走哪条路）
    graph.add_conditional_edges(
        "supervisor_route",
        route_to_agent,              # 路由函数
        {
            "knowledge_rag": "knowledge_rag",
            "ticket_handler": "ticket_handler",
        }
    )
    
    # 所有Agent处理后都经过合规审查
    graph.add_edge("knowledge_rag", "compliance_check")
    graph.add_edge("ticket_handler", "compliance_check")
    graph.add_edge("compliance_check", "synthesize")
    graph.add_edge("synthesize", END)
    
    return graph.compile(checkpointer=MemorySaver())

面试时怎么讲这段代码？

“我们用LangGraph的StateGraph构建了一个有向图，Supervisor作为中心节点负责路由，子Agent各司其职。所有回复都强制经过合规审查节点，这是金融场景的合规要求。MemorySaver提供检查点功能，支持对话断点续接。”

MCP工具协议实现

# python-impl/mcp/tools.py

# MCP工具的核心：描述工具能力，让AI知道什么时候用这个工具
order_query_tool = {
    "name": "order_query",
    "description": "查询用户订单的状态、物流、金额等信息",
    "inputSchema": {
        "type": "object",
        "properties": {
            "order_id": {
                "type": "string", 
                "description": "订单编号，如 ORD-2024-001"
            },
            "user_id": {
                "type": "string",
                "description": "用户ID，用于权限验证"
            }
        },
        "required": ["order_id", "user_id"]
    }
}

📚 面试准备材料

配套完整面试资料，帮你从"能看懂代码"到"面试时能流畅讲清楚"：

常见面试问题预览

Q: 为什么用Supervisor模式而不是让Agent直接互相调用？

A: Supervisor模式的优势在于集中控制，便于追踪和调试；避免Agent之间形成循环依赖；Supervisor可以做全局优化，比如并行调度多个Agent；出错时有统一的错误处理和回退机制。

Q: 三层记忆的设计原则是什么？

A: 参考了人类认知的记忆模型。工作记忆对应当前注意力焦点，速度最快但容量有限；短期记忆用Redis实现30分钟TTL，保持对话上下文连贯性；长期记忆用向量数据库存储知识库和用户历史，支持语义相似度检索。

Q: MCP协议相比直接调用函数有什么优势？

A: MCP是标准化协议，工具描述用JSON Schema，AI可以自动发现和理解工具能力，不需要硬编码工具调用逻辑；支持动态工具注册，新增工具不需要修改Agent代码；协议层做了权限控制和参数验证。

📖 参考项目

本项目设计参考了以下企业级开源项目，建议结合阅读：

🔒 安全说明

• 本项目不包含任何真实的API Key、Token或密码
• 所有敏感配置通过环境变量注入（见 .env.example）
• .env.example 仅提供占位符示例，不要直接使用
• 请勿将含有真实凭据的 .env 文件提交到版本控制

📄 License

MIT License — 自由使用、修改、分发，保留原始版权声明即可。