# 第六章 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"：

```java
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，还能做**计费**：

```java
@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 旧写法（仅供对照，不要再写新代码）

```java
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 新写法

```java
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 的入口和出口

```java
@Override
public Mono<HookEvent> onAgent(MiddlewareContext ctx, HookEvent event) {
    System.out.println(">>> call 开始, session=" + ctx.runtime().getSessionId());
    return Mono.just(event);
}
```

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

### ② `onReasoning` —— 推理阶段

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

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

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

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

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

### ④ `onModelCall`

```java
@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`

```java
@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` 里：

```java
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);
    }
}
```

挂载：

```java
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 完整可运行示例

```java
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();
    }
}
```

运行后控制台类似：

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


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

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

Hook与Middleware — 五类 Middleware 回调点（onModelCall/onActing等）替代 1.x Hook，实现日志埋点与限流。

后端

编程语言

架构设计

本文介绍AI Agent 2.0中的Middleware机制，通过5个关键插桩点（onAgent、onSystemPrompt、onReasoning、onActing、onModelCall）实现日志埋点、限流、token计费等功能。相比1.x的Hook，Middleware支持响应式编程，覆盖模型调用全流程，特别适合实现提示词脱敏、响应缓存等场景，与Permission系统形成互补，提升AI应用的可观测性和安全性。

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

本文介绍AI Agent 2.0中的Middleware机制，通过5个关键插桩点（onAgent、onSystemPrompt、onReasoning、onActing、onModelCall）实现日志埋点、限流、token计费等功能。相比1.x的Hook，Middleware支持响应式编程，覆盖模型调用全流程，特别适...

【AgentScope Java新手村系列】（6）Hook与Middleware-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐