与提供商无关的中间件
以下中间件可与任何 LLM 提供商配合使用:| 中间件 | 描述 |
|---|---|
| 摘要 | 在接近令牌限制时自动总结对话历史。 |
| [Human in the Loop](#Human in the Loop) | 暂停执行以等待人工批准工具调用。 |
| 模型调用限制 | 限制模型调用次数以防止成本过高。 |
| 工具调用限制 | 通过限制调用次数来控制工具执行。 |
| 模型回退 | 当主模型失败时自动回退到备用模型。 |
| PII 检测 | 检测和处理个人身份信息 (PII)。 |
| 待办事项列表 | 为智能体配备任务规划和跟踪能力。 |
| LLM 工具选择器 | 在调用主模型之前使用 LLM 选择相关工具。 |
| 工具重试 | 使用指数退避自动重试失败的工具调用。 |
| 模型重试 | 使用指数退避自动重试失败的模型调用。 |
| LLM 工具模拟器 | 使用 LLM 模拟工具执行以用于测试目的。 |
| 上下文编辑 | 通过修剪或清除工具使用来管理对话上下文。 |
| Shell 工具 | 向智能体暴露一个持久的 shell 会话以执行命令。 |
| 文件搜索 | 提供基于文件系统的 Glob 和 Grep 搜索工具。 |
| 文件系统 | 为智能体提供用于存储上下文和长期记忆的文件系统。 |
| 子智能体 | 添加生成子智能体的能力。 |
摘要
在接近令牌限制时自动总结对话历史,保留最近的消息同时压缩较旧的上下文。摘要对于以下情况很有用:- 超出上下文窗口的长时间运行对话。
- 具有大量历史记录的多轮对话。
- 保留完整对话上下文很重要的应用程序。
SummarizationMiddleware
配置选项
配置选项
用于生成摘要的模型。可以是模型标识符字符串(例如,
'openai:gpt-5.4-mini')或
BaseChatModel 实例。更多信息请参阅
init_chat_model。触发摘要的条件。可以是:
- 单个
ContextSize元组(必须满足指定条件) ContextSize元组列表(必须满足任一条件 - OR 逻辑)
fraction(float):模型上下文大小的比例 (0-1)tokens(int):绝对令牌数messages(int):消息数
ContextSize 的 API 参考。摘要后保留多少上下文。请精确指定以下之一:
fraction(float):保留模型上下文大小的比例 (0-1)tokens(int):保留的绝对令牌数messages(int):保留的最近消息数
ContextSize 的 API 参考。自定义令牌计数函数。默认为基于字符的计数。
用于摘要的自定义提示模板。如果未指定,则使用内置模板。模板应包含
{messages}
占位符,对话历史将插入其中。生成摘要时包含的最大令牌数。消息将在摘要前被修剪以适应此限制。
已弃用: 请改用
summary_prompt 提供完整提示。已弃用: 请改用
trigger: ("tokens", value)。触发摘要的令牌阈值。已弃用: 请改用
keep: ("messages", value)。要保留的最近消息数。完整示例
完整示例
摘要中间件监控消息令牌数,并在达到阈值时自动总结较旧的消息。触发条件控制摘要何时运行:
- 单个条件对象(必须满足指定条件)
- 条件数组(必须满足任一条件 - OR 逻辑)
- 每个条件可以使用
fraction(模型上下文大小的比例)、tokens(绝对计数)或messages(消息数)
fraction- 保留模型上下文大小的比例tokens- 保留的绝对令牌数messages- 保留的最近消息数
Human in the Loop
暂停智能体执行,以便在工具调用执行前进行人工批准、编辑或拒绝。Human in the Loop对于以下情况很有用:- 需要人工批准的高风险操作(例如数据库写入、金融交易)。
- 需要人工监督的合规工作流程。
- 人工反馈指导智能体的长时间运行对话。
HumanInTheLoopMiddleware
观看此视频指南演示Human in the
Loop中间件的行为。
模型调用限制
限制模型调用次数以防止无限循环或成本过高。模型调用限制对于以下情况很有用:- 防止失控的智能体进行过多的 API 调用。
- 对生产部署实施成本控制。
- 在特定调用预算内测试智能体行为。
ModelCallLimitMiddleware
观看此视频指南演示模型调用限制中间件的行为。
配置选项
配置选项
工具调用限制
通过限制工具调用次数来控制智能体执行,可以全局限制所有工具,也可以针对特定工具。工具调用限制对于以下情况很有用:- 防止对昂贵的外部 API 进行过多调用。
- 限制网络搜索或数据库查询。
- 对特定工具使用实施速率限制。
- 防止智能体循环失控。
ToolCallLimitMiddleware
观看此视频指南演示工具调用限制中间件的行为。
配置选项
配置选项
要限制的特定工具的名称。如果未提供,限制将应用于所有全局工具。
线程(对话)中所有运行的最大工具调用次数。使用相同线程 ID
的多次调用会持久化。需要检查点来维护状态。
None 表示无线程限制。单次调用(一个用户消息 → 响应周期)的最大工具调用次数。每次新用户消息时重置。
None 表示无运行限制。注意: 必须指定 thread_limit 或 run_limit 中的至少一个。达到限制时的行为:
'continue'(默认)- 用错误消息阻止超出的工具调用,让其他工具和模型继续。模型根据错误消息决定何时结束。'error'- 立即引发ToolCallLimitExceededError异常,停止执行'end'- 立即停止执行,并为超出的工具调用提供ToolMessage和 AI 消息。仅在限制单个工具时有效;如果其他工具有挂起的调用,则引发NotImplementedError。
完整示例
完整示例
使用以下方式指定限制:
- 线程限制 - 对话中所有运行的最大调用次数(需要检查点)
- 运行限制 - 单次调用的最大调用次数(每轮重置)
'continue'(默认)- 用错误消息阻止超出的调用,智能体继续'error'- 立即引发异常'end'- 以 ToolMessage + AI 消息停止(仅限单工具场景)
模型回退
当主模型失败时自动回退到备用模型。模型回退对于以下情况很有用:- 构建能够处理模型中断的弹性智能体。
- 通过回退到更便宜的模型来优化成本。
- 跨 OpenAI、Anthropic 等的提供商冗余。
ModelFallbackMiddleware
观看此视频指南演示模型回退中间件的行为。
配置选项
配置选项
PII 检测
使用可配置的策略检测和处理对话中的个人身份信息 (PII)。PII 检测对于以下情况很有用:- 具有合规要求的医疗和金融应用程序。
- 需要清理日志的客户服务智能体。
- 任何处理敏感用户数据的应用程序。
PIIMiddleware
自定义 PII 类型
您可以通过提供detector 参数来创建自定义 PII 类型。这允许您检测超出内置类型的、特定于您用例的模式。
创建自定义检测器的三种方式:
- 正则表达式模式字符串 - 简单的模式匹配
- 自定义函数 - 带有验证的复杂检测逻辑
text、start 和 end 键的字典列表:
配置选项
配置选项
要检测的 PII
类型。可以是内置类型(
email、credit_card、ip、mac_address、url)或自定义类型名称。如何处理检测到的 PII。选项:
'block'- 检测到时引发异常'redact'- 替换为[REDACTED_{PII_TYPE}]'mask'- 部分遮蔽(例如,****-****-****-1234)'hash'- 替换为确定性哈希值
自定义检测器函数或正则表达式模式。如果未提供,则使用该 PII 类型的内置检测器。
在模型调用前检查用户消息
在模型调用后检查 AI 消息
在执行后检查工具结果消息
待办事项列表
为智能体配备任务规划和跟踪能力,以处理复杂的多步骤任务。待办事项列表对于以下情况很有用:- 需要跨多个工具协调的复杂多步骤任务。
- 进度可见性很重要的长时间运行操作。
此中间件自动为智能体提供
write_todos 工具和系统提示,以指导有效的任务规划。TodoListMiddleware
观看此视频指南演示待办事项列表中间件的行为。
配置选项
配置选项
LLM 工具选择器
在调用主模型之前,使用 LLM 智能地选择相关工具。LLM 工具选择器对于以下情况很有用:- 具有许多工具(10+)的智能体,其中大多数与每个查询无关。
- 通过过滤不相关的工具来减少令牌使用量。
- 提高模型的专注度和准确性。
LLMToolSelectorMiddleware
配置选项
配置选项
用于工具选择的模型。可以是模型标识符字符串(例如,
'openai:gpt-5.4-mini')或 BaseChatModel 实例。更多信息请参阅 init_chat_model。默认为智能体的主模型。给选择模型的指令。如果未指定,则使用内置提示。
要选择的最大工具数。如果模型选择更多,则仅使用前 max_tools
个。如果未指定,则无限制。
无论选择如何都始终包含的工具名称。这些不计入 max_tools 限制。
工具重试
使用可配置的指数退避自动重试失败的工具调用。工具重试对于以下情况很有用:- 处理外部 API 调用中的暂时性故障。
- 提高依赖网络的工具的可靠性。
- 构建能够优雅处理临时错误的弹性智能体。
ToolRetryMiddleware
配置选项
配置选项
初始调用后的最大重试次数(默认为 3 次总尝试)
可选的工具或工具名称列表,用于应用重试逻辑。如果为
None,则应用于所有工具。要重试的异常类型元组,或一个接受异常并在应重试时返回
True 的可调用对象。所有重试耗尽后的行为。选项: -
'return_message' - 返回包含错误详情的
ToolMessage(允许 LLM 处理失败) - 'raise' -
重新引发异常(停止智能体执行) - 自定义可调用对象 - 接受异常并返回
ToolMessage 内容字符串的函数指数退避的乘数。每次重试等待
initial_delay * (backoff_factor ** retry_number) 秒。设置为 0.0 表示恒定延迟。首次重试前的初始延迟(秒)
重试之间的最大延迟(秒)(限制指数退避增长)
是否向延迟添加随机抖动(
±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'- 重新引发异常- 自定义函数 - 返回错误消息的函数
模型重试
使用可配置的指数退避自动重试失败的模型调用。模型重试对于以下情况很有用:- 处理模型 API 调用中的暂时性故障。
- 提高依赖网络的模型请求的可靠性。
- 构建能够优雅处理临时模型错误的弹性智能体。
ModelRetryMiddleware
配置选项
配置选项
初始调用后的最大重试次数(默认为 3 次总尝试)
要重试的异常类型元组,或一个接受异常并在应重试时返回
True 的可调用对象。所有重试耗尽后的行为。选项: -
'continue'(默认)- 返回包含错误详情的
AIMessage,允许智能体可能优雅地处理失败 - 'error' -
重新引发异常(停止智能体执行) - 自定义可调用对象 - 接受异常并返回 AIMessage
内容字符串的函数指数退避的乘数。每次重试等待
initial_delay * (backoff_factor ** retry_number) 秒。设置为 0.0 表示恒定延迟。首次重试前的初始延迟(秒)
重试之间的最大延迟(秒)(限制指数退避增长)
是否向延迟添加随机抖动(
±25%)以避免惊群效应完整示例
完整示例
中间件使用指数退避自动重试失败的模型调用。
LLM 工具模拟器
使用 LLM 模拟工具执行以用于测试目的,用 AI 生成的响应替换实际的工具调用。LLM 工具模拟器对于以下情况很有用:- 在不执行真实工具的情况下测试智能体行为。
- 在外部工具不可用或昂贵时开发智能体。
- 在实现实际工具之前原型化智能体工作流程。
LLMToolEmulator
配置选项
配置选项
要模拟的工具名称(str)或 BaseTool 实例列表。如果为
None(默认),则所有工具都将被模拟。如果为空列表
[],则不会模拟任何工具。如果包含工具名称/实例的数组,则仅模拟这些工具。用于生成模拟工具响应的模型。可以是模型标识符字符串(例如,
'google_genai:gemini-3.1-pro-preview')或
BaseChatModel 实例。如果未指定,则默认为智能体的模型。更多信息请参阅
init_chat_model。完整示例
完整示例
中间件使用 LLM 为工具调用生成合理的响应,而不是执行实际工具。
上下文编辑
通过在达到令牌限制时清除较旧的工具调用输出来管理对话上下文,同时保留最近的结果。这有助于在具有许多工具调用的长对话中保持上下文窗口的可管理性。上下文编辑对于以下情况很有用:- 具有许多工具调用且超出令牌限制的长对话
- 通过删除不再相关的较旧工具输出来降低令牌成本
- 仅在上下文中保留最近的 N 个工具结果
ContextEditingMiddleware, ClearToolUsesEdit
配置选项
配置选项
要应用的
ContextEdit
策略列表令牌计数方法。选项:
'approximate' 或 'model'ClearToolUsesEdit 选项:触发编辑的令牌数。当对话超过此令牌数时,较旧的工具输出将被清除。
编辑运行时要回收的最小令牌数。如果设置为 0,则清除所需的所有内容。
必须保留的最近工具结果数。这些永远不会被清除。
是否清除 AI 消息上发起的工具调用参数。当为
True
时,工具调用参数将被替换为空对象。要排除在清除之外的工具名称列表。这些工具的输出永远不会被清除。
为已清除的工具输出插入的占位符文本。这将替换原始工具消息内容。
完整示例
完整示例
中间件在达到令牌限制时应用上下文编辑策略。最常见的策略是
ClearToolUsesEdit,它清除较旧的工具结果,同时保留最近的结果。工作原理:- 监控对话中的令牌数
- 达到阈值时,清除较旧的工具输出
- 保留最近的 N 个工具结果
- 可选地保留工具调用参数以获取上下文
Shell 工具
向智能体暴露一个持久的 shell 会话以执行命令。Shell 工具中间件对于以下情况很有用:- 需要执行系统命令的智能体
- 开发和部署自动化任务
- 测试和验证工作流程
- 文件系统操作和脚本执行
限制:持久 shell 会话目前不支持中断(Human in the
Loop)。我们预计将来会添加对此的支持。
ShellToolMiddleware
配置选项
配置选项
shell 会话的基目录。如果省略,智能体启动时会创建一个临时目录,并在结束时删除。
会话启动后顺序执行的可选命令
会话关闭前执行的可选命令
控制超时、输出限制和资源配置的执行策略。选项:
HostExecutionPolicy- 完整主机访问(默认);最适合智能体已在容器或 VM 内运行的受信任环境DockerExecutionPolicy- 为每次智能体运行启动一个单独的 Docker 容器,提供更强的隔离性CodexSandboxExecutionPolicy- 重用 Codex CLI 沙箱以进行额外的系统调用/文件系统限制
可选的编辑规则,用于在将命令输出返回给模型之前清理它。
注册的 shell 工具描述的可选覆盖
用于启动持久会话的可选 shell 可执行文件(字符串)或参数序列。默认为
/bin/bash。提供给 shell 会话的可选环境变量。值在命令执行前被强制转换为字符串。
完整示例
完整示例
中间件提供一个持久的 shell 会话,智能体可以使用它顺序执行命令。执行策略:
HostExecutionPolicy(默认)- 具有完整主机访问权限的本机执行DockerExecutionPolicy- 隔离的 Docker 容器执行CodexSandboxExecutionPolicy- 通过 Codex CLI 进行沙箱执行
文件搜索
提供基于文件系统的 Glob 和 Grep 搜索工具。文件搜索中间件对于以下情况很有用:- 代码探索和分析
- 按名称模式查找文件
- 使用正则表达式搜索代码内容
- 需要文件发现的大型代码库
FilesystemFileSearchMiddleware
配置选项
配置选项
完整示例
完整示例
中间件向智能体添加两个搜索工具:Glob 工具 - 快速文件模式匹配:
- 支持
**/*.py、src/**/*.ts等模式 - 返回按修改时间排序的匹配文件路径
- 完整的正则表达式语法支持
- 使用
include参数按文件模式过滤 - 三种输出模式:
files_with_matches、content、count
文件系统中间件
上下文工程是构建有效智能体的主要挑战。当使用返回可变长度结果的工具(例如web_search 和 RAG)时,这尤其困难,因为较长的工具结果会快速填满您的上下文窗口。
来自 Deep Agents 的 FilesystemMiddleware 提供了四个用于与短期和长期记忆交互的工具:
ls:列出文件系统中的文件read_file:读取整个文件或文件中的特定行数write_file:将新文件写入文件系统edit_file:编辑文件系统中的现有文件
短期与长期文件系统
默认情况下,这些工具写入图状态中的本地“文件系统”。要启用跨线程的持久存储,请配置一个CompositeBackend,将特定路径(如 /memories/)路由到 StoreBackend。
/memories/ 配置带有 StoreBackend 的 CompositeBackend 时,任何以 /memories/ 为前缀的文件都会保存到持久存储中,并在不同线程间保留。没有此前缀的文件保留在临时状态存储中。
子智能体
将任务交给子智能体可以隔离上下文,保持主(主管)智能体的上下文窗口干净,同时仍然深入处理任务。 来自 Deep Agents 的子智能体中间件允许您通过task 工具提供子智能体。
general-purpose 子智能体。此子智能体具有与主智能体相同的指令和它可访问的所有工具。general-purpose 子智能体的主要目的是上下文隔离——主智能体可以将复杂任务委托给此子智能体,并获得简洁的答案,而不会因中间工具调用而膨胀。
特定于提供商的中间件
这些中间件针对特定的 LLM 提供商进行了优化。有关完整详情和示例,请参阅每个提供商的文档。Anthropic
用于 Claude 模型的提示缓存、bash 工具、文本编辑器、记忆和文件搜索中间件。
AWS
用于 Amazon Bedrock 模型的提示缓存中间件。
OpenAI
用于 OpenAI 模型的内容审核中间件。
将这些文档通过 MCP 连接到 Claude、VSCode
等,以获取实时答案。

