LangGraph工作流跑通了，为什么上线第一天就翻车？

Java技术那些事儿

墨衍会员 · 1平台 · 300+阅读码龄5年

关注

原创最新推荐文章于 2026-08-25 19:11:49 发布 325 阅读 AI 写同款· GEO 优化 ›

MBIST --- PATR1.Memorybist测试原理 mem bist作为现在design设计中不可或缺的DFT设计内容，越发重要。本章节主要介绍mem bist组成部分，测试的原理以及注意事项。阅读详情

聊《会用LangGraph只是起点，能解释失败才算真正入门》之前，先说一句实在的：别急着背概念，先看它在真实项目里到底解决什么问题。

摘要

最近在带一个内部AI助手项目，Agent的逻辑用LangGraph搭了个图，Demo跑起来丝滑得像是广告片。结果一上线，权限问题、日志缺失、审批卡死，团队直接懵了。这篇文章复盘这个翻车经历，顺便把LangGraph工作流从Demo到生产的真实路径讲清楚。

为什么需要图工作流

文章插图 1

做AI应用这段时间，我见过太多团队卡在同一个坑里：Agent在本地跑得好好的，一上线就乱套。

问题出在哪？很多人第一反应是"模型不够强"或者"工具调用写错了"。但真正的问题往往更工程化——你的Agent是个脚本，不是系统。

脚本的问题在于：没有状态管理、没有分支控制、没有人工介入点。你写个if-else就以为能处理复杂场景，结果模型偶尔抽风，整个流程直接崩。

图工作流解决的核心问题是可控性。

---

真实案例：审批助手的翻车现场

文章插图 2

我们团队上个月上线了一个内部请假审批助手。流程很简单：

1. 员工提交请假申请（文字描述）
2. Agent提取请假时间、天数、原因
3. 判断是否需要主管审批（超过3天需要）
4. 如果需要，发送审批请求给主管
5. 主管审批通过后，通知HR系统

Demo阶段，我们用模拟数据跑通了全流程，看起来一切正常。

上线第一天，问题集中爆发：

有3个请假申请卡在"等待审批"状态，主管明明已经点了通过，但系统显示pending
HR系统收不到通知，因为审批状态没有正确传递
日志里只有一行"流程结束"，完全看不出哪里出了问题

排查后发现，根本原因是我们没有配置checkpoint，中断点（interrupt）的状态没有持久化。主管审批后，Agent恢复执行时拿到的状态是旧的，导致流程走偏。

这个案例说明了一个问题：Demo能跑通，和生产能上线，中间隔着一整套工程化能力。

---

State与Node

LangGraph的核心抽象是状态图。

状态（State）是整个工作流的全局上下文，节点（Node）是具体的处理单元。每个节点接收当前状态，返回更新后的状态。

我们项目的状态定义是这样的：

from typing import TypedDict, Annotated
import operator

class ApprovalState(TypedDict):
    # 原始申请信息
    request_text: str

    # 提取后的结构化信息
    extracted_info: dict

    # 审批状态
    approval_status: str  # pending/approved/rejected

    # 审批人
    approver: str

    # 当前流程节点
    current_node: str

    # 日志记录
    logs: Annotated[list, operator.add]

注意logs字段用了operator.add，这意味着每次节点更新时，新日志会追加到现有日志后面，而不是覆盖。这是LangGraph特有的状态合并机制，很重要。

节点的定义很简单：

def extract_info(state: ApprovalState) -> ApprovalState:
    state["logs"].append(f"[{datetime.now()}] 开始提取信息: {state['request_text']}")

    # 调用LLM提取信息
    result = llm.extract_leave_info(state["request_text"])

    state["extracted_info"] = result
    state["logs"].append(f"[{datetime.now()}] 提取完成: {result}")

    return state

def check_approval_needed(state: ApprovalState) -> ApprovalState:
    days = state["extracted_info"]["days"]

    if days > 7:
        state["approval_status"] = "pending"
        state["approver"] = "director"
    elif days > 3:
        state["approval_status"] = "pending"
        state["approver"] = "manager"
    else:
        state["approval_status"] = "auto_approved"
        state["approver"] = ""

    state["logs"].append(f"[{datetime.now()}] 审批判断: 需要审批, 审批人={state['approver']}")

    return state

每个节点都是纯函数，输入状态，输出状态。这种设计的好处是可测试性极强——你可以单独测试每个节点，不用跑完整流程。

---

Edge与条件分支

图工作流和脚本最大的区别之一是条件边。

在脚本里，你用if-else控制流程。在LangGraph里，你用条件边（Conditional Edge）控制流程。

from langgraph.graph import StateGraph, END

# 定义图
graph = StateGraph(ApprovalState)

# 添加节点
graph.add_node("extract", extract_info)
graph.add_node("check", check_approval_needed)
graph.add_node("send_approval", send_approval_to_manager)
graph.add_node("notify_hr", notify_hr_system)
graph.add_node("timeout_handler", handle_timeout)

# 设置入口
graph.set_entry_point("extract")

# 条件边：根据审批状态决定下一步
def route_by_status(state: ApprovalState) -> str:
    if state["approval_status"] == "auto_approved":
        return "notify_hr"
    elif state["approval_status"] == "pending":
        return "send_approval"
    else:
        return "timeout_handler"

graph.add_conditional_edges(
    "check",
    route_by_status,
    {
        "notify_hr": "notify_hr",
        "send_approval": "send_approval",
        "timeout_handler": "timeout_handler"
    }
)

# 普通边
graph.add_edge("extract", "check")
graph.add_edge("send_approval", END)
graph.add_edge("notify_hr", END)
graph.add_edge("timeout_handler", END)

# 编译
app = graph.compile()

条件边的核心优势是流程可视化。你可以直接看到所有可能的执行路径，不用在代码里找if-else。

但我们踩过的坑是：条件函数写错了，流程会静默失败。

比如上面这个例子，如果route_by_status返回了一个不在字典里的字符串，LangGraph不会报错，而是直接结束流程。你只会看到日志里没有后续记录，完全不知道发生了什么。

---

人工审批节点

这是我们的Agent上线第一天翻车的核心原因。

在Demo里，我们模拟审批流程是这样的：

def send_approval_to_manager(state: ApprovalState) -> ApprovalState:
    # 模拟审批
    state["approval_status"] = "approved"
    state["logs"].append(f"[{datetime.now()}] 审批通过")
    return state

上线后，真实场景是：

def send_approval_to_manager(state: ApprovalState) -> ApprovalState:
    approver = state["approver"]
    request = state["extracted_info"]

    # 发送审批请求
    send_approval_request(approver, request)

    # 等待审批结果
    # 问题：这里怎么等？
    state["logs"].append(f"[{datetime.now()}] 已发送审批请求给 {approver}")

    return state

问题出现了：Agent怎么等待人工审批？

常见的错误做法：

1. 轮询：每秒查询一次审批状态。这种方式在Demo里没问题，但上线后会造成大量无效请求。
2. 阻塞等待：让节点线程sleep。这会占用线程资源，无法水平扩展。
3. 直接跳过：假设审批会自动通过。这是最危险的做法，会导致数据错误。

正确的做法是使用中断点（Interrupt）。

LangGraph支持在节点执行后暂停流程，等待人工干预：

from langgraph.types import interrupt

def wait_for_approval(state: ApprovalState) -> ApprovalState:
    approver = state["approver"]
    request = state["extracted_info"]

    # 发送审批请求
    send_approval_request(approver, request)

    # 中断流程，等待人工输入
    approval_result = interrupt({
        "type": "approval_request",
        "approver": approver,
        "request": request,
        "request_id": state.get("request_id")
    })

    # 恢复后更新状态
    state["approval_status"] = approval_result["status"]
    state["approval_comment"] = approval_result.get("comment", "")
    state["logs"].append(f"[{datetime.now()}] 审批结果: {approval_result['status']}")

    return state

中断点的使用有几个关键点：

1. 编译时需要checkpoint：

from langgraph.checkpoint.memory import MemorySaver

checkpointer = MemorySaver()
app = graph.compile(checkpointer=checkpointer)

2. 恢复时需要config：


# 保存config
config = {"configurable": {"thread_id": "request-001"}}

# 执行到中断点
result = app.invoke(input, config)

# 恢复执行
result = app.invoke(input, config)

3. 超时处理：中断点需要设置超时，否则流程会永久挂起。

我们上线第一天翻车的原因就是：没有配置checkpoint，也没有处理中断超时。主管审批后，Agent的状态没有正确恢复，导致后续流程执行了错误的路径。

---

优快云资料领取方式

排查过程

翻车之后，我们花了两天时间排查问题。整个过程是这样的：

现象：主管在审批系统点了"通过"，但Agent状态仍然是pending，HR系统没有收到通知。

第一步：查日志

我们首先查看了Agent的运行日志，发现日志里只有"已发送审批请求"的记录，没有后续的审批结果。这说明中断点没有被正确恢复。

第二步：检查checkpoint配置

我们检查了编译代码，发现确实没有配置checkpointer。Demo阶段我们用的是默认配置，没有持久化状态。


# 错误配置
app = graph.compile()

# 正确配置
checkpointer = MemorySaver()
app = graph.compile(checkpointer=checkpointer)

第三步：验证恢复逻辑

修复checkpoint后，我们手动测试了恢复流程。发现恢复时需要传入相同的config，否则Agent无法找到之前的状态。


# 必须保存并使用相同的config
config = {"configurable": {"thread_id": "request-001"}}

第四步：添加超时处理

即使修复了checkpoint，我们仍然担心主管长时间不审批会导致流程卡死。于是我们添加了超时检测逻辑，超过24小时未审批的请求自动标记为超时。

结论：问题的根本原因是Demo和生产环境的配置差异。Demo阶段不需要持久化状态，但生产环境必须考虑状态管理和异常处理。

---

代码解释

下面对关键代码进行逐段解释，帮助你理解实现原理。

1. 状态定义

class ApprovalState(TypedDict):
    request_text: str
    extracted_info: dict
    approval_status: str
    approver: str
    current_node: str
    logs: Annotated[list, operator.add]

这段代码定义了工作流的状态结构。每个字段的作用：

request_text：员工提交的原始请假申请，作为输入
extracted_info：LLM提取后的结构化信息，包含天数、原因等
approval_status：当前审批状态，枚举值为pending/approved/rejected
approver：审批人标识，可能是manager或director
current_node：当前执行的节点名称，用于调试和日志
logs：日志列表，使用operator.add实现追加合并而非覆盖

关键点：operator.add是LangGraph的状态合并策略。默认情况下，节点返回的状态会完全覆盖旧状态。使用operator.add后，list类型的字段会追加新元素而不是替换。这对于日志记录非常重要。

2. 条件路由函数

def route_by_status(state: ApprovalState) -> str:
    if state["approval_status"] == "auto_approved":
        return "notify_hr"
    elif state["approval_status"] == "pending":
        return "send_approval"
    else:
        return "timeout_handler"

这个函数决定了流程的下一步走向。输入是当前状态，输出是下一个节点的名称。

核心逻辑：

如果审批状态是auto_approved，直接通知HR
如果是pending，发送审批请求
其他情况（包括异常状态）走超时处理

异常处理：如果返回的值不在addconditionaledges的映射字典中，LangGraph会静默结束流程，不会报错。这就是为什么条件函数必须保证所有分支都有对应的目标节点。

3. 中断点实现

approval_result = interrupt({
    "type": "approval_request",
    "approver": approver,
    "request": request,
    "request_id": state.get("request_id")
})

interrupt函数会暂停流程执行，等待外部输入。传入的字典会作为中断信息返回给调用方。

实现原理：
1. 调用interrupt时，LangGraph保存当前状态到checkpoint
2. 抛出InterruptException，终止当前invoke调用
3. 调用方获取中断信息，触发人工审批
4. 使用相同的config再次调用invoke，LangGraph从checkpoint恢复状态
5. interrupt返回人工输入的结果，流程继续执行

关键点：checkpoint是必须的。没有checkpoint，中断的状态无法保存，恢复时会丢失上下文。

4. 重试装饰器

@tenacity.retry(
    stop=tenacity.stop_after_attempt(3),
    wait=tenacity.wait_exponential(multiplier=1, min=4, max=10),
    retry=tenacity.retry_if_exception_type((requests.exceptions.Timeout, requests.exceptions.ConnectionError))
)
def send_approval_request(approver: str, request: dict):
    ...

这个装饰器实现了自动重试逻辑。

参数说明：

stop_after_attempt(3)：最多重试3次
wait_exponential：指数退避，第一次等4秒，第二次等8秒，第三次等10秒（上限）
retry_if_exception_type：只重试超时和连接错误，其他异常直接抛出

code walkthrough：当API调用失败时，tenacity会捕获异常，等待一段时间后重试。如果3次都失败，异常会传播到上层，由调用方处理。

---

失败原因

我们的翻车经历可以归纳为几类常见错误。理解这些失败原因，能帮助你在设计阶段就规避风险。

业务错误

业务错误是指逻辑设计缺陷导致的结果错误。

案例1：条件分支遗漏

def route_by_status(state):
    if state["approval_status"] == "auto_approved":
        return "notify_hr"
    # 遗漏了pending状态的處理

这种错误会导致流程静默失败。LangGraph不会报错，只是走到一个没有定义的目标节点，流程直接结束。

区分方法：检查所有可能的状态值，确保每个值都有对应的路由目标。

案例2：中断点未恢复

这是我们的踩坑经历。没有配置checkpoint，中断状态无法持久化。主管审批后，Agent恢复时拿到的是旧状态。

区分方法：检查compile时是否传入了checkpointer参数。

配置错误

配置错误是指环境配置不当导致的功能失效。

案例3：API密钥硬编码

HR_API_KEY = "sk-已完善内容"  # 错误做法

测试环境的密钥和生产环境的密钥不同。硬编码会导致生产环境调用失败。

区分方法：检查所有敏感配置是否从环境变量或密钥管理服务读取。

案例4：超时时间过短


# 开发环境测试用的超时
timeout=5  # 生产环境可能不够

人工审批流程通常需要较长时间。过短的超时会导致流程提前终止。

区分方法：根据实际业务场景设置合理的超时时间，人工审批流程建议至少24小时。

环境错误

环境错误是指运行环境差异导致的问题。

案例5：checkpoint存储差异


# 开发环境：内存存储
checkpointer = MemorySaver()

# 生产环境：应该用数据库
checkpointer = PostgresSaver()

MemorySaver在进程重启后数据丢失。生产环境必须使用持久化存储。

区分方法：检查生产环境的checkpoint配置是否与开发环境一致。

案例6：网络隔离

开发环境可以访问外部API，生产环境可能有防火墙限制。

区分方法：在生产环境部署前，验证所有外部依赖的网络连通性。

如何快速定位失败原因

1. 查看日志：检查logs字段，确认每个节点的执行时间
2. 检查状态：打印当前状态，确认字段值是否符合预期
3. 验证配置：对比开发和生产环境的配置差异
4. 复现问题：在测试环境模拟生产配置，复现问题

---

工程化落地

从Demo到生产，LangGraph工作流需要解决的工程问题远不止代码本身。

1. 权限控制

我们的Agent需要访问多个系统：HR系统、审批系统、通知系统。每个系统的API密钥和权限配置完全不同。

错误做法：

HR_API_KEY = "sk-已完善内容"
APPROVAL_API_KEY = "sk-yyy"

正确做法：

import os
from pathlib import Path

def load_config():
    config_path = Path(os.getenv("AGENT_CONFIG_PATH", "./config.json"))
    with open(config_path) as f:
        return json.load(f)

config = load_config()
HR_API_KEY = config["hr"]["api_key"]

权限问题上线第一天就暴露了：测试环境的密钥在生产环境不存在，Agent直接无法调用任何外部API。

2. 日志和可观测性

LangGraph的logs字段只能记录节点执行日志，无法覆盖系统级的问题。

我们需要：

请求追踪ID：每个请求分配唯一ID，贯穿整个流程
外部调用日志：记录所有API调用的请求和响应
错误堆栈：异常时的完整堆栈信息
性能指标：每个节点的执行时间

import uuid
import logging

logger = logging.getLogger("agent.approval")
logger.setLevel(logging.INFO)
handler = logging.FileHandler("approval.log")
formatter = logging.Formatter("%(asctime)s - %(levelname)s - %(message)s")
handler.setFormatter(formatter)
logger.addHandler(handler)

def extract_info(state: ApprovalState) -> ApprovalState:
    trace_id = state.get("trace_id", str(uuid.uuid4()))
    state["trace_id"] = trace_id

    logger.info(f"[{trace_id}] 开始提取信息")
    # ... 业务逻辑 ...
    logger.info(f"[{trace_id}] 提取完成")

    return state

3. 错误处理和重试

Demo里通常不处理错误，但生产环境必须考虑。

import tenacity

@tenacity.retry(
    stop=tenacity.stop_after_attempt(3),
    wait=tenacity.wait_exponential(multiplier=1, min=4, max=10),
    retry=tenacity.retry_if_exception_type((requests.exceptions.Timeout, requests.exceptions.ConnectionError))
)
def send_approval_request(approver: str, request: dict):
    response = requests.post(
        f"{APPROVAL_API_URL}/approve",
        json={"approver": approver, "request": request},
        headers={"Authorization": f"Bearer {APPROVAL_API_KEY}"},
        timeout=30
    )
    response.raise_for_status()
    return response.json()

4. 配置管理

不同环境（开发、测试、生产）的配置差异很大，需要通过配置管理解决。


# config/environments/development.json
{
    "llm": {"model": "gpt-4o-mini", "temperature": 0.3},
    "hr_api": {"base_url": "http://localhost:8080/api", "timeout": 10},
    "approval_api": {"base_url": "http://localhost:8081/api", "timeout": 10},
    "max_retries": 1,
    "timeout_seconds": 60
}

# config/environments/production.json
{
    "llm": {"model": "gpt-4o", "temperature": 0.1},
    "hr_api": {"base_url": "https://api.company.com/hr", "timeout": 30},
    "approval_api": {"base_url": "https://api.company.com/approval", "timeout": 30},
    "max_retries": 3,
    "timeout_seconds": 120
}

5. 监控和告警

上线后需要实时监控：

流程执行成功率
平均执行时间
中断等待时间
错误类型分布

import time
from prometheus_client import Counter, Histogram

REQUEST_COUNT = Counter("approval_requests_total", "Total approval requests", ["status"])
EXECUTION_TIME = Histogram("approval_execution_seconds", "Execution time")
INTERRUPT_WAIT_TIME = Histogram("approval_interrupt_wait_seconds", "Wait time for approval")

def monitor_execution(func):
    def wrapper(*args, **kwargs):
        start_time = time.time()
        try:
            result = func(*args, **kwargs)
            REQUEST_COUNT.labels(status="success").inc()
            return result
        except Exception as e:
            REQUEST_COUNT.labels(status="error").inc()
            raise
        finally:
            execution_time = time.time() - start_time
            EXECUTION_TIME.observe(execution_time)
    return wrapper

---