LangChain v1.0 Middleware(中间件)使用指南

[LangChain v1.0 Middleware(中间件)使用指南](#LangChain v1.0 Middleware(中间件)使用指南)
[1. 概述](#1. 概述)
- - 中间件工作原理
- [2. 核心中间件详解](#2. 核心中间件详解)
- - [2.1 SummarizationMiddleware（摘要中间件）](#2.1 SummarizationMiddleware（摘要中间件）)
  - - 配置参数
    - 触发条件类型
    - 使用示例
  - [2.2 HumanInTheLoopMiddleware（人机协作中间件）](#2.2 HumanInTheLoopMiddleware（人机协作中间件）)
  - - 配置参数
    - 使用示例
    - 决策类型
  - [2.3 ModelCallLimitMiddleware（模型调用限制）](#2.3 ModelCallLimitMiddleware（模型调用限制）)
  - - 配置参数
    - 使用示例
  - [2.4 ToolCallLimitMiddleware（工具调用限制）](#2.4 ToolCallLimitMiddleware（工具调用限制）)
  - - 配置参数
    - 退出行为
    - 使用示例
  - [2.5 ModelFallbackMiddleware（模型回退）](#2.5 ModelFallbackMiddleware（模型回退）)
  - - 配置参数
    - 使用示例
  - [2.6 PIIMiddleware（个人隐私信息检测）](#2.6 PIIMiddleware（个人隐私信息检测）)
  - - 配置参数
    - 处理策略
    - [内置 PII 类型](#内置 PII 类型)
    - 使用示例
  - [2.7 ToolRetryMiddleware（工具重试）](#2.7 ToolRetryMiddleware（工具重试）)
  - - 配置参数
    - 使用示例
  - [2.8 ModelRetryMiddleware（模型重试）](#2.8 ModelRetryMiddleware（模型重试）)
  - - 配置参数
    - 使用示例
  - [2.9 LLMToolSelectorMiddleware（工具选择器）](#2.9 LLMToolSelectorMiddleware（工具选择器）)
  - - 配置参数
    - 使用示例
  - [2.10 LLMToolEmulator（工具模拟器）](#2.10 LLMToolEmulator（工具模拟器）)
  - - 配置参数
    - 使用示例
  - [2.11 ContextEditingMiddleware（上下文编辑）](#2.11 ContextEditingMiddleware（上下文编辑）)
  - - 配置参数
    - [ClearToolUsesEdit 参数](#ClearToolUsesEdit 参数)
    - 使用示例
  - [2.12 ShellToolMiddleware（Shell 工具）](#2.12 ShellToolMiddleware（Shell 工具）)
  - - 配置参数
    - 执行策略
    - 使用示例
  - [2.13 FilesystemFileSearchMiddleware（文件搜索）](#2.13 FilesystemFileSearchMiddleware（文件搜索）)
  - - 配置参数
    - 添加的工具
    - 使用示例
  - [2.14 FilesystemMiddleware（文件系统）](#2.14 FilesystemMiddleware（文件系统）)
  - - 配置参数
    - 添加的工具
    - [短期 vs 长期文件系统](#短期 vs 长期文件系统)
  - [2.15 SubAgentMiddleware（子代理）](#2.15 SubAgentMiddleware（子代理）)
  - - 配置参数
    - 子代理配置参数
    - 使用示例
- [3. 中间件架构对比](#3. 中间件架构对比)
- - 中间件分类矩阵
  - 优缺点对比

LangChain v1.0 Middleware(中间件)使用指南

1. 概述

LangChain 和 Deep Agents 提供了多种生产就绪的预构建中间件，用于处理常见的 Agent 使用场景。这些中间件分为两大类：

提供者无关中间件：适用于任何 [[LLM]] 提供商
提供者特定中间件：针对特定 LLM 提供商优化

中间件工作原理

官方图
middleware官方文档

核心代理循环包括调用模型、让其选择执行工具，并在不再调用工具时结束：

中间件在每个步骤前后都暴露了钩子:

2. 核心中间件详解

2.1 SummarizationMiddleware（摘要中间件）

用途

自动压缩接近 Token 限制的对话历史，保留最新消息的同时压缩旧上下文。

适用场景：

超出上下文窗口的长对话
具有大量历史记录的多轮对话
需要保留完整对话上下文的应用

配置参数

参数	类型	必需	说明
`model`	`str	BaseChatModel`	✓
`trigger`	`ContextSize	list[ContextSize]`	-
`keep`	`ContextSize`	-	摘要后保留的上下文量
`summary_prompt`	`str`	-	自定义摘要提示模板
`trim_tokens_to_summarize`	`int`	-	限制摘要输入的token数，防止超出模型最大输入长度
`token_counter`	`function`	-	自定义令牌计数功能。默认为基于字符的计数。

触发条件类型

python 复制代码

# 方式一：单一条件
trigger=("tokens", 4000)           # Token数 >= 4000 时触发
trigger=("messages", 20)           # 消息数 >= 20 时触发
trigger=("fraction", 0.8)          # 达到上下文大小的80%时触发

# 方式二：多条件（OR逻辑）
trigger=[("tokens", 3000), ("messages", 6)]  # 任一条件满足即触发

使用示例

python 复制代码

from langchain.agents import create_agent
from langchain.agents.middleware import SummarizationMiddleware

# 基础配置
agent = create_agent(
    model="gpt-4.1",
    tools=[weather_tool, calculator_tool],
    middleware=[
        SummarizationMiddleware(
            model="gpt-4.1-mini",      # 使用更便宜的模型生成摘要
            trigger=("tokens", 4000),   # 4000 tokens时触发
            keep=("messages", 20),      # 保留最近20条消息
        ),
    ],
)

# 多条件触发配置
agent = create_agent(
    model="gpt-4.1",
    tools=[weather_tool, calculator_tool],
    middleware=[
        SummarizationMiddleware(
            model="gpt-4.1-mini",
            trigger=[("tokens", 3000), ("messages", 6)],  # OR逻辑
            keep=("messages", 20),
        ),
    ],
)

# 使用比例配置
agent = create_agent(
    model="gpt-4.1",
    tools=[weather_tool, calculator_tool],
    middleware=[
        SummarizationMiddleware(
            model="gpt-4.1-mini",
            trigger=("fraction", 0.8),   # 上下文的80%时触发
            keep=("fraction", 0.3),      # 保留上下文的30%
        ),
    ],
)

2.2 HumanInTheLoopMiddleware（人机协作中间件）

$**用途** \| 在工具调用执行前暂停，等待人工批准、编辑或拒绝。$

适用场景：

需要人工批准的高风险操作（如数据库写入、金融交易）
强制人工监督的合规工作流
需要人工反馈引导的长对话

配置参数

参数	类型	必需	说明
`interrupt_on`	`dict`	✓	工具名到决策配置的映射，`False` 表示不中断

使用示例

python 复制代码

from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver


def 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 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-4.1",
    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,
            }
        ),
    ],
)

决策类型

决策类型	说明
`approve`	批准执行原始工具调用
`edit`	编辑参数后执行
`reject`	拒绝执行，继续对话

2.3 ModelCallLimitMiddleware（模型调用限制）

成本控制

| 限制模型调用次数，防止无限循环或过度消费。

适用场景：

防止失控的 Agent 进行过多 API 调用
生产部署的成本控制
在特定调用预算内测试 Agent 行为

配置参数

参数	类型	默认值	说明
`thread_limit`	`int`	`None`	跨所有运行的最大模型调用数
`run_limit`	`int`	`None`	单次调用的最大模型调用数
`exit_behavior`	`str`	`"end"`	达到限制时的行为：`'end'` 或 `'error'`

使用示例

python 复制代码

from langchain.agents import create_agent
from langchain.agents.middleware import ModelCallLimitMiddleware
from langgraph.checkpoint.memory import InMemorySaver

agent = create_agent(
    model="gpt-4.1",
    checkpointer=InMemorySaver(),  # thread_limit必需
    tools=[],
    middleware=[
        ModelCallLimitMiddleware(
            thread_limit=10,      # 每个对话最多10次调用
            run_limit=5,          # 每次交互最多5次调用
            exit_behavior="end",  # 优雅终止
        ),
    ],
)

2.4 ToolCallLimitMiddleware（工具调用限制）

精细控制

| 控制特定工具的调用次数，支持全局和工具级别限制。

适用场景：

限制对昂贵外部 API 的调用
限制网络搜索或数据库查询
对特定工具执行速率限制
防止失控的 Agent 循环

配置参数

参数	类型	默认值	说明
`tool_name`	`str`	`None`	要限制的特定工具名
`thread_limit`	`int`	`None`	跨所有运行的最大调用数
`run_limit`	`int`	`None`	单次调用的最大调用数
`exit_behavior`	`str`	`"continue"`	达到限制时的行为

退出行为

行为	说明
`'continue'`	阻止超出的调用，Agent 继续（默认）
`'error'`	立即抛出异常
`'end'`	立即停止执行（仅单工具场景）

使用示例

python 复制代码

from langchain.agents import create_agent
from langchain.agents.middleware import ToolCallLimitMiddleware

agent = create_agent(
    model="gpt-4.1",
    tools=[search_tool, database_tool, scraper_tool],
    middleware=[
        # 全局限制
        ToolCallLimitMiddleware(thread_limit=20, run_limit=10),

        # 搜索工具限制
        ToolCallLimitMiddleware(
            tool_name="search",
            thread_limit=5,
            run_limit=3,
        ),

        # 数据库工具限制
        ToolCallLimitMiddleware(
            tool_name="query_database",
            thread_limit=10,
        ),

        # 爬虫工具严格限制
        ToolCallLimitMiddleware(
            tool_name="scrape_webpage",
            run_limit=2,
            exit_behavior="error",  # 立即抛出异常
        ),
    ],
)

2.5 ModelFallbackMiddleware（模型回退）

高可用性

| 主模型失败时自动回退到备用模型。

适用场景：

构建能处理模型故障的弹性 Agent
通过回退到更便宜的模型优化成本
跨 OpenAI、Anthropic 等提供商的冗余

配置参数

参数	类型	必需	说明
`first_model`	`string	BaseChatModel`	✓
`additional_models`	`string	BaseChatModel`	-

使用示例

python 复制代码

from langchain.agents import create_agent
from langchain.agents.middleware import ModelFallbackMiddleware

agent = create_agent(
    model="gpt-4.1",  # 主模型
    tools=[],
    middleware=[
        ModelFallbackMiddleware(
            "gpt-4.1-mini",                      # 第一个回退
            "claude-3-5-sonnet-20241022",        # 第二个回退
        ),
    ],
)

2.6 PIIMiddleware（个人隐私信息检测）

合规必需

| 检测和处理对话中的敏感个人信息。

适用场景：

具有合规要求的医疗和金融应用
需要清理日志的客户服务 Agent
处理敏感用户数据的任何应用

配置参数

参数	类型	必需	说明
`pii_type`	`str`	✓	PII 类型（内置或自定义名称）
`strategy`	`str`	-	处理策略：`'block'`/`'redact'`/`'mask'`/`'hash'`
`detector`	`str	re.Pattern	callable`
`apply_to_input`	`bool`	-	检查用户消息
`apply_to_output`	`bool`	-	检查 AI 消息
`apply_to_tool_result`	`bool`	-	检查工具结果

处理策略

策略	说明
`'block'`	检测时抛出异常
`'redact'`	替换为 `[REDACTED_{PII_TYPE}]`
`'mask'`	部分掩码（如 `**--**-1234`）
`'hash'`	替换为确定性哈希

内置 PII 类型

类型	说明
`email`	电子邮件地址
`credit_card`	信用卡号
`ip`	IP 地址
`mac_address`	MAC 地址
`url`	URL 链接

使用示例

python 复制代码

from langchain.agents import create_agent
from langchain.agents.middleware import PIIMiddleware

# 使用内置类型
agent = create_agent(
    model="gpt-4.1",
    tools=[],
    middleware=[
        PIIMiddleware("email", strategy="redact", apply_to_input=True),
        PIIMiddleware("credit_card", strategy="mask", apply_to_input=True),
    ],
)

# 自定义 PII 类型（三种方式）
import re

# 方式一：正则字符串
agent1 = create_agent(
    model="gpt-4.1",
    tools=[],
    middleware=[
        PIIMiddleware(
            "api_key",
            detector=r"sk-[a-zA-Z0-9]{32}",  # 正则模式
            strategy="block",
        ),
    ],
)

# 方式二：编译后的正则
agent2 = create_agent(
    model="gpt-4.1",
    tools=[],
    middleware=[
        PIIMiddleware(
            "phone_number",
            detector=re.compile(r"\+?\d{1,3}[\s.-]?\d{3,4}[\s.-]?\d{4}"),
            strategy="mask",
        ),
    ],
)

# 方式三：自定义检测函数
def detect_ssn(content: str) -> list[dict]:
    """检测带有验证的社会保障号。"""
    matches = []
    pattern = r"\d{3}-\d{2}-\d{4}"
    for match in re.finditer(pattern, content):
        ssn = match.group(0)
        # 验证：前3位不能是000、666或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-4.1",
    tools=[],
    middleware=[
        PIIMiddleware("ssn", detector=detect_ssn, strategy="hash"),
    ],
)

2.7 ToolRetryMiddleware（工具重试）

弹性增强

| 自动重试失败的工具调用，支持指数退避。

适用场景：

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

配置参数

参数	类型	默认值	说明
`max_retries`	`int`	`2`	最大重试次数
`backoff_factor`	`float`	`2.0`	指数退避乘数
`initial_delay`	`float`	`1.0`	首次重试前的延迟（秒）
`max_delay`	`float`	`60.0`	最大重试间隔（秒）
`jitter`	`bool`	`True`	添加随机抖动避免惊群效应
`on_failure`	`str	callable`	`"return_message"`

使用示例

python 复制代码

from langchain.agents import create_agent
from langchain.agents.middleware import ToolRetryMiddleware

agent = create_agent(
    model="gpt-4.1",
    tools=[search_tool, database_tool, api_tool],
    middleware=[
        ToolRetryMiddleware(
            max_retries=3,
            backoff_factor=2.0,     # 延迟序列: 1, 2, 4, 8...秒
            initial_delay=1.0,
            max_delay=60.0,
            jitter=True,            # ±25% 随机抖动
            tools=["api_tool"],     # 仅对特定工具应用
            retry_on=(ConnectionError, TimeoutError),
            on_failure="continue",  # 返回错误消息给 LLM
        ),
    ],
)

2.8 ModelRetryMiddleware（模型重试）

模型层弹性

| 自动重试失败的模型 API 调用。

适用场景：

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

配置参数

参数	类型	默认值	说明
`max_retries`	`int`	`2`	最大重试次数
`retry_on`	`tuple	callable`	`(Exception,)`
`on_failure`	`str	callable`	`"continue"`

使用示例

python 复制代码

from langchain.agents import create_agent
from langchain.agents.middleware import ModelRetryMiddleware

# 基础使用（默认2次重试，指数退避）
agent = create_agent(
    model="gpt-4.1",
    tools=[search_tool],
    middleware=[ModelRetryMiddleware()],
)

# 自定义异常过滤
retry = ModelRetryMiddleware(
    max_retries=4,
    retry_on=(TimeoutError, ConnectionError),
    backoff_factor=1.5,
)

# 条件重试函数
def should_retry(error: Exception) -> bool:
    if isinstance(error, TimeoutError):
        return True
    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,
)

# 自定义错误消息格式化
def format_error(error: Exception) -> str:
    return f"模型调用失败: {error}。请稍后重试。"

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

2.9 LLMToolSelectorMiddleware（工具选择器）

性能优化

| 使用 LLM 智能选择相关工具，减少 Token 使用。

适用场景：

具有许多工具（10+）的 Agent，大多数工具与每个查询无关
通过过滤无关工具减少 Token 使用
提高模型焦点和准确性

配置参数

参数	类型	默认值	说明
`model`	`str	BaseChatModel`	Agent 主模型
`max_tools`	`int`	`None`	最多选择的工具数量
`always_include`	`list[str]`	`[]`	始终包含的工具名列表
`prompt`	`str`	内置提示	自定义选择提示

使用示例

python 复制代码

from langchain.agents import create_agent
from langchain.agents.middleware import LLMToolSelectorMiddleware

agent = create_agent(
    model="gpt-4.1",
    tools=[tool1, tool2, tool3, tool4, tool5, ...],
    middleware=[
        LLMToolSelectorMiddleware(
            model="gpt-4.1-mini",  # 使用更便宜的模型选择
            max_tools=3,            # 最多选择3个工具
            always_include=["search"],  # 始终包含搜索工具
        ),
    ],
)

2.10 LLMToolEmulator（工具模拟器）

测试利器

| 使用 LLM 模拟工具执行，用于测试目的。

适用场景：

在不执行真实工具的情况下测试 Agent 行为
外部工具不可用或昂贵时的开发
在实现实际工具之前原型化 Agent 工作流

配置参数

参数	类型	默认值	说明
`tools`	`list[str	BaseTool]`	`None`
`model`	`str	BaseChatModel`	Agent 主模型

使用示例

python 复制代码

from langchain.agents import create_agent
from langchain.agents.middleware import LLMToolEmulator
from langchain.tools import tool

@tool
def get_weather(location: str) -> str:
    """获取位置的当前天气。"""
    return f"{location} 的天气"

@tool
def send_email(to: str, subject: str, body: str) -> str:
    """发送邮件。"""
    return "邮件已发送"

# 模拟所有工具（默认行为）
agent = create_agent(
    model="gpt-4.1",
    tools=[get_weather, send_email],
    middleware=[LLMToolEmulator()],
)

# 仅模拟特定工具
agent2 = create_agent(
    model="gpt-4.1",
    tools=[get_weather, send_email],
    middleware=[LLMToolEmulator(tools=["get_weather"])],
)

# 使用自定义模型模拟
agent4 = create_agent(
    model="gpt-4.1",
    tools=[get_weather, send_email],
    middleware=[LLMToolEmulator(model="claude-sonnet-4-5-20250929")],
)

2.11 ContextEditingMiddleware（上下文编辑）

上下文管理

| 清除较旧的工具调用输出以管理上下文窗口。

适用场景：

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

配置参数

参数	类型	默认值	说明
`edits`	`list[ContextEdit]`	`[ClearToolUsesEdit()]`	上下文编辑策略列表
`token_count_method`	`str`	`"approximate"`	Token 计数方法：`'approximate'` 或 `'model'`

ClearToolUsesEdit 参数

参数	类型	默认值	说明
`trigger`	`int`	-	触发编辑的 Token 数量
`keep`	`int`	-	必须保留的最新工具结果数量
`min_reclaim`	`int`	`0`	最少回收的 Token 数
`clear_tool_inputs`	`bool`	-	是否清除工具调用参数
`exclude_tools`	`list[str]`	`[]`	排除的工具名列表
`placeholder`	`str`	`"[cleared]"`	替换清除内容的占位符

使用示例

python 复制代码

from langchain.agents import create_agent
from langchain.agents.middleware import ContextEditingMiddleware, ClearToolUsesEdit

agent = create_agent(
    model="gpt-4.1",
    tools=[search_tool, calculator_tool, database_tool],
    middleware=[
        ContextEditingMiddleware(
            edits=[
                ClearToolUsesEdit(
                    trigger=2000,           # 2000 tokens时触发
                    keep=3,                  # 保留最近3个工具结果
                    clear_tool_inputs=False,  # 保留工具调用参数
                    exclude_tools=[],        # 不排除任何工具
                    placeholder="[cleared]", # 替换占位符
                ),
            ],
        ),
    ],
)

2.12 ShellToolMiddleware（Shell 工具）

安全注意

| 向 Agent 暴露持久 Shell 会话以执行命令。

适用场景：

需要执行系统命令的 Agent
开发和部署自动化任务
测试和验证工作流

配置参数

参数	类型	默认值	说明
`workspace_root`	`str`	临时目录	Shell 会话的基础目录
`startup_commands`	`list[str]`	`[]`	会话启动后执行的命令
`shutdown_commands`	`list[str]`	`[]`	会话关闭前执行的命令
`execution_policy`	`BaseExecutionPolicy`	`HostExecutionPolicy()`	执行策略
`redaction_rules`	`list[RedactionRule]`	`[]`	输出脱敏规则
`shell_command`	`str	list[str]`	`"/bin/bash"`
`env`	`dict`	`{}`	环境变量

执行策略

策略	说明
`HostExecutionPolicy`	完整主机访问（默认），适用于容器/VM 环境
`DockerExecutionPolicy`	为每次运行启动独立的 Docker 容器
`CodexSandboxExecutionPolicy`	通过 Codex CLI 沙箱执行

使用示例

python 复制代码

from langchain.agents import create_agent
from langchain.agents.middleware import (
    ShellToolMiddleware,
    HostExecutionPolicy,
    DockerExecutionPolicy,
    RedactionRule,
)

# 基础 Shell 工具
agent = create_agent(
    model="gpt-4.1",
    tools=[search_tool],
    middleware=[
        ShellToolMiddleware(
            workspace_root="/workspace",
            execution_policy=HostExecutionPolicy(),
        ),
    ],
)

# Docker 隔离与启动命令
agent_docker = create_agent(
    model="gpt-4.1",
    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,
            ),
        ),
    ],
)

# 带输出脱敏
agent_redacted = create_agent(
    model="gpt-4.1",
    tools=[],
    middleware=[
        ShellToolMiddleware(
            workspace_root="/workspace",
            redaction_rules=[
                RedactionRule(pii_type="api_key", detector=r"sk-[a-zA-Z0-9]{32}"),
            ],
        ),
    ],
)

2.13 FilesystemFileSearchMiddleware（文件搜索）

代码探索

| 提供 Glob 和 Grep 搜索工具。

适用场景：

代码探索和分析
按名称模式查找文件
使用正则搜索代码内容
需要文件发现的大型代码库

配置参数

参数	类型	默认值	说明
`root_path`	`str`	工作目录	搜索的根目录
`use_ripgrep`	`bool`	`True`	是否使用 ripgrep
`max_file_size_mb`	`int`	`10`	搜索的最大文件大小（MB）

添加的工具

工具	功能
`glob_search`	快速文件模式匹配（如 `*/.py`）
`grep_search`	正则内容搜索

使用示例

python 复制代码

from langchain.agents import create_agent
from langchain.agents.middleware import FilesystemFileSearchMiddleware

agent = create_agent(
    model="gpt-4.1",
    tools=[],
    middleware=[
        FilesystemFileSearchMiddleware(
            root_path="/workspace",
            use_ripgrep=True,      # 使用 ripgrep（更快）
            max_file_size_mb=10,    # 跳过大于10MB的文件
        ),
    ],
)

# Agent 现在可以使用 glob_search 和 grep_search 工具
result = agent.invoke({
    "messages": ["查找所有包含 'async def' 的 Python 文件"]
})

# Agent 将使用：
# 1. glob_search(pattern="**/*.py") 查找 Python 文件
# 2. grep_search(pattern="async def", include="*.py") 查找异步函数

2.14 FilesystemMiddleware（文件系统）

记忆管理

| 提供 ls、read_file、write_file、edit_file 工具。

适用场景：

短期和长期记忆存储
上下文工程挑战的解决方案
处理可变长度工具结果

配置参数

参数	类型	默认值	说明
`backend`	`callable	None`	`StateBackend`
`system_prompt`	`str`	内置提示	自定义系统提示
`custom_tool_descriptions`	`dict`	`{}`	自定义工具描述

添加的工具

工具	功能
`ls`	列出文件系统中的文件
`read_file`	读取整个文件或指定行数
`write_file`	写入新文件
`edit_file`	编辑现有文件

短期 vs 长期文件系统

python 复制代码

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_short = create_agent(
    model="claude-sonnet-4-5-20250929",
    middleware=[FilesystemMiddleware()],
)

# 长期 - /memories/ 路径持久化到 Store
agent_long = create_agent(
    model="claude-sonnet-4-5-20250929",
    store=store,
    middleware=[
        FilesystemMiddleware(
            backend=lambda rt: CompositeBackend(
                default=StateBackend(rt),
                routes={"/memories/": StoreBackend(rt)}  # 持久化路径
            ),
        ),
    ],
)

2.15 SubAgentMiddleware（子代理）

任务隔离

| 允许 Agent 生成子代理来处理特定任务。

适用场景：

需要深度上下文隔离的任务
将复杂任务委托给专门子代理
保持主代理上下文窗口清洁

配置参数

参数	类型	默认值	说明
`default_model`	`str	BaseChatModel`	-
`default_tools`	`list`	`[]`	子代理的默认工具列表
`subagents`	`list[dict	CompiledSubAgent]`	`[]`
`always_include_general_purpose`	`bool`	`True`	是否包含通用子代理

子代理配置参数

参数	类型	必需	说明
`name`	`str`	✓	子代理名称
`description`	`str`	✓	子代理描述
`system_prompt`	`str`	✓	子代理系统提示
`tools`	`list`	✓	子代理可用工具
`model`	`str	BaseChatModel`	-
`middleware`	`list`	-	额外的中间件

使用示例

python 复制代码

from langchain.tools import tool
from langchain.agents import create_agent
from deepagents.middleware.subagents import SubAgentMiddleware

@tool
def get_weather(city: str) -> str:
    """获取城市天气。"""
    return f"{city} 的天气是晴天。"

agent = create_agent(
    model="claude-sonnet-4-5-20250929",
    middleware=[
        SubAgentMiddleware(
            default_model="claude-sonnet-4-5-20250929",
            default_tools=[],
            subagents=[
                {
                    "name": "weather",
                    "description": "此子代理可以获取城市天气。",
                    "system_prompt": "使用 get_weather 工具获取城市天气。",
                    "tools": [get_weather],
                    "model": "gpt-4.1",
                    "middleware": [],
                }
            ],
        )
    ],
)

3. 中间件架构对比

中间件分类矩阵

工具增强
工具选择器

性能优化
工具模拟器

测试支持
文件系统

记忆管理
子代理

任务隔离
安全中间件
PII检测

隐私保护
Shell

命令执行
可靠性中间件
重试

弹性增强
回退

高可用
核心中间件
摘要

上下文管理
人机协作

安全控制
限制

成本控制

优缺点对比

维度	优势	局限
模块化	可插拔、易组合、职责单一	过多中间件可能影响性能
可配置	灵活的参数配置	配置复杂度随中间件数量增加
生产就绪	经充分测试、支持错误处理	部分功能依赖特定提供商
状态管理	自动处理跨请求状态	需要 checkpointer 支持

middleware官方文档

LangChain v1.0 Middleware(中间件)使用指南

目录