LangGraph
核对日期：2026-05-09。
1. 定义与边界
LangGraph 是 LangChain 生态中的低层 Agent 编排框架，核心是用状态图（StateGraph）描述可循环、可分支、可持久化的人机协作流程。它更接近“Agent 运行时/工作流内核”，不是简单 prompt 模板库。
2. 官方能力、社区能力、实验能力和营销说法
| 类型 | 内容 |
|---|---|
| 官方能力 | StateGraph、节点/边、持久化、checkpoint、human-in-the-loop、streaming、subgraph、LangSmith 集成 |
| 社区能力 | 第三方节点、模板、平台部署样例 |
| 实验/快速变化 | 部分云平台功能、预构建 Agent 模板和版本迁移细节 |
| 营销说法 | “用 LangGraph 就自动得到可靠多 Agent”不成立，状态和评测仍需设计 |
3. 核心机制
LangGraph 将 Agent 流程表示为图：
状态是核心数据结构，节点读写状态，边决定下一步。
4. 架构与工程实现
适合场景：
| 场景 | 原因 |
|---|---|
| 多步工具链 | 图结构明确控制循环和终止 |
| 需要恢复/暂停 | checkpoint 支持中断后继续 |
| 人类在环 | 可在图节点中暂停等待审批 |
| 多 Agent 协作 | 用 subgraph 或节点隔离角色 |
简化示意：
from langgraph.graph import StateGraph, END
def plan(state):
return {"next": "tool" if state["need_tool"] else "finish"}
def call_tool(state):
return {"observation": "tool result"}
graph = StateGraph(dict)
graph.add_node("plan", plan)
graph.add_node("call_tool", call_tool)
graph.add_conditional_edges("plan", lambda s: s["next"], {"tool": "call_tool", "finish": END})
graph.add_edge("call_tool", "plan")
app = graph.compile()
5. 生产实践
- 把状态 schema 设计成可迁移、可回放的数据结构。
- 对节点做幂等设计，避免恢复后重复执行外部副作用。
- checkpoint 存储要考虑租户隔离、加密和数据保留。
- 人类审批节点应显示足够证据和拟执行动作。
- 复杂图需要可视化、Trace 和单节点测试。
6. 常见反模式
| 反模式 | 风险 |
|---|---|
| 图里到处写隐式全局状态 | 难以恢复和测试 |
| 让模型决定所有边 | 图退化成不可控循环 |
| 缺少终止条件 | 成本失控 |
| 把 LangGraph 当普通 chain 使用 | 没发挥持久化和状态控制优势 |
7. 评测方法
评测不仅看最终回答，还要看状态迁移是否正确、节点是否按预期触发、恢复后是否一致、人工审批是否被正确请求、工具调用是否幂等。
8. 安全与治理
LangGraph 不替代权限系统。每个工具节点仍需鉴权、审计、限流和敏感信息过滤。checkpoint 中可能包含用户数据和工具结果，需要按数据分类保护。
9. 权威资料
- LangGraph overview: https://docs.langchain.com/oss/python/langgraph/overview
- LangGraph concepts: https://langchain-ai.github.io/langgraph/concepts/why-langgraph/
- LangGraph persistence: https://langchain-ai.github.io/langgraph/concepts/persistence/
- LangGraph human-in-the-loop: https://langchain-ai.github.io/langgraph/concepts/human_in_the_loop/
- LangGraph GitHub: https://github.com/langchain-ai/langgraph
10. 二次精修：生产级状态图决策
10.1 官方能力补充
| 能力 | 作用 | 生产关注点 |
|---|---|---|
| Durable execution / persistence | 长任务可暂停、恢复、回放 | checkpoint 加密、schema 迁移 |
| Human-in-the-loop | 在节点中断等待人工输入 | 审批证据和参数一致性 |
| Streaming | 输出事件和中间状态 | 事件脱敏、前端状态一致 |
| Subgraph | 将复杂流程拆成可组合子图 | 子图输入输出契约 |
| LangSmith 集成 | trace、调试、评测 | 数据保留和敏感字段 |
10.2 适用与不适用
| 适合 LangGraph | 不适合 LangGraph |
|---|---|
| 多步工具链、循环、分支、恢复 | 一次性问答或简单结构化抽取 |
| 需要中断审批和继续执行 | 只需要 prompt 模板管理 |
| 需要可回放的状态迁移 | 团队不愿设计状态 schema |
| 多 Agent 但希望显式控制边界 | 追求纯自然语言自组织协作 |
10.3 状态 schema 设计
class AgentState(TypedDict):
run_id: str
user_id: str
task: str
plan: list[dict]
retrieved_docs: list[dict]
pending_approval: dict | None
tool_results: list[dict]
risk_flags: list[str]
final_answer: str | None
10.4 控制流建议
10.5 生产实践
- 每个节点只做一类动作：规划、检索、策略、工具、审批、总结不要混在一起。
- 外部副作用节点必须幂等，恢复后要能识别已执行动作。
- checkpoint 存储需要版本字段，状态结构变更要有迁移脚本。
- 条件边尽量由可测试函数决定，减少“让模型自由决定下一节点”。
- 图运行超时、最大循环次数、最大工具调用次数必须配置。
10.6 评测方法
| 评测项 | 指标 |
|---|---|
| 状态迁移 | 每个节点输入输出符合 schema |
| 路由 | 条件边选择准确率 |
| 恢复 | checkpoint 恢复后一致性 |
| 人类在环 | 高风险动作 interrupt 覆盖率 |
| 安全 | 越权工具阻断率、注入用例通过率 |
10.7 迁移策略
- 从 LangChain chain 迁移：先把隐式链路画成节点图，再迁移状态对象。
- 从低代码平台迁移：先保留平台作为入口，把高风险流程抽到 LangGraph。
- 从自研脚本迁移：先迁移需要恢复、审批和循环控制的部分，不要一次重写所有工具。
- 从多 Agent 原型迁移：把角色对话改成显式节点和边，减少不可控通信。
10.8 安全治理
| 风险 | 控制 |
|---|---|
| checkpoint 存敏感数据 | 加密、脱敏、保留周期、访问审计 |
| 恢复后重复执行写操作 | 幂等键、执行记录、补偿事务 |
| 条件边被提示注入影响 | 策略函数外置、风险节点强制检查 |
| 子图权限混乱 | 子图输入输出契约和工具 scope 分离 |
核对日期：2026-05-09。