Skip to main content
通过实现在智能体执行流程中特定点运行的钩子来构建自定义中间件。

钩子

中间件提供两种风格的钩子来拦截智能体执行:

节点式钩子

在特定执行点按顺序运行。

包装式钩子

围绕每次模型或工具调用运行。

节点式钩子

在特定执行点按顺序运行。用于日志记录、验证和状态更新。 选择你的中间件需要的钩子。你可以在节点式钩子和包装式钩子之间选择。 节点式钩子在特定执行点运行: 包装式钩子围绕每次调用运行,让你控制执行: 示例:

包装式钩子

拦截执行并控制何时调用处理程序。用于重试、缓存和转换。 你决定处理程序被调用零次(短路)、一次(正常流程)或多次(重试逻辑)。 可用钩子:
  • wrap_model_call - 围绕每次模型调用
  • wrap_tool_call - 围绕每次工具调用
示例:

状态更新

节点式和包装式钩子都可以更新智能体状态。机制有所不同:
  • 节点式钩子before_agentbefore_modelafter_modelafter_agent):直接返回字典。字典通过图的归约器应用到智能体状态。
  • 包装式钩子wrap_model_callwrap_tool_call):对于模型调用,返回带有 CommandExtendedModelResponse,以在模型响应旁注入状态更新。对于工具调用,直接返回 Command。当你需要基于模型或工具调用期间运行的逻辑来跟踪或更新状态时使用这些,例如摘要触发点、使用元数据或从请求或响应计算的自定义字段。

节点式钩子

从节点式钩子返回字典以将更新合并到智能体状态。字典键映射到状态字段。

包装式钩子

wrap_model_call 返回带有 CommandExtendedModelResponse,以从模型调用层注入状态更新:
Command 通过图的归约器传递,因此更新会被正确应用,消息是累加的而不是替换现有状态。

多中间件组合

当多个中间件层返回 ExtendedModelResponse 时,它们的命令会组合:
  • 命令通过归约器应用: 每个 Command 成为单独的状态更新。对于消息,这意味着它们是累加的。
  • 外层优先于冲突: 对于非归约器状态字段,命令先从内层应用,再从外层应用。最外层中间件的值在冲突键上优先。
  • 重试安全: 如果外层中间件实现了可能导致多次调用 handler() 的逻辑(例如重试逻辑),来自早期调用的命令将被丢弃。

创建中间件

你可以通过两种方式创建中间件:

基于装饰器的中间件

快速简单,适用于单钩子中间件。使用装饰器包装单个函数。

基于类的中间件

更强大,适用于具有多个钩子或配置的复杂中间件。

基于装饰器的中间件

快速简单,适用于单钩子中间件。使用装饰器包装单个函数。 可用装饰器: 节点式: 包装式: 便捷: 示例:
何时使用装饰器:
  • 只需要单个钩子
  • 无需复杂配置
  • 快速原型设计

基于类的中间件

更强大,适用于具有多个钩子或配置的复杂中间件。当你需要为同一个钩子定义同步和异步实现,或者想要在单个中间件中组合多个钩子时,使用类。 示例:
何时使用类:
  • 为同一个钩子定义同步和异步实现
  • 单个中间件需要多个钩子
  • 需要复杂配置(例如可配置的阈值、自定义模型)
  • 通过初始化时配置在项目间复用

自定义状态模式

如果你的中间件需要跨钩子跟踪状态,中间件可以用自定义属性扩展智能体的状态。这使中间件能够:
  • 跨执行跟踪状态:维护在智能体整个执行生命周期中持久化的计数器、标志或其他值
  • 在钩子之间共享数据:在 before_modelafter_model 之间或不同中间件实例之间传递信息
  • 实现横切关注点:添加诸如速率限制、用量跟踪、用户上下文或审计日志等功能,而无需修改核心智能体逻辑
  • 做出条件决策:使用累积的状态来决定是否继续执行、跳转到不同节点或动态修改行为

执行顺序

使用多个中间件时,了解它们的执行方式:
Before 钩子按顺序运行:
  1. middleware1.before_agent()
  2. middleware2.before_agent()
  3. middleware3.before_agent()
智能体循环开始
  1. middleware1.before_model()
  2. middleware2.before_model()
  3. middleware3.before_model()
Wrap 钩子像函数调用一样嵌套:
  1. middleware1.wrap_model_call()middleware2.wrap_model_call()middleware3.wrap_model_call() → 模型
After 钩子按逆序运行:
  1. middleware3.after_model()
  2. middleware2.after_model()
  3. middleware1.after_model()
智能体循环结束
  1. middleware3.after_agent()
  2. middleware2.after_agent()
  3. middleware1.after_agent()
关键规则:
  • before_* 钩子:从前到后
  • after_* 钩子:从后到前(逆序)
  • wrap_* 钩子:嵌套(第一个中间件包装所有其他的)

智能体跳转

要从中间件提前退出,返回包含 jump_to 的字典: 可用跳转目标:
  • 'end':跳转到智能体执行的结尾(或第一个 after_agent 钩子)
  • 'tools':跳转到工具节点
  • 'model':跳转到模型节点(或第一个 before_model 钩子)

最佳实践

  1. 保持中间件专注 - 每个中间件应该只做好一件事
  2. 优雅地处理错误 - 不要让中间件错误导致智能体崩溃
  3. 使用适当的钩子类型
    • 节点式用于顺序逻辑(日志记录、验证)
    • 包装式用于控制流(重试、回退、缓存)
  4. 清晰记录任何自定义状态属性
  5. 在集成之前独立地对中间件进行单元测试
  6. 考虑执行顺序 - 将关键中间件放在列表的前面
  7. 尽可能使用内置中间件

示例

动态提示词

在运行时动态修改系统提示词,以在每次模型调用前注入上下文、用户特定的指令或其他信息。这是最常见的中间件用例之一。 使用 ModelRequest 上的 system_message 字段来读取和修改系统提示词。它包含一个 SystemMessage 对象(即使智能体是用字符串 system_prompt 创建的)。
  • ModelRequest.system_message 始终是 SystemMessage 对象,即使智能体是用 system_prompt="string" 创建的
  • 使用 SystemMessage.content_blocks 以块列表的形式访问内容,无论原始内容是字符串还是列表
  • 修改系统消息时,使用 content_blocks 并追加新块以保留现有结构
  • 你可以将 SystemMessage 对象直接传递给 create_agentsystem_prompt 参数,用于缓存控制等高级用例

动态模型选择

动态选择工具

在运行时选择相关工具以提高性能和准确性。本节介绍过滤预注册工具。要注册在运行时发现的工具(例如来自 MCP 服务器的工具),请参阅运行时工具注册 优势:
  • 更短的提示词 - 通过仅暴露相关工具来降低复杂性
  • 更高的准确性 - 模型从更少的选项中更正确地选择
  • 权限控制 - 根据用户访问权限动态过滤工具

工具调用监控

提示词缓存(Anthropic)

在使用 Anthropic 模型时,使用带缓存控制指令的结构化内容块来缓存大型系统提示词:
注意事项:
  • ModelRequest.system_message 始终是 SystemMessage 对象,即使智能体是用 system_prompt="string" 创建的
  • 使用 SystemMessage.content_blocks 以块列表的形式访问内容,无论原始内容是字符串还是列表
  • 修改系统消息时,使用 content_blocks 并追加新块以保留现有结构
  • 你可以将 SystemMessage 对象直接传递给 create_agentsystem_prompt 参数,用于缓存控制等高级用例
:::

其他资源