容错

通过限流、重试、回退和错误处理让你的深度智能体更具韧性

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

错误处理策略

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

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

以下各节通过代码示例介绍每种策略。

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

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

限流

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

服务商限流

聊天模型服务商会限制在给定时间段内可发起的调用次数。要控制请求发出的速率，请在初始化模型时传入 rate_limiter：

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

rate_limiter = InMemoryRateLimiter(
    requests_per_second=0.1,  # 1 request every 10s
    check_every_n_seconds=0.1,  # Check every 100ms whether allowed to make a request
    max_bucket_size=10,  # Controls the maximum burst size
)

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

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

完整配置请参阅限流。

调用上限

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

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。

重试

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

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=[
        # Retry model calls on rate limits, timeouts, and 5xx errors
        ModelRetryMiddleware(max_retries=3, backoff_factor=2.0, initial_delay=1.0),
        # Retry specific tools that hit external APIs (not all tools)
        ToolRetryMiddleware(
            max_retries=2,
            tools=["search", "fetch_url"],
            retry_on=(TimeoutError, ConnectionError),
        ),
    ],
)

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

NOTE

主要的集成包会抛出标准异常类型（ModelAuthenticationError、ModelRateLimitError、ModelTimeoutError 等），它们携带一个 is_retryable 标志，重试 middleware 默认会遵循该标志。完整列表请参阅模型异常。

回退

如果你的主模型服务商完全宕机，回退 middleware 会切换到替代模型：

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

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    middleware=[
        # If the primary model is fully down, fall back to an alternative
        ModelFallbackMiddleware("gpt-5.5"),
    ],
)

完整配置请参阅 ModelFallbackMiddleware。

错误处理

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

NOTE

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']}` failed with {type(exc).__name__}."
    # propagate everything else

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

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

---