目录
一、为什么写这个系列？
二、项目特色与学习路径
（一）基本特色
（二）学习路径
（三）项目结构
（四）技术栈说明与环境要求
1. 技术栈总览
2. 环境要求
3. 推荐开发环境
三、LangGraph 实战系列文章目录（推荐顺序）
从原理到工程化，从单节点 Agent 到复杂工作流，系统学习 LangGraph 的完整实践路线。
一、为什么写这个系列？
随着 AI Agent、Workflow、Multi-Agent 与 LLM 应用编排的快速发展，单纯“写一段 Prompt 再单次调用模型”的范式，已经很难撑起真实业务系统。
LangGraph 出现的意义，本质上是在回答一个问题：怎样让大模型应用真正“跑得起来、管得过来”。
- 大模型应用如何“状态化”：用 State 把上下文固定下来；
- 多步骤推理如何“流程化”：用边把节点串成可控的图；
- Agent 如何“可控”：用条件路由在关键点让人或规则介入；
- 工作流如何“工程化”：用统一编排替代零散脚本；
- AI 系统如何“长期运行”：用 Checkpoint 与持久化支撑长跑任务。
它远不止是一个 Prompt 框架，更像是一整套面向 Agent 的工程底座。
- AI 工作流引擎
- Agent 编排框架
- LLM 状态机
- AI Runtime
- AI Orchestration Layer
整个系列按由浅入深的顺序展开，依次覆盖核心原理、Graph 机制、State 状态管理、条件路由、Memory、Tool Calling、Multi-Agent 协作，最终整合成一个具备 Web UI、Streaming 与 Human-in-the-Loop 的生产级平台。
- 核心原理
- Graph 机制
- State 状态管理
- 条件路由
- Memory
- Tool Calling
- Multi-Agent
- 工作流设计
- 企业级工程化
沿着这条路走下去，目标是系统化掌握 LangGraph：从最基础的 Graph 编排，到 Tool Calling、Memory 架构、Reasoning Agent、Multi-Agent 协作，最后整合成一个带 Web UI、SSE 流式、人机审批与 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
02|
深入 LangGraph State：Reducer 是如何让状态“自动合并”的
| 基础认知| 深入 LangGraph State：Reducer 是如何让状态“自动合并”的-CSDN博客
03|
LangGraph 条件边：让 AI Agent 学会“做选择”
| 基础认知| LangGraph 条件边：让 AI Agent 学会“做选择”-CSDN博客
04|
LangGraph MessagesState：用 add_messages 优雅管理 LangGraph 多轮对话
| 基础认知| LangGraph MessagesState：用 add_messages 优雅管理 LangGraph 多轮对话-CSDN博客
05|
可视化 LangGraph：让你的 AI Agent 图表「看得见」
| 基础认知| 可视化 LangGraph：让你的 AI Agent 图表「看得见」
06|
LangGraph Tool Calling 入门：从 @tool 到完整调用链
| Tool Calling| LangGraph Tool Calling 入门：从 @tool 到完整调用链-CSDN博客
评论0