跳到主要内容

生命周期 Hooks

中间件的 6 个 Hook 点——before_agent、before_model、wrap_model_call、wrap_tool_call、after_model、after_agent——提供了在 Agent 执行全流程中插入自定义逻辑的能力。

6 个切入点​

Hook时机说明
before_agentAgent 执行前全局初始化，设置全局状态
before_model模型调用前输入预处理、验证、清洗
wrap_model_call包裹模型调用包装模型调用过程
wrap_tool_call包裹工具调用拦截控制工具执行
after_model模型调用后结果验证、格式转换
after_agentAgent 执行后资源清理、状态记录

执行顺序​

before_agent
    └── before_model
            └── wrap_model_call
                    └── [LLM 模型调用]
                └── after_model
                    └── wrap_tool_call
                            └── [工具执行]
    └── after_agent

各 Hook 详解​

before_agent​

在 Agent 执行的最开始，提供全局初始化的机会。这个阶段通常用于：

  • 设置全局状态
  • 检查环境变量
  • 初始化资源

before_model​

输入预处理的关键节点。可以对输入数据进行：

  • 预处理
  • 验证
  • 清洗

wrap_model_call​

最核心的 Hook，包装了实际的模型调用过程。决定如何与底层模型交互。是实现高级功能（如缓存、重试、熔断等）的关键位置。

wrap_tool_call​

它包装了每次工具调用。这个阶段的处理逻辑可以是：

  • 权限控制
  • 重试机制
  • 日志记录
  • 审批审核

after_model​

处理模型返回的原始结果。任务包括：

  • 验证输出质量
  • 进行格式转换
  • 提取关键信息

after_agent​

整个生命周期的收尾工作：

  • 清理资源
  • 记录最终状态
  • 生成报告

数据传递机制​

上下文对象​

每个 Hook 都能访问和修改共享的上下文对象，这个对象就像是整个处理过程的"记忆"。

上下文对象不仅包含请求信息和响应数据，还包含运行时状态、中间计算结果、元数据等。

元数据传递​

元数据传递机制允许中间件在不直接共享状态的情况下传递信息。例如，一个中间件可以在元数据中标记某个输入是 VIP 用户的请求，后续的中间件可以根据这个标记采取不同的处理策略。

状态管理​

中间件需要维护状态，包括：

  • 错误处理
  • 回滚机制
  • 事务性操作

高级 Hook 使用模式​

条件 Hook 执行​

通过智能的条件判断来决定是否执行某个 Hook。例如，对于 VIP 用户，系统可能需要启用更复杂的处理逻辑。

错误恢复 Hook​

不同层级的错误需要不同的恢复策略：

  • 简单错误：通过重试解决
  • 复杂错误：切换到备用方案

性能优化 Hook​

缓存 Hook 通过在 wrap_model_call 阶段检查缓存来决定是否直接返回结果，避免重复调用模型。