LangGraph Agent 实战

从「LangChain 出零件」到「LangGraph 控流程」—— 手把手还原一个带工具调用的 Agent 到底怎么跑。

用最少依赖讲清楚 Agent 的两个层次：

• 离线：不接任何模型，纯手跑 StateGraph（图编排 / 状态流转 / 条件边 / checkpoint 持久化）
• 在线：接真实 LLM，手写 ReAct 工具调用循环（模型 → 调工具 → 回填 → 结束）

关键词：LangGraph · LangChain · ReAct · Function Calling · StateGraph · SqliteCheckpoint

---

为什么做这个

面试/自学时，"我懂 Agent" 很容易被一句"那你讲讲 ReAct 循环底层怎么实现的"问倒。这个仓库用两个能跑的最小 demo，把 Agent 的核心机制从黑白盒翻出来：

demo	接模型？	讲清楚什么
demo.py	❌ 离线	StateGraph 图编排、共享状态、条件边、Sqlite checkpoint 持久化与恢复
demo_agent.py	✅ 接 DeepSeek	真实 ReAct 循环（模型 → 调工具 → 回填 ToolMessage → 模型 → … → 结束），跑在 StateGraph 图上

---

快速开始

环境（Windows，已验证 2026-08）

uv venv --python 3.11                       # 务必用 3.11+（本机 `python` 是 3.7，装不了）
uv pip install --python .venv/Scripts/python.exe \
    langgraph langchain langchain-openai langgraph-checkpoint-sqlite

依赖清单见 requirements.txt。LangGraph 1.x 已把 create_agent 移出 langgraph.prebuilt —— 这里用的是稳定的底层 langgraph.graph API（StateGraph/START/END/add_edge/add_conditional_edges/compile）。

Demo 1 · 离线（无需任何 key）

.venv/Scripts/python.exe demo.py

纯 Python 节点，不烧 token。输出会演示三条核心路径：

• short → low 质量 → 走 review 复核分支 → 加"已人工复核"标记
• long → high 质量 → 直接结束（条件边走 __end__）
• checkpoint → 从 Sqlite 存档恢复上次状态

Demo 2 · 在线 ReAct（需要 DeepSeek key）

export DEEPSEEK_API_KEY=sk-...      # 或从 .env 读取，勿提交进仓库
.venv/Scripts/python.exe demo_agent.py

模型自行决定要不要调工具、调哪个、拿结果后组织成最终回答 —— 这就是 Agent 的"自由行动 + 工具调用"真实形态。

---

代码在讲什么（关键概念映射）

代码	概念	人话
class State(TypedDict)	共享状态	一张图上的"进度板"，所有节点都读写它
builder.add_node(name, fn)	节点	图上的一个动作（一次计算/一个工具）
builder.add_edge(a, b)	边	固定流向，A 做完必然接 B
add_conditional_edges(grade, route, ...)	条件边	按状态分流：good 走完、low 去复核
SqliteSaver	持久化	每一步存档，能从 checkpoint 恢复（断点续跑）
@tool + bind_tools	Function Calling	把函数"注册"成模型可调用的工具
route_after_model	ReAct 拆解	模型这轮还要调工具？→ 去执行；否则 → 结束（循环出口）

一句话：LLM 是"会思考的零件"，LangGraph 是"把这些零件编排成一条可控流水线的引擎"。 工具调用、分支、持久化、人机协同（HITL），都是在 StateGraph 这张图上"接线"而已。

---

目录结构

langgraph/
├── demo.py            # 离线：图编排 / 状态 / 条件边 / checkpoint
├── demo_agent.py      # ★ 在线：ReAct 工具调用循环（DeepSeek）
├── 运行展示.html       # 竹青风可视化演示页（含真实运行输出）
├── requirements.txt
├── docs/run_demo.png  # 运行效果截图
└── .venv/             # Python 3.11 虚拟环境（gitignore）

---

踩过的坑（LangGraph 1.x）

1. create_agent 挪走了 —— from langgraph.prebuilt import create_agent 在 1.x 会失败；稳定核心在 langgraph.graph。
2. 裸 python 是 3.7 —— 本机 Anaconda base = Python 3.7，LangChain/LangGraph 需 3.9+；用 uv venv --python 3.11（uv 本地已缓存，免下载）。
3. 写之前先 probe API —— 版本迭代快（0.x→1.x 挪动导出），写码前 dir(StateGraph) 确认。

---

可以往哪扩展

• 接入 MCP 工具（模型上下文协议）让 agent 连任意外部工具
• 加 Human-in-the-loop（HITL）：interrupt() 在关键节点等人工确认
• 多 agent 协作（orchestrator ↔ worker）
• 加 RAG 检索节点，做成带知识库的问答 agent
• checkpoint 用真库（Postgres/Redis）跑持久化

---

基于 LangGraph 1.2.11 / LangChain 1.3.17 验证。所有代码为本仓库原创，可自由用于学习与再分发。