容错处理 (Fault tolerance)

通过速率限制、重试、模型回退降级和异常处理提升 deep agent 的健壮性

容错中间件能够在发生异常时保持 deep agent 的平稳运行。并非所有错误都应该以相同的方式处理：瞬态故障（网络超时、速率超限）应自动重试；大语言模型能够自行纠错的错误（不良工具输出、解析失败）应反馈给模型重试；而需要人工介入的错误则应暂停智能体等待指导。

错误处理策略

不同的错误类型需要匹配不同的处理策略：

错误类型	修复责任方	对应策略	采用的中间件或功能
瞬时错误（网络波动、速率超限）	系统（自动）	带指数退避的重试机制	ModelRetryMiddleware, ToolRetryMiddleware
用户可修复错误（缺失信息、指令模糊）	人工处理	使用 interrupt() 暂停执行	人在回路 (Human-in-the-loop)
模型提供商宕机	系统（自动）	降级故障转移至备选模型	ModelFallbackMiddleware
过度调用（失控死循环）	系统（自动）	限制单次运行的模型与工具调用上限	ModelCallLimitMiddleware, ToolCallLimitMiddleware
未预期的系统错误	开发者排查	向上抛出异常由上层捕获	无需中间件，让异常向外冒泡以便排查

以下各节通过代码示例详细阐述每种策略的具体落地方式。

瞬时错误 (Transient errors)

添加重试中间件以自动重试网络异常和速率限制。模型调用和工具调用各自拥有专属的指数退避重试中间件：

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

const agent = createAgent({
  model: "google: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],
    }),
  ],
});

用户可修复错误 (User-fixable)

在需要时（如缺失账号 ID、订单号或需要澄清需求）暂停执行并向用户收集信息。使用 interruptOn 在特定工具调用前暂停智能体：

import { createDeepAgent } from "deepagents";

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

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

模型提供商故障 (Provider outage)

当你的主力模型提供商发生全站宕机时，使用 ModelFallbackMiddleware 自动无缝降级切换至备选模型：

import { createAgent, modelFallbackMiddleware } from "langchain";

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

过度调用失控 (Excessive calls)

如果不加限制，陷入死循环的智能体可能会在几分钟内耗尽你的 LLM API 预算。建议为每次运行的模型调用与工具执行次数分别设置安全上限：

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

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

未预期错误 (Unexpected)

允许其向外冒泡以便调试排查。切勿盲目吞掉无法妥善处理的异常。这一准则同样适用于 JavaScript SDK 中的自定义中间件。

速率限制 (Rate limiting)

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

提供商速率限制 (Provider rate limiting)

聊天模型提供商通常会限制在特定时间窗口内允许发起的请求数量。为了平滑请求速率，可在初始化模型时配置 rate_limiter。

调用次数上限 (Call limits)

设置调用次数熔断上限：

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

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

使用 run_limit 限制单次调用的执行次数（每轮对话均会重置）。使用 thread_limit 限制跨整个对话线程的累计调用次数（需要配合检查点器）。完整配置请参阅 ModelCallLimitMiddleware 和 ToolCallLimitMiddleware。

重试机制 (Retries)

瞬态故障（网络超时、429 速率限制）应自动重试。模型调用和工具调用各自拥有独立的指数退避重试中间件：

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

const agent = createAgent({
  model: "google: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。

模型降级回退 (Fallbacks)

当主力模型提供商全站故障时，Fallback 中间件会自动将请求路由至备选模型：

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

const agent = createAgent({
  model: "google:gemini-3.6-flash",
  middleware: [
    // 当主力模型完全宕机时，自动回退到备用模型
    modelFallbackMiddleware("gpt-5.5"),
  ],
});

完整配置请参阅 ModelFallbackMiddleware。

错误处理状态

当某个工具在执行期间抛出未捕获的异常时，智能体运行默认会中止。ToolErrorMiddleware 目前在 JavaScript SDK 中尚未正式提供。