容错能力

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

错误处理策略

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

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

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

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

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

使用 @[ToolErrorMiddleware] 来捕获工具异常，并将其转换为错误 ToolMessage，以便 LLM 能够了解问题所在并尝试重新执行：此中间件在 JavaScript SDK 中尚未提供。

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

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 切换至备用模型：

import { createAgent, modelFallbackMiddleware } from "langchain";

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

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

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

速率限制

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

提供商速率限制

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

调用次数限制

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。

重试

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

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。

降级

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

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

const agent = createAgent({
  model: "google_genai:gemini-3.6-flash",
  middleware: [
    // 如果主模型完全宕机，则降级至备用模型
    modelFallbackMiddleware("gpt-5.5"),
  ],
});

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

错误处理

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

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

错误处理策略

速率限制

提供商速率限制

调用次数限制

重试

降级

错误处理

​错误处理策略

​速率限制

​提供商速率限制

​调用次数限制

​重试

​降级

​错误处理

错误处理策略

速率限制

提供商速率限制

调用次数限制

重试

降级

错误处理