LangGraph从零构建生产级 AI Agent 平台的递进式学习项目

逐步深入，最终实现系统化掌握 LangGraph 核心概念，从基础 Graph 编排出发，逐步深入 Tool Calling、Memory 架构、Reasoning Agent、Multi-Agent 协作，最终整合为一个包含 Web UI、Streaming、Human in the Loop、Checkpoint 持久化和 LangSmith 可观测性的"生产级 AI Agent 平台"。

二、项目特色与学习路径

（一）基本特色

6 阶段递进学习: 每个阶段独立可运行，由浅入深，循序渐进
26 个可运行 Demo: 每个知识点都有可直接执行的代码演示
Mock LLM 支持: 无 API Key 也能运行所有 Demo，聚焦理解 Graph 执行流程
七要素文档体系: 每个模块覆盖 "为什么存在 → 核心原理 → 源码分析 → 实战代码 → 工程化问题"
生产级平台: 含 FastAPI + SSE 流式 + HITL 审批 + LangSmith 可观测性的完整系统

（二）学习路径

Stage 1: LangGraph 基础（5 个 Demo）

StateGraph / Node / Edge / Conditional Edge / MessagesState

│

▼

Stage 2: Tool Calling（5 个 Demo）

@tool 装饰器 / Tool Agent / 错误处理 / 自定义工具 / 多工具协作

│

▼

Stage 3: Memory 架构（6 个 Demo）

短期记忆 / Checkpoint / Redis / PostgreSQL / 向量语义记忆 / 摘要记忆

│

▼

Stage 4: Reasoning Agent（5 个 Demo）

ReAct / Planning / Reflection / Self-Correction / Tree of Thought

│

▼

Stage 5: Multi-Agent（5 个 Demo）

Supervisor-Worker / Router / Handoff / 共享记忆 / Agent 团队

│

▼

Stage 6: 生产级平台（agent_platform/）

FastAPI + Web UI + SSE Streaming + HITL + Checkpoint + LangSmith 可观测性

（三）项目结构

后续更新对应的代码仓库，此处保留思路项目安排：

zyf-langgraph/

├── shared/ # 公共库（LLM Factory、配置、日志、Mock LLM）

│ ├── init.py # 统一导出

│ ├── config.py # 配置管理（Pydantic BaseSettings）

│ ├── llm_factory.py # 多模型切换抽象工厂

│ ├── mock_llm.py # Mock LLM 实现

│ ├── logging_utils.py # 结构化日志

│ └── env_check.py # 环境检查工具

├── stages/ # 学习阶段（Stage 1-5）

│ ├── stage1_fundamentals/ # Stage 1: LangGraph 基础（5 Demo）

│ ├── stage2_tool_calling/ # Stage 2: Tool Calling（5 Demo）

│ ├── stage3_memory/ # Stage 3: Memory 架构（6 Demo）

│ ├── stage4_reasoning/ # Stage 4: Reasoning Agent（5 Demo）

│ └── stage5_multi_agent/ # Stage 5: Multi-Agent（5 Demo）

├── agent_platform/ # 生产级平台 (Stage 6)

│ ├── api/ # FastAPI 路由 + 依赖注入

│ ├── engine/ # Agent 引擎 + Graph Registry

│ ├── memory/ # 持久化（Redis / PostgreSQL / ChromaDB）

│ ├── hitl/ # Human in the Loop 审批

│ ├── observability/ # 健康检查 + LangSmith

│ └── ui/ # Web UI 静态文件

├── tests/ # 测试

│ ├── test_shared/ # 公共库测试

│ ├── test_stages/ # Demo 测试

│ └── test_platform/ # 平台测试

├── scripts/ # 工具脚本

├── docs/ # 补充文档

│ ├── TROUBLESHOOTING.md # 排障指南

│ └── LLM_PROVIDERS.md # LLM Provider 切换指南

├── pyproject.toml # 项目配置 + 依赖管理

├── docker-compose.yml # 基础设施（Redis、PostgreSQL、ChromaDB）

├── Makefile # 常用命令

├── .env.example # 环境变量模板

（四）技术栈说明与环境要求

1. 技术栈总览

分类	技术组件	版本要求	说明
AI 工作流框架	LangGraph	≥ 0.2	核心 AI Workflow / Agent 编排框架
LLM 编排框架	LangChain	≥ 0.3	Tool Calling、Prompt、Model 抽象层
大语言模型	OpenAI / DeepSeek / Claude / Gemini / Ollama / Mock	-	支持云端与本地模型
Web 框架	FastAPI	最新稳定版	提供 REST API 与 AI 服务接口
流式推送	sse-starlette	最新稳定版	支持 SSE 流式响应
关系型数据库	PostgreSQL	16	工作流状态与业务数据存储
缓存 / Memory	Redis	7	Session、Memory、Checkpoint
向量数据库	ChromaDB	最新稳定版	RAG 向量检索
可观测性	LangSmith	最新稳定版	Trace、调试、链路观测
测试框架	pytest	最新稳定版	单元测试
覆盖率测试	pytest-cov	最新稳定版	测试覆盖率统计
异步测试	pytest-asyncio	最新稳定版	Async 测试支持
HTTP 测试	httpx	最新稳定版	API 集成测试
代码质量	ruff	最新稳定版	lint + format
容器化部署	Docker Compose	V2	本地开发与部署
Python	Python	≥ 3.12	推荐使用 3.12.x

2. 环境要求

|----------------|--------|--------|
| 依赖项 | 版本要求 | 用途说明 |
| Python | ≥ 3.12 | 核心运行环境 |
| Docker | ≥ 24.0 | 容器化部署 |
| Docker Compose | V2 | 多容器编排 |
| Git | ≥ 2.0 | 代码版本管理 |

3. 推荐开发环境

|------------|---------------------------|
| 工具 | 推荐 |
| IDE | PyCharm / VSCode / Cursor |
| Python 管理 | pyenv |
| 包管理 | uv / poetry |
| API 调试 | Apifox / Postman |
| 数据库管理 | DBeaver |
| Docker GUI | Docker Desktop |

三、LangGraph 实战系列文章目录（推荐顺序）

序号	文章标题	学习阶段	链接跳转
01	从零认识 LangGraph：用 30 行代码构建你的第一个 AI Graph	基础认知	从零认识 LangGraph：用 30 行代码构建你的第一个 AI Graph