23 - 综合实战（上）：需求分析与架构设计！从零到一构建生产级智能客服Agent

适合前后端/测试等有编程基础的同学，手把手带你走完企业级Agent项目的完整交付流程

前言

经过前面22节课的系统学习，你已经掌握了AI Agent开发的完整技能树：

模块	课时	核心能力
模块一：认知篇	第1-2节	理解Agent是什么、能做什么
模块二：基础篇	第3-6节	API调用、Prompt Engineering、Function Calling、上下文管理
模块三：框架篇	第7-12节	LangChain核心组件、Chain、Memory、RAG、LangGraph
模块四：进阶篇	第13-18节	ReAct、Plan-and-Execute、多Agent协作、记忆系统、安全对齐
模块五：工程篇	第19-22节	评估测试、部署上线、可观测性、性能优化

现在是时候把所有知识串起来了。

一句话定义：综合实战是将前面22节课的所有知识点，通过一个完整的企业级项目从需求分析、架构设计、代码开发、测试评估到部署上线的全流程，进行一次系统性的整合与验证。

今天这一节（第23节）聚焦于需求分析与架构设计------这是整个项目成败的关键。代码可以重构，但架构错了，整个项目都要推倒重来。

一、项目选题：三个实战方向

我们从以下三个实战项目中三选一，每个项目都覆盖了前面22节课的核心知识点：

项目A：智能客服Agent（推荐⭐）

业务场景：为一家中型电商公司构建智能客服系统，处理用户售前咨询、售后问题和工单创建。

核心功能	涉及的技术点	对应课时
多轮对话	Memory + Checkpointer	第6、9、17节
知识库问答（商品信息、退换货政策）	RAG + Vector Store	第10节
订单查询	Function Calling + Tool	第5、11节
自动创建工单	Tool + API集成	第11节
人工转接	Human-in-the-Loop	第18节
多Agent协作（售前/售后分流）	Multi-Agent	第15-16节

为什么推荐：业务逻辑清晰、技术覆盖全面、可落地性强、简历含金量高。

项目B：代码审查Agent

业务场景：为开发团队构建自动化代码审查工具，在PR阶段自动分析代码质量、发现潜在Bug。

核心功能	涉及的技术点	对应课时
代码解析与静态分析	Tool + Code Parser	第5、11节
AI代码审查	ReAct + LLM	第13节
自动修复建议	Plan-and-Execute	第14节
多语言支持	Tool扩展	第11节
审查报告生成	Chain + Output Parser	第4、8节
CI/CD集成	部署与API	第20节

项目C：数据分析Agent

业务场景：让业务人员用自然语言查询数据、自动生成SQL、执行分析并输出可视化图表。

核心功能	涉及的技术点	对应课时
NL2SQL	Tool + LLM	第5、11节
数据查询与聚合	Tool + 数据库	第11节
自动可视化	Tool + 图表库	第5、11节
分析报告生成	Chain + RAG	第8、10节
多数据源支持	Tool扩展	第11节

二、项目选择与决策

💡 建议：如果你时间有限或想快速上手，选择项目A（智能客服）。它是三个项目中最"标准"的Agent应用场景，技术覆盖最全面，也是面试中最常被问到的案例。

决策矩阵：

你的背景	推荐项目	理由
后端/全栈开发	项目A（智能客服）	涉及API集成、数据库、服务化部署，后端技能可复用
前端/测试开发	项目B（代码审查）	代码分析、CI/CD集成，贴近开发工具链
数据/算法背景	项目C（数据分析）	NL2SQL、数据可视化，发挥数据技能

本文以项目A（智能客服）为主线进行完整实战，项目B和C的架构思路类似，可在理解A的基础上自行迁移。

三、需求分析与功能拆解

3.1 业务需求文档（BRD）

项目名称：智能客服Agent系统（E-commerce Customer Service Agent）

目标用户：电商平台普通消费者（C端）+ 客服管理人员（B端）

核心价值：

7×24小时即时响应，解决80%的常见问题
自动分流复杂问题到人工客服
降低客服人力成本40%以上

3.2 功能需求清单（FRD）

编号	功能	优先级	说明
F1	多轮对话	P0	支持上下文记忆，理解用户意图
F2	售前咨询	P0	商品信息查询、推荐、比价
F3	售后服务	P0	订单查询、退换货、物流跟踪
F4	知识库问答	P0	基于产品手册、政策文档的RAG问答
F5	工单创建	P1	复杂问题自动创建工单流转到人工
F6	人工转接	P1	识别需要人工介入的场景并转接
F7	用户身份识别	P2	识别登录用户，个性化服务
F8	多轮对话	P0	支持上下文记忆，理解用户意图
F9	售前咨询	P0	商品信息查询、推荐、比价
F10	售后服务	P0	订单查询、退换货、物流跟踪
F11	知识库问答	P0	基于产品手册、政策文档的RAG问答
F12	工单创建	P1	复杂问题自动创建工单流转到人工
F13	人工转接	P1	识别需要人工介入的场景并转接
F14	用户身份识别	P2	识别登录用户，个性化服务

3.3 非功能需求（NFR）

编号	需求	目标值
N1	响应延迟（P95）	< 3秒
N2	并发支持	100 QPS
N3	可用性	99.5%
N4	Token成本	< ¥0.1/会话
N5	会话持久化	支持断点续传
N6	可观测性	LangSmith全链路追踪

3.4 Agent能力边界定义

这是架构设计中最容易被忽略、但最关键的环节：

Agent应该做什么，不应该做什么？

应该做	不应该做
回答商品信息和库存状态	直接修改库存（只读操作）
查询订单状态和物流信息	直接操作订单（通过工具间接）
创建售后工单（提交后需人工审核）	自动执行退款
引导用户自助完成退换货	绕过用户确认直接发起退款

能力边界的影响：

工具设计：你只需要给Agent"只读"或"受控写入"的工具
权限模型：Agent不需要拥有写权限，只有受控写入的中间层
安全风险：如果有人注入攻击，最多泄露信息而不是删除数据

四、技术选型

4.1 技术栈总览

层级	技术选型	理由
Web框架	FastAPI	高性能、异步、自动生成OpenAPI文档
Agent框架	LangChain + LangGraph	工业级标准，生态完善
大模型	DeepSeek-V4-Flash（推理） + BGE（Embedding）	性价比高，中文友好
向量数据库	Chroma（开发） / Milvus（生产）	轻量级→分布式平滑迁移
关系数据库	PostgreSQL（+ pgvector）	检查点持久化+向量存储二合一
任务队列	Celery + Redis	异步处理长耗时任务
容器化	Docker + Docker Compose	一键启动全部服务
可观测性	LangSmith + LangFuse	全链路追踪+成本监控
评估框架	LangSmith + Ragas	离线评估+质量监控

4.2 为什么选DeepSeek-V4-Flash？

维度	DeepSeek-V4-Flash	GPT-4o-mini	通义千问
价格（输入/输出）	$0.003 /$ 0.015	$0.15 /$ 0.60	¥0.002 / ¥0.006
中文能力	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐⭐
工具调用	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐
推理能力	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐

DeepSeek的性价比优势在客服场景中非常明显------每日海量会话，成本差异直接决定项目能否盈利。

五、架构设计

5.1 系统架构图

复制代码

┌─────────────────────────────────────────────────────────────────────┐
│                         用户层                                      │
│   ┌──────────────┐  ┌──────────────┐  ┌──────────────┐            │
│   │  Web/小程序  │  │   APP客户端  │  │  API调用方   │            │
│   └──────┬───────┘  └──────┬───────┘  └──────┬───────┘            │
│          └─────────────────┼─────────────────┘                     │
│                            ↓                                       │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │                  API Gateway / Nginx                        │  │
│  │              （限流 + 认证 + 负载均衡）                      │  │
│  └─────────────────────────────────────────────────────────────┘  │
│                            ↓                                       │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │                    FastAPI 服务层                           │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │  │
│  │  │ 会话管理    │  │ 意图识别    │  │ 路由分发    │        │  │
│  │  └─────────────┘  └─────────────┘  └─────────────┘        │  │
│  └─────────────────────────────────────────────────────────────┘  │
│                            ↓                                       │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │              LangGraph Agent 核心编排层                     │  │
│  │  ┌──────────────────────────────────────────────────────┐  │  │
│  │  │                    Supervisor                        │  │  │
│  │  │   ┌──────────┐  ┌──────────┐  ┌──────────┐         │  │  │
│  │  │   │ 售前Agent│  │ 售后Agent│  │ 工单Agent│         │  │  │
│  │  │   └────┬─────┘  └────┬─────┘  └────┬─────┘         │  │  │
│  │  │        └──────┬──────┘              │               │  │  │
│  │  │               ↓                     ↓               │  │  │
│  │  │          ┌──────────┐          ┌──────────┐        │  │  │
│  │  │          │ RAG引擎  │          │工具执行器│        │  │  │
│  │  │          └──────────┘          └──────────┘        │  │  │
│  │  └──────────────────────────────────────────────────────┘  │  │
│  └─────────────────────────────────────────────────────────────┘  │
│                            ↓                                       │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │                      基础设施层                             │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │  │
│  │  │PostgreSQL│  │   Redis  │  │ 向量数据库│  │ 对象存储 │  │  │
│  │  │(检查点)  │  │(缓存/队列)│  │ (知识库) │  │ (日志)   │  │  │
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │  │
│  └─────────────────────────────────────────────────────────────┘  │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │                    可观测性层                               │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐                 │  │
│  │  │LangSmith │  │ LangFuse │  │Prometheus│                 │  │
│  │  │(追踪+评估)│  │ (成本监控)│  │ (指标)   │                 │  │
│  │  └──────────┘  └──────────┘  └──────────┘                 │  │
│  └─────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘

5.2 Agent工作流设计（LangGraph状态图）

python 复制代码

from typing import TypedDict, Literal
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import InMemorySaver

class CustomerServiceState(TypedDict):
    """客服Agent全局状态"""
    messages: list                    # 对话历史
    user_id: str                      # 用户ID
    intent: str                       # 意图分类
    query: str                        # 当前查询
    knowledge_context: str            # RAG检索结果
    order_info: dict                  # 订单信息
    need_human: bool                  # 是否需要转人工
    ticket_created: bool              # 是否已创建工单
    iteration: int                    # 当前迭代次数

def supervisor_node(state: CustomerServiceState) -> dict:
    """监督者节点：意图识别与路由分发"""
    # 1. 识别用户意图（售前/售后/转人工/通用）
    intent = classify_intent(state["query"])
    return {"intent": intent}

def router(state: CustomerServiceState) -> Literal["pre_sales", "after_sales", "human", "general"]:
    """路由函数：根据意图分发到不同子Agent"""
    return state["intent"]

# 构建图
graph = StateGraph(CustomerServiceState)
graph.add_node("supervisor", supervisor_node)
graph.add_node("pre_sales_agent", pre_sales_node)   # 售前Agent
graph.add_node("after_sales_agent", after_sales_node) # 售后Agent
graph.add_node("human_agent", human_node)          # 转人工Agent
graph.add_node("general_agent", general_node)      # 通用Agent
graph.add_node("retriever", retriever_node)        # RAG检索节点
graph.add_node("tool_executor", tool_executor_node) # 工具执行节点

# 定义路由
graph.add_edge(START, "supervisor")
graph.add_conditional_edges("supervisor", router, {
    "pre_sales": "pre_sales_agent",
    "after_sales": "after_sales_agent",
    "human": "human_agent",
    "general": "general_agent"
})
graph.add_edge("pre_sales_agent", "retriever")
graph.add_edge("after_sales_agent", "tool_executor")
graph.add_edge("retriever", "tool_executor")
graph.add_edge("tool_executor", END)
graph.add_edge("human_agent", END)
graph.add_edge("general_agent", END)

checkpointer = InMemorySaver()
app = graph.compile(checkpointer=checkpointer)

5.3 数据模型设计

sql 复制代码

-- 用户表
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    phone VARCHAR(20) UNIQUE,
    email VARCHAR(255) UNIQUE,
    created_at TIMESTAMP DEFAULT NOW()
);

-- 会话表
CREATE TABLE sessions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id),
    thread_id VARCHAR(255) UNIQUE,  -- LangGraph thread_id
    status VARCHAR(20) DEFAULT 'active',
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

-- 消息表
CREATE TABLE messages (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    session_id UUID REFERENCES sessions(id),
    role VARCHAR(20),  -- user / assistant / tool
    content TEXT,
    tool_calls JSONB,
    created_at TIMESTAMP DEFAULT NOW()
);

-- 工单表
CREATE TABLE tickets (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    session_id UUID REFERENCES sessions(id),
    user_id UUID REFERENCES users(id),
    category VARCHAR(50),
    description TEXT,
    status VARCHAR(20) DEFAULT 'pending',
    created_at TIMESTAMP DEFAULT NOW()
);

-- 知识库（向量存储在pgvector）
CREATE TABLE knowledge_base (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    content TEXT,
    metadata JSONB,
    embedding vector(1536),  -- pgvector
    created_at TIMESTAMP DEFAULT NOW()
);

-- 创建向量索引
CREATE INDEX knowledge_embedding_idx ON knowledge_base 
    USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);

5.4 工具设计（Tools）

python 复制代码

from langchain.tools import tool

# 只读工具（低风险）
@tool
def get_product_info(product_name: str) -> str:
    """查询商品信息，包括价格、库存、规格。仅用于售前咨询。"""
    # SELECT * FROM products WHERE name LIKE '%{product_name}%'
    pass

@tool
def get_order_status(order_id: str) -> str:
    """查询订单状态和物流信息。仅用于售后咨询。"""
    # SELECT status, tracking FROM orders WHERE order_id = '{order_id}'
    pass

# 受控写入工具（中风险，需要确认）
@tool
def create_return_request(order_id: str, reason: str) -> str:
    """创建退换货申请。需要用户确认后才能调用。"""
    # INSERT INTO returns (order_id, reason, status) VALUES ...
    pass

# 高风险操作（需要Human-in-the-Loop）
@tool
def escalate_to_human(reason: str) -> str:
    """将对话转接给人工客服。用于复杂问题。"""
    # 触发转人工流程
    pass

5.5 RAG知识库设计

文档类型	内容	分割策略
商品手册	商品规格、使用方法	按商品分块，每块500-800字符
退换货政策	退换货规则、流程	按政策条款分块
FAQ	常见问题及答案	每问一答，独立成块
物流说明	配送范围、时效	按物流方式分块

六、项目初始化

6.1 项目目录结构

复制代码

customer-service-agent/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI入口
│   ├── agent/
│   │   ├── __init__.py
│   │   ├── graph.py         # LangGraph定义
│   │   ├── nodes.py         # 各节点实现
│   │   └── state.py         # 状态定义
│   ├── tools/
│   │   ├── __init__.py
│   │   ├── product.py       # 商品查询工具
│   │   ├── order.py         # 订单查询工具
│   │   ├── ticket.py        # 工单工具
│   │   └── human.py         # 转人工工具
│   ├── rag/
│   │   ├── __init__.py
│   │   ├── loader.py        # 文档加载器
│   │   ├── splitter.py      # 文本分割器
│   │   ├── embedding.py     # 向量化
│   │   └── retriever.py     # 检索器
│   ├── memory/
│   │   ├── __init__.py
│   │   ├── checkpointer.py  # 检查点配置
│   │   └── store.py         # 长期记忆配置
│   ├── api/
│   │   ├── __init__.py
│   │   ├── routes.py        # API路由
│   │   └── models.py        # Pydantic模型
│   ├── config/
│   │   ├── __init__.py
│   │   └── settings.py      # 配置管理
│   └── utils/
│       ├── __init__.py
│       └── logging.py       # 日志配置
├── tests/
│   ├── unit/
│   └── integration/
├── deployments/
│   ├── docker-compose.yml
│   └── Dockerfile
├── scripts/
│   ├── init_db.py           # 数据库初始化
│   └── load_knowledge.py    # 知识库加载
├── requirements.txt
├── .env.example
└── README.md

6.2 环境配置

bash 复制代码

# .env.example
# LangChain
LANGSMITH_API_KEY=your_langsmith_key
LANGSMITH_TRACING=true
LANGSMITH_PROJECT=cs-agent

# 模型
LLM_API_KEY=your_deepseek_key
LLM_BASE_URL=https://api.deepseek.com
LLM_MODEL=deepseek-v4-flash

# 数据库
DATABASE_URL=postgresql://agent:pass@localhost:5432/cs_agent

# Redis
REDIS_URL=redis://localhost:6379/0

# 向量数据库
VECTOR_STORE_PATH=./chroma_db

6.3 依赖清单

复制代码

# requirements.txt
# Core
langchain>=1.0.0
langgraph>=1.0.0
langchain-openai>=1.0.0
langchain-community>=1.0.0

# Web
fastapi>=0.115.0
uvicorn[standard]>=0.30.0
pydantic>=2.0.0

# Database
asyncpg>=0.29.0
pgvector>=0.2.5
sqlalchemy>=2.0.0

# Vector DB
chromadb>=0.5.0

# Async
celery>=5.3.0
redis>=5.0.0

# Observability
langsmith>=0.1.0
langfuse>=2.0.0

# Utils
python-dotenv>=1.0.0
python-multipart>=0.0.9

6.4 核心配置类

python 复制代码

# app/config/settings.py
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    """应用配置"""
    # LangSmith
    langsmith_api_key: str
    langsmith_tracing: bool = True
    langsmith_project: str = "cs-agent"
    
    # LLM
    llm_api_key: str
    llm_base_url: str = "https://api.deepseek.com"
    llm_model: str = "deepseek-v4-flash"
    llm_temperature: float = 0.3
    
    # Embedding
    embedding_model: str = "text-embedding-3-small"
    
    # Database
    database_url: str = "postgresql://agent:pass@localhost:5432/cs_agent"
    
    # Redis
    redis_url: str = "redis://localhost:6379/0"
    
    # Vector Store
    vector_store_path: str = "./chroma_db"
    
    # Agent
    max_iterations: int = 10
    max_tokens_per_session: int = 50000
    cost_budget_per_session: float = 0.5  # USD
    
    class Config:
        env_file = ".env"

settings = Settings()

七、动手：搭建项目骨架

🚀 本节动手任务：完成项目的初始化搭建，为下一节的完整开发做好准备。

任务清单

任务	说明	状态
1. 创建项目目录结构	按上述结构创建所有目录和`__init__.py`	☐
2. 初始化虚拟环境	`python -m venv venv && source venv/bin/activate`	☐
3. 安装依赖	`pip install -r requirements.txt`	☐
4. 配置环境变量	复制`.env.example`为`.env`并填写	☐
5. 启动基础设施	`docker-compose up -d postgres redis`	☐
6. 初始化数据库	运行`scripts/init_db.py`创建表	☐
7. 加载知识库	运行`scripts/load_knowledge.py`	☐
8. 启动API服务	`uvicorn app.main:app --reload`	☐
9. 验证健康检查	`curl http://localhost:8000/health`	☐
10. 创建第一个Agent节点	实现`supervisor_node`基础版本	☐

快速启动脚本

bash 复制代码

#!/bin/bash
# scripts/setup.sh

echo "🚀 初始化智能客服Agent项目..."

# 1. 创建虚拟环境
python -m venv venv
source venv/bin/activate

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

# 3. 复制环境配置
cp .env.example .env
echo "⚠️ 请编辑.env文件，填写API Key"

# 4. 启动依赖服务
docker-compose up -d postgres redis

# 5. 初始化数据库
python scripts/init_db.py

# 6. 加载示例知识库
python scripts/load_knowledge.py --sample

echo "✅ 项目初始化完成！"
echo "启动API服务：uvicorn app.main:app --reload"

八、实战小练习（作业）

练习：完成项目骨架搭建 + 架构文档

第一部分：动手搭建

按照本节的任务清单，完成项目的初始化搭建，确保所有服务能够正常启动。

第二部分：架构文档

撰写一份简短的架构文档（README.md），包含：

项目概述（一句话说明项目是什么）
技术栈（列出所有使用的技术和版本）
系统架构图（可以手绘或用工具绘制）
核心流程说明（用户请求的完整处理链路）
部署说明（如何启动、如何配置）

第三部分：扩展思考

请思考以下问题并写出你的答案：

如果客服Agent每天要处理10万次会话，架构中哪个环节最可能成为瓶颈？
如果用户恶意攻击（如高频请求、注入攻击），你的架构如何防御？
如果大模型API突然不可用，系统应该如何降级？

提交物：

项目Git仓库地址（或本地目录截图）
README.md（架构文档）
扩展思考的答案

结语

今天这节课，我们完成了综合实战项目的第一阶段------需求分析与架构设计：

阶段	产出物	状态
项目选题	智能客服Agent（三选一决策）	✅
需求分析	BRD + FRD + NFR + Agent能力边界	✅
技术选型	完整技术栈清单	✅
架构设计	系统架构图 + Agent工作流 + 数据模型 + 工具设计	✅
项目初始化	目录结构 + 配置文件 + 启动脚本	✅
动手任务	10项任务清单	🔄 待完成

第23节核心价值 ："一个清晰、完整的架构设计，比草率的代码实现重要100倍。" 好的架构能让后续开发事半功倍，糟糕的架构会让你在代码中迷失方向。

下节课（第24节，最后一节） ，我们将进入综合实战（下） ------完成全部代码开发、集成测试、部署上线与项目交付！

如果觉得有帮助，欢迎点赞、收藏、评论三连！我们最后一节课见！

📌 本文是《AI Agent开发实战》课程第23节的完整内容，系列文章持续更新中，关注我不迷路！