【AgentScope Java新手村系列】（6）Hook与Middleware
第六章 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 ← 真正打 HTTP 给 LLM API 之前/之后（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
用途：思维链审计、敏感词检测、reasoning 阶段限流。
③ 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 的功能是通过规则 / mode 决定某个工具调用能不能跑（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 工具构建层级化系统。
