langchain-ai/langgraph¶
这个项目在系统里负责哪一层¶
LangGraph 负责的是长生命周期 Agent 和工作流运行时。它解决的不是“怎么多调几次模型”，而是“当一个任务会持续很久、会失败、会暂停、会恢复、会被人工打断时，怎么把它建模成正式运行系统”。
所以它最适合补状态机思维，而不是给所有 AI 功能都套一层图。
先抓整体结构¶
读这个项目时，建议先抓这条主线：
- state：系统当前到底处在什么状态。
- node / edge：状态如何被节点处理、如何决定下一跳。
- checkpoint：哪些状态需要被写下来，供失败恢复和跨进程续接。
- interrupt / resume：什么时候停给人看，什么时候从中断处继续。
- memory / observability：哪些状态长期保留，哪些事件进入 trace。
这个顺序很重要，因为 LangGraph 的核心从来不是“图很酷”，而是状态什么时候被写下、什么时候能恢复、什么时候允许人改。
一条典型执行链¶
一条 LangGraph 任务通常这样跑：
- 输入先被放进一份明确的 state。
- 当前 node 读取 state，执行模型推理、工具调用或业务逻辑。
- 节点输出 state 更新，edge 决定下一步走向。
- 关键节点写 checkpoint，保证失败后能恢复。
- 如果命中人工确认或策略边界，运行时 interrupt。
- 人确认后，系统按 checkpoint resume，继续往后走。
- 最终结果和完整状态转移记录被保留下来。
如果你在做长任务，比如“整理本周事故周报，先查工单、再查知识库、最后生成总结”，这条链会非常有感觉。没有 checkpoint 和 interrupt，这类任务一旦失败，通常就只能整条重来。
值得学的设计¶
LangGraph 最出彩的地方，是它把 state 放在 prompt 前面。很多团队做 Agent 时，习惯把所有东西都往模型上下文里塞。LangGraph 强迫你区分三类东西：运行状态、需要持久化的事实、这一步推理用到的局部上下文。这个区分一旦立住，可恢复性和可解释性都会明显提升。
另一个值得学的点是 interrupt 和 human-in-the-loop 被放进正式状态转移里，而不是做成“外面按个暂停键”。这意味着人工接入不是临时打断黑盒，而是运行时设计的一部分。
适合借回自己项目的点¶
- 先把状态和提示词分开，不要什么都往上下文里塞。
- 真遇到长任务时，先问自己有没有 checkpoint 和恢复边界。
- 把 trace 当状态转移观测，而不是只看模型调用日志。
- 把人工确认设计成状态节点，而不是外层补丁。
不要照抄的地方¶
- 不要把很短、很确定的流程也硬画成图。
- 不要让状态对象无限膨胀，最后谁都不敢改。
- 不要把 durable execution 当成“更高级”就默认上。它带来的心智成本和治理成本都很真实。