容错能力

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

错误处理策略

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

错误类型	修复方	策略	中间件或功能
临时性错误（网络问题、速率限制）	系统（自动）	采用指数退避进行重试	ModelRetryMiddleware, ToolRetryMiddleware
LLM 可恢复的错误（工具故障、解析问题）	LLM	转换为错误 `ToolMessage` 并让模型调整	ToolErrorMiddleware
用户可修复的错误（信息缺失、指令不清）	人工	使用 `interrupt()` 暂停	人机协同
服务提供商中断	系统（自动）	切换至备用模型	ModelFallbackMiddleware
过度调用（失控循环）	系统（自动）	限制单次运行中的模型和工具调用次数	ModelCallLimitMiddleware, ToolCallLimitMiddleware
意外错误	开发者	让其向上传播	无中间件 — 让异常继续传播

以下章节将结合代码示例介绍每种策略。

添加重试中间件以自动重试网络问题和速率限制错误。模型调用和工具调用各有其支持指数退避的重试中间件：

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),
        ),
    ],
)

使用 ToolErrorMiddleware 来捕获工具异常，并将其转换为错误 ToolMessage，以便 LLM 能够了解问题所在并尝试重新执行：

ToolErrorMiddleware 需要 langchain>=1.3.14。

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"工具 `{request.tool_call['name']}` 执行失败：{type(exc).__name__}。请修正输入并重试。"
    # 其他错误继续传播


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

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

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,
    },
)

有关完整的人机协同指南，请参阅人机协同。

如果您的主要模型提供商完全中断，可使用 ModelFallbackMiddleware 切换至备用模型：

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"),
    ],
)

若不加限制，一个困惑的智能体可能在几分钟内耗尽您的 LLM API 预算，例如在同一个工具调用上循环或执行数百次模型调用。请为单次运行设置模型调用和工具执行的次数上限：

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),
    ],
)

让它们向上传播以便调试。不要捕获您无法处理的错误。ToolErrorMiddleware 只会向模型返回您明确处理的异常内容；其他所有异常将保持原样传播：

def on_error(exc: Exception, request: ToolCallRequest) -> str | None:
    if isinstance(exc, (ValueError, KeyError)):
        # 将已知的、可恢复的错误反馈给模型
        return f"工具 `{request.tool_call['name']}` 执行失败：{type(exc).__name__}。"
    # 其他所有错误（意外错误）将传播并导致运行中止

速率限制

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

提供商速率限制

聊天模型提供商会对特定时间段内的调用次数施加限制。要控制发出请求的速率，请在初始化模型时配置 rate_limiter：

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])

有关完整配置，请参阅速率限制。

调用次数限制

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),
    ],
)

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

重试

临时性故障（网络超时、速率限制）应自动重试。模型调用和工具调用各有其支持指数退避的重试中间件：

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),
        ),
    ],
)

将 ToolRetryMiddleware 的作用范围限定于特定工具，而不是重试所有工具。文件系统的 read_file 失败后重试可能无济于事，但网络搜索超时则可能有效。有关完整配置，请参阅 ModelRetryMiddleware。

降级

如果您的主要模型提供商完全中断，降级中间件将切换至备用模型：

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"),
    ],
)

有关完整配置，请参阅 ModelFallbackMiddleware。

错误处理

当工具在执行过程中抛出异常时，默认情况下智能体运行会中止。使用 ToolErrorMiddleware 来捕获特定异常，并将其转换为模型可见且可恢复的错误 ToolMessage，而不是导致运行崩溃。

ToolErrorMiddleware 需要 langchain>=1.3.14。

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']}` 失败，错误类型：{type(exc).__name__}。"
    # 其他错误继续传播


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

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

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Get started

Deployment

Execution environment

Context management

Delegation

Steering

Frontend

Protocols

错误处理策略

速率限制

提供商速率限制

调用次数限制

重试

降级

错误处理

​错误处理策略

​速率限制

​提供商速率限制

​调用次数限制

​重试

​降级

​错误处理

错误处理策略

速率限制

提供商速率限制

调用次数限制

重试

降级

错误处理