基于 LangGraph 构建的全功能 AI Agent 系统

这是一个基于 LangGraph + FastAPI + Next.js 的 AI Agent 项目，完整实现了对话、记忆、工具调用、MCP 集成、知识库（文档解析、分片、增量更新、混合检索、精排）、流式输出、多用户认证和会话管理等核心模块。整个系统通过 Docker Compose 编排为 4 个容器，开箱即用，根据业务需求定制后可直接部署到生产环境。

1. 项目架构

4 个 Docker 容器，使用 docker compose up 部署。FastAPI 后端跑 LangGraph Agent，Next.js 前端做交互，FastMCP 服务提供业务数据交互能力，PostgreSQL（pgvector 扩展）统一承载数据存储——业务数据、RAG 向量化存储、长期记忆、对话检查点，在一个数据库中，无需额外维护 Redis 或者 Milvus。

2. 核心能力

2.1 带循环的 Agent 工作流

基于 LangGraph StateGraph 构建，不是线性的 chain，而是一个可循环的有向图。LLM 推理后如果需要调工具，执行完结果送回来继续推理，可根据需要多次调用工具，直到它认为可以直接回答用户了才结束。

实际场景里用户经常一句话包含多个意图（”查一下北京和上海的天气”），Agent 需要连续调用多次工具再整合回答，线性 chain 做不了这个事。

更典型的场景是跨工具的链式推理——用户说”帮我查一下上个月各区域的销售数据，找出业绩最差的区域，我下周要过去出差，顺便看看那边天气怎么样”，Agent 需要先调 MCP 查销售报表，从结果中提取出目标城市，再调天气工具查询，最后把两步结果整合成一个完整的回答。这种多步骤、有依赖关系的任务，只有循环图结构才能自然表达。

记忆层把 Agent 夹在中间——进来先召回长期记忆注入上下文，出去时提取新的记忆存储。Agent 本身不用关心记忆管理，专注推理和工具调用。

2.2 三层记忆体系

项目实现了三层记忆体系，覆盖从当前会话级、用户级跨会话、企业级RAG知识库的完整记忆链路：

短期记忆：LangGraph Checkpointer 自动保存完整消息历史到 PostgreSQL，发送给 LLM 时经过合理的裁剪到最近 20 条，防止 token 超限，也不会丢失早期消息。

长期记忆：集成 Mem0，按用户维度跨会话持久化。每轮对话结束后自动提取关键事实（姓名、偏好、职业），下次对话开始时语义召回注入上下文。用户在 A 会话说”我是做前端的”，B 会话里 Agent 也知道。

这里做了一个关键优化：通过自定义提取指令，让 Mem0 只记”关于用户的事”，跳过工具返回的临时数据（天气结果、销售报表之类的）。不做这个过滤的话，长期记忆里全是噪音。

知识记忆：RAG 知识库，全局共享，所有用户都能查。

2.3 混合 RAG 检索 + 精排

纯向量检索有个常见问题：用户搜”退换货政策第三条”，向量可能返回语义相近但不对的内容。纯关键词检索又搞不定”这个东西坏了怎么办”这种模糊表述。两种方式各有短板，向量检索和关键词检索一起的混合检索的效果更好。

第一阶段粗召回：PGVector 向量检索和 BM25 关键词检索并行执行，用 RRF 加权融合去重，两种不同量纲的结果统一排序。

第二阶段精排：融合结果送给 Rerank 交叉编码器（bge-reranker-v2-m3）做精排，取 top 5。交叉编码器同时看 query 和 document 的交互信息，精度远超粗召回阶段的独立编码。

BM25 部分用 jieba 做中文分词，索引在知识库处理完成后立即重建，不在用户查询时懒加载，避免第一个请求卡很久，确保性能达到要求。

2.4 知识库全生命周期管理

不只是”导入文档”这么简单。完整实现了文档的解析、切片、入库、增量更新、删除的全流程。

两级切片：先按 Markdown 标题结构拆分，再对超长块二次切分。最后把标题层级注入到 chunk 文本前面——一个内容是”电池容量 5000mAh”的 chunk，注入后变成 [智能手表 > 规格说明] 电池容量 5000mAh，embedding 语义精确很多。

增量更新：MD5 对比文件变更，只处理新增、修改和删除的文档，不需要每次全量重新导入。前端有知识库管理界面，一键检查更新和处理。

按目录分知识库：rag_files/ 下每个子目录就是一个知识库，放进去 Markdown 文件就行，不需要额外配置。

2.5 工具调用 + MCP 动态扩展

内置了天气查询、IP 查询、RAG 知识库搜索三个基础工具。业务数据查询通过 MCP 协议接入——单独部署一个 FastMCP 服务容器，Agent 启动时自动发现和注册。

要加新的数据查询能力，在 MCP 服务里写个函数就行，Agent 不用改任何代码，重启自动加载。业务数据接入和 Agent 核心完全解耦，这在实际项目中很重要——数据侧和 AI 侧可以独立迭代。

2.6 流式输出 + 全链路追踪

通过 SSE 实现了 Agent 关键节点的事件输出，前端可以实时展示当前 Agent 正在执行的环节——记忆召回、LLM 推理、工具调用、记忆存储，每个阶段的状态变化都有对应事件推送。具体包括：

• 工具调用的开始和结束事件（前端实时展示”正在查询天气…”等执行状态）
• 逐 token 的文字流
• token 用量统计和各环节耗时（LLM 推理、工具执行、记忆处理分别花了多久）
• 自动生成的会话标题

统计数据持久化到数据库，方便后续分析调用成本。前端的消息气泡底部会显示类似 “856 tokens · LLM 2.3s · 工具 0.8s” 的信息。

2.7 认证与配置

用户认证（JWT + users.json）和模型配置（llm.json）都通过配置文件管理，没有硬编码在代码里。会话按用户隔离，模型全部走 OpenAI 兼容协议，换 DeepSeek、Qwen、GPT 或自部署的 vLLM 只需改配置文件。这两部分刻意做得简单，方便对接业务系统的用户体系和数据库时进行二次开发。

3. 业务接入与扩展

这个项目的每个模块都是可以独立替换和扩展的：

换 LLM：改 llm.json，加一个模型配置就行。只要是 OpenAI 兼容的 API 都能接。

接业务数据：在 MCP 服务里加工具函数。查数据库也好、调内部 API 也好，包装成 MCP tool 就能被 Agent 自动使用。

换知识库内容：把 Markdown 文档扔到 rag_files/ 对应目录下，前端点”检查更新”触发增量处理。

加新的内置工具：用 LangChain 的 @tool 装饰器写一个函数，注册到 BUILTIN_TOOLS 列表。

调整检索策略：RRF 融合权重、粗召回数量、Rerank top_n 这些参数都是可配置的。甚至可以关掉 BM25 或 Rerank 只用向量检索。

改前端 UI：基于 Next.js + shadcn/ui，组件化结构清晰。聊天区域、侧边栏、模型选择器、知识库管理都是独立组件。

4. 技术选型

模块	选型	理由
Agent 框架	LangGraph StateGraph	循环工作流 + Checkpointer + 事件流
LLM 协议	OpenAI 兼容	一套代码适配所有主流模型
长期记忆	Mem0 库模式	自动提取 + 去重更新，开箱即用
向量存储	PGVector	跟业务库统一，少一个组件
关键词检索	BM25 + jieba	精确匹配补位，中文友好
精排	bge-reranker-v2-m3	交叉编码器，精度高
工具扩展	FastMCP (HTTP)	独立部署，动态加载
后端	FastAPI + SSE	原生异步，流式推送
前端	Next.js + Zustand	SSR/SSG + 轻量状态管理
数据库	PostgreSQL + pgvector	一库搞定所有存储
部署	Docker Compose	4 容器，一键拉起

5. 总结

这是一个功能完善，细节慢慢的，契合当前很多企业项目需求适合二开的项目，对话、记忆、工具调用、MCP、知识库（解析、切片、增量更新、混合召回、精排）、流式输出、多用户认证、会话管理、Docker 部署——这些模块都是完整跑通，不是写了一半的 TODO。

如果你打算基于 LangChain / LangGraph 做自己的 Agent 应用，这个项目可以省掉你搭骨架的时间，直接可以在这个骨架上接入业务需求即可。

项目源码获取：

---

技术栈：LangGraph / FastAPI / Next.js / PostgreSQL / Mem0 / FastMCP