AgentScope Java 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 ← 实际向 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 消耗和费用自动输出——不用在每个 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
适用场景：动态注入时间、组织名称、当前角色身份、计划模式下的摘要。
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 工具构建层级化系统。