从底层范式理解 Agent 编排：状态图 + 节点 + 条件边。
本项目是一套从零到生产的多智能体系统实战教程：以 LangChain / LangGraph 为载体，带你吃透 Agent 编排的底层范式（状态图 + 节点 + 条件边），并落地一整套生产级工程能力——持久化记忆（checkpoint）、人工介入（HITL）、可溯源的记忆独立层、MCP 工具接口、多智能体协作（A2A）、服务化部署与可观测性。它既是一条循序渐进的学习路径，也是一份可直接演示的生产级多智能体系统样板。
项目定位 / Positioning：本仓库脱胎于 LangChain 官方教程的工程化封装与扩展——我据此吃透了 LangGraph 状态机、checkpoint、HITL 的底层原理，并补齐了原教程缺失的生产要素（记忆独立层、MCP 通信底座、部署与可观测性）。面试中若被问「是否独立设计」，请诚实说明这一点；重点应放在你真正吃透并可深挖的原理上。与自研内核项目（如「灵犀」）的关系是互补：一个证明「会用框架快速落地」，一个证明「能自研底层」。
我们认为：市面主流 Agent 框架（CrewAI、AutoGen 等）的底层逻辑，都可以映射到 LangGraph 的 状态图（StateGraph）+ 节点（Node）+ 条件边（Conditional Edge） 模型。掌握 LangChain 与 LangGraph，就等于掌握了 Agent 编排的底层范式。
- 本文档提供双语：简体中文（默认）与 English（
/en/）。 - This project is bilingual: Simplified Chinese (default) and English (
/en/).
本仓库提供编辑器无关的 Makefile，在 PyCharm / WebStorm 终端、VS Code 或 CI 中都能直接运行：
make setup # 创建 .venv 并安装 Python + Node 依赖，复制 .env
make docs # 构建双语文档站 -> docs/.vitepress/dist
make docs-dev # 本地实时预览 http://localhost:5173
make run p=1 # 运行 Phase 1 示例（p=2..13 同理，需先配置 .env，见下方「配置大模型」）
make lint # 对所有示例做语法校验💡 环境就绪后，先看文档再动手（推荐）：上面 make setup 装好 Node 依赖后，运行 make docs-dev（或 npm run docs:dev）即可在浏览器打开 http://localhost:5173 阅读教程——文档站对每个 Phase 的原理、代码、验收清单都有详细说明。建议按 Phase 顺序读完对应章节，再回来 make run p=N 跑示例，效果更佳。
IDE 用法（PyCharm + WebStorm）：Python 代码用 PyCharm 打开项目根目录即可识别
examples/；文档站用 WebStorm 打开docs/，或在 PyCharm 终端跑make docs-dev。两者都自带 Terminal，可直接执行上面的make命令。开发环境要求：Python 3.13+、Node 22+。
很多人看到 README 一长串命令，会误以为「快速开始」跑完项目就结束了。并不是。 本 README 的区块分三类，请先建立这个整体认知再动手：
1. 环境准备（一次性）
- 「快速开始（推荐一键）」：用
Makefile装好 Python+Node 环境、复制.env，并告诉你有哪些make命令。它只装环境，不含任何学习内容。 - 「配置大模型（.env）」：上一步复制出的
.env默认指向本地 Ollama，需按实际情况改成 Ollama / DeepSeek / OpenAI。跑示例前的必做配置。
2. 真正的学习内容（核心）
- 「学习路线（13 个 Phase）」：P1–P9 循序渐进讲 Agent 编排基础（状态图 + 节点 + 条件边），P10/P11/P12/P13 为进阶实战（记忆独立层 / MCP 工具接口 / 多智能体协作 A2A / A2A 标准协议）；每个 Phase 配原理讲解、示例代码与验收清单。这才是你要"学"的部分。
3. 可选 / 维护向（普通学习者可跳过）
- 「运行示例」「本地预览文档站」：分别是
make run p=N和make docs-dev的手动等价写法（裸pip/python/npm命令）。你用make就不用看它们。 - 「部署文档站（GitHub Pages）」：把站点发布到公网，仅仓库维护者需要。
推荐学习顺序：
make setup # 1. 装好环境（一次性）
# 然后编辑 .env 选好大模型（见「配置大模型」）
make docs-dev # 2. 打开 http://localhost:5173 读 Phase 1 讲解
make run p=1 # 3. 跑 Phase 1 示例验证理解
# 4. 按 P1 -> P13 重复 2 -> 3，直到学完整个项目（P10/P11/P12/P13 为进阶，可按需深入）一句话：快速开始 = 把工具装好；13 个 Phase = 真正要学的课程（P1–P9 基础，P10/P11/P12/P13 进阶实战）；运行示例 / 本地预览 = 怎么用工具；部署 = 把成果公开。 跑完快速开始只是刚进门。
⚠️ 运行示例前必须完成这一步。 上面的make setup已经自动从.env.example复制出了.env，但它的默认值是LLM_PROVIDER=ollama——如果你没启动本地 Ollama 就直接make run，会报httpx.ConnectError: [Errno 61] Connection refused。请按下面二选一编辑.env（例如nano .env或直接在编辑器打开），再回来跑示例。
- 安装 Ollama：Homebrew
brew install ollama，或前往 https://ollama.com 下载 App。 - 启动服务：打开 Ollama App 即自动后台启动；命令行则
ollama serve &。 - 拉取模型：
ollama pull qwen2.5:7b # 对话模型（Phase 1–9 通用） ollama pull nomic-embed-text # 嵌入模型（Phase 2 RAG 章节需要）
- 在
.env中确认：LLM_PROVIDER=ollama - 验证服务已起来：
curl http://localhost:11434 # 返回 "Ollama is running" 即正常
编辑 .env，三选一：
# DeepSeek（便宜、国内可达，推荐）
LLM_PROVIDER=deepseek
DEEPSEEK_API_KEY=你的key
# 通义千问 Qwen（阿里 DashScope，贴合「自主可控 / 国产模型」）
LLM_PROVIDER=qwen
QWEN_API_KEY=你的key
# 或 OpenAI
# LLM_PROVIDER=openai
# OPENAI_API_KEY=你的key用云端 API 时无需安装/启动 Ollama，示例会直接走官方或兼容接口。配置好
.env后即可make run p=N。
下面章节为等价的手动步骤。
| Phase | 主题 |
|---|---|
| 1 | LangChain 核心概念与开发环境（含可跳过速补） |
| 2 | Chains、Memory 与 RAG 基础 |
| 3 | Agent 原理：从 ReAct 到自主循环 |
| 4 | Tools 与 Function Calling |
| 5 | 多 Agent 协作范式与主流框架对比 |
| 6 | LangGraph 图编排核心 |
| 7 | 状态、记忆与 Human-in-the-loop |
| 8 | 生产部署实战 |
| 9 | Capstone 综合实战与全景复盘 |
| 10 | 记忆独立层：episodic + semantic + 溯源（防幻觉） |
| 11 | MCP 工具接口：让智能体调用标准协议工具 |
| 12 | 多智能体协作（A2A）：supervisor + worker 原生多智能体 |
| 13 | A2A 标准协议：Agent Card + JSON-RPC 跨进程互联 |
- 安装依赖：
python -m venv .venv && source .venv/bin/activate pip install -r requirements.txt
- 复制并配置环境变量：
cp .env.example .env # 编辑 .env，选择 LLM_PROVIDER（openai / deepseek / qwen / ollama） - 运行示例（以 Phase 1 为例）：
python -m examples.p1.hello_chain
仓库根目录的 verify.sh 会依次运行 Phase 10–13，并对照各示例的关键输出标记判断跑通与否（不依赖具体回答，因为 LLM 输出非确定）。需先 make setup 且 .env 已配好可用 provider。
./verify.sh # 依次验证 Phase 10 -> 13
./verify.sh 11 # 只验证单个 Phase
./verify.sh 10 13 # 只验证指定的几个 Phase每个 Phase 会真正调用 LLM，耗时取决于模型响应速度（默认超时 360s，可在脚本内调整）。判分依据是打印出的关键标记，而非回答内容本身。
npm install
npm run docs:dev # 开发预览
npm run docs:build # 构建静态站文档站通过 GitHub Actions 自动构建并部署到 GitHub Pages，无需手动上传。
- 在仓库 Settings → Pages → Source 选择 GitHub Actions（仅需设置一次）。
- 推送
main分支即触发部署：make deploy-docs # = npm run docs:build + git push origin main - 部署完成后，站点地址为：
https://shadowquill.github.io/langchain-langgraph-tutorial/
部署工作流见
.github/workflows/deploy-docs.yml；docs/.vitepress/config.ts中的base已按仓库名langchain-langgraph-tutorial配置好，无需改动。
所有示例通过一个统一的 LLM Provider 抽象层（examples/common/llm.py）切换模型：
openai：官方 OpenAI（默认），需OPENAI_API_KEY。deepseek：DeepSeek，OpenAI 兼容接口，需DEEPSEEK_API_KEY。qwen：通义千问（阿里 DashScope，OpenAI 兼容接口），需QWEN_API_KEY，贴合「自主可控 / 国产模型」。ollama：本地 Ollama，免 key，前几章推荐用于零门槛体验。
详见 .env.example 与各 Phase 文档。