适合前后端/测试等有编程基础的同学手把手带你走完企业级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、执行分析并输出可视化图表。核心功能涉及的技术点对应课时NL2SQLTool 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 QPSN3可用性99.5%N4Token成本 ¥0.1/会话N5会话持久化支持断点续传N6可观测性LangSmith全链路追踪3.4 Agent能力边界定义这是架构设计中最容易被忽略、但最关键的环节Agent应该做什么不应该做什么应该做不应该做回答商品信息和库存状态直接修改库存只读操作查询订单状态和物流信息直接操作订单通过工具间接创建售后工单提交后需人工审核自动执行退款引导用户自助完成退换货绕过用户确认直接发起退款能力边界的影响工具设计你只需要给Agent“只读”或“受控写入”的工具权限模型Agent不需要拥有写权限只有受控写入的中间层安全风险如果有人注入攻击最多泄露信息而不是删除数据四、技术选型4.1 技术栈总览层级技术选型理由Web框架FastAPI高性能、异步、自动生成OpenAPI文档Agent框架LangChain LangGraph工业级标准生态完善大模型DeepSeek-V4-Flash推理 BGEEmbedding性价比高中文友好向量数据库Chroma开发 / Milvus生产轻量级→分布式平滑迁移关系数据库PostgreSQL pgvector检查点持久化向量存储二合一任务队列Celery Redis异步处理长耗时任务容器化Docker Docker Compose一键启动全部服务可观测性LangSmith LangFuse全链路追踪成本监控评估框架LangSmith Ragas离线评估质量监控4.2 为什么选DeepSeek-V4-Flash维度DeepSeek-V4-FlashGPT-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状态图fromtypingimportTypedDict,Literalfromlanggraph.graphimportStateGraph,START,ENDfromlanggraph.checkpoint.memoryimportInMemorySaverclassCustomerServiceState(TypedDict):客服Agent全局状态messages:list# 对话历史user_id:str# 用户IDintent:str# 意图分类query:str# 当前查询knowledge_context:str# RAG检索结果order_info:dict# 订单信息need_human:bool# 是否需要转人工ticket_created:bool# 是否已创建工单iteration:int# 当前迭代次数defsupervisor_node(state:CustomerServiceState)-dict:监督者节点意图识别与路由分发# 1. 识别用户意图售前/售后/转人工/通用intentclassify_intent(state[query])return{intent:intent}defrouter(state:CustomerServiceState)-Literal[pre_sales,after_sales,human,general]:路由函数根据意图分发到不同子Agentreturnstate[intent]# 构建图graphStateGraph(CustomerServiceState)graph.add_node(supervisor,supervisor_node)graph.add_node(pre_sales_agent,pre_sales_node)# 售前Agentgraph.add_node(after_sales_agent,after_sales_node)# 售后Agentgraph.add_node(human_agent,human_node)# 转人工Agentgraph.add_node(general_agent,general_node)# 通用Agentgraph.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)checkpointerInMemorySaver()appgraph.compile(checkpointercheckpointer)5.3 数据模型设计-- 用户表CREATETABLEusers(id UUIDPRIMARYKEYDEFAULTgen_random_uuid(),phoneVARCHAR(20)UNIQUE,emailVARCHAR(255)UNIQUE,created_atTIMESTAMPDEFAULTNOW());-- 会话表CREATETABLEsessions(id UUIDPRIMARYKEYDEFAULTgen_random_uuid(),user_id UUIDREFERENCESusers(id),thread_idVARCHAR(255)UNIQUE,-- LangGraph thread_idstatusVARCHAR(20)DEFAULTactive,created_atTIMESTAMPDEFAULTNOW(),updated_atTIMESTAMPDEFAULTNOW());-- 消息表CREATETABLEmessages(id UUIDPRIMARYKEYDEFAULTgen_random_uuid(),session_id UUIDREFERENCESsessions(id),roleVARCHAR(20),-- user / assistant / toolcontentTEXT,tool_calls JSONB,created_atTIMESTAMPDEFAULTNOW());-- 工单表CREATETABLEtickets(id UUIDPRIMARYKEYDEFAULTgen_random_uuid(),session_id UUIDREFERENCESsessions(id),user_id UUIDREFERENCESusers(id),categoryVARCHAR(50),descriptionTEXT,statusVARCHAR(20)DEFAULTpending,created_atTIMESTAMPDEFAULTNOW());-- 知识库向量存储在pgvectorCREATETABLEknowledge_base(id UUIDPRIMARYKEYDEFAULTgen_random_uuid(),contentTEXT,metadata JSONB,embedding vector(1536),-- pgvectorcreated_atTIMESTAMPDEFAULTNOW());-- 创建向量索引CREATEINDEXknowledge_embedding_idxONknowledge_baseUSINGivfflat(embedding vector_cosine_ops)WITH(lists100);5.4 工具设计Toolsfromlangchain.toolsimporttool# 只读工具低风险tooldefget_product_info(product_name:str)-str:查询商品信息包括价格、库存、规格。仅用于售前咨询。# SELECT * FROM products WHERE name LIKE %{product_name}%passtooldefget_order_status(order_id:str)-str:查询订单状态和物流信息。仅用于售后咨询。# SELECT status, tracking FROM orders WHERE order_id {order_id}pass# 受控写入工具中风险需要确认tooldefcreate_return_request(order_id:str,reason:str)-str:创建退换货申请。需要用户确认后才能调用。# INSERT INTO returns (order_id, reason, status) VALUES ...pass# 高风险操作需要Human-in-the-Looptooldefescalate_to_human(reason:str)-str:将对话转接给人工客服。用于复杂问题。# 触发转人工流程pass5.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.md6.2 环境配置# .env.example# LangChainLANGSMITH_API_KEYyour_langsmith_keyLANGSMITH_TRACINGtrueLANGSMITH_PROJECTcs-agent# 模型LLM_API_KEYyour_deepseek_keyLLM_BASE_URLhttps://api.deepseek.comLLM_MODELdeepseek-v4-flash# 数据库DATABASE_URLpostgresql://agent:passlocalhost:5432/cs_agent# RedisREDIS_URLredis://localhost:6379/0# 向量数据库VECTOR_STORE_PATH./chroma_db6.3 依赖清单# requirements.txt # Core langchain1.0.0 langgraph1.0.0 langchain-openai1.0.0 langchain-community1.0.0 # Web fastapi0.115.0 uvicorn[standard]0.30.0 pydantic2.0.0 # Database asyncpg0.29.0 pgvector0.2.5 sqlalchemy2.0.0 # Vector DB chromadb0.5.0 # Async celery5.3.0 redis5.0.0 # Observability langsmith0.1.0 langfuse2.0.0 # Utils python-dotenv1.0.0 python-multipart0.0.96.4 核心配置类# app/config/settings.pyfrompydantic_settingsimportBaseSettingsclassSettings(BaseSettings):应用配置# LangSmithlangsmith_api_key:strlangsmith_tracing:boolTruelangsmith_project:strcs-agent# LLMllm_api_key:strllm_base_url:strhttps://api.deepseek.comllm_model:strdeepseek-v4-flashllm_temperature:float0.3# Embeddingembedding_model:strtext-embedding-3-small# Databasedatabase_url:strpostgresql://agent:passlocalhost:5432/cs_agent# Redisredis_url:strredis://localhost:6379/0# Vector Storevector_store_path:str./chroma_db# Agentmax_iterations:int10max_tokens_per_session:int50000cost_budget_per_session:float0.5# USDclassConfig:env_file.envsettingsSettings()七、动手搭建项目骨架本节动手任务完成项目的初始化搭建为下一节的完整开发做好准备。任务清单任务说明状态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基础版本☐快速启动脚本#!/bin/bash# scripts/setup.shecho 初始化智能客服Agent项目...# 1. 创建虚拟环境python-mvenv venvsourcevenv/bin/activate# 2. 安装依赖pipinstall-rrequirements.txt# 3. 复制环境配置cp.env.example .envecho⚠️ 请编辑.env文件填写API Key# 4. 启动依赖服务docker-composeup-dpostgres redis# 5. 初始化数据库python scripts/init_db.py# 6. 加载示例知识库python scripts/load_knowledge.py--sampleecho✅ 项目初始化完成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节的完整内容系列文章持续更新中关注我不迷路