从零到生产的 Agent Platform 完整学习路线
图文文档 + 代码导读 + 20+ 个可运行示例 + 多 Agent 工作流系统 + 生产部署实战
大多数 AI Agent 框架（CrewAI、AutoGen、Dify）的底层逻辑，都可以映射到 LangGraph 的 状态图 + 节点 + 条件边 这套模型。掌握 LangChain + LangGraph，就掌握了 Agent 编排的底层范式。
LangChain → 解决"调用 LLM" → prompt | model | parser（线性管道）
LangGraph → 解决"控制 LLM" → StateGraph 有向图（循环 + 分支 + 持久化）
两者共享 langchain-core 基础设施，不是替代，而是从简单到复杂的连续谱
|
LangChain 分层架构
|
LCEL 管道组合
|
|
LangGraph StateGraph
|
多 Agent Supervisor 模式
|
RAG 检索增强生成（点击展开）
文档加载 → 文本分割 → 向量嵌入 → 存入向量库 → 检索 + LLM 生成回答
基础 进阶 生产
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Phase 1-2 Phase 3 Phase 4-5 Phase 6 Phase 7-9
LangChain 核心 Agent+Tools LangGraph 图编排 进阶 & 部署 Agent Platform
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ ┌──────────────┐
│ Runnable │ │ @tool │ │ State │ │ interrupt() │ │ Observability │
│ LCEL │───▶│ ReAct │───▶│ Node │───▶│ Checkpoint │───▶│ Evaluation │
│ Prompt │ │ Agent │ │ Edge │ │ Streaming │ │ Deployment │
│ RAG │ │ 结构化输出│ │ 条件路由 │ │ Subgraph │ │ (LangGraph) │
└──────────┘ └──────────┘ └──────────┘ │ Swarm │ └──────────────┘
│ 部署 │
└──────────────┘
| # | 文档 | 内容 | 难度 |
|---|---|---|---|
| 00 | 学习路线总览 | 9 个 Phase 完整规划，模块-知识点-代码映射 | - |
| 01 | LangChain 核心 | Runnable / LCEL / ChatModel / Prompt / RAG / Agent | 入门 |
| 02 | LangGraph 核心 | StateGraph / Node / Edge / Reducer / Checkpoint / 多Agent | 入门 |
| 03 | 架构总览 | 两者关系、选型指南、本项目架构解析 | 入门 |
| 04 | 代码导读 | 每个文件的关键行号标注，建议阅读顺序 | 入门 |
| 05 | 进阶专题 | HITL / Checkpoint / Streaming / Subgraph / Swarm / 部署 | 进阶 |
| 06 | FAQ & 踩坑指南 | 17 个常见错误的症状、原因、修复 + 调试技巧速查表 | 全阶段 |
| 07 | Agent 可观测性 | LangSmith / OpenTelemetry / Node Metrics / 结构化日志 | 进阶 |
| 08 | Agent 评估体系 | RAGAS / 自定义 Eval Pipeline / CI 集成 / 断言测试 | 进阶 |
| 09 | 生产部署实战 | langgraph.json / Docker Compose / LangGraph Cloud / Server API | 进阶 |
| 步骤 | 示例 | 你将学到 | 难度 |
|---|---|---|---|
| 1 | simple_chatbot.py | StateGraph + Node + Edge 最小可运行图 | ★ |
| 2 | agent_with_tools.py | @tool + bind_tools() + 条件路由 |
★★ |
| 步骤 | 示例 | 你将学到 | 难度 |
|---|---|---|---|
| 3 | conditional_flows.py | 4 路条件分支 add_conditional_edges |
★★ |
| 4 | loops_and_iteration.py | 循环迭代 + 收敛检测 + 防无限循环 | ★★★ |
| 5 | error_handling.py | 错误恢复 + 重试 + 指数退避 | ★★★ |
| 6 | role_based_agents.py | Supervisor 模式: Coordinator ↔ Workers 循环 | ★★★ |
| 7 | message_passing.py | Agent 间消息总线通信 | ★★★ |
| 8 | file_tools.py | MCP 工具定义 + StateGraph 集成 | ★★★ |
| 9 | demo.py | 完整多 Agent 工作流系统 | ★★★★ |
Phase 6: 进阶 → 生产 (进阶专题文档)
| 步骤 | 示例 | 你将学到 | 难度 |
|---|---|---|---|
| 10 | checkpoint_memory.py | MemorySaver 多轮记忆 + Thread 隔离 + 时间旅行 | ★★★ |
| 11 | human_in_the_loop.py | interrupt() 暂停 + Command(resume) 恢复 + 审批流 |
★★★ |
| 12 | streaming_output.py | 4 种 stream_mode + astream_events 逐 token 流式 |
★★★ |
| 13 | subgraph_composition.py | 共享/不同 Schema 子图 + State 转换 + 子图流式事件 | ★★★★ |
| 14 | swarm_agents.py | Command(goto=) Agent 间 handoff + 防无限循环 |
★★★★ |
| 步骤 | 示例 | 你将学到 | 难度 |
|---|---|---|---|
| 15 | langsmith_tracing.py | LANGCHAIN_TRACING_V2 自动追踪 + 环境配置 |
★★ |
| 16 | opentelemetry_tracing.py | 手动 Span 创建 + ConsoleSpanExporter 本地观测 |
★★★ |
| 17 | ragas_evaluation.py | RAGAS 信仰度/相关性/context 相关性评估 | ★★★ |
| 18 | custom_eval_pipeline.py | 纯 Python 自定义 Eval Pipeline (轨迹评分) | ★★★ |
| 19 | examples/platform/langgraph_server/ | langgraph.json + Docker Compose + Server API |
★★★ |
对应文档：
遇到问题？查看 FAQ & 踩坑指南 — 17 个常见错误的症状、原因、一行修复
一个完整的 LangGraph 生产级示例，展示了条件路由、循环重试、MCP 工具集成等核心模式。
START → task_assigner → tool_selector ─┬─ mcp_executor → executor → reviewer ─┬─ END
│ │
└─ executor (直接) ────────────────────│
│
retry (< 6分且 < 2次) ─┘
| LangGraph 模式 | 代码位置 | 说明 |
|---|---|---|
| State 定义 + 归约器 | src/models/states.py |
Annotated[List, operator.add] |
| StateGraph 构建 | src/workflow/orchestrator.py |
5 节点 + 2 条件路由 |
| Agent 节点 | src/agents/task_assigner.py |
LLM 任务分类 |
| MCP 工具链路 | src/mcp/ |
注册 → 选择 → 并行执行 |
完整项目结构（点击展开）
ai-agent-langgraph/
├── docs/ # 学习文档 (10 篇 + 13 张图示)
│ ├── 00 ~ 05 # 学习路线/核心概念/进阶专题
│ ├── 06-faq-and-pitfalls.md # FAQ & 踩坑指南
│ ├── 07 ~ 09 # 可观测性 / 评估 / 生产部署
│ └── images/ # 13 张配图
├── src/ # 多 Agent 工作流系统
│ ├── models/ # State 定义 (base.py, states.py)
│ ├── agents/ # Agent 节点 (task_assigner.py)
│ ├── mcp/ # MCP 工具 (client, registry, selector, executor)
│ ├── utils/ # 状态管理 (state_manager.py)
│ └── workflow/ # 图编排 (orchestrator.py)
├── examples/ # 20+ 个可运行示例
│ ├── basic_agent/ # 基础 Agent (chatbot, tools)
│ ├── multi_agent/ # 多 Agent (supervisor, message passing)
│ ├── complex_workflow/ # 复杂工作流 (条件/循环/错误处理)
│ ├── mcp_integration/ # MCP 集成 (file tools)
│ ├── advanced/ # 进阶 (checkpoint/HITL/streaming/subgraph/swarm)
│ └── platform/ # 平台能力 (观测/评估/部署)
├── config/ # 配置 (.env.example)
├── demo.py # 完整系统演示
├── langgraph.json # LangGraph Server 入口配置
├── Dockerfile # 多阶段构建
├── docker-compose.yml # 本地 production-like 部署
└── requirements.txt # 依赖 (带中文注释)
# 1. 克隆项目
git clone https://github.com/kevinten-ai/ai-agent-langgraph.git
cd ai-agent-langgraph
# 2. 环境准备
python -m venv venv && source venv/bin/activate
# 3. 安装依赖
pip install -r requirements.txt
# 4. 配置 API Key
cp config/.env.example config/.env
# 编辑 config/.env，填入 OPENAI_API_KEY
# 5. 运行第一个示例
python examples/basic_agent/simple_chatbot.py
# 6. 运行完整系统演示
python demo.py| 依赖 | 用途 |
|---|---|
langgraph |
核心: StateGraph, 条件路由, Checkpoint |
langchain-core |
基础: Runnable, Messages, Tools |
langchain-openai |
LLM: ChatOpenAI |
langchain-community |
社区集成: DocumentLoaders, VectorStores |
pydantic |
状态模型定义与验证 |
- LangChain Academy: Intro to LangGraph — 官方免费课程
- LangChain 文档 / LangGraph 文档
- LangGraph GitHub / MCP 协议
MIT