【AgentScope Java新手村系列】（6）Hook与Middleware

第六章 Hook 与 Middleware：五类插桩点，替代 1.x Hook，覆盖模型调用与系统提示

"我们想给 agent 加上日志埋点、限流、token 计费、敏感词过滤......这些需求有一个共同点：在 agent 干活的特定时刻 插一段自己的代码。1.x 用 Hook 实现，2.0 用更通用的 Middleware。"

6.0 Middleware 是什么？

Middleware = 一段可以在 agent 执行流程的特定节点被自动调用的代码。

把它类比成 Web 框架的过滤器（Filter / Interceptor）：

复制代码

HTTP 请求                                                                 Agent 执行
─────────                                                                 ─────────
客户端 → [Filter] → [Filter] → Controller         用户提问 → [MW] → [MW] → LLM 推理 → 工具调用
                                                                  ↑ 你可以在这 5 个节点插代码

每次 agent.call() 的执行经过 5 个阶段，每个阶段前后都可以插入 Middleware：

复制代码

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<HookEvent> 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<ModelCallResponse> 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() 后面手动算。

Middleware 的核心价值：把"每次都要做的事"抽出来，写一次，挂一次，自动生效。

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<HookEvent> 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<T>，方便链式组合。
旧版只能接 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<HookEvent> onAgent(MiddlewareContext ctx, HookEvent event) {
    System.out.println(">>> call 开始, session=" + ctx.runtime().getSessionId());
    return Mono.just(event);
}

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

② `onReasoning` ------ 推理阶段

复制代码

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

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

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

复制代码

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

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

④ `onModelCall` ------ 实际打 LLM API 的前后 ⭐新增

复制代码

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

@Override
public Mono<ModelCallResponse> 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<String> onSystemPrompt(MiddlewareContext ctx, String sysPrompt) {
    return Mono.just(sysPrompt + "\n\n[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<HookEvent> 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<HookEvent> onReasoning(MiddlewareContext ctx, HookEvent event) {
        if (event.getMessage() != null) {
            System.out.println("[reason] " + event.getMessage().getTextContent());
        }
        return Mono.just(event);
    }

    @Override
    public Mono<ModelCallRequest> onModelCall(MiddlewareContext ctx, ModelCallRequest req) {
        long t0 = System.nanoTime();
        ctx.putAttachment("model_t0", t0);   // 把计时写到 ctx，让对应 onModelCall 回调能读到
        return Mono.just(req);
    }

    @Override
    public Mono<ModelCallResponse> 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。详见第 14 章。

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 java.nio.file.Path;
import java.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 工具构建层级化系统。

【AgentScope Java新手村系列】（6）Hook与Middleware

第六章 Hook 与 Middleware：五类插桩点，替代 1.x Hook，覆盖模型调用与系统提示

6.0 Middleware 是什么？

6.1 与 1.x Hook 的关系

1.x 旧写法（仅供对照，不要再写新代码）

2.0 新写法

6.2 五个插桩点速查

① onAgent ------ 整轮 call 的入口和出口

② onReasoning ------ 推理阶段

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

④ onModelCall ------ 实际打 LLM API 的前后 ⭐新增

⑤ onSystemPrompt ------ 系统提示词阶段 ⭐新增

6.3 一个完整的"生产可观测"中间件

6.4 与 Permission 系统的协作

6.5 完整可运行示例

6.6 本章小结

① `onAgent` ------ 整轮 call 的入口和出口

② `onReasoning` ------ 推理阶段

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

④ `onModelCall` ------ 实际打 LLM API 的前后 ⭐新增

⑤ `onSystemPrompt` ------ 系统提示词阶段 ⭐新增