提供商无关的中间件
以下中间件适用于任何 LLM 提供商:| 中间件 | 描述 |
|---|---|
| 摘要 | 当接近 token 限制时自动摘要对话历史。 |
| 人工介入 | 暂停执行以等待人工批准工具调用。 |
| 模型调用限制 | 限制模型调用次数以防止过度成本。 |
| 工具调用限制 | 通过限制调用计数来控制工具执行。 |
| 模型回退 | 当主模型失败时自动回退到替代模型。 |
| PII 检测 | 检测和处理个人身份信息(PII)。 |
| 待办事项列表 | 为代理配备任务规划和跟踪功能。 |
| LLM 工具选择器 | 在调用主模型之前使用 LLM 选择相关工具。 |
| 工具重试 | 使用指数退避自动重试失败的工具调用。 |
| 模型重试 | 使用指数退避自动重试失败的模型调用。 |
| LLM 工具模拟器 | 使用 LLM 模拟工具执行以进行测试。 |
| 上下文编辑 | 通过修剪或清除工具使用来管理对话上下文。 |
| Shell 工具 | 向代理公开持久性 shell 会话以执行命令。 |
| 文件搜索 | 提供文件系统上的 Glob 和 Grep 搜索工具。 |
| 文件系统 | 为代理提供文件系统以存储上下文和长期记忆。 |
| 子代理 | 添加生成子代理的能力。 |
摘要
当接近 token 限制时自动摘要对话历史,保留最近的消息同时压缩较旧的上下文。摘要适用于以下情况:- 超出上下文窗口的长时间运行对话。
- 具有大量历史的多次对话。
- 需要保留完整对话上下文的应用程序。
SummarizationMiddleware
配置选项
配置选项
用于生成摘要的模型。可以是模型标识符字符串(例如
'openai:gpt-4.1-mini')或 BaseChatModel 实例。有关更多信息,请参阅 init_chat_model。触发摘要的条件。可以是:
- 单个
ContextSize元组(必须满足指定条件) ContextSize元组列表(必须满足任何条件 - 或逻辑)
fraction(float):模型上下文大小的分数(0-1)tokens(int):绝对 token 计数messages(int):消息计数
ContextSize 的 API 参考。摘要后保留多少上下文。准确指定以下之一:
fraction(float):保留的模型上下文大小分数(0-1)tokens(int):保留的绝对 token 计数messages(int):保留的最近消息数量
ContextSize 的 API 参考。自定义 token 计数函数。默认为基于字符的计数。
摘要的自定义提示词模板。如果未指定,使用内置模板。模板应包含
{messages} 占位符,对话历史将在此处插入。生成摘要时包含的最大 token 数。消息将在摘要之前被修剪以适应此限制。
已弃用: 使用
summary_prompt 提供完整提示词。已弃用: 改用
trigger: ("tokens", value)。触发摘要的 token 阈值。已弃用: 改用
keep: ("messages", value)。要保留的最近消息。完整示例
完整示例
摘要中间件监视消息 token 计数,并在达到阈值时自动摘要较旧的消息。触发条件控制摘要何时运行:
- 单个条件对象(必须满足指定条件)
- 条件数组(必须满足任何条件 - 或逻辑)
- 每个条件可以使用
fraction(模型上下文大小的分数)、tokens(绝对计数)或messages(消息计数)
fraction- 保留的模型上下文大小分数tokens- 保留的绝对 token 计数messages- 保留的最近消息数量
人工介入
暂停代理执行以等待人工批准、编辑或拒绝工具调用,然后才能执行。人工介入适用于以下情况:- 需要人工批准的高风险操作(例如数据库写入、金融交易)。
- 必须有人类监督的合规工作流。
- 人类反馈指导代理的长时间运行对话。
HumanInTheLoopMiddleware
观看此视频指南,了解人工介入中间件行为演示。
模型调用限制
限制模型调用次数以防止无限循环或过度成本。模型调用限制适用于以下情况:- 防止失控代理进行过多 API 调用。
- 在生产部署上实施成本控制。
- 在特定调用预算内测试代理行为。
ModelCallLimitMiddleware
观看此视频指南,了解模型调用限制中间件行为演示。
配置选项
配置选项
工具调用限制
通过限制工具调用次数来控制代理执行,可以全局限制所有工具或针对特定工具限制。工具调用限制适用于以下情况:- 防止对昂贵的外部 API 进行过多调用。
- 限制网络搜索或数据库查询。
- 对特定工具使用实施速率限制。
- 防止失控的代理循环。
ToolCallLimitMiddleware
观看此视频指南,了解工具调用限制中间件行为演示。
配置选项
配置选项
要限制的特定工具名称。如果未提供,限制适用于所有工具全局。
线程(对话)中所有运行的最大工具调用数。在具有相同线程 ID 的多次调用中持续。需要 checkpointer 维护状态。
None 表示无线程限制。单次调用(一个用户消息 → 响应周期)的最大工具调用数。每次新用户消息时重置。
None 表示无运行限制。注意: 必须指定 thread_limit 或 run_limit 中的至少一个。达到限制时的行为:
'continue'(默认)- 用错误消息阻止超出的工具调用,让其他工具和模型继续。模型根据错误消息决定何时结束。'error'- 立即抛出ToolCallLimitExceededError异常,停止执行'end'- 立即停止,用ToolMessage和 AI 消息表示超出的工具调用。仅在限制单个工具时有效;如果其他工具有待处理调用则抛出NotImplementedError。
完整示例
完整示例
指定限制:
- 线程限制 - 对话中所有运行的最大调用数(需要 checkpointer)
- 运行限制 - 每次单独调用的最大调用数(每次轮次重置)
'continue'(默认)- 用错误消息阻止超出的调用,代理继续'error'- 立即抛出异常'end'- 停止并返回 ToolMessage + AI 消息(仅限单工具场景)
模型回退
当主模型失败时自动回退到替代模型。模型回退适用于以下情况:- 构建能够处理模型停机的弹性代理。
- 通过回退到更便宜的模型进行成本优化。
- 跨 OpenAI、Anthropic 等的提供商冗余。
ModelFallbackMiddleware
观看此视频指南,了解模型回退中间件行为演示。
配置选项
配置选项
PII 检测
使用可配置策略检测和处理对话中的个人身份信息(PII)。PII 检测适用于以下情况:- 具有合规要求的医疗和金融应用程序。
- 需要清理日志的客户服务代理。
- 处理敏感用户数据的任何应用程序。
PIIMiddleware
自定义 PII 类型
您可以通过提供detector 参数来创建自定义 PII 类型。这允许您检测超出内置类型的特定于用例的模式。
创建自定义检测器的三种方式:
- 正则表达式字符串 - 简单模式匹配
- 自定义函数 - 带验证的复杂检测逻辑
text、start 和 end 键的字典列表:
配置选项
配置选项
PII 类型标识符。内置类型包括:
"email"、"phone_number"、"ip_address"、"credit_card"、"ssn"、"us_passport"、"us_driver_license"、"us_bank_routing_number"、"us_bank_account"、"international_bank_account"、"custom_api_key"。检测到 PII 时的处理策略。选项:
"redact"- 用[REDACTED]替换 PII"mask"- 用****部分掩盖 PII"hash"- 用 SHA256 哈希替换 PII"block"- 如果在输入中检测到则阻止请求
已弃用。 改用新的检测器参数。
自定义检测器。可以是:
- 正则表达式字符串(例如
r"sk-[a-zA-Z0-9]{32}") - 编译的正则表达式对象(例如
re.compile(r"pattern")) - 自定义检测器函数
是否将策略应用于输入消息
是否将策略应用于模型输出
待办事项列表
为代理配备任务规划和跟踪功能。待办事项列表适用于以下情况:- 需要完成多个步骤的复杂任务。
- 按顺序跟踪子任务进展。
- 确保所有必需步骤都完成。
ToDoListMiddleware
配置选项
配置选项
LLM 工具选择器
在调用主模型之前使用 LLM 选择相关工具。LLM 工具选择器适用于以下情况:- 大量工具可用的情况。
- 减少主模型的工具选择开销。
- 过滤不相关工具以减少上下文大小。
LLMToolSelectorMiddleware
工具重试
使用指数退避自动重试失败的工具调用。工具重试适用于以下情况:- 处理暂时性故障(例如网络问题、超时)。
- 提高依赖外部 API 的工具的可靠性。
- 构建能够优雅处理临时错误的弹性代理。
ToolRetryMiddleware
观看此视频指南,了解工具重试中间件行为演示。
配置选项
配置选项
要重试的工具名称列表或工具实例。如果为
None(默认),重试所有工具。如果为空列表 [],不重试任何工具。初始调用后的最大重试次数(默认总共 3 次尝试)
要重试的异常类型元组,或接受异常并返回
True 的可调用对象(如果应该重试)。所有重试耗尽时的行为。选项:
'return_message'(默认)- 返回带有错误详情的ToolMessage,允许代理可能优雅地处理失败'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
配置选项
配置选项
要模拟的工具名称列表或 BaseTool 实例。如果为
None(默认),所有工具都会被模拟。如果为空列表 [],不模拟任何工具。如果数组包含工具名称/实例,则仅模拟那些工具。用于生成模拟工具响应的模型。可以是模型标识符字符串(例如
'anthropic:claude-sonnet-4-6')或 BaseChatModel 实例。如果未指定,默认为代理的模型。更多信息请参阅 init_chat_model。完整示例
完整示例
中间件使用 LLM 为工具调用生成合理的响应,而不是执行实际工具。
上下文编辑
通过清除达到 token 限制时的较旧工具调用输出来管理对话上下文,同时保留最近的结果。这有助于在具有许多工具调用的长对话中保持上下文窗口可管理。上下文编辑适用于以下情况:- 具有超出 token 限制的许多工具调用的长对话
- 通过删除不再相关的较旧工具输出来降低 token 成本
- 仅在上下文中保留最近的 N 个工具结果
ContextEditingMiddleware, ClearToolUsesEdit
配置选项
配置选项
要应用的
ContextEdit 策略列表Token 计数方法。选项:
'approximate' 或 'model'ClearToolUsesEdit 选项:触发编辑的 token 计数。当对话超过此 token 计数时,较旧的工具输出将被清除。
编辑运行时至少要回收的最小 token 数。如果设置为 0,则根据需要清除尽可能多的内容。
必须保留的最近工具结果的数量。这些永远不会被清除。
是否清除 AI 消息上的源工具调用参数。当为
True 时,工具调用参数将被替换为空对象。从清除中排除的工具名称列表。这些工具的输出永远不会被清除。
为清除的工具输出插入的占位符文本。这将替换原始工具消息内容。
完整示例
完整示例
中间件在达到 token 限制时应用上下文编辑策略。最常见的策略是
ClearToolUsesEdit,它在保留最近结果的同时清除较旧的工具结果。工作原理:- 监视对话中的 token 计数
- 达到阈值时清除较旧的工具输出
- 保留最近的 N 个工具结果
- 可选保留工具调用参数以提供上下文
Shell 工具
向代理公开持久性 shell 会话以执行命令。Shell 工具中间件适用于以下情况:- 需要执行系统命令的代理
- 开发和部署自动化任务
- 测试和验证工作流
- 文件系统操作和脚本执行
限制:持久性 shell 会话目前不适用于中断(人工介入)。我们预计将来会添加对此的支持。
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
文件系统中间件
为代理提供文件系统以存储上下文和长期记忆。文件系统中间件适用于以下情况:- 需要持久存储的代理
- 需要文件系统访问的代理
- 需要长期记忆的代理
FilesystemMiddleware
配置选项
配置选项
子代理
为代理添加生成子代理的能力。子代理中间件适用于以下情况:- 需要将复杂任务分解为更小子任务的代理
- 需要并行处理多个任务的代理
- 需要隔离不同任务上下文的代理
SubagentMiddleware

