跳到主要内容

文档索引

在以下地址获取完整的文档索引:https://docs.langchain.org.cn/llms.txt

在进一步探索之前,请使用此文件发现所有可用页面。

LangChain 和 Deep Agents 提供了适用于常见用例的预置中间件。每个中间件都已达到生产级标准,并可根据您的具体需求进行配置。

跨提供商中间件

以下中间件适用于任何 LLM 提供商
中间件描述
总结当接近 Token 限制时,自动总结对话历史。
人工干预暂停执行以获取人工对工具调用的批准。
模型调用限制限制模型调用次数以防止产生过高费用。
工具调用限制通过限制调用次数来控制工具执行。
模型后备 (Fallback)当主模型失败时,自动切换到备用模型。
PII 检测检测并处理个人身份信息 (PII)。
待办事项列表为智能体配备任务规划和跟踪能力。
LLM 工具选择器在调用主模型之前,使用 LLM 选择相关的工具。
工具重试使用指数级退避策略自动重试失败的工具调用。
模型重试使用指数级退避策略自动重试失败的模型调用。
LLM 工具模拟器使用 LLM 模拟工具执行,以进行测试。
上下文编辑通过修剪或清除工具使用记录来管理对话上下文。
Shell 工具为智能体提供持久的 Shell 会话以执行命令。
文件搜索提供基于文件系统的 Glob 和 Grep 搜索工具。
文件系统为智能体提供文件系统,用于存储上下文和长期记忆。
子智能体增加生成子智能体(Subagents)的能力。

总结

当接近 Token 限制时,自动总结对话历史,在压缩旧上下文的同时保留最近的消息。总结功能适用于以下情况:
  • 超出上下文窗口的长期对话。
  • 具有广泛历史记录的多轮对话。
  • 需要保留完整对话上下文的应用场景。
API 参考: SummarizationMiddleware
from langchain.agents import create_agent
from langchain.agents.middleware import SummarizationMiddleware

agent = create_agent(
    model="gpt-5.4",
    tools=[your_weather_tool, your_calculator_tool],
    middleware=[
        SummarizationMiddleware(
            model="gpt-5.4-mini",
            trigger=("tokens", 4000),
            keep=("messages", 20),
        ),
    ],
)
如果使用 langchain>=1.1triggerkeepfraction 条件(如下所示)依赖于聊天模型的 配置数据 (profile data)。如果数据不可用,请使用其他条件或手动指定。
from langchain.chat_models import init_chat_model

custom_profile = {
    "max_input_tokens": 100_000,
    # ...
}
model = init_chat_model("gpt-5.4", profile=custom_profile)
model
string | BaseChatModel
必填
用于生成摘要的模型。可以是模型标识符字符串(例如 'openai:gpt-5.4-mini')或 BaseChatModel 实例。有关详细信息,请参阅 init_chat_model
触发器 (trigger)
ContextSize | list[ContextSize] | None
触发总结的条件。可以是:
  • 单个 ContextSize 元组(必须满足指定条件)
  • 一个 ContextSize 元组列表(满足任何一个条件即可 - 或逻辑)
条件应为以下之一:
  • fraction (float): 模型上下文大小的比例 (0-1)
  • tokens (int): 绝对 Token 计数
  • messages (int): 消息条数
必须至少指定一个条件。如果未提供,总结将不会自动触发。有关更多信息,请参阅 ContextSize 的 API 参考。
keep
ContextSize
默认值:"('messages', 20)"
总结后保留多少上下文。请确切指定以下之一:
  • fraction (float): 保留模型上下文大小的比例 (0-1)
  • tokens (int): 保留的绝对 Token 计数
  • messages (int): 保留的最近消息条数
有关更多信息,请参阅 ContextSize 的 API 参考。
Token 计数器 (token_counter)
函数 (function)
自定义 Token 计数函数。默认为基于字符的计数。
总结提示词 (summary_prompt)
字符串
用于总结的自定义提示词模板。如果未指定,则使用内置模板。该模板应包含 {messages} 占位符,对话历史将插入此处。
待总结 Token 修剪 (trim_tokens_to_summarize)
数字
默认值:"4000"
生成摘要时包含的最大 Token 数。消息将在总结前修剪以符合此限制。
总结前缀 (summary_prefix)
字符串
已弃用
已弃用: 请改用 summary_prompt 提供完整的提示词。
总结前的最大 Token 数 (max_tokens_before_summary)
数字
已弃用
已弃用: 请改用 trigger: ("tokens", value)。触发总结的 Token 阈值。
保留的消息数 (messages_to_keep)
数字
已弃用
已弃用: 请改用 keep: ("messages", value)。要保留的最近消息条数。
总结中间件监视消息的 Token 计数,并在达到阈值时自动总结旧消息。触发条件 控制总结何时运行:
  • 单个条件对象(必须满足指定条件)
  • 条件数组(满足任何一个条件即可 - 或逻辑)
  • 每个条件可以使用 fraction(模型上下文大小比例)、tokens(绝对计数)或 messages(消息计数)
保留条件 控制保留多少上下文(确切指定一个)
  • fraction - 保留模型上下文大小的比例
  • tokens - 保留的绝对 Token 计数
  • messages - 保留的最近消息条数
from langchain.agents import create_agent
from langchain.agents.middleware import SummarizationMiddleware


# Single condition: trigger if tokens >= 4000
agent = create_agent(
    model="gpt-5.4",
    tools=[your_weather_tool, your_calculator_tool],
    middleware=[
        SummarizationMiddleware(
            model="gpt-5.4-mini",
            trigger=("tokens", 4000),
            keep=("messages", 20),
        ),
    ],
)

# Multiple conditions: trigger if number of tokens >= 3000 OR messages >= 6
agent2 = create_agent(
    model="gpt-5.4",
    tools=[your_weather_tool, your_calculator_tool],
    middleware=[
        SummarizationMiddleware(
            model="gpt-5.4-mini",
            trigger=[
                ("tokens", 3000),
                ("messages", 6),
            ],
            keep=("messages", 20),
        ),
    ],
)

# Using fractional limits
agent3 = create_agent(
    model="gpt-5.4",
    tools=[your_weather_tool, your_calculator_tool],
    middleware=[
        SummarizationMiddleware(
            model="gpt-5.4-mini",
            trigger=("fraction", 0.8),
            keep=("fraction", 0.3),
        ),
    ],
)

人工干预

在工具执行前暂停智能体,以便由人工批准、编辑或拒绝工具调用。人机交互 (Human-in-the-loop) 适用于以下情况:
  • 需要人工批准的高风险操作(例如:数据库写入、金融交易)。
  • 强制要求人工监督的合规工作流。
  • 由人工反馈引导智能体的长期对话。
API 参考: HumanInTheLoopMiddleware
人机交互中间件需要一个 检查点管理器 (checkpointer) 以在中断期间维持状态。
from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver


def your_read_email_tool(email_id: str) -> str:
    """Mock function to read an email by its ID."""
    return f"Email content for ID: {email_id}"

def your_send_email_tool(recipient: str, subject: str, body: str) -> str:
    """Mock function to send an email."""
    return f"Email sent to {recipient} with subject '{subject}'"

agent = create_agent(
    model="gpt-5.4",
    tools=[your_read_email_tool, your_send_email_tool],
    checkpointer=InMemorySaver(),
    middleware=[
        HumanInTheLoopMiddleware(
            interrupt_on={
                "your_send_email_tool": {
                    "allowed_decisions": ["approve", "edit", "reject"],
                },
                "your_read_email_tool": False,
            }
        ),
    ],
)
有关完整示例、配置选项和集成模式,请参阅 人机交互文档
观看此 视频指南,了解人机交互中间件的行为演示。

模型调用限制

限制模型调用次数以防止无限循环或产生过高费用。模型调用限制适用于以下情况:
  • 防止失控的智能体进行过多的 API 调用。
  • 在生产部署中实施成本控制。
  • 在特定的调用预算内测试智能体行为。
API 参考: ModelCallLimitMiddleware
from langchain.agents import create_agent
from langchain.agents.middleware import ModelCallLimitMiddleware
from langgraph.checkpoint.memory import InMemorySaver

agent = create_agent(
    model="gpt-5.4",
    checkpointer=InMemorySaver(),  # Required for thread limiting
    tools=[],
    middleware=[
        ModelCallLimitMiddleware(
            thread_limit=10,
            run_limit=5,
            exit_behavior="end",
        ),
    ],
)
观看此 视频指南,了解模型调用限制中间件的行为演示。
线程限制 (thread_limit)
数字
同一线程中所有运行的最大模型调用次数。默认为无限制。
运行限制 (run_limit)
数字
单次调用中的最大模型调用次数。默认为无限制。
退出行为 (exit_behavior)
字符串
默认值:"end"
达到限制时的行为。选项:'end' (正常终止) 或 'error' (抛出异常)

工具调用限制

通过限制全局或特定工具的工具调用次数来控制智能体执行。工具调用限制适用于以下情况:
  • 防止对昂贵的外部 API 进行过量调用。
  • 限制网页搜索或数据库查询次数。
  • 对特定工具的使用实施速率限制。
  • 防御智能体循环失控。
API 参考: ToolCallLimitMiddleware
from langchain.agents import create_agent
from langchain.agents.middleware import ToolCallLimitMiddleware

agent = create_agent(
    model="gpt-5.4",
    tools=[search_tool, database_tool],
    middleware=[
        # Global limit
        ToolCallLimitMiddleware(thread_limit=20, run_limit=10),
        # Tool-specific limit
        ToolCallLimitMiddleware(
            tool_name="search",
            thread_limit=5,
            run_limit=3,
        ),
    ],
)
观看此 视频指南,了解工具调用限制中间件的行为演示。
工具名称 (tool_name)
字符串
要限制的特定工具名称。如果未提供,限制将应用于 全局所有工具
线程限制 (thread_limit)
数字
一个线程(对话)中所有运行的最大工具调用次数。在具有相同线程 ID 的多次调用中持续存在。需要检查点管理器来维持状态。None 表示无线程限制。
运行限制 (run_limit)
数字
单次调用(一个用户消息 → 响应周期)的最大工具调用次数。每次有新用户消息时重置。None 表示无运行限制。注意: 必须至少指定 thread_limitrun_limit 之一。
退出行为 (exit_behavior)
字符串
默认值:"continue"
达到限制时的行为
  • 'continue' (默认) - 使用错误消息阻断超出限制的工具调用,让其他工具和模型继续运行。模型根据错误消息决定何时结束。
  • 'error' - 抛出 ToolCallLimitExceededError 异常,立即停止执行。
  • 'end' - 立即停止执行,并为超出限制的工具调用返回 ToolMessage 和 AI 消息。仅在限制单个工具时有效;如果其他工具仍有待处理的调用,则抛出 NotImplementedError
指定限制方式:
  • 线程限制 (Thread limit) - 整个对话中的最大调用次数(需要检查点管理器)
  • 运行限制 (Run limit) - 单次调用的最大次数(每轮重置)
退出行为
  • 'continue' (默认) - 阻断超出限制的调用并返回错误消息,智能体继续运行
  • 'error' - 立即抛出异常
  • 'end' - 以 ToolMessage + AI 消息停止(仅限单工具场景)
from langchain.agents import create_agent
from langchain.agents.middleware import ToolCallLimitMiddleware


global_limiter = ToolCallLimitMiddleware(thread_limit=20, run_limit=10)
search_limiter = ToolCallLimitMiddleware(tool_name="search", thread_limit=5, run_limit=3)
database_limiter = ToolCallLimitMiddleware(tool_name="query_database", thread_limit=10)
strict_limiter = ToolCallLimitMiddleware(tool_name="scrape_webpage", run_limit=2, exit_behavior="error")

agent = create_agent(
    model="gpt-5.4",
    tools=[search_tool, database_tool, scraper_tool],
    middleware=[global_limiter, search_limiter, database_limiter, strict_limiter],
)

模型后备 (Fallback)

当主模型失败时自动切换到后备模型。模型后备适用于以下情况:
  • 构建弹性智能体以应对模型故障。
  • 通过切换到更便宜的模型来优化成本。
  • 在 OpenAI、Anthropic 等提供商之间实现冗余。
API 参考: ModelFallbackMiddleware
from langchain.agents import create_agent
from langchain.agents.middleware import ModelFallbackMiddleware

agent = create_agent(
    model="gpt-5.4",
    tools=[],
    middleware=[
        ModelFallbackMiddleware(
            "gpt-5.4-mini",
            "claude-3-5-sonnet-20241022",
        ),
    ],
)
观看此 视频指南,了解模型后备中间件的行为演示。
首个模型 (first_model)
string | BaseChatModel
必填
主模型失败时尝试的第一个后备模型。可以是模型标识符字符串(例如 'openai:gpt-5.4-mini')或 BaseChatModel 实例。
额外模型 (*additional_models)
string | BaseChatModel
如果前面的模型都失败,将按顺序尝试的额外后备模型。

PII 检测

使用可配置的策略检测并处理对话中的个人身份信息 (PII)。PII 检测适用于以下情况:
  • 具有合规要求的医疗和金融应用。
  • 需要脱敏日志的客户服务智能体。
  • 任何处理敏感用户数据的应用。
API 参考: PIIMiddleware
from langchain.agents import create_agent
from langchain.agents.middleware import PIIMiddleware

agent = create_agent(
    model="gpt-5.4",
    tools=[],
    middleware=[
        PIIMiddleware("email", strategy="redact", apply_to_input=True),
        PIIMiddleware("credit_card", strategy="mask", apply_to_input=True),
    ],
)

自定义 PII 类型

您可以通过提供 detector 参数来创建自定义 PII 类型。这允许您检测内置类型之外的特定于您用例的模式。 创建自定义检测器的三种方法:
  1. 正则表达式模式字符串 - 简单的模式匹配
  2. 自定义函数 - 带有验证的复杂检测逻辑
from langchain.agents import create_agent
from langchain.agents.middleware import PIIMiddleware
import re


# Method 1: Regex pattern string
agent1 = create_agent(
    model="gpt-5.4",
    tools=[],
    middleware=[
        PIIMiddleware(
            "api_key",
            detector=r"sk-[a-zA-Z0-9]{32}",
            strategy="block",
        ),
    ],
)

# Method 2: Compiled regex pattern
agent2 = create_agent(
    model="gpt-5.4",
    tools=[],
    middleware=[
        PIIMiddleware(
            "phone_number",
            detector=re.compile(r"\+?\d{1,3}[\s.-]?\d{3,4}[\s.-]?\d{4}"),
            strategy="mask",
        ),
    ],
)

# Method 3: Custom detector function
def detect_ssn(content: str) -> list[dict[str, str | int]]:
    """Detect SSN with validation.

    Returns a list of dictionaries with 'text', 'start', and 'end' keys.
    """
    import re
    matches = []
    pattern = r"\d{3}-\d{2}-\d{4}"
    for match in re.finditer(pattern, content):
        ssn = match.group(0)
        # Validate: first 3 digits shouldn't be 000, 666, or 900-999
        first_three = int(ssn[:3])
        if first_three not in [0, 666] and not (900 <= first_three <= 999):
            matches.append({
                "text": ssn,
                "start": match.start(),
                "end": match.end(),
            })
    return matches

agent3 = create_agent(
    model="gpt-5.4",
    tools=[],
    middleware=[
        PIIMiddleware(
            "ssn",
            detector=detect_ssn,
            strategy="hash",
        ),
    ],
)
自定义检测器函数签名: 检测器函数必须接收一个字符串 (content) 并返回匹配项: 返回包含 textstartend 键的字典列表:
def detector(content: str) -> list[dict[str, str | int]]:
    return [
        {"text": "matched_text", "start": 0, "end": 12},
        # ... more matches
    ]
对于自定义检测器:
  • 对于简单模式,使用正则表达式字符串
  • 当需要标志(如不区分大小写匹配)时,使用 RegExp 对象
  • 当需要模式匹配之外的验证逻辑时,使用自定义函数
  • 自定义函数让您完全控制检测逻辑,并能实现复杂的验证规则
PII 类型 (pii_type)
字符串
必填
要检测的 PII 类型。可以是内置类型(email, credit_card, ip, mac_address, url)或自定义类型名称。
strategy
字符串
默认值:"redact"
如何处理检测到的 PII。选项:
  • 'block' - 检测到时抛出异常
  • 'redact' - 替换为 [REDACTED_{PII_TYPE}]
  • 'mask' - 部分掩码(例如 ****-****-****-1234
  • 'hash' - 替换为确定性哈希
detector
函数 | 正则表达式 (function | regex)
自定义检测器函数或正则表达式模式。如果未提供,则使用该 PII 类型的内置检测器。
应用于输入 (apply_to_input)
布尔值
默认值:"True"
在模型调用前检查用户消息
应用于输出 (apply_to_output)
布尔值
默认值:"False"
在模型调用后检查 AI 消息
应用于工具结果 (apply_to_tool_results)
布尔值
默认值:"False"
执行后检查工具结果消息

待办事项列表

为智能体配备任务规划和跟踪能力,以处理复杂的多步骤任务。待办事项列表适用于以下情况:
  • 需要跨多个工具协作的复杂多步骤任务。
  • 进度可见性至关重要的长期运行操作。
此中间件会自动为智能体提供 write_todos 工具和系统提示词,以引导有效的任务规划。
API 参考: TodoListMiddleware
from langchain.agents import create_agent
from langchain.agents.middleware import TodoListMiddleware

agent = create_agent(
    model="gpt-5.4",
    tools=[read_file, write_file, run_tests],
    middleware=[TodoListMiddleware()],
)
观看此 视频指南,了解待办事项列表中间件的行为演示。
system_prompt
字符串
用于引导待办事项使用的自定义系统提示词。如果未指定,则使用内置提示词。
工具描述 (tool_description)
字符串
write_todos 工具的自定义描述。如果未指定,则使用内置描述。

LLM 工具选择器

在调用主模型之前,使用 LLM 智能地选择相关的工具。LLM 工具选择器适用于以下情况:
  • 拥有大量工具 (10+) 的智能体,且大多数工具与单个查询无关。
  • 通过过滤无关工具来减少 Token 使用量。
  • 提高模型的专注度和准确性。
该中间件使用结构化输出来询问 LLM 哪些工具与当前查询最相关。结构化输出模式定义了可用的工具名称和描述。模型提供商通常会在幕后将这些结构化输出信息添加到系统提示词中。 API 参考: LLMToolSelectorMiddleware
from langchain.agents import create_agent
from langchain.agents.middleware import LLMToolSelectorMiddleware

agent = create_agent(
    model="gpt-5.4",
    tools=[tool1, tool2, tool3, tool4, tool5, ...],
    middleware=[
        LLMToolSelectorMiddleware(
            model="gpt-5.4-mini",
            max_tools=3,
            always_include=["search"],
        ),
    ],
)
model
string | BaseChatModel
用于工具选择的模型。可以是模型标识符字符串(例如 'openai:gpt-5.4-mini')或 BaseChatModel 实例。有关详细信息,请参阅 init_chat_model默认为智能体的主模型。
system_prompt
字符串
用于选择模型的指令。如果未指定,则使用内置提示词。
最大工具数 (max_tools)
数字
选择的最大工具数量。如果模型选择了更多,则仅使用前 max_tools 个。如果未指定,则无限制。
始终包含 (always_include)
字符串列表 (list[string])
无论选择结果如何,始终包含的工具名称。这些不计入 max_tools 限制。

工具重试

使用可配置的指数级退避策略自动重试失败的工具调用。工具重试适用于以下情况:
  • 处理外部 API 调用中的暂时性故障。
  • 提高依赖网络工具的可靠性。
  • 构建能够优雅处理临时错误的弹性智能体。
API 参考: ToolRetryMiddleware
from langchain.agents import create_agent
from langchain.agents.middleware import ToolRetryMiddleware

agent = create_agent(
    model="gpt-5.4",
    tools=[search_tool, database_tool],
    middleware=[
        ToolRetryMiddleware(
            max_retries=3,
            backoff_factor=2.0,
            initial_delay=1.0,
        ),
    ],
)
最大重试次数 (max_retries)
数字
默认值:"2"
初始调用后的最大重试尝试次数(默认情况下总计 3 次尝试)
tools
list[BaseTool | str]
可选的工具或工具名称列表,用于应用重试逻辑。如果为 None,则应用于所有工具。
重试条件 (retry_on)
元组 | 可调用对象
默认值:"(Exception,)"
可以是一个触发重试的异常类型元组,也可以是一个接收异常并返回 True(表示应重试)的可调用对象。
失败时行为 (on_failure)
字符串 | 可调用对象
默认值:"return_message"
当所有重试都耗尽时的行为。选项:
  • 'return_message' - 返回包含错误详情的 ToolMessage(允许 LLM 处理失败)
  • 'raise' - 重新抛出异常(停止智能体执行)
  • 自定义可调用对象 - 一个接收异常并返回作为 ToolMessage 内容的字符串的函数
退避因子 (backoff_factor)
数字
默认值:"2.0"
指数退避的乘数。每次重试等待 initial_delay * (backoff_factor ** retry_number) 秒。设为 0.0 则为恒定延迟。
初始延迟 (initial_delay)
数字
默认值:"1.0"
第一次重试前的初始延迟(秒)
最大延迟 (max_delay)
数字
默认值:"60.0"
重试之间的最大延迟秒数(限制指数退避的增长上限)
抖动 (jitter)
布尔值
默认值:"true"
是否为延迟添加随机抖动 (±25%) 以避免“惊群效应”
中间件使用指数级退避策略自动重试失败的工具调用。关键配置:
  • max_retries - 重试尝试次数(默认:2)
  • backoff_factor - 指数退避的乘数(默认:2.0)
  • initial_delay - 起始延迟秒数(默认:1.0)
  • max_delay - 延迟增长上限(默认:60.0)
  • jitter - 添加随机波动(默认:True)
失败处理:
  • on_failure='return_message' - 返回错误消息
  • on_failure='raise' - 重新抛出异常
  • 自定义函数 - 返回错误消息的函数
from langchain.agents import create_agent
from langchain.agents.middleware import ToolRetryMiddleware


agent = create_agent(
    model="gpt-5.4",
    tools=[search_tool, database_tool, api_tool],
    middleware=[
        ToolRetryMiddleware(
            max_retries=3,
            backoff_factor=2.0,
            initial_delay=1.0,
            max_delay=60.0,
            jitter=True,
            tools=["api_tool"],
            retry_on=(ConnectionError, TimeoutError),
            on_failure="continue",
        ),
    ],
)

模型重试

使用可配置的指数级退避策略自动重试失败的模型调用。模型重试适用于以下情况:
  • 处理模型 API 调用中的暂时性故障。
  • 提高依赖网络模型请求的可靠性。
  • 构建能够优雅处理临时模型错误的弹性智能体。
API 参考: ModelRetryMiddleware
from langchain.agents import create_agent
from langchain.agents.middleware import ModelRetryMiddleware

agent = create_agent(
    model="gpt-5.4",
    tools=[search_tool, database_tool],
    middleware=[
        ModelRetryMiddleware(
            max_retries=3,
            backoff_factor=2.0,
            initial_delay=1.0,
        ),
    ],
)
最大重试次数 (max_retries)
数字
默认值:"2"
初始调用后的最大重试尝试次数(默认情况下总计 3 次尝试)
重试条件 (retry_on)
元组 | 可调用对象
默认值:"(Exception,)"
可以是一个触发重试的异常类型元组,也可以是一个接收异常并返回 True(表示应重试)的可调用对象。
失败时行为 (on_failure)
字符串 | 可调用对象
默认值:"continue"
当所有重试都耗尽时的行为。选项:
  • 'continue' (默认) - 返回包含错误详情的 AIMessage,允许智能体尝试优雅地处理失败
  • 'error' - 重新抛出异常(停止智能体执行)
  • 自定义可调用对象 - 接收异常并返回作为 AIMessage 内容的字符串的函数
退避因子 (backoff_factor)
数字
默认值:"2.0"
指数退避的乘数。每次重试等待 initial_delay * (backoff_factor ** retry_number) 秒。设为 0.0 则为恒定延迟。
初始延迟 (initial_delay)
数字
默认值:"1.0"
第一次重试前的初始延迟(秒)
最大延迟 (max_delay)
数字
默认值:"60.0"
重试之间的最大延迟秒数(限制指数退避的增长上限)
抖动 (jitter)
布尔值
默认值:"true"
是否为延迟添加随机抖动 (±25%) 以避免“惊群效应”
中间件使用指数级退避策略自动重试失败的模型调用。
from langchain.agents import create_agent
from langchain.agents.middleware import ModelRetryMiddleware


# Basic usage with default settings (2 retries, exponential backoff)
agent = create_agent(
    model="gpt-5.4",
    tools=[search_tool],
    middleware=[ModelRetryMiddleware()],
)

# Custom exception filtering
class TimeoutError(Exception):
    """Custom exception for timeout errors."""
    pass

class ConnectionError(Exception):
    """Custom exception for connection errors."""
    pass

# Retry specific exceptions only
retry = ModelRetryMiddleware(
    max_retries=4,
    retry_on=(TimeoutError, ConnectionError),
    backoff_factor=1.5,
)


def should_retry(error: Exception) -> bool:
    # Only retry on rate limit errors
    if isinstance(error, TimeoutError):
        return True
    # Or check for specific HTTP status codes
    if hasattr(error, "status_code"):
        return error.status_code in (429, 503)
    return False

retry_with_filter = ModelRetryMiddleware(
    max_retries=3,
    retry_on=should_retry,
)

# Return error message instead of raising
retry_continue = ModelRetryMiddleware(
    max_retries=4,
    on_failure="continue",  # Return AIMessage with error instead of raising
)

# Custom error message formatting
def format_error(error: Exception) -> str:
    return f"Model call failed: {error}. Please try again later."

retry_with_formatter = ModelRetryMiddleware(
    max_retries=4,
    on_failure=format_error,
)

# Constant backoff (no exponential growth)
constant_backoff = ModelRetryMiddleware(
    max_retries=5,
    backoff_factor=0.0,  # No exponential growth
    initial_delay=2.0,  # Always wait 2 seconds
)

# Raise exception on failure
strict_retry = ModelRetryMiddleware(
    max_retries=2,
    on_failure="error",  # Re-raise exception instead of returning message
)

LLM 工具模拟器

使用 LLM 模拟工具执行以进行测试,用 AI 生成的响应替换真实的工具调用。LLM 工具模拟器适用于以下情况:
  • 在不执行真实工具的情况下测试智能体行为。
  • 当外部工具不可用或非常昂贵时开发智能体。
  • 在实现真实工具之前原型化智能体工作流。
API 参考: LLMToolEmulator
from langchain.agents import create_agent
from langchain.agents.middleware import LLMToolEmulator

agent = create_agent(
    model="gpt-5.4",
    tools=[get_weather, search_database, send_email],
    middleware=[
        LLMToolEmulator(),  # Emulate all tools
    ],
)
tools
list[str | BaseTool]
要模拟的工具名称 (str) 或 BaseTool 实例列表。如果为 None(默认),将模拟所有工具。如果为空列表 [],则不模拟任何工具。如果是包含工具名称/实例的数组,则仅模拟这些工具。
model
string | BaseChatModel
用于生成模拟工具响应的模型。可以是模型标识符字符串(例如 'google_genai:gemini-3.1-pro-preview')或 BaseChatModel 实例。如果未指定,则默认为智能体的模型。有关详细信息,请参阅 init_chat_model
该中间件使用 LLM 为工具调用生成合理的响应,而不是执行真实的工具。
from langchain.agents import create_agent
from langchain.agents.middleware import LLMToolEmulator
from langchain.tools import tool


@tool
def get_weather(location: str) -> str:
    """Get the current weather for a location."""
    return f"Weather in {location}"

@tool
def send_email(to: str, subject: str, body: str) -> str:
    """Send an email."""
    return "Email sent"


# Emulate all tools (default behavior)
agent = create_agent(
    model="gpt-5.4",
    tools=[get_weather, send_email],
    middleware=[LLMToolEmulator()],
)

# Emulate specific tools only
agent2 = create_agent(
    model="gpt-5.4",
    tools=[get_weather, send_email],
    middleware=[LLMToolEmulator(tools=["get_weather"])],
)

# Use custom model for emulation
agent4 = create_agent(
    model="gpt-5.4",
    tools=[get_weather, send_email],
    middleware=[LLMToolEmulator(model="claude-sonnet-4-6")],
)

上下文编辑

通过在达到 Token 限制时清除旧的工具调用输出(同时保留最近的结果)来管理对话上下文。这有助于在包含大量工具调用的长期对话中保持上下文窗口可控。上下文编辑适用于以下情况:
  • 工具调用次数多且超过 Token 限制的长期对话
  • 通过移除不再相关的旧工具输出来降低 Token 成本
  • 在上下文中仅维护最近的 N 个工具结果
API 参考: ContextEditingMiddleware, ClearToolUsesEdit
from langchain.agents import create_agent
from langchain.agents.middleware import ContextEditingMiddleware, ClearToolUsesEdit

agent = create_agent(
    model="gpt-5.4",
    tools=[],
    middleware=[
        ContextEditingMiddleware(
            edits=[
                ClearToolUsesEdit(
                    trigger=100000,
                    keep=3,
                ),
            ],
        ),
    ],
)
编辑策略 (edits)
list[ContextEdit]
默认值:"[ClearToolUsesEdit()]"
要应用的 ContextEdit 策略列表
Token 计数方法 (token_count_method)
字符串
默认值:"approximate"
Token 计数方法。选项:'approximate' (近似) 或 'model' (模型)
ClearToolUsesEdit 选项
触发器 (trigger)
数字
默认值:"100000"
触发编辑的 Token 计数。当对话超过此 Token 计数时,旧的工具输出将被清除。
至少清除 (clear_at_least)
数字
默认值:"0"
运行编辑时要回收的最小 Token 数量。如果设为 0,则根据需要清除。
keep
数字
默认值:"3"
必须保留的最近工具结果的数量。这些永远不会被清除。
清除工具输入 (clear_tool_inputs)
布尔值
默认值:"False"
是否清除 AI 消息中原始工具调用的参数。当为 True 时,工具调用参数将被替换为空对象。
排除工具 (exclude_tools)
字符串列表 (list[string])
默认值:"()"
要排除在清除范围之外的工具名称列表。这些工具的输出永远不会被清除。
占位符 (placeholder)
字符串
默认值:"[cleared]"
为清除的工具输出插入的占位符文本。这将替换原始工具消息的内容。
中间件在达到 Token 限制时应用上下文编辑策略。最常用的策略是 ClearToolUsesEdit,它在清除旧工具结果的同时保留最近的结果。工作原理:
  1. 监视对话中的 Token 计数
  2. 当达到阈值时,清除旧的工具输出
  3. 保留最近的 N 个工具结果
  4. (可选)为保持上下文而保留工具调用参数
from langchain.agents import create_agent
from langchain.agents.middleware import ContextEditingMiddleware, ClearToolUsesEdit


agent = create_agent(
    model="gpt-5.4",
    tools=[search_tool, your_calculator_tool, database_tool],
    middleware=[
        ContextEditingMiddleware(
            edits=[
                ClearToolUsesEdit(
                    trigger=2000,
                    keep=3,
                    clear_tool_inputs=False,
                    exclude_tools=[],
                    placeholder="[cleared]",
                ),
            ],
        ),
    ],
)

Shell 工具

为智能体提供持久的 Shell 会话以执行命令。Shell 工具中间件适用于以下情况:
  • 需要执行系统命令的智能体
  • 开发和部署自动化任务
  • 测试和验证工作流
  • 文件系统操作和脚本执行
安全注意事项:请使用合适的执行策略(HostExecutionPolicyDockerExecutionPolicyCodexSandboxExecutionPolicy)以匹配您部署环境的安全要求。
局限性:持久 Shell 会话目前不适用于中断(人机交互)。我们预计在未来增加对此功能的支持。
API 参考: ShellToolMiddleware
from langchain.agents import create_agent
from langchain.agents.middleware import (
    ShellToolMiddleware,
    HostExecutionPolicy,
)

agent = create_agent(
    model="gpt-5.4",
    tools=[search_tool],
    middleware=[
        ShellToolMiddleware(
            workspace_root="/workspace",
            execution_policy=HostExecutionPolicy(),
        ),
    ],
)
工作区根目录 (workspace_root)
str | Path | None
Shell 会话的基目录。如果省略,则在智能体启动时创建一个临时目录,并在结束时将其删除。
启动命令 (startup_commands)
元组 | 列表 | 字符串 | None
在会话开始后按顺序执行的可选命令
关闭命令 (shutdown_commands)
元组 | 列表 | 字符串 | None
在会话关闭前执行的可选命令
执行策略 (execution_policy)
BaseExecutionPolicy | None
控制超时、输出限制和资源配置的执行策略。选项:
  • HostExecutionPolicy - 完全的主机访问权限(默认);最适合智能体已运行在容器或虚拟机内的受信任环境
  • DockerExecutionPolicy - 为每次智能体运行启动一个单独的 Docker 容器,提供更强的隔离性
  • CodexSandboxExecutionPolicy - 复用 Codex CLI 沙箱以获得额外的系统调用/文件系统限制
脱敏规则 (redaction_rules)
元组 | 列表 | None
在将命令输出返回给模型之前用于脱敏的可选规则。
脱敏规则在执行后应用,在使用 HostExecutionPolicy 时不能防止机密或敏感数据的泄露。
工具描述 (tool_description)
str | None
可选,用于覆盖已注册的 Shell 工具描述
Shell 命令 (shell_command)
字符串序列 | 字符串 | None
用于启动持久会话的可选 Shell 可执行文件(字符串)或参数序列。默认为 /bin/bash
env
Mapping[str, Any] | None
提供给 Shell 会话的可选环境变量。在命令执行前,值会被强制转换为字符串。
该中间件提供一个单一的持久 Shell 会话,智能体可以使用它按顺序执行命令。执行策略:
  • HostExecutionPolicy (默认) - 具有完全主机访问权限的原生执行
  • DockerExecutionPolicy - 隔离的 Docker 容器执行
  • CodexSandboxExecutionPolicy - 通过 Codex CLI 的沙箱执行
from langchain.agents import create_agent
from langchain.agents.middleware import (
    ShellToolMiddleware,
    HostExecutionPolicy,
    DockerExecutionPolicy,
    RedactionRule,
)


# Basic shell tool with host execution
agent = create_agent(
    model="gpt-5.4",
    tools=[search_tool],
    middleware=[
        ShellToolMiddleware(
            workspace_root="/workspace",
            execution_policy=HostExecutionPolicy(),
        ),
    ],
)

# Docker isolation with startup commands
agent_docker = create_agent(
    model="gpt-5.4",
    tools=[],
    middleware=[
        ShellToolMiddleware(
            workspace_root="/workspace",
            startup_commands=["pip install requests", "export PYTHONPATH=/workspace"],
            execution_policy=DockerExecutionPolicy(
                image="python:3.11-slim",
                command_timeout=60.0,
            ),
        ),
    ],
)

# With output redaction (applied post execution)
agent_redacted = create_agent(
    model="gpt-5.4",
    tools=[],
    middleware=[
        ShellToolMiddleware(
            workspace_root="/workspace",
            redaction_rules=[
                RedactionRule(pii_type="api_key", detector=r"sk-[a-zA-Z0-9]{32}"),
            ],
        ),
    ],
)
提供基于文件系统的 Glob 和 Grep 搜索工具。文件搜索中间件适用于以下情况:
  • 代码探索与分析
  • 按名称模式查找文件
  • 使用正则表达式搜索代码内容
  • 需要进行文件发现的大型代码库
API 参考: FilesystemFileSearchMiddleware
from langchain.agents import create_agent
from langchain.agents.middleware import FilesystemFileSearchMiddleware

agent = create_agent(
    model="gpt-5.4",
    tools=[],
    middleware=[
        FilesystemFileSearchMiddleware(
            root_path="/workspace",
            use_ripgrep=True,
        ),
    ],
)
根路径 (root_path)
str
必填
要搜索的根目录。所有文件操作都是相对于此路径的。
使用 ripgrep (use_ripgrep)
bool
默认值:"True"
是否使用 ripgrep 进行搜索。如果 ripgrep 不可用,则回退到 Python 正则表达式。
最大文件大小 (max_file_size_mb)
int
默认值:"10"
允许搜索的最大文件大小(MB)。大于此值的文件将被跳过。
该中间件为智能体增加了两个搜索工具:Glob 工具 - 快速文件模式匹配:
  • 支持 **/*.py, src/**/*.ts 等模式
  • 返回按修改时间排序的匹配文件路径
Grep 工具 - 使用正则表达式进行内容搜索
  • 支持完整的正则表达式语法
  • 可通过 include 参数按文件模式过滤
  • 三种输出模式:files_with_matches (匹配文件), content (内容), count (计数)
from langchain.agents import create_agent
from langchain.agents.middleware import FilesystemFileSearchMiddleware
from langchain.messages import HumanMessage


agent = create_agent(
    model="gpt-5.4",
    tools=[],
    middleware=[
        FilesystemFileSearchMiddleware(
            root_path="/workspace",
            use_ripgrep=True,
            max_file_size_mb=10,
        ),
    ],
)

# Agent can now use glob_search and grep_search tools
result = agent.invoke({
    "messages": [HumanMessage("Find all Python files containing 'async def'")]
})

# The agent will use:
# 1. glob_search(pattern="**/*.py") to find Python files
# 2. grep_search(pattern="async def", include="*.py") to find async functions

文件系统中间件

上下文工程是构建有效智能体的主要挑战。当使用返回可变长度结果的工具(例如 web_search 和 RAG)时,这一点尤为困难,因为长工具结果会迅速填满您的上下文窗口。 Deep Agents 提供的 FilesystemMiddleware 包含四个用于与短期和长期记忆交互的工具:
  • ls: 列出文件系统中的文件
  • read_file: 读取整个文件或文件中的特定行数
  • write_file: 向文件系统写入一个新文件
  • edit_file: 编辑文件系统中现有的文件
from langchain.agents import create_agent
from deepagents.middleware.filesystem import FilesystemMiddleware

# FilesystemMiddleware is included by default in create_deep_agent
# You can customize it if building a custom agent
agent = create_agent(
    model="claude-sonnet-4-6",
    middleware=[
        FilesystemMiddleware(
            backend=None,  # Optional: custom backend (defaults to StateBackend)
            system_prompt="Write to the filesystem when...",  # Optional custom addition to the system prompt
            custom_tool_descriptions={
                "ls": "Use the ls tool when...",
                "read_file": "Use the read_file tool to..."
            }  # Optional: Custom descriptions for filesystem tools
        ),
    ],
)

短期 vs. 长期文件系统

默认情况下,这些工具写入图形状态中的本地“文件系统”。要启用跨线程的持久存储,请配置 CompositeBackend,将特定路径(如 /memories/)路由到 StoreBackend
from langchain.agents import create_agent
from deepagents.middleware import FilesystemMiddleware
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

store = InMemoryStore()

agent = create_agent(
    model="claude-sonnet-4-6",
    store=store,
    middleware=[
        FilesystemMiddleware(
            backend=CompositeBackend(
                default=StateBackend(),
                routes={"/memories/": StoreBackend()}
            ),
            custom_tool_descriptions={
                "ls": "Use the ls tool when...",
                "read_file": "Use the read_file tool to..."
            }  # Optional: Custom descriptions for filesystem tools
        ),
    ],
)
当您为 /memories/ 配置了带有 StoreBackendCompositeBackend 时,任何带 /memories/ 前缀的文件都会保存到持久存储中,并在不同线程之间保留。不带此前缀的文件保留在临时状态存储中。

子智能体

将任务交给子智能体 (subagents) 可以隔离上下文,使主(主管)智能体的上下文窗口保持整洁,同时仍能深入处理任务。 Deep Agents 的子智能体中间件允许您通过 task 工具提供子智能体。
from langchain.tools import tool
from langchain.agents import create_agent
from deepagents.middleware.subagents import SubAgentMiddleware


@tool
def get_weather(city: str) -> str:
    """Get the weather in a city."""
    return f"The weather in {city} is sunny."

agent = create_agent(
    model="claude-sonnet-4-6",
    middleware=[
        SubAgentMiddleware(
            default_model="claude-sonnet-4-6",
            default_tools=[],
            subagents=[
                {
                    "name": "weather",
                    "description": "This subagent can get weather in cities.",
                    "system_prompt": "Use the get_weather tool to get the weather in a city.",
                    "tools": [get_weather],
                    "model": "gpt-5.4",
                    "middleware": [],
                }
            ],
        )
    ],
)
子智能体由 名称描述系统提示词工具 定义。您还可以为子智能体提供自定义 模型 或额外的 中间件。当您想给子智能体一个额外的状态键来与主智能体共享时,这特别有用。 对于更复杂的用例,您还可以提供自己预构建的 LangGraph 图作为子智能体。
from langchain.agents import create_agent
from deepagents.middleware.subagents import SubAgentMiddleware
from deepagents import CompiledSubAgent
from langgraph.graph import StateGraph

# Create a custom LangGraph graph
def create_weather_graph():
    workflow = StateGraph(...)
    # Build your custom graph
    return workflow.compile()

weather_graph = create_weather_graph()

# Wrap it in a CompiledSubAgent
weather_subagent = CompiledSubAgent(
    name="weather",
    description="This subagent can get weather in cities.",
    runnable=weather_graph
)

agent = create_agent(
    model="claude-sonnet-4-6",
    middleware=[
        SubAgentMiddleware(
            default_model="claude-sonnet-4-6",
            default_tools=[],
            subagents=[weather_subagent],
        )
    ],
)
除了用户定义的子智能体外,主智能体随时都可以访问一个 general-purpose(通用)子智能体。该子智能体具有与主智能体相同的指令和所有工具。general-purpose 子智能体的主要目的是上下文隔离——主智能体可以将复杂的任务委派给该子智能体,并获得简明的答案,而不会受到中间工具调用的膨胀干扰。

特定提供商中间件

这些中间件针对特定的 LLM 提供商进行了优化。有关完整详情和示例,请参阅各提供商的文档。
https://mintcdn.com/langchain-5e9cc07a/y4fKEo7ANyWBQMjp/images/providers/anthropic-icon.svg?fit=max&auto=format&n=y4fKEo7ANyWBQMjp&q=85&s=9212db764598a2d3f02f471b5436ae9e

Anthropic

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

AWS

适用于 Amazon Bedrock 模型的提示词缓存中间件。

OpenAI

适用于 OpenAI 模型的内容审核中间件。

© . This site is unofficial and not affiliated with LangChain, Inc.