# LangGraph 生产级容错机制：重试、超时、错误处理与幂等性实践

> 本文详细解析了 LangGraph 在 Python (1.2+) 和 JavaScript (1.4+) 版本中引入的生产级容错机制。核心内容包括：1) 细粒度的节点级重试策略 (RetryPolicy)，支持自定义异常类型和退避参数；2) 超时控制 (Timeouts)，防止节点无限期挂起，支持动态超时覆盖；3) 错误处理器 (Error Handler)，在重试耗尽后运行，支持通过 Command 实现 Saga/补偿模式；4) 幂等性实践，强调使用持久化键确保外部副作用的幂等性；5) 图级默认配置 (Graph Defaults)，简化多节点配置。这些机制共同提升了 LangGraph 智能体在复杂生产环境中的执行可靠性。

原文：/knowledge/crawler-2db4f2943e906da7662052170f8223cc35f95e0b898a58df04c43e84c40e4321

LangGraph 在 `1.2` (Python) 和 `1.4` (JavaScript) 版本中引入了生产级容错机制，旨在解决智能体在运行过程中因外部 API 故障、网络波动或逻辑错误导致的执行中断问题。这些机制包括细粒度的节点级重试策略、超时控制、错误处理器（Error Handler）以及幂等性保障，从单纯的“状态记忆”扩展到了“执行可靠性”。

## 核心容错机制概览

LangGraph 的容错机制由三个可组合的部分组成，按固定顺序执行：

1.  **重试 (Retries)**：基于异常类型和退避策略自动重新运行失败的节点。
2.  **超时 (Timeouts)**：限制单个节点尝试运行的最长时间。
3.  **错误处理 (Error Handling)**：在重试耗尽后运行恢复函数，支持 Saga/补偿模式。

执行流程如下：当节点抛出异常（包括超时异常）时，重试策略首先判断是否匹配重试条件。如果匹配且还有剩余尝试次数，则重新执行节点；如果重试耗尽或未配置重试策略，则调用错误处理器。如果未配置错误处理器，异常将向上冒泡导致运行失败。

```mermaid
flowchart LR
    start([Attempt starts]) --> exec[Run node]
    exec -->|"success"| done([Continue graph])
    exec -->|"any exception\u003cbr/\u003eincluding NodeTimeoutError"| retry{retry_policy\u003cbr/\u003ematches?}
    retry -->|"yes, attempts left"| exec
    retry -->|"exhausted or absent"| handler{error_handler?}
    handler -->|"yes"| run_handler["Invoke handler\u003cbr/\u003ewith NodeError"]
    run_handler --> route([Update state +\u003cbr/\u003eCommand goto])
    handler -->|"no"| bubble([Exception\u003cbr/\u003ebubbles up])

    classDef process fill:#E5F4FF,stroke:#006DDD,stroke-width:2px,color:#030710
    classDef decision fill:#FDF3FF,stroke:#7E65AE,stroke-width:2px,color:#504B5F
    classDef alert fill:#F8E8E6,stroke:#B27D75,stroke-width:2px,color:#634643
    classDef output fill:#EBD0F0,stroke:#885270,stroke-width:2px,color:#441E33

    class exec,run_handler process
    class retry,handler decision
    class bubble alert
    class done,route,start output
```

> **注意**：节点级超时和错误处理器需要 `langgraph>=1.2` (Python) 或 `@langchain/langgraph>=1.4.0` (JavaScript)。

来源：[s2](https://docs.langchain.com/oss/python/langgraph/fault-tolerance), [s4](https://docs.langchain.com/oss/javascript/langgraph/fault-tolerance)

## 细粒度重试策略 (Retry Policy)

重试策略允许开发者根据异常类型和退避设置自动重新运行失败的节点尝试。重试是可选的，只有配置了 `retry_policy` 的节点才会触发重试。

### Python 实现 (`langgraph>=1.2`)

在 Python 中，通过 `RetryPolicy` 类配置重试参数：

```python
from langgraph.types import RetryPolicy

builder.add_node(
    "call_api",
    call_api,
    retry_policy=RetryPolicy(max_attempts=3),
)
```

**关键参数：**

| 参数 | 类型 | 默认值 | 描述 |
| :--- | :--- | :--- | :--- |
| `max_attempts` | `int` | `3` | 最大尝试次数（包含首次） |
| `initial_interval` | `float` | `0.5` | 第一次重试前的秒数 |
| `backoff_factor` | `float` | `2.0` | 每次重试后间隔时间的乘数 |
| `max_interval` | `float` | `128.0` | 重试之间的最大秒数 |
| `jitter` | `bool` | `True` | 是否在间隔中添加随机抖动 |
| `retry_on` | `type[Exception] | Callable` | `default_retry_on` | 指定哪些异常需要重试 |

**默认行为：**
默认情况下，`default_retry_on` 会重试除 `ValueError`、`TypeError`、`OSError` 等特定异常外的所有异常。对于 `requests` 和 `httpx` 等 HTTP 库，默认仅重试 5xx 状态码。`NodeTimeoutError` 默认是可重试的。

### JavaScript 实现 (`@langchain/langgraph>=1.4.0`)

在 JavaScript 中，直接在 `addNode` 的配置对象中传入 `retryPolicy`：

```typescript
import { StateGraph } from "@langchain/langgraph";

const graph = new StateGraph(State)
  .addNode("callApi", callApi, { retryPolicy: { maxAttempts: 3 } })
  .compile();
```

**关键参数差异：**

| 参数 | 类型 | 默认值 | 描述 |
| :--- | :--- | :--- | :--- |
| `maxAttempts` | `number` | `3` | 最大尝试次数 |
| `initialInterval` | `number` | `500` | 第一次重试前的毫秒数 |
| `backoffFactor` | `number` | `2.0` | 退避乘数 |
| `maxInterval` | `number` | `128000` | 最大毫秒间隔 |
| `jitter` | `boolean` | `true` | 是否添加抖动 |
| `retryOn` | `(error: unknown) => boolean` | 内置处理器 | 判断是否重试的函数 |

**默认行为差异：**
JavaScript 的默认处理器会重试除 `AbortError`、`GraphValueError`、`ECONNABORTED`、4xx 客户端错误（如 400, 401, 404 等）以及 OpenAI 配额错误外的所有错误。`NodeTimeoutError` 在配置了策略时是可重试的。

### 自定义重试逻辑

开发者可以通过 `retry_on` (Python) 或 `retryOn` (JavaScript) 传入自定义函数，以扩展或修改默认行为。例如，排除特定自定义异常：

```python
from langgraph.types import RetryPolicy, default_retry_on

def custom_retry_on(exc: BaseException) -> bool:
    if isinstance(exc, MyCustomError):
        return False
    return default_retry_on(exc)

builder.add_node(
    "call_api",
    call_api,
    retry_policy=RetryPolicy(max_attempts=3, retry_on=custom_retry_on),
)
```

来源：[s2](https://docs.langchain.com/oss/python/langgraph/fault-tolerance), [s4](https://docs.langchain.com/oss/javascript/langgraph/fault-tolerance)

## 超时控制 (Timeouts)

超时机制用于防止节点因外部 API 响应缓慢或死锁而无限期挂起。超时发生在单个节点尝试期间，如果节点执行时间超过设定的阈值，将抛出 `NodeTimeoutError`，该异常会被视为普通异常并触发重试策略（如果已配置）。

### Python 实现

```python
from langgraph.types import TimeoutPolicy

builder.add_node(
    "slow_node",
    slow_node,
    timeout=TimeoutPolicy(run_timeout=30),  # 30秒运行超时
)
```

### JavaScript 实现

```typescript
const graph = new StateGraph(State)
  .addNode("callModel", callModel, {
    timeout: { idleTimeout: 30_000 },  // 30秒空闲超时
    retryPolicy: { maxAttempts: 3 },
  })
  .compile();
```

### 动态超时 (Dynamic Timeouts)

在使用 `Send` 进行动态节点分发（如 Map-Reduce 模式）时，可以在 `Send` 对象中直接覆盖目标节点的静态超时设置：

```typescript
import { Send } from "@langchain/langgraph";

const fanOut = (state: typeof State.State) =>
  state.items.map(
    (item) =>
      new Send("processItem", { item }, { timeout: { idleTimeout: 15_000 } })
  );
```

如果 `Send` 中未指定超时，则使用 `addNode` 时设置的节点默认超时。这允许在节点级别设置默认值，并在特定调用中收紧超时限制。

来源：[s2](https://docs.langchain.com/oss/python/langgraph/fault-tolerance), [s4](https://docs.langchain.com/oss/javascript/langgraph/fault-tolerance)

## 错误处理器与 Saga 模式 (Error Handler)

错误处理器在节点失败且所有重试耗尽后运行。它接收当前状态和错误上下文，允许开发者更新状态或通过 `Command` 路由到不同的节点，从而实现 Saga/补偿模式，避免整个图运行失败。

### 错误处理器签名

错误处理器接收两个参数：`state` 和 `error` (类型为 `NodeError`)。`NodeError` 包含失败节点的名称 (`node`) 和抛出的异常 (`error`)。

```python
from langgraph.errors import NodeError
from langgraph.types import Command

def payment_error_handler(state: State, error: NodeError) -> Command:
    return Command(
        update={"status": f"compensated: {error.error}"},
        goto="finalize",
    )
```

### Saga/补偿模式示例

在电商场景中，如果支付节点失败，错误处理器可以触发补偿逻辑（如取消库存预留）：

```python
from langgraph.graph import StateGraph, START
from langgraph.types import Command, RetryPolicy
from langgraph.errors import NodeError
from typing_extensions import TypedDict

class State(TypedDict):
    status: str

def reserve_inventory(state: State) -> State:
    return {"status": "reserved"}

def charge_payment(state: State) -> State:
    raise RuntimeError("payment timeout")

def payment_error_handler(state: State, error: NodeError) -> Command:
    return Command(
        update={"status": f"compensated_after_{error.node}: {error.error}"},
        goto="finalize",
    )

def finalize(state: State) -> State:
    return state

graph = (
    StateGraph(State)
    .add_node("reserve_inventory", reserve_inventory)
    .add_node(
        "charge_payment",
        charge_payment,
        retry_policy=RetryPolicy(max_attempts=3, retry_on=ConnectionError),
        error_handler=payment_error_handler,
    )
    .add_node("finalize", finalize)
    .add_edge(START, "reserve_inventory")
    .add_edge("reserve_inventory", "charge_payment")
    .compile()
)
```

在此示例中，`charge_payment` 在 `ConnectionError` 上重试 3 次。如果重试耗尽或错误不是 `ConnectionError`，错误处理器将更新状态并路由到 `finalize` 节点，而不是中止图运行。

### 恢复安全性 (Resume-safe Failures)

故障溯源信息会被检查点持久化。如果图在节点失败后但在错误处理器完成前被中断或进程崩溃，当图从检查点恢复时，错误处理器将看到相同的 `NodeError` 上下文。

> **注意**：`interrupt()` 引发的中断不会路由到错误处理器。中断使用 `GraphBubbleUp` 机制暂停图执行，绕过重试策略和错误处理器。

来源：[s2](https://docs.langchain.com/oss/python/langgraph/fault-tolerance), [s4](https://docs.langchain.com/oss/javascript/langgraph/fault-tolerance)

## 幂等性实践 (Idempotency)

重试机制提供的是**至少一次 (at-least-once)** 执行语义。如果节点在外部副作用（如支付、发送邮件）发生后但在返回结果前崩溃，重试将导致重复执行。因此，应用代码必须确保外部副作用是幂等的。

### 使用幂等性键 (Idempotency Key)

向外部服务发送稳定的幂等性键，以便服务去重重试。键必须在副作用运行之前已经持久化。不要在同一个节点内生成键并依赖返回值，因为如果节点崩溃，键不会被检查点持久化。

```python
def charge_customer(state: State) -> dict:
    # 相同的顺序在重试和恢复时始终生成相同的键。
    idempotency_key = f"charge:{state['order_id']}"

    provider.charge(
        customer_id=state["customer_id"],
        amount=state["amount"],
        idempotency_key=idempotency_key,
    )

    # 仅用于可观测性。重试不应依赖此返回值。
    return {"last_payment_key": idempotency_key, "charged": True}
```

### 持久化生成的键

如果没有现有的持久化业务标识，可以在副作用之前的单独节点中持久化生成的键：

```python
import uuid

def reserve_key(state: State) -> dict:
    # 独立节点，确保键在外部操作运行前被检查点持久化。
    return {"payment_key": state.get("payment_key") or str(uuid.uuid4())}

def charge_customer(state: State) -> dict:
    provider.charge(..., idempotency_key=state["payment_key"])
    return {"charged": True}
```

**要求：**
1. 键必须能从持久化状态中重现。重试或在新进程中恢复时应重建相同的键。
2. 外部服务必须支持并尊重该键。在依赖之前请查阅提供商文档。

### 处理缺失的确认

如果提供商提交了操作但确认丢失，图本地没有记录，但副作用可能已发生。使用相同的键进行后续尝试可避免盲目重复，但结果仍未知。应将缺失的本地状态视为未知，而非证明副作用未发生。在补偿或继续之前，应查询提供商的操作状态。

来源：[s2](https://docs.langchain.com/oss/python/langgraph/fault-tolerance), [s4](https://docs.langchain.com/oss/javascript/langgraph/fault-tolerance)

## 图级默认配置 (Graph Defaults)

为了避免在每个 `add_node` 调用中重复配置重试策略、错误处理器和超时，可以使用 `set_node_defaults` (Python) 或 `setNodeDefaults` (JavaScript) 设置图级默认值。

### Python 示例

```python
from langgraph.errors import NodeError
from langgraph.types import RetryPolicy, TimeoutPolicy
from langgraph.graph import StateGraph, START

def default_error_handler(state: State, error: NodeError) -> State:
    return {"status": f"handled: {error.error}"}

graph = (
    StateGraph(State)
    .set_node_defaults(
        retry_policy=RetryPolicy(max_attempts=3),
        error_handler=default_error_handler,
        timeout=TimeoutPolicy(run_timeout=30),
    )
    .add_node("step_a", step_a)
    .add_node("step_b", step_b)
    .add_edge(START, "step_a")
    .compile()
)
```

### JavaScript 示例

```typescript
import { StateGraph, START, NodeError } from "@langchain/langgraph";

const defaultErrorHandler = (
  state: typeof State.State,
  error: NodeError
) => ({ status: `handled: ${error.error.message}` });

const graph = new StateGraph(State)
  .setNodeDefaults({
    retryPolicy: { maxAttempts: 3 },
    errorHandler: defaultErrorHandler,
    timeout: { runTimeout: 30_000 },
    cachePolicy: { ttl: 60 },
  })
  .addNode("stepA", stepA)
  .addNode("stepB", stepB)
  .addEdge(START, "stepA")
  .compile();
```

### 优先级

直接传递给 `add_node` (Python) 或 `addNode` (JavaScript) 的节点级值始终覆盖 `set_node_defaults` 设置的默认值。默认值在 `compile()` 时解析，因此可以在 `add_node` 之前或之后调用 `set_node_defaults`。

来源：[s2](https://docs.langchain.com/oss/python/langgraph/fault-tolerance), [s4](https://docs.langchain.com/oss/javascript/langgraph/fault-tolerance)

## 恢复策略总结

LangGraph 提供了多种恢复策略，适用于不同类型的错误：

| 策略 | 修复者 | 机制 |
| :--- | :--- | :--- |
| 瞬时错误 | 系统 | 节点上的 [重试策略](#retries) |
| 重试后的可恢复故障 | 开发者 | [错误处理器](#error-handler) (Saga/补偿) |
| LLM 可恢复错误 | LLM | 将错误存储到状态中，并通过 [Command](#command) 路由回智能体 |
| 用户可修复错误 | 人类 | 使用 [interrupt()](#interrupts) 暂停 |
| 意外错误 | 开发者 | 让异常冒泡并导致运行失败 |

### LLM 可恢复错误

当工具调用或解析失败且模型可以纠正时，在节点中捕获该错误，将其写入状态，并路由回智能体，以便 LLM 进行调整：

```python
from langgraph.types import Command

def execute_tool(state: State) -> Command:
    try:
        result = run_tool(state["tool_call"])
        return Command(update={"tool_result": result}, goto="agent")
    except ToolError as e:
        # 让 LLM 看到错误并重试
        return Command(
            update={"tool_result": f"Tool error: {e}"},
            goto="agent",
        )
```

这是应用级控制流，不是 `error_handler`。节点处理已知故障模式并保持运行存活。

来源：[s2](https://docs.langchain.com/oss/python/langgraph/fault-tolerance), [s4](https://docs.langchain.com/oss/javascript/langgraph/fault-tolerance)

<!-- knowledgefill:references -->
## 参考资料

- [Fault tolerance - Docs by LangChain](https://docs.langchain.com/oss/python/langgraph/fault-tolerance)
- [Fault tolerance - Docs by LangChain](https://docs.langchain.com/oss/javascript/langgraph/fault-tolerance)
