容错 | LangChain 中文文档

容错中间件确保你的深度智能体在出错时仍能继续运行。并非所有错误都应以相同的方式处理：瞬时故障（网络超时、限流）应自动重试，LLM 可以自行恢复的错误（工具输出错误、解析失败）应反馈给模型，而需要人工输入的错误则应暂停智能体。

错误处理策略

不同的错误需要不同的处理策略：

错误类型	谁修复	策略	中间件或功能
瞬时错误（网络问题、限流）	系统（自动）	指数退避重试	ModelRetryMiddleware, ToolRetryMiddleware
LLM 可恢复的错误（工具故障、解析问题）	LLM	转换为错误 `ToolMessage` 并让模型调整	ToolErrorMiddleware
用户可修复的错误（信息缺失、指令不清）	人类	使用 `interrupt()` 暂停	人在回路
提供商中断	系统（自动）	回退到替代模型	ModelFallbackMiddleware
调用过多（失控循环）	系统（自动）	限制每次运行的模型和工具调用次数	ModelCallLimitMiddleware, ToolCallLimitMiddleware
意外错误	开发者	让其向上抛出	无中间件——让异常传播

以下各节将以代码示例逐一介绍每种策略。

瞬时错误

添加重试中间件，以自动重试网络问题和限流。模型调用和工具调用各有自己的带指数退避的重试中间件：

python

from langchain.agents import create_agent
from langchain.agents.middleware import ModelRetryMiddleware, ToolRetryMiddleware

agent = create_agent(
    model="google_genai:gemini-3.6-flash",
    tools=[search_tool, fetch_url_tool],
    middleware=[
        ModelRetryMiddleware(max_retries=3, backoff_factor=2.0, initial_delay=1.0),
        ToolRetryMiddleware(
            max_retries=2,
            tools=["search", "fetch_url"],
            retry_on=(TimeoutError, ConnectionError),
        ),
    ],
)

typescript

import { createAgent, modelRetryMiddleware, toolRetryMiddleware } from "langchain";

const agent = createAgent({
  model: "google_genai:gemini-3.6-flash",
  tools: [searchTool, fetchUrlTool],
  middleware: [
    modelRetryMiddleware({ maxRetries: 3, backoffFactor: 2.0, initialDelayMs: 1000 }),
    toolRetryMiddleware({
      maxRetries: 2,
      tools: ["search", "fetch_url"],
      retryOn: [TimeoutError, TypeError],
    }),
  ],
});

LLM 可恢复

使用 ToolErrorMiddleware 捕获工具异常并将其转换为错误 ToolMessage，这样 LLM 就能看到哪里出错了并重试：

INFO

ToolErrorMiddleware 需要 langchain>=1.3.14。

python

from langchain.agents import create_agent
from langchain.agents.middleware import ToolErrorMiddleware

def on_error(exc: Exception, request: ToolCallRequest) -> str | None:
    if isinstance(exc, ValueError):
        return f"Tool `{request.tool_call['name']}` failed: {type(exc).__name__}. Fix the input and retry."
    # 其余异常原样传播

agent = create_agent(
    model="google_genai:gemini-3.6-flash",
    tools=[search_tool],
    middleware=[ToolErrorMiddleware(on_error)],
)

此中间件在 JavaScript SDK 中尚不可用。

用户可修复

在需要时暂停并从用户处收集信息（如账户 ID、订单号或澄清说明）。使用 interrupt_on 在特定工具调用之前暂停智能体：

python

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    tools=[send_email_tool, delete_record_tool],
    interrupt_on={
        "send_email": True,
        "delete_record": True,
    },
)

typescript

import { createDeepAgent } from "deepagents";

const agent = createDeepAgent({
  model: "google_genai:gemini-3.6-flash",
  tools: [sendEmailTool, deleteRecordTool],
  interruptOn: {
    send_email: true,
    delete_record: true,
  },
});

完整的人在回路指南，请参阅人在回路。

提供商中断

如果你的主要模型提供商完全中断，请使用 ModelFallbackMiddleware 切换到替代模型：

python

from langchain.agents import create_agent
from langchain.agents.middleware import ModelFallbackMiddleware

agent = create_agent(
    model="google_genai:gemini-3.6-flash",
    tools=[search_tool],
    middleware=[
        ModelFallbackMiddleware("gpt-5.5"),
    ],
)

typescript

import { createAgent, modelFallbackMiddleware } from "langchain";

const agent = createAgent({
  model: "google_genai:gemini-3.6-flash",
  tools: [searchTool],
  middleware: [
    modelFallbackMiddleware("gpt-5.5"),
  ],
});

调用过多

如果没有限制，一个困惑的智能体可能会通过反复循环同一工具调用或进行数百次模型调用，在几分钟内烧光你的 LLM API 预算。为每次运行的模型调用和工具执行设置上限：

python

from langchain.agents import create_agent
from langchain.agents.middleware import ModelCallLimitMiddleware, ToolCallLimitMiddleware

agent = create_agent(
    model="google_genai:gemini-3.6-flash",
    tools=[search_tool],
    middleware=[
        ModelCallLimitMiddleware(run_limit=50),
        ToolCallLimitMiddleware(run_limit=200),
    ],
)

typescript

import { createAgent, modelCallLimitMiddleware, toolCallLimitMiddleware } from "langchain";

const agent = createAgent({
  model: "google_genai:gemini-3.6-flash",
  tools: [searchTool],
  middleware: [
    modelCallLimitMiddleware({ runLimit: 50 }),
    toolCallLimitMiddleware({ runLimit: 200 }),
  ],
});

意外

让它们向上抛出以便调试。不要捕获你无法处理的东西。ToolErrorMiddleware 只暴露你显式返回内容的异常；其他所有异常都会原样传播：

python

def on_error(exc: Exception, request: ToolCallRequest) -> str | None:
    if isinstance(exc, (ValueError, KeyError)):
        # 向模型呈现已知的、可恢复的错误
        return f"Tool `{request.tool_call['name']}` failed: {type(exc).__name__}."
    # 其余（意外）错误会原样传播并终止运行

此模式同样适用于 JavaScript SDK 中的自定义中间件。

限流

有两种互补的方式来限制资源使用：控制对模型提供商的请求速率，以及限制每次运行的总调用次数。

提供商限流

对话模型提供商会限制在给定时间段内可以进行的调用次数。要控制发起请求的速率，请使用 rate_limiter 初始化你的模型：

python

from langchain.rate_limiters import InMemoryRateLimiter
from langchain.chat_models import init_chat_model

rate_limiter = InMemoryRateLimiter(
    requests_per_second=0.1,  # 每 10 秒 1 个请求
    check_every_n_seconds=0.1,  # 每 100 毫秒检查一次是否允许发起请求
    max_bucket_size=10,  # 控制最大突发大小
)

model = init_chat_model(
    model="google_genai:gemini-3.6-flash",
    rate_limiter=rate_limiter,  
)

agent = create_deep_agent(model=model, tools=[search_tool])

有关完整配置，请参阅限流。

调用限制

python

from deepagents import create_deep_agent
from langchain.agents.middleware import ModelCallLimitMiddleware, ToolCallLimitMiddleware

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    middleware=[
        ModelCallLimitMiddleware(run_limit=50),
        ToolCallLimitMiddleware(run_limit=200),
    ],
)

typescript

import { createAgent, modelCallLimitMiddleware, toolCallLimitMiddleware } from "langchain";

const agent = createAgent({
  model: "google_genai:gemini-3.6-flash",
  middleware: [
    modelCallLimitMiddleware({ runLimit: 50 }),
    toolCallLimitMiddleware({ runLimit: 200 }),
  ],
});

使用 run_limit 来限制单次调用内的调用次数（每轮重置）。使用 thread_limit 来限制整个对话中的调用次数（需要检查点）。完整配置请参阅 ModelCallLimitMiddleware 和 ToolCallLimitMiddleware。

重试

瞬时故障（网络超时、限流）应自动重试。模型调用和工具调用各有自己的带指数退避的重试中间件：

python

from deepagents import create_deep_agent
from langchain.agents.middleware import ModelRetryMiddleware, ToolRetryMiddleware

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    middleware=[
        # 在限流、超时和 5xx 错误时重试模型调用
        ModelRetryMiddleware(max_retries=3, backoff_factor=2.0, initial_delay=1.0),
        # 重试命中外部 API 的特定工具（不是所有工具）
        ToolRetryMiddleware(
            max_retries=2,
            tools=["search", "fetch_url"],
            retry_on=(TimeoutError, ConnectionError),
        ),
    ],
)

typescript

import {
  createAgent,
  modelRetryMiddleware,
  toolRetryMiddleware,
} from "langchain";

const agent = createAgent({
  model: "google_genai:gemini-3.6-flash",
  middleware: [
    // 在限流、超时和 5xx 错误时重试模型调用
    modelRetryMiddleware({ maxRetries: 3, backoffFactor: 2.0, initialDelayMs: 1000 }),
    // 重试命中外部 API 的特定工具（不是所有工具）
    toolRetryMiddleware({
      maxRetries: 2,
      tools: ["search", "fetch_url"],
      retryOn: [TimeoutError, TypeError],
    }),
  ],
});

将 ToolRetryMiddleware 的作用域限定到特定工具，而不是重试所有内容。失败的文件系统 read_file 不会因重试而受益，但超时的网络搜索可能会。完整配置请参阅 ModelRetryMiddleware。

回退

如果你的主要模型提供商完全中断，回退中间件会切换到替代模型：

python

from deepagents import create_deep_agent
from langchain.agents.middleware import ModelFallbackMiddleware

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    middleware=[
        # 如果主要模型完全不可用，回退到替代模型
        ModelFallbackMiddleware("gpt-5.5"),
    ],
)

typescript

import {
  createAgent,
  modelFallbackMiddleware,
} from "langchain";

const agent = createAgent({
  model: "google_genai:gemini-3.6-flash",
  middleware: [
    // 如果主要模型完全不可用，回退到替代模型
    modelFallbackMiddleware("gpt-5.5"),
  ],
});

完整配置请参阅 ModelFallbackMiddleware。

错误处理

当工具在执行期间抛出异常时，智能体运行默认会停止。使用 ToolErrorMiddleware 捕获特定异常并将其转换为模型可以看到并恢复的错误 ToolMessage，而不是让运行崩溃。

INFO

ToolErrorMiddleware 需要 langchain>=1.3.14。

python

from deepagents import create_deep_agent
from langchain.agents.middleware import ToolErrorMiddleware

def on_error(exc: Exception, request: ToolCallRequest) -> str | None:
    if isinstance(exc, ValueError):
        return f"`{request.tool_call['name']}` failed with {type(exc).__name__}."
    # 其余异常原样传播

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    middleware=[ToolErrorMiddleware(on_error)],
)

有关完整配置选项和使用模式（包括异步处理程序以及与重试中间件的组合），请参阅预置中间件。

Going to production

Interpreters

Patterns

Configuration

错误处理策略

瞬时错误

LLM 可恢复

用户可修复

提供商中断

调用过多

意外

限流

提供商限流

调用限制

重试

回退

错误处理

错误处理策略 ​

瞬时错误 ​

LLM 可恢复 ​

用户可修复 ​

提供商中断 ​

调用过多 ​

意外 ​

限流 ​

提供商限流 ​

调用限制 ​

重试 ​

回退 ​

错误处理 ​

错误处理策略

瞬时错误

LLM 可恢复

用户可修复

提供商中断

调用过多

意外

限流

提供商限流

调用限制

重试

回退

错误处理