【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 onAgent(MiddlewareContext ctx, HookEvent event) { System.out.println(">>> agent 被调用了, session=" + ctx.runtime().getSessionId()); return Mono.just(event); } }

挂到 Agent 上之后，每次 agent.call() 都会自动打印这行日志——不需要在每个调用点手写 System.out.println。

再看一个更实用的场景：每次调 LLM 之前打印消耗了多少 token，顺便算个账。

@Override public Mono onModelCall(MiddlewareContext ctx, ModelCallResponse resp) { long tokens = resp.getUsage().totalTokens(); long cost = tokens * 2 / 1000; // 假设 2 元/千 token System.out.printf("本轮消耗 %d token，费用约 %d 分%n", tokens, cost); return Mono.just(resp); }

挂上之后，所有 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 onReasoning(MiddlewareContext ctx, HookEvent event) { System.out.println("[reasoning] " + event.getMessage().getTextContent()); return Mono.just(event); } } HarnessAgent agent = HarnessAgent.builder() ... .middleware(new LoggingMiddleware()) .build();

对比一下就能看出两个关键变化：

旧 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 onAgent(MiddlewareContext ctx, HookEvent event) { System.out.println(">>> call 开始, session=" + ctx.runtime().getSessionId()); return Mono.just(event); }

用途：日志开头、整轮计时、traceId 注入、整体限流。

② onReasoning —— 推理阶段

@Override public Mono onReasoning(MiddlewareContext ctx, HookEvent event) { System.out.println("[reason] " + event.getMessage().getTextContent()); return Mono.just(event); }

用途：思维链审计、敏感词检测、reasoning 阶段限流。

③ onActing —— 行动阶段（工具调用之前）

@Override public Mono onActing(MiddlewareContext ctx, HookEvent event) { System.out.println("[act] tools=" + event.getToolCalls().size()); return Mono.just(event); }

用途：判断 LLM 想调什么工具、决定是否要先把这次调用转人工。

④ onModelCall

@Override public Mono onModelCall(MiddlewareContext ctx, ModelCallRequest req) { return Mono.fromSupplier(() -> { System.out.println("[model] in=" + req.getMessages().size() + " msgs"); return req; }); } @Override public Mono onModelCall(MiddlewareContext ctx, ModelCallResponse resp) { return Mono.fromSupplier(() -> { System.out.println("[model] out tokens=" + resp.getUsage().totalTokens()); return resp; }); }

onModelCall 是 1.x Hook 没有的位点，专门为"模型调用前后"留出来——非常适合做：

提示词脱敏（脱敏后再发到模型）、模型响应缓存（命中后直接返回短路 ModelCallResponse）、token 计数 / 限流 / 计费埋点、模型熔断（连续失败 N 次后直接抛错）。

⑤ onSystemPrompt

@Override public Mono onSystemPrompt(MiddlewareContext ctx, String sysPrompt) { return Mono.just(sysPrompt + "[organization] 当前时间: 2026-06-07"); }

用途：动态注入时间、组织名、当前角色身份、计划模式下的 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 onAgent(MiddlewareContext ctx, HookEvent event) { RuntimeContext rt = ctx.runtime(); System.out.printf("[agent] start session=%s user=%s%n", rt.getSessionId(), rt.getUserId()); return Mono.just(event); } @Override public Mono onReasoning(MiddlewareContext ctx, HookEvent event) { if (event.getMessage() != null) { System.out.println("[reason] " + event.getMessage().getTextContent()); } return Mono.just(event); } @Override public Mono onModelCall(MiddlewareContext ctx, ModelCallRequest req) { long t0 = System.nanoTime(); ctx.putAttachment("model_t0", t0); // 把计时写到 ctx，让对应 onModelCall 回调能读到 return Mono.just(req); } @Override public Mono onModelCall(MiddlewareContext ctx, ModelCallResponse resp) { long t0 = (long) ctx.getAttachmentOrDefault("model_t0", 0L); long elapsed = (System.nanoTime() - t0) / 1_000_000; System.out.printf("[model] %d in / %d out / %d ms%n", resp.getUsage().inputTokens(), resp.getUsage().outputTokens(), elapsed); return Mono.just(resp); } }

挂载方式也很简单：

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 工具构建层级化系统。