钩子
中间件提供两种风格的钩子来拦截代理执行:节点式钩子
在特定的执行点按顺序运行。
包装式钩子
在每个模型或工具调用周围运行。
节点式钩子
在特定的执行点按顺序运行。用于日志记录、验证和状态更新。 选择您的中间件需要的钩子。您可以在节点式钩子和包装式钩子之间进行选择。 节点式钩子在特定的执行点运行:| 钩子 | 何时运行 |
|---|---|
before_agent | 代理启动前(每次调用一次) |
before_model | 每次模型调用前 |
after_model | 每次模型响应后 |
after_agent | 代理完成后(每次调用一次) |
| 钩子 | 何时运行 |
|---|---|
wrap_model_call | 每个模型调用周围 |
wrap_tool_call | 每个工具调用周围 |
- 装饰器
- 类
包装式钩子
拦截执行并控制处理程序的调用时机。用于重试、缓存和转换。 您可以决定处理程序被调用零次(短路)、一次(正常流程)还是多次(重试逻辑)。 可用钩子:wrap_model_call- 每个模型调用周围wrap_tool_call- 每个工具调用周围
- 装饰器
- 类
状态更新
节点式钩子和包装式钩子都可以更新代理状态。机制有所不同:- 节点式钩子 (
before_agent,before_model,after_model,after_agent):直接返回一个字典。该字典使用图的归约器应用于代理状态。 - 包装式钩子 (
wrap_model_call,wrap_tool_call):对于模型调用,返回ExtendedModelResponse并附带Command以将状态更新与模型响应一起注入。对于工具调用,直接返回Command。当您需要根据在模型或工具调用期间运行的逻辑来跟踪或更新状态时使用,例如摘要触发点、使用情况元数据,或从请求或响应计算出的自定义字段。
节点式钩子
从节点式钩子返回一个字典以将更新合并到代理状态中。字典键映射到状态字段。包装式钩子
从wrap_model_call 返回带有 Command 的 ExtendedModelResponse 以从模型调用层注入状态更新:
Command 流经图的归约器,因此更新会正确应用,消息是累加的而不是替换现有状态。
与多个中间件的组合
当多个中间件层返回ExtendedModelResponse 时,它们的命令会组合:
- 命令通过归约器应用: 每个
Command成为单独的状态更新。对于消息,这意味着它们是累加的。 - 冲突时外层获胜: 对于非归约器状态字段,命令先应用内层,然后应用外层。最外层中间件的值在冲突键上具有优先级。
- 重试安全: 如果外层中间件实现了可能导致再次多次调用
handler()的逻辑(例如重试逻辑),则早期调用的命令会被丢弃。
创建中间件
您可以通过两种方式创建中间件:基于装饰器的中间件
简单快捷,适用于单钩子中间件。使用装饰器包装单个函数。
基于类的中间件
功能更强大,适用于具有多个钩子或配置的复杂中间件。
基于装饰器的中间件
简单快捷,适用于单钩子中间件。使用装饰器包装单个函数。 可用装饰器: 节点式:@before_agent- 代理启动前运行(每次调用一次)@before_model- 每次模型调用前运行@after_model- 每次模型响应后运行@after_agent- 代理完成后运行(每次调用一次)
@wrap_model_call- 用自定义逻辑包装每个模型调用@wrap_tool_call- 用自定义逻辑包装每个工具调用
@dynamic_prompt- 生成动态系统提示词
- 需要单个钩子
- 无需复杂配置
- 快速原型设计
基于类的中间件
功能更强大,适用于具有多个钩子或配置的复杂中间件。当您需要为同一个钩子定义同步和异步实现,或者希望在一个中间件中组合多个钩子时使用类。 示例:- 为同一个钩子定义同步和异步实现
- 需要在单个中间件中定义多个钩子
- 需要复杂配置(例如可配置阈值、自定义模型)
- 跨项目重用,带初始化时配置
自定义状态模式
如果您的中间件需要在钩子之间跟踪状态,中间件可以使用自定义属性扩展代理状态。这使得中间件能够:- 在执行过程中跟踪状态:维护在整个代理执行生命周期中持续存在的计数器、标志或其他值
-
在钩子之间共享数据:从
before_model向after_model或不同中间件实例之间传递信息 - 实现横切关注点:添加功能,如速率限制、使用情况跟踪、用户上下文或审计日志,而无需修改核心代理逻辑
- 进行条件决策:使用累积状态来确定是否继续执行、跳转到不同节点或动态修改行为
- 装饰器
- 类
执行顺序
使用多个中间件时,了解它们的执行方式:执行流程
执行流程
Before 钩子按顺序运行:
middleware1.before_agent()middleware2.before_agent()middleware3.before_agent()
middleware1.before_model()middleware2.before_model()middleware3.before_model()
middleware1.wrap_model_call()→middleware2.wrap_model_call()→middleware3.wrap_model_call()→ 模型
middleware3.after_model()middleware2.after_model()middleware1.after_model()
middleware3.after_agent()middleware2.after_agent()middleware1.after_agent()
before_*钩子:第一个到最后after_*钩子:最后到第一个(反向)wrap_*钩子:嵌套(第一个中间件包装所有其他中间件)
代理跳转
要从中间件提前退出,返回包含jump_to 的字典:
可用跳转目标:
'end':跳转到代理执行的末尾(或第一个after_agent钩子)'tools':跳转到工具节点'model':跳转到模型节点(或第一个before_model钩子)
- 装饰器
- 类
最佳实践
- 保持中间件专注 - 每个应做好一件事
- 优雅地处理错误 - 不要让中间件错误导致代理崩溃
- 使用适当的钩子类型:
- 节点式用于顺序逻辑(日志记录、验证)
- 包装式用于控制流(重试、回退、缓存)
- 清楚记录任何自定义状态属性
- 集成前独立单元测试中间件
- 考虑执行顺序 - 将关键中间件放在列表前面
- 尽可能使用内置中间件
示例
动态提示词
在运行时动态修改系统提示词,以便在每次模型调用之前注入上下文、用户特定指令或其他信息。这是最常见的中间件用例之一。 使用ModelRequest 上的 system_message 字段读取和修改系统提示词。它包含一个 SystemMessage 对象(即使代理是使用字符串 system_prompt 创建的)。
- 装饰器
- 类
ModelRequest.system_message始终是一个SystemMessage对象,即使代理是使用system_prompt="string"创建的- 使用
SystemMessage.content_blocks将内容作为块列表访问,无论原始内容是字符串还是列表 - 修改系统消息时,使用
content_blocks并追加新块以保留现有结构 - 您可以直接将
SystemMessage对象传递给create_agent的system_prompt参数,用于高级用例,如缓存控制
动态模型选择
- 装饰器
- 类
动态选择工具
在运行时选择相关工具以提高性能和准确性。本节介绍过滤预注册的工具。有关注册在运行时发现的工具(例如来自 MCP 服务器),请参阅 Runtime tool registration。 好处:- 更短的提示词 - 通过仅暴露相关工具来降低复杂性
- 更好的准确性 - 模型从较少的选项中正确选择
- 权限控制 - 根据用户访问权限动态过滤工具
- 装饰器
- 类
工具调用监控
- 装饰器
- 类
提示词缓存(Anthropic)
在使用 Anthropic 模型时,使用带有缓存控制指令的结构化内容块来缓存大型系统提示词:- 装饰器
- 类
ModelRequest.system_message始终是一个SystemMessage对象,即使代理是使用system_prompt="string"创建的- 使用
SystemMessage.content_blocks将内容作为块列表访问,无论原始内容是字符串还是列表 - 修改系统消息时,使用
content_blocks并追加新块以保留现有结构 - 您可以直接将
SystemMessage对象传递给create_agent的system_prompt参数,用于高级用例,如缓存控制
其他资源
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

