第六章 Hook 与 Middleware：五大插桩点全面覆盖模型调用与系统提示，完美替代 1.x Hook
6.0 Middleware 是什么？
Middleware，本质上是一段可被自动调用的代码——在 Agent 执行流程中的特定节点被触发。你可以将其类比为 Web 框架中常见的过滤器（Filter / Interceptor），理解起来非常直观。
以 Web 请求为例：客户端发起的请求会依次经过多层过滤器，最终到达控制器；类似地，用户的问题进入 Agent 后，也会经过一系列中间件，然后才由 LLM 进行推理或调用工具。区别在于，Agent 的执行路径上，你可以在 5 个特定节点自由插入自定义逻辑。
这 5 个节点，对应了一次 agent.call() 执行的完整生命周期：
agent.call(msg, rt)
│
├─ ① onAgent ← 整轮调用的起点（日志记录、计时、限流）
│
├─ ② onSystemPrompt ← 系统提示词拼接完成后、发送给 LLM 之前（动态注入当前时间、角色等信息）
│
├─ ③ onReasoning ← LLM 进行推理、生成文本（内容审计、敏感词检测）
│
├─ ④ onActing ← LLM 决定调用工具时（HITL 人工审批、工具调用审计）
│
└─ ⑤ onModelCall ← 真正向 LLM API 发起 HTTP 请求的前后（Token 计费、缓存、熔断）
最直观的例子仍然是这个——每次 Agent 被调用时自动输出一行日志。试想，如果没有 Middleware，你需要在多少地方手动添加打印语句？
class LoggingMiddleware extends MiddlewareBase {
@Override
public Mono
挂载到 Agent 后，每次 agent.call() 都会自动打印这行日志——无需在每个调用点手写 System.out.println。
再看一个更实用的场景：每次调用 LLM 之前打印已消耗的 Token 数量，并自动计算费用。
@Override
public Mono
挂载后，所有 Agent 调用的 Token 消耗和费用都将自动打印——如果不使用 Middleware，每一次 agent.call() 后面都需要手动计算一遍。
6.1 与 1.x Hook 的关系
1.x 旧写法（仅供对照，请不要再编写新代码）
import io.agentscope.core.hook.Hook;
import io.agentscope.core.hook.HookEvent;
class LoggingHook implements Hook {
@Override
public void onReasoning(HookEvent event) {
System.out.println("[reasoning] " + event.getMessage().getTextContent());
}
}
ReActAgent agent = ReActAgent.builder()
...
.hook(new LoggingHook())
.build();
2.0 新写法
import io.agentscope.core.hook.HookEvent;
import io.agentscope.core.middleware.MiddlewareBase;
import io.agentscope.core.middleware.MiddlewareContext;
import io.agentscope.core.middleware.ModelCallRequest;
import io.agentscope.core.middleware.ModelCallResponse;
import reactor.core.publisher.Mono;
class LoggingMiddleware extends MiddlewareBase {
@Override
public Mono
对比可见两个关键变化：
旧版 Hook 采用 void 同步方法；新版 Middleware 全部返回 Mono，便于链式组合。旧版仅能绑定 ReActAgent；新版既可装配在 HarnessAgent，也可装配在 ReActAgent。
6.2 五个插桩点速查
只需重写 MiddlewareBase 的以下方法即可。每个节点对应 Agent 执行流程中的一个关键时刻：
| 插桩点 | 触发时机 | 典型用途 |
|---|---|---|
onAgent | agent.call() 开始和结束 | 全链路日志、计时、限流 |
onSystemPrompt | 系统提示词拼接后，发送给 LLM 前 | 动态注入当前时间、角色、计划摘要 |
onReasoning | LLM 推理过程中（每段文字输出时） | 内容审计、敏感词检测 |
onActing | LLM 决定调用工具时 | HITL 人工审批、工具调用审计 |
onModelCall | 真正向 LLM API 发送 HTTP 请求的前后 | Token 计费、缓存、熔断、提示词脱敏 |
下面逐一讲解每个节点的代码实现：
① onAgent —— 整轮 call 的入口与出口
@Override
public Mono
用途：日志开头、整轮计时、TraceId 注入、整体限流。
② onReasoning —— 推理阶段
@Override
public Mono
用途：思维链审计、敏感词检测、推理阶段限流。
③ onActing —— 行动阶段（工具调用之前）
@Override
public Mono
用途：判断 LLM 将要调用哪些工具，决定是否需要转人工审核。
④ onModelCall
@Override
public Mono
onModelCall 是 1.x Hook 中不存在的节点，专门为“模型调用前后”预留——非常适合实现：
提示词脱敏（脱敏后再发送到模型）、模型响应缓存（命中缓存后直接返回 ModelCallResponse 并短路）、Token 计数 / 限流 / 计费埋点、模型熔断（连续失败 N 次后直接抛出异常）。
⑤ onSystemPrompt
@Override
public Mono
用途：动态注入当前时间、组织名称、角色身份、计划模式下的 Plan 摘要。
6.3 一个完整的“生产可观测性”中间件
将“Trace 注入 / Token 计数 / 推理审计”三合一放入一个 Middleware：
import io.agentscope.core.RuntimeContext;
import io.agentscope.core.hook.HookEvent;
import io.agentscope.core.middleware.MiddlewareBase;
import io.agentscope.core.middleware.MiddlewareContext;
import io.agentscope.core.middleware.ModelCallRequest;
import io.agentscope.core.middleware.ModelCallResponse;
import reactor.core.publisher.Mono;
public class ObservabilityMiddleware extends MiddlewareBase {
@Override
public Mono
挂载方式同样简洁：
HarnessAgent agent = HarnessAgent.builder()
.name("weather_bot")
.sysPrompt("...")
.model(model)
.workspace(Path.of("./workspace"))
.middleware(new ObservabilityMiddleware())
.build();
6.4 与 Permission 系统的协作
需要特别说明：Middleware 拦截的是所有事件，而 Permission 系统仅拦截工具调用。两者分工非常明确：
Permission 的功能是通过规则或模式决定某个工具调用是否允许执行（ALLOW / DENY / ASK），但不能修改事件内容。Middleware.onActing 和 Middleware.onModelCall 的职责是修改事件内容、记录指标、发出告警。
实践中的推荐做法是：将业务级“全局跨工具”的任务放在 Middleware；将具体“某个工具是否允许执行”的判断交给 Permission。关于 Permission 的详细内容，我们将在第 14 章展开。这里请记住一个原则：Middleware 负责“改”，Permission 负责“卡”。
6.5 完整可运行示例
import io.agentscope.core.RuntimeContext;
import io.agentscope.core.message.UserMessage;
import io.agentscope.core.model.DashScopeChatModel;
import io.agentscope.harness.HarnessAgent;
import ja va.nio.file.Path;
import ja va.util.List;
public class Chapter06_Middleware {
public static void main(String[] args) {
HarnessAgent agent = HarnessAgent.builder()
.name("weather_bot")
.sysPrompt("你是一个中文天气助手，每次回答不超过 50 字。")
.model(DashScopeChatModel.builder()
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.modelName("qwen-plus")
.build())
.workspace(Path.of("./workspace"))
.middleware(new ObservabilityMiddleware())
.build();
agent.call(
List.of(new UserMessage("user", "杭州今天多少度？")),
RuntimeContext.builder()
.sessionId("s-1")
.userId("u-1")
.build()
).block();
}
}
运行后控制台输出大致如下：
[agent] start session=s-1 user=u-1
[reason] 用户问天气
[model] 51 in / 84 out / 612 ms
[agent] end session=s-1
6.6 本章小结
现在，我们来快速回顾本章核心要点：
2.0 推荐使用 Middleware 替代 1.x 的 Hook，抽象更通用、支持 Mono 响应式编程。五大插桩点覆盖 Agent 全生命周期：onAgent / onReasoning / onActing / onModelCall / onSystemPrompt。onModelCall 是 1.x 没有的新节点，尤其适合提示词脱敏、响应缓存、Token 计费、模型熔断等场景。Middleware 与 Permission 互补：Middleware 修改事件 / 埋点，Permission 决定工具调用能否执行。
下一章，我们将把同样的 Middleware 思路推广到“子 Agent”，借助更轻量的 SubagentDeclaration 和 agent_spawn 工具构建层级化系统。
