预构建中间件 - Docs by LangChain

LangChain 和 Deep Agents 为常见用例提供预构建中间件。每个中间件都已可用于生产环境，并可根据你的具体需求进行配置。

与提供商无关的中间件

以下中间件适用于任何 LLM 提供商：

中间件	描述
摘要	在接近 Token 限制时自动摘要对话历史。
人机协作	暂停执行以等待人工审批工具调用。
模型调用限制	限制模型调用次数以防止过度成本。
工具调用限制	通过限制调用次数来控制工具执行。
模型回退	当主模型失败时自动回退到替代模型。
PII 检测	检测和处理个人身份信息（PII）。
待办事项列表	为智能体配备任务规划和跟踪能力。
LLM 工具选择器	在调用主模型之前使用 LLM 选择相关工具。
工具重试	使用指数退避自动重试失败的工具调用。
模型重试	使用指数退避自动重试失败的模型调用。
LLM 工具模拟器	使用 LLM 模拟工具执行，用于测试目的。
上下文编辑	通过修剪或清除工具使用来管理对话上下文。
文件系统	为智能体提供用于存储上下文和长期记忆的文件系统。
子智能体中间件	添加生成子智能体的能力。

摘要

在接近 Token 限制时自动摘要对话历史，保留最近的消息同时压缩较旧的上下文。摘要适用于以下场景：

超过上下文窗口的长时间对话。
具有大量历史的多轮对话。
保留完整对话上下文很重要的应用。

import { createAgent, summarizationMiddleware } from "langchain";

const agent = createAgent({
  model: "gpt-5.4",
  tools: [weatherTool, calculatorTool],
  middleware: [
    summarizationMiddleware({
      model: "gpt-5.4-mini",
      trigger: { tokens: 4000 },
      keep: { messages: 20 },
    }),
  ],
});

配置选项

trigger 和 keep 的 fraction 条件（如下所示）依赖于聊天模型的配置数据（如果使用 langchain@1.1.0）。如果数据不可用，使用其他条件或手动指定：

const customProfile: ModelProfile = {
    maxInputTokens: 100_000,
    // ...
}
model = await initChatModel("...", {
    profile: customProfile,
});

model

string | BaseChatModel

required

用于生成摘要的模型。可以是模型标识符字符串（例如 'openai:gpt-5.4-mini'）或 BaseChatModel 实例。

trigger

object | object[]

触发摘要的条件。可以是：

单个条件对象（所有属性必须满足 - AND 逻辑）
条件对象数组（任一条件满足即可 - OR 逻辑）

每个条件可以包括：

fraction（number）：模型上下文大小的比例（0-1）
tokens（number）：绝对 Token 数
messages（number）：消息数量

每个条件至少必须指定一个属性。如果未提供，摘要不会自动触发。

keep

object

default:"{messages: 20}"

摘要后保留多少上下文。精确指定以下之一：

fraction（number）：保留模型上下文大小的比例（0-1）
tokens（number）：保留的绝对 Token 数
messages（number）：保留的最近消息数量

tokenCounter

function

自定义 Token 计数函数。默认使用基于字符的计数。

summaryPrompt

string

用于摘要的自定义提示词模板。如果未指定则使用内置模板。模板应包含 {messages} 占位符，对话历史将被插入此处。

trimTokensToSummarize

number

default:"4000"

生成摘要时要包含的最大 Token 数。消息将被修剪以适应此限制，然后再进行摘要。

summaryPrefix

string

添加到摘要消息前面的前缀。如果未提供，使用默认前缀。

maxTokensBeforeSummary

number

deprecated

已弃用： 请使用 trigger: { tokens: value } 代替。触发摘要的 Token 阈值。

messagesToKeep

number

deprecated

已弃用： 请使用 keep: { messages: value } 代替。要保留的最近消息数。

完整示例

摘要中间件监控消息 Token 数量，并在达到阈值时自动摘要较旧的消息。触发条件控制何时运行摘要：

单个条件对象（指定的条件必须满足）
条件数组（任一条件满足即可 - OR 逻辑）
每个条件可以使用 fraction（模型上下文大小的比例）、tokens（绝对数量）或 messages（消息数量）

保留条件控制保留多少上下文（精确指定一个）：

fraction - 保留模型上下文大小的比例
tokens - 保留的绝对 Token 数
messages - 保留的最近消息数量

import { createAgent, summarizationMiddleware } from "langchain";

// 单个条件
const agent = createAgent({
  model: "gpt-5.4",
  tools: [weatherTool, calculatorTool],
  middleware: [
    summarizationMiddleware({
      model: "gpt-5.4-mini",
      trigger: { tokens: 4000, messages: 10 },
      keep: { messages: 20 },
    }),
  ],
});

// 多个条件
const agent2 = createAgent({
  model: "gpt-5.4",
  tools: [weatherTool, calculatorTool],
  middleware: [
    summarizationMiddleware({
      model: "gpt-5.4-mini",
      trigger: [
        { tokens: 3000, messages: 6 },
      ],
      keep: { messages: 20 },
    }),
  ],
});

// 使用比例限制
const agent3 = createAgent({
  model: "gpt-5.4",
  tools: [weatherTool, calculatorTool],
  middleware: [
    summarizationMiddleware({
      model: "gpt-5.4-mini",
      trigger: { fraction: 0.8 },
      keep: { fraction: 0.3 },
    }),
  ],
});

人机协作

在工具调用执行之前暂停智能体执行以等待人工审批、编辑或拒绝。人机协作适用于以下场景：

需要人工审批的高风险操作（例如数据库写入、金融交易）。
人工监督是强制性的合规工作流。
人类反馈引导智能体的长时间对话。

人机协作中间件需要检查点来跨中断维护状态。

import { createAgent, humanInTheLoopMiddleware } from "langchain";

function readEmailTool(emailId: string): string {
  /** 模拟函数，通过 ID 读取邮件。 */
  return `Email content for ID: ${emailId}`;
}

function sendEmailTool(recipient: string, subject: string, body: string): string {
  /** 模拟函数，发送邮件。 */
  return `Email sent to ${recipient} with subject '${subject}'`;
}

const agent = createAgent({
  model: "gpt-5.4",
  tools: [readEmailTool, sendEmailTool],
  middleware: [
    humanInTheLoopMiddleware({
      interruptOn: {
        sendEmailTool: {
          allowedDecisions: ["approve", "edit", "reject"],
        },
        readEmailTool: false,
      }
    })
  ]
});

如需完整示例、配置选项和集成模式，请参阅人机协作文档。

观看此视频指南，演示人机协作中间件的行为。

模型调用限制

限制模型调用次数以防止无限循环或过度成本。模型调用限制适用于以下场景：

防止失控的智能体进行过多 API 调用。
在生产部署中强制执行成本控制。
在特定调用预算内测试智能体行为。

import { createAgent, modelCallLimitMiddleware } from "langchain";
import { MemorySaver } from "@langchain/langgraph";

const agent = createAgent({
  model: "gpt-5.4",
  checkpointer: new MemorySaver(), // 线程限制所需
  tools: [],
  middleware: [
    modelCallLimitMiddleware({
      threadLimit: 10,
      runLimit: 5,
      exitBehavior: "end",
    }),
  ],
});

观看此视频指南，演示模型调用限制中间件的行为。

配置选项

threadLimit

number

线程中所有运行的最大模型调用次数。默认无限制。

runLimit

number

单次调用的最大模型调用次数。默认无限制。

exitBehavior

string

default:"end"

达到限制时的行为。选项：'end'（优雅终止）或 'error'（抛出异常）

工具调用限制

通过限制工具调用次数来控制智能体执行，可以全局应用于所有工具或针对特定工具。工具调用限制适用于以下场景：

防止对昂贵外部 API 的过多调用。
限制网页搜索或数据库查询。
对特定工具使用强制执行速率限制。
防止智能体失控循环。

import { createAgent, toolCallLimitMiddleware } from "langchain";

const agent = createAgent({
  model: "gpt-5.4",
  tools: [searchTool, databaseTool],
  middleware: [
    toolCallLimitMiddleware({ threadLimit: 20, runLimit: 10 }),
    toolCallLimitMiddleware({
      toolName: "search",
      threadLimit: 5,
      runLimit: 3,
    }),
  ],
});

观看此视频指南，演示工具调用限制中间件的行为。

配置选项

toolName

string

要限制的特定工具名称。如果未提供，限制全局应用于所有工具。

threadLimit

number

线程（对话）中所有运行的最大工具调用次数。跨多次使用相同线程 ID 的调用持久化。需要检查点来维护状态。undefined 表示无线程限制。

runLimit

number

单次调用（一个用户消息 → 响应周期）的最大工具调用次数。每条新用户消息时重置。undefined 表示无运行限制。注意： 必须至少指定 threadLimit 或 runLimit 之一。

exitBehavior

string

default:"continue"

达到限制时的行为：

'continue'（默认）- 用错误消息阻止超出的工具调用，让其他工具和模型继续。模型根据错误消息决定何时结束。
'error' - 抛出 ToolCallLimitExceededError 异常，立即停止执行
'end' - 立即停止执行，为超出的工具调用提供 ToolMessage 和 AI 消息。仅在限制单个工具时有效；如果其他工具有待处理的调用则抛出错误。

完整示例

使用以下方式指定限制：

线程限制 - 对话中所有运行的最大调用次数（需要检查点）
运行限制 - 单次调用的最大调用次数（每轮重置）

退出行为：

'continue'（默认）- 用错误消息阻止超出的调用，智能体继续
'error' - 立即引发异常
'end' - 带 ToolMessage + AI 消息停止（仅限单工具场景）

import { createAgent, toolCallLimitMiddleware } from "langchain";

const globalLimiter = toolCallLimitMiddleware({ threadLimit: 20, runLimit: 10 });
const searchLimiter = toolCallLimitMiddleware({ toolName: "search", threadLimit: 5, runLimit: 3 });
const databaseLimiter = toolCallLimitMiddleware({ toolName: "query_database", threadLimit: 10 });
const strictLimiter = toolCallLimitMiddleware({ toolName: "scrape_webpage", runLimit: 2, exitBehavior: "error" });

const agent = createAgent({
  model: "gpt-5.4",
  tools: [searchTool, databaseTool, scraperTool],
  middleware: [globalLimiter, searchLimiter, databaseLimiter, strictLimiter],
});

模型回退

当主模型失败时自动回退到替代模型。模型回退适用于以下场景：

构建能处理模型中断的弹性智能体。
通过回退到更便宜的模型进行成本优化。
跨 OpenAI、Anthropic 等提供商的冗余。

import { createAgent, modelFallbackMiddleware } from "langchain";

const agent = createAgent({
  model: "gpt-5.4",
  tools: [],
  middleware: [
    modelFallbackMiddleware(
      "gpt-5.4-mini",
      "claude-3-5-sonnet-20241022"
    ),
  ],
});

配置选项

该中间件接受可变数量的字符串参数，按顺序表示回退模型：

...models

string[]

required

当主模型失败时按顺序尝试的一个或多个回退模型字符串

modelFallbackMiddleware(
  "first-fallback-model",
  "second-fallback-model",
  // ... 更多模型
)

PII 检测

使用可配置策略检测和处理对话中的个人身份信息（PII）。PII 检测适用于以下场景：

有合规要求的医疗保健和金融应用。
需要清理日志的客户服务智能体。
处理敏感用户数据的任何应用。

import { createAgent, piiMiddleware } from "langchain";

const agent = createAgent({
  model: "gpt-5.4",
  tools: [],
  middleware: [
    piiMiddleware("email", { strategy: "redact", applyToInput: true }),
    piiMiddleware("credit_card", { strategy: "mask", applyToInput: true }),
  ],
});

自定义 PII 类型

你可以通过提供 detector 参数来创建自定义 PII 类型。这允许你检测超出内置类型的特定于你的用例的模式。 创建自定义检测器的三种方式：

正则表达式模式字符串 - 简单的模式匹配
RegExp 对象 - 对正则表达式标志有更多控制
自定义函数 - 带验证的复杂检测逻辑

import { createAgent, piiMiddleware, type PIIMatch } from "langchain";

// 方法 1：正则表达式模式字符串
const agent1 = createAgent({
  model: "gpt-5.4",
  tools: [],
  middleware: [
    piiMiddleware("api_key", {
      detector: "sk-[a-zA-Z0-9]{32}",
      strategy: "block",
    }),
  ],
});

// 方法 2：RegExp 对象
const agent2 = createAgent({
  model: "gpt-5.4",
  tools: [],
  middleware: [
    piiMiddleware("phone_number", {
      detector: /\+?\d{1,3}[\s.-]?\d{3,4}[\s.-]?\d{4}/,
      strategy: "mask",
    }),
  ],
});

// 方法 3：自定义检测器函数
function detectSSN(content: string): PIIMatch[] {
  const matches: PIIMatch[] = [];
  const pattern = /\d{3}-\d{2}-\d{4}/g;
  let match: RegExpExecArray | null;

  while ((match = pattern.exec(content)) !== null) {
    const ssn = match[0];
    // 验证：前 3 位不应为 000、666 或 900-999
    const firstThree = parseInt(ssn.substring(0, 3), 10);
    if (firstThree !== 0 && firstThree !== 666 && !(firstThree >= 900 && firstThree <= 999)) {
      matches.push({
        text: ssn,
        start: match.index ?? 0,
        end: (match.index ?? 0) + ssn.length,
      });
    }
  }
  return matches;
}

const agent3 = createAgent({
  model: "gpt-5.4",
  tools: [],
  middleware: [
    piiMiddleware("ssn", {
      detector: detectSSN,
      strategy: "hash",
    }),
  ],
});

自定义检测器函数签名： 检测器函数必须接受一个字符串（内容）并返回匹配项：返回 PIIMatch 对象的数组：

interface PIIMatch {
  text: string;    // 匹配的文本
  start: number;   // 内容中的起始索引
  end: number;      // 内容中的结束索引
}

function detector(content: string): PIIMatch[] {
  return [
    { text: "matched_text", start: 0, end: 12 },
    // ... 更多匹配
  ];
}

对于自定义检测器：

对简单模式使用正则字符串
需要标志时使用 RegExp 对象（例如不区分大小写的匹配）
需要超出模式匹配的验证逻辑时使用自定义函数
自定义函数让你完全控制检测逻辑，可以实现复杂的验证规则

配置选项

piiType

string

required

要检测的 PII 类型。可以是内置类型（email、credit_card、ip、mac_address、url）或自定义类型名称。

strategy

string

default:"redact"

如何处理检测到的 PII。选项：

'block' - 检测到时抛出错误
'redact' - 替换为 [REDACTED_TYPE]
'mask' - 部分遮蔽（例如 ****-****-****-1234）
'hash' - 替换为确定性哈希（例如 <email_hash:a1b2c3d4>）

detector

RegExp | string | function

自定义检测器。可以是：

RegExp - 用于匹配的正则表达式
string - 正则表达式模式字符串（例如 "sk-[a-zA-Z0-9]{32}"）
function - 自定义检测器函数 (content: string) => PIIMatch[]

如果未提供，使用 PII 类型的内置检测器。

applyToInput

boolean

default:"true"

在模型调用前检查用户消息

applyToOutput

boolean

default:"false"

在模型调用后检查 AI 消息

applyToToolResults

boolean

default:"false"

在执行后检查工具结果消息

待办事项列表

为智能体配备任务规划和跟踪能力，用于复杂的多步任务。待办事项列表适用于以下场景：

需要跨多个工具协调的复杂多步任务。
进度可见性很重要的长时间运行操作。

此中间件自动为智能体提供 write_todos 工具和系统提示词来指导有效的任务规划。

import { createAgent, todoListMiddleware } from "langchain";

const agent = createAgent({
  model: "gpt-5.4",
  tools: [readFile, writeFile, runTests],
  middleware: [todoListMiddleware()],
});

观看此视频指南，演示待办事项列表中间件的行为。

配置选项

无可用配置选项（使用默认值）。

LLM 工具选择器

在调用主模型之前使用 LLM 智能选择相关工具。LLM 工具选择器适用于以下场景：

拥有很多工具（10+）且每次查询大多数不相关的智能体。
通过过滤不相关的工具来减少 Token 使用。
提高模型的聚焦度和准确性。

此中间件使用结构化输出来询问 LLM 哪些工具与当前查询最相关。结构化输出模式定义了可用的工具名称和描述。模型提供商通常在幕后将此结构化输出信息添加到系统提示词中。

import { createAgent, llmToolSelectorMiddleware } from "langchain";

const agent = createAgent({
  model: "gpt-5.4",
  tools: [tool1, tool2, tool3, tool4, tool5, ...],
  middleware: [
    llmToolSelectorMiddleware({
      model: "gpt-5.4-mini",
      maxTools: 3,
      alwaysInclude: ["search"],
    }),
  ],
});

配置选项

model

string | BaseChatModel

用于工具选择的模型。可以是模型标识符字符串（例如 'openai:gpt-5.4-mini'）或 BaseChatModel 实例。默认为智能体的主模型。

systemPrompt

string

选择模型的指令。如果未指定则使用内置提示词。

maxTools

number

选择的最大工具数。如果模型选择了更多，只使用前 maxTools 个。如果未指定则无限制。

alwaysInclude

string[]

无论选择结果如何都始终包含的工具名称。这些不计入 maxTools 限制。

工具重试

使用可配置的指数退避自动重试失败的工具调用。工具重试适用于以下场景：

处理外部 API 调用中的瞬态故障。
提高依赖网络的工具的可靠性。
构建能优雅处理临时错误的弹性智能体。

API 参考： toolRetryMiddleware

import { createAgent, toolRetryMiddleware } from "langchain";

const agent = createAgent({
  model: "gpt-5.4",
  tools: [searchTool, databaseTool],
  middleware: [
    toolRetryMiddleware({
      maxRetries: 3,
      backoffFactor: 2.0,
      initialDelayMs: 1000,
    }),
  ],
});

配置选项

maxRetries

number

default:"2"

初始调用后的最大重试次数（默认为总共 3 次尝试）。必须 >= 0。

tools

(ClientTool | ServerTool | string)[]

可选的工具或工具名称数组，用于应用重试逻辑。可以是 BaseTool 实例列表或工具名称字符串。如果为 undefined，则应用于所有工具。

retryOn

((error: Error) => boolean) | (new (...args: any[]) => Error)[]

default:"() => true"

要重试的错误构造函数数组，或接受错误并返回 true 表示应重试的函数。默认为对所有错误重试。

onFailure

'error' | 'continue' | ((error: Error) => string)

default:"continue"

所有重试耗尽时的行为。选项：

'continue'（默认）- 返回带错误详情的 ToolMessage，允许 LLM 处理故障并可能恢复
'error' - 重新抛出异常，停止智能体执行
自定义函数 - 接受异常并返回 ToolMessage 内容的字符串的函数，允许自定义错误格式

已弃用的值： 'raise'（使用 'error' 代替）和 'return_message'（使用 'continue' 代替）。这些已弃用的值仍然有效但会显示警告。

backoffFactor

number

default:"2.0"

指数退避的乘数。每次重试等待 initialDelayMs * (backoffFactor ** retryNumber) 毫秒。设为 0.0 表示恒定延迟。必须 >= 0。

initialDelayMs

number

default:"1000"

首次重试前的初始延迟（毫秒）。必须 >= 0。

maxDelayMs

number

default:"60000"

重试之间的最大延迟（毫秒，限制指数退避增长）。必须 >= 0。

jitter

boolean

default:"true"

是否添加随机抖动（±25%）到延迟以避免雷群效应

完整示例

该中间件使用指数退避自动重试失败的工具调用。关键配置：

maxRetries - 重试尝试次数（默认：2）
backoffFactor - 指数退避乘数（默认：2.0）
initialDelayMs - 起始延迟（毫秒）（默认：1000ms）
maxDelayMs - 延迟增长上限（默认：60000ms）
jitter - 添加随机变化（默认：true）

失败处理：

onFailure: "continue"（默认）- 返回错误消息
onFailure: "error" - 重新抛出异常
自定义函数 - 返回错误消息的函数

import { createAgent, toolRetryMiddleware } from "langchain";
import { tool } from "@langchain/core/tools";
import { z } from "zod";

// 使用默认设置的基本用法（2 次重试，指数退避）
const agent = createAgent({
  model: "gpt-5.4",
  tools: [searchTool, databaseTool],
  middleware: [toolRetryMiddleware()],
});

// 仅重试特定异常
const retry = toolRetryMiddleware({
  maxRetries: 4,
  retryOn: [TimeoutError, NetworkError],
  backoffFactor: 1.5,
});

// 自定义异常过滤
function shouldRetry(error: Error): boolean {
  // 仅对 5xx 错误重试
  if (error.name === "HTTPError" && "statusCode" in error) {
    const statusCode = (error as any).statusCode;
    return 500 <= statusCode && statusCode < 600;
  }
  return false;
}

const retryWithFilter = toolRetryMiddleware({
  maxRetries: 3,
  retryOn: shouldRetry,
});

// 应用于特定工具并自定义错误处理
const formatError = (error: Error) =>
  "Database temporarily unavailable. Please try again later.";

const retrySpecificTools = toolRetryMiddleware({
  maxRetries: 4,
  tools: ["search_database"],
  onFailure: formatError,
});

// 使用 BaseTool 实例应用于特定工具
const searchDatabase = tool(
  async ({ query }) => {
    // 搜索实现
    return results;
  },
  {
    name: "search_database",
    description: "Search the database",
    schema: z.object({ query: z.string() }),
  }
);

const retryWithToolInstance = toolRetryMiddleware({
  maxRetries: 4,
  tools: [searchDatabase], // 传递 BaseTool 实例
});

// 恒定退避（无指数增长）
const constantBackoff = toolRetryMiddleware({
  maxRetries: 5,
  backoffFactor: 0.0, // 无指数增长
  initialDelayMs: 2000, // 始终等待 2 秒
});

// 失败时抛出异常
const strictRetry = toolRetryMiddleware({
  maxRetries: 2,
  onFailure: "error", // 重新抛出异常而非返回消息
});

模型重试

使用可配置的指数退避自动重试失败的模型调用。模型重试适用于以下场景：

处理模型 API 调用中的瞬态故障。
提高依赖网络的模型请求的可靠性。
构建能优雅处理临时模型错误的弹性智能体。

API 参考： modelRetryMiddleware

import { createAgent, modelRetryMiddleware } from "langchain";

const agent = createAgent({
  model: "gpt-5.4",
  tools: [searchTool, databaseTool],
  middleware: [
    modelRetryMiddleware({
      maxRetries: 3,
      backoffFactor: 2.0,
      initialDelayMs: 1000,
    }),
  ],
});

配置选项

maxRetries

number

default:"2"

初始调用后的最大重试次数（默认为总共 3 次尝试）。必须 >= 0。

retryOn

((error: Error) => boolean) | (new (...args: any[]) => Error)[]

default:"() => true"

要重试的错误构造函数数组，或接受错误并返回 true 表示应重试的函数。默认为对所有错误重试。

onFailure

'error' | 'continue' | ((error: Error) => string)

default:"continue"

所有重试耗尽时的行为。选项：

'continue'（默认）- 返回带错误详情的 AIMessage，允许智能体可能优雅地处理故障
'error' - 重新抛出异常，停止智能体执行
自定义函数 - 接受异常并返回 AIMessage 内容的字符串的函数，允许自定义错误格式

backoffFactor

number

default:"2.0"

指数退避的乘数。每次重试等待 initialDelayMs * (backoffFactor ** retryNumber) 毫秒。设为 0.0 表示恒定延迟。必须 >= 0。

initialDelayMs

number

default:"1000"

首次重试前的初始延迟（毫秒）。必须 >= 0。

maxDelayMs

number

default:"60000"

重试之间的最大延迟（毫秒，限制指数退避增长）。必须 >= 0。

jitter

boolean

default:"true"

是否添加随机抖动（±25%）到延迟以避免雷群效应

完整示例

该中间件使用指数退避自动重试失败的模型调用。

import { createAgent, modelRetryMiddleware } from "langchain";

// 使用默认设置的基本用法（2 次重试，指数退避）
const agent = createAgent({
  model: "gpt-5.4",
  tools: [searchTool],
  middleware: [modelRetryMiddleware()],
});

class TimeoutError extends Error {
    // ...
}
class NetworkError extends Error {
    // ...
}

// 仅重试特定异常
const retry = modelRetryMiddleware({
  maxRetries: 4,
  retryOn: [TimeoutError, NetworkError],
  backoffFactor: 1.5,
});

// 自定义异常过滤
function shouldRetry(error: Error): boolean {
  // 仅对速率限制错误重试
  if (error.name === "RateLimitError") {
    return true;
  }
  // 或检查特定 HTTP 状态码
  if (error.name === "HTTPError" && "statusCode" in error) {
    const statusCode = (error as any).statusCode;
    return statusCode === 429 || statusCode === 503;
  }
  return false;
}

const retryWithFilter = modelRetryMiddleware({
  maxRetries: 3,
  retryOn: shouldRetry,
});

// 返回错误消息而非抛出
const retryContinue = modelRetryMiddleware({
  maxRetries: 4,
  onFailure: "continue", // 返回带错误的 AIMessage 而非抛出
});

// 自定义错误消息格式
const formatError = (error: Error) =>
  `Model call failed: ${error.message}. Please try again later.`;

const retryWithFormatter = modelRetryMiddleware({
  maxRetries: 4,
  onFailure: formatError,
});

// 恒定退避（无指数增长）
const constantBackoff = modelRetryMiddleware({
  maxRetries: 5,
  backoffFactor: 0.0, // 无指数增长
  initialDelayMs: 2000, // 始终等待 2 秒
});

// 失败时抛出异常
const strictRetry = modelRetryMiddleware({
  maxRetries: 2,
  onFailure: "error", // 重新抛出异常而非返回消息
});

LLM 工具模拟器

使用 LLM 模拟工具执行以用于测试目的，用 AI 生成的响应替代实际工具调用。LLM 工具模拟器适用于以下场景：

无需执行真实工具即可测试智能体行为。
当外部工具不可用或成本昂贵时开发智能体。
在实现实际工具之前原型化智能体工作流。

import { createAgent, toolEmulatorMiddleware } from "langchain";

const agent = createAgent({
  model: "gpt-5.4",
  tools: [getWeather, searchDatabase, sendEmail],
  middleware: [
    toolEmulatorMiddleware(), // 模拟所有工具
  ],
});

配置选项

tools

(string | ClientTool | ServerTool)[]

要模拟的工具名称（字符串）或工具实例列表。如果为 undefined（默认），所有工具都将被模拟。如果为空数组 []，则不模拟任何工具。如果是包含工具名称/实例的数组，则只模拟那些工具。

model

string | BaseChatModel

用于生成模拟工具响应的模型。可以是模型标识符字符串（例如 'google_genai:gemini-3.1-pro-preview'）或 BaseChatModel 实例。如果未指定则默认为智能体的模型。

完整示例

该中间件使用 LLM 为工具调用生成合理的响应，而非执行实际工具。

import { createAgent, toolEmulatorMiddleware, tool } from "langchain";
import * as z from "zod";

const getWeather = tool(
  async ({ location }) => `Weather in ${location}`,
  {
    name: "get_weather",
    description: "Get the current weather for a location",
    schema: z.object({ location: z.string() }),
  }
);

const sendEmail = tool(
  async ({ to, subject, body }) => "Email sent",
  {
    name: "send_email",
    description: "Send an email",
    schema: z.object({
      to: z.string(),
      subject: z.string(),
      body: z.string(),
    }),
  }
);

// 模拟所有工具（默认行为）
const agent = createAgent({
  model: "gpt-5.4",
  tools: [getWeather, sendEmail],
  middleware: [toolEmulatorMiddleware()],
});

// 按名称模拟特定工具
const agent2 = createAgent({
  model: "gpt-5.4",
  tools: [getWeather, sendEmail],
  middleware: [
    toolEmulatorMiddleware({
      tools: ["get_weather"],
    }),
  ],
});

// 通过传递工具实例模拟特定工具
const agent3 = createAgent({
  model: "gpt-5.4",
  tools: [getWeather, sendEmail],
  middleware: [
    toolEmulatorMiddleware({
      tools: [getWeather],
    }),
  ],
});

// 使用自定义模型进行模拟
const agent5 = createAgent({
  model: "gpt-5.4",
  tools: [getWeather, sendEmail],
  middleware: [
    toolEmulatorMiddleware({
      model: "claude-sonnet-4-6",
    }),
  ],
});

上下文编辑

通过在达到 Token 限制时清除较旧的工具调用输出来管理对话上下文，同时保留最近的结果。这有助于在有很多工具调用的长对话中保持上下文窗口可管理。上下文编辑适用于以下场景：

有很多工具调用且超过 Token 限制的长对话
通过移除不再相关的较旧工具输出来降低 Token 成本
仅在上下文中保留最近的 N 个工具结果

import { createAgent, contextEditingMiddleware, ClearToolUsesEdit } from "langchain";

const agent = createAgent({
  model: "gpt-5.4",
  tools: [],
  middleware: [
    contextEditingMiddleware({
      edits: [
        new ClearToolUsesEdit({
          triggerTokens: 100000,
          keep: 3,
        }),
      ],
    }),
  ],
});

配置选项

edits

ContextEdit[]

default:"[new ClearToolUsesEdit()]"

要应用的 ContextEdit 策略数组

ClearToolUsesEdit 选项：

triggerTokens

number

default:"100000"

触发编辑的 Token 数。当对话超过此 Token 数时，较旧的工具输出将被清除。

clearAtLeast

number

default:"0"

编辑运行时要回收的最小 Token 数。如果设为 0，则尽可能多地清除。

keep

number

default:"3"

必须保留的最近工具结果数。这些永远不会被清除。

clearToolInputs

boolean

default:"false"

是否清除 AI 消息上的原始工具调用参数。当为 true 时，工具调用参数会被替换为空对象。

excludeTools

string[]

default:"[]"

排除在清除之外的工具名称列表。这些工具的输出永远不会被清除。

placeholder

string

default:"[cleared]"

为已清除的工具输出插入的占位文本。这会替换原始工具消息内容。

完整示例

该中间件在达到 Token 限制时应用上下文编辑策略。最常用的策略是 ClearToolUsesEdit，它清除较旧的工具结果同时保留最近的结果。工作原理：

监控对话中的 Token 数
达到阈值时，清除较旧的工具输出
保留最近的 N 个工具结果
可选保留工具调用参数以提供上下文

import { createAgent, contextEditingMiddleware, ClearToolUsesEdit } from "langchain";

const agent = createAgent({
  model: "gpt-5.4",
  tools: [searchTool, calculatorTool, databaseTool],
  middleware: [
    contextEditingMiddleware({
      edits: [
        new ClearToolUsesEdit({
          triggerTokens: 2000,
          keep: 3,
          clearToolInputs: false,
          excludeTools: [],
          placeholder: "[cleared]",
        }),
      ],
    }),
  ],
});

文件系统中间件

上下文工程是构建有效智能体的主要挑战。当使用返回可变长度结果的工具时（例如 web_search 和 RAG），这尤其困难，因为长工具结果可以快速填满你的上下文窗口。来自 Deep Agents 的 FilesystemMiddleware 提供四个工具用于与短期和长期记忆交互：

ls：列出文件系统中的文件
read_file：读取整个文件或从文件中读取特定行数
write_file：将新文件写入文件系统
edit_file：编辑文件系统中的现有文件

import { createAgent } from "langchain";
import { createFilesystemMiddleware } from "deepagents";

// FilesystemMiddleware 在 createDeepAgent 中默认包含
// 如果构建自定义智能体可以自定义它
const agent = createAgent({
  model: "claude-sonnet-4-6",
  middleware: [
    createFilesystemMiddleware({
      backend: undefined,  // 可选：自定义后端（默认为 StateBackend）
      systemPrompt: "Write to the filesystem when...",  // 可选自定义系统提示词覆盖
      customToolDescriptions: {
        ls: "Use the ls tool when...",
        read_file: "Use the read_file tool to...",
      },  // 可选：文件系统工具的自定义描述
    }),
  ],
});

短期 vs 长期文件系统

默认情况下，这些工具写入你的图状态中的本地”文件系统”。要启用跨线程的持久存储，配置一个 CompositeBackend，将特定路径（如 /memories/）路由到 StoreBackend。

import { createAgent } from "langchain";
import { createFilesystemMiddleware, CompositeBackend, StateBackend, StoreBackend } from "deepagents";
import { InMemoryStore } from "@langchain/langgraph-checkpoint";

const store = new InMemoryStore();

const agent = createAgent({
  model: "claude-sonnet-4-6",
  store,
  middleware: [
    createFilesystemMiddleware({
      backend: new CompositeBackend(
        new StateBackend(),
        { "/memories/": new StoreBackend() }
      ),
      systemPrompt: "Write to the filesystem when...", // 可选自定义系统提示词覆盖
      customToolDescriptions: {
        ls: "Use the ls tool when...",
        read_file: "Use the read_file tool to...",
      }, // 可选：文件系统工具的自定义描述
    }),
  ],
});

当你为 /memories/ 配置带有 StoreBackend 的 CompositeBackend 时，任何以 /memories/ 为前缀的文件都会保存到持久存储，并在不同线程之间保持。没有此前缀的文件保留在临时状态存储中。

子智能体

将任务交接给子智能体可以隔离上下文，保持主（主管）智能体的上下文窗口干净，同时仍能深入处理任务。来自 Deep Agents 的子智能体中间件允许你通过 task 工具提供子智能体。

import { tool } from "langchain";
import { createAgent } from "langchain";
import { createSubAgentMiddleware } from "deepagents";
import { z } from "zod";

const getWeather = tool(
  async ({ city }: { city: string }) => {
    return `The weather in ${city} is sunny.`;
  },
  {
    name: "get_weather",
    description: "Get the weather in a city.",
    schema: z.object({
      city: z.string(),
    }),
  },
);

const agent = createAgent({
  model: "claude-sonnet-4-6",
  middleware: [
    createSubAgentMiddleware({
      defaultModel: "claude-sonnet-4-6",
      defaultTools: [],
      subagents: [
        {
          name: "weather",
          description: "This subagent can get weather in cities.",
          systemPrompt: "Use the get_weather tool to get the weather in a city.",
          tools: [getWeather],
          model: "gpt-5.4",
          middleware: [],
        },
      ],
    }),
  ],
});

子智能体通过名称、描述、系统提示词和工具来定义。你还可以为子智能体提供自定义模型或额外的中间件。当你想给子智能体一个额外的状态键来与主智能体共享时，这特别有用。对于更复杂的用例，你也可以提供自己预构建的 LangGraph 图作为子智能体。

import { tool, createAgent } from "langchain";
import { createSubAgentMiddleware, type SubAgent } from "deepagents";
import { z } from "zod";

const getWeather = tool(
  async ({ city }: { city: string }) => {
    return `The weather in ${city} is sunny.`;
  },
  {
    name: "get_weather",
    description: "Get the weather in a city.",
    schema: z.object({
      city: z.string(),
    }),
  },
);

const weatherSubagent: SubAgent = {
  name: "weather",
  description: "This subagent can get weather in cities.",
  systemPrompt: "Use the get_weather tool to get the weather in a city.",
  tools: [getWeather],
  model: "gpt-5.4",
  middleware: [],
};

const agent = createAgent({
  model: "claude-sonnet-4-6",
  middleware: [
    createSubAgentMiddleware({
      defaultModel: "claude-sonnet-4-6",
      defaultTools: [],
      subagents: [weatherSubagent],
    }),
  ],
});

除了任何用户定义的子智能体之外，主智能体还可以随时访问一个 general-purpose 子智能体。该子智能体与主智能体具有相同的指令和可访问的所有工具。general-purpose 子智能体的主要目的是上下文隔离——主智能体可以将复杂任务委托给这个子智能体，并获得简洁的答案，而不会因为中间工具调用而膨胀。

特定提供商的中间件

这些中间件针对特定的 LLM 提供商进行了优化。请参阅每个提供商的文档以获取完整的详情和示例。

Anthropic

用于 Claude 模型的提示词缓存、bash 工具、文本编辑器、记忆和文件搜索中间件。

连接这些文档到 Claude、VSCode 等，通过 MCP 获取实时答案。

在 GitHub 上编辑此页面或提交 issue。

Documentation Index

​与提供商无关的中间件

​摘要

​人机协作

​模型调用限制

​工具调用限制

​模型回退

​PII 检测

​自定义 PII 类型

​待办事项列表

​LLM 工具选择器

​工具重试

​模型重试

​LLM 工具模拟器

​上下文编辑

​文件系统中间件

​短期 vs 长期文件系统

​子智能体

​特定提供商的中间件

Anthropic

与提供商无关的中间件

摘要

人机协作

模型调用限制

工具调用限制

模型回退

PII 检测

自定义 PII 类型

待办事项列表

LLM 工具选择器

工具重试

模型重试

LLM 工具模拟器

上下文编辑

文件系统中间件

短期 vs 长期文件系统

子智能体

特定提供商的中间件