LangGraph 工作流：一篇讲清核心用法

聊《LangGraph 工作流：一篇讲清核心用法》之前，先说一句实在的：别急着背概念，先看它在真实项目里到底解决什么问题。

摘要

很多开发者刚接触 Agent 时，习惯用链式调用（Chain）拼凑功能，遇到复杂逻辑就陷入状态混乱和死循环。本文从初学者转型路线切入，梳理 LangGraph 的学习顺序与常见误区，结合真实场景讲解 State 定义、动态路由、人工干预等关键机制，并给出工程化部署与简历项目包装的实操建议。

目录

• 为什么需要图工作流
• State 与 Node
• Edge 与条件分支
• 人工审批节点
• 工程化落地
• 总结

为什么需要图工作流

我刚带团队做智能客服升级时，发现用传统的链式管道写了一堆 `.pipe()`，结果某个环节失败后整个流程直接崩掉，连个兜底都找不到。后来把架构改成图结构，才真正稳下来。很多人学大模型应用，第一反应是“怎么调 API”、“怎么写 prompt”，其实真正的分水岭在于**数据流向的控制**。

初学者最容易犯的一个错，是先啃完一套复杂的框架文档再动手，结果写出的是“能跑但改不动”的代码。我建议的学习顺序是：先理解有向图的基本概念（节点、边、状态），再用 LangGraph 把业务逻辑画出来，最后才去抠配置细节。图工作流不是炫技，它是把散落的脚本串成可追踪、可中断、可重试的系统骨架。如果你现在的 Agent 只是“输入一句话，吐出一段话”，那叫脚本；一旦需要记忆上下文、处理异常分支、或者根据中间结果决定下一步动作，就必须引入图。

State 与 Node

State 是图的血液。别把它当成简单的字典传递，它应该是强类型的共享内存。每个 Node 进来读状态，出去写状态，不依赖外部变量。这样你才能随时 checkpoint 断点续传。

from typing import TypedDict, List, Annotated, Literal
import operator
from langchain_core.messages import AIMessage, HumanMessage
from langgraph.graph.message import add_messages

class AgentState(TypedDict):
    messages: Annotated[List, add_messages]
    user_intent: str
    confidence_score: float
    action_taken: str
    error_log: List[str]

我见过太多人把中间结果塞进局部变量，或者靠全局单例存上下文，一旦并发请求上来，状态就交叉污染了。Node 的设计要遵循单一职责，一个节点只干一件事：比如叫 `llm_router_node` 的只管发请求和拉取原始回答，别在里面硬编码业务规则。状态更新一定要明确，用 `operator.add` 追加消息，用直接赋值覆盖配置项。这样后续加调试日志或者做版本回滚，才有据可查。

记住一条原则：**Node 是无状态的处理器，State 才是唯一的真相来源。** 任何跨节点的通信都必须经过 State。

Edge 与条件分支

边决定了图的走向。静态边适合固定流程，但 Agent 的灵魂在于动态路由。这里有个明显的认知误区：很多人喜欢让大模型直接输出 JSON 路径（比如 `"next_node": "finance_handler"`），然后代码里硬写 `if next == "finance": ...`。这种做法耦合度太高，模型稍微换个表述就挂。

更好的做法是让路由节点返回标准化的控制信号，或者直接用 LangGraph 内置的条件边函数。我在做合同审核 Agent 时，写过这样的路由逻辑：

def route_after_review(state: AgentState) -> Literal["legal_review", "clarification_request", "finalize_contract"]:
    last_msg = state["messages"][-1].content.lower()
    if "高风险" in last_msg or "需法务介入" in last_msg:
        return "legal_review"
    elif "条款模糊" in last_msg or "金额不一致" in last_msg:
        return "clarification_request"
    else:
        return "finalize_contract"

学习的时候，先跑通直来直去的线性图，再引入条件分支。判断标准很简单：如果流程超过 3 个可能的跳转方向，或者存在重试/降级逻辑，就必须上动态边。别为了追求“智能”而把路由逻辑全扔给大模型自己猜，控制流必须留在代码层。大模型负责理解意图，代码负责调度流程。

人工审批节点

生产环境里，有些操作不能全自动执行。资金划转、敏感内容发布、客户投诉升级，这些场景必须留一道人工闸口。LangGraph 提供了 `interrupt_before` 和 `interrupt_after`，配合 `Command` 可以优雅地暂停并等待反馈。

我之前踩过一个坑：在 Node 里直接写 `input("确认执行？Y/N")`，这在 CLI 测试没问题，但放到 Web 服务或异步任务里会直接阻塞线程，导致连接超时。正确的姿势是利用图的状态机特性，触发中断后保存 Checkpoint，前端轮询或 WebSocket 推送状态变更，用户确认后通过 API 恢复执行。

做项目展示时，这里特别加分。面试官不关心你能不能跑通 demo，他们看重你有没有处理过“不可逆操作”的灰度策略。把人工审批节点设计成可配置的开关，支持按角色/金额阈值动态开启，这种工程思维比单纯调 API 值钱得多。简历里提到这类设计时，务必写明中断后的状态恢复机制和防并发冲突方案，这能直接拉开你和培训班学员的距离。

工程化落地

代码能在 Jupyter Notebook 里跑通，离正式上线还差得很远。工程化阶段我最常提醒团队抓三件事：持久化存储、结构化日志、独立测试。

首先，Checkpoint 机制必须配。没有数据库支撑的图就是单机玩具。PostgreSQL 搭配 LangGraph 的持久化适配器，能自动记录每次迭代的 State 快照。这样即使服务重启，对话也能无缝接续。其次，日志不要只打 `print`，要用结构化格式记录节点进入/退出时间、Token 消耗和决策依据。方便后期做延迟分析和成本核算。

测试方面，别指望端到端黑盒测试能覆盖所有分支。应该对每个 Node 和路由函数做单元测试，注入伪造的 State 验证边界条件。部署时，把 Prompt 模板、路由配置和模型参数抽离到环境变量或配置中心，避免每次微调都要重新编译容器。

至于学习路径，从 Demo 到产品，中间横亘着大量的“脏活”。先保证核心链路可用，再逐步补上监控、限流、熔断。不要一开始就追求完美的微服务拆分，Agent 工作流本身就应该保持轻量，重业务编排，轻基础设施。后端同学做这一块的优势在于熟悉并发控制和数据一致性，把这套经验迁移过来，避开纯前端视角下的状态同步陷阱，你的项目交付质量会高出一个台阶。

总结

把 Agent 从脚本升级到可控系统，本质上是思维方式从“过程导向”转向“状态与流向导向”。初学者最容易在过度抽象和盲目自信之间摇摆：要么一上来就套重型框架，要么全靠 Prompt 魔法解决所有问题。掌握 LangGraph 的正确姿势，是按图索骥定义 State，用代码锁死控制流，把不可控的模型输出关在规范的边界里。实战中多预留人工干预点和状态快照，你的项目不仅能跑起来，还能经得起生产环境的反复打磨。

资料展示

下面是我整理的AI大模型学习资料和工具包预览，适合收藏后按主题逐步学习。

如果你想看完整资料目录，可以在评论区留言「资料」；也欢迎告诉我你更关注AI大模型里的哪类内容。