MiddlewareBase
public interface MiddlewareBaseio/agentscope/core/middleware/MiddlewareBase.java:59–161MiddlewareBase 以 Flux 链的方式包装智能体执行，提供 onAgent、onReasoning、onActing、onModelCall 与 onSystemPrompt 等钩子。order 控制多个中间件的嵌套顺序。位于 io.agentscope.core.middleware 包。核心成员包括 order、onAgent、onReasoning、onActing、onModelCall、onSystemPrompt。
Middleware provides interception mechanisms at 5 key execution points in the Agent lifecycle.
Onion Pattern (4 hooks — wrap execution with before/after logic):
-
#onAgent— intercepts the entire agent invocation -
#onReasoning— intercepts the reasoning/model-call phase -
#onActing— intercepts individual tool-call execution -
#onModelCall— intercepts the raw model API call
Transformer/Pipeline Pattern (1 hook — sequential transform):
#onSystemPrompt— transforms the system prompt string
Each hook has a default implementation that delegates directly to
next, so subclasses only need to override the hooks they care about.
Example:
`MiddlewareBase logging = new MiddlewareBase() {
@Override
public Flux<AgentEvent> onReasoning(
Agent agent, RuntimeContext ctx, ReasoningInput input,
Function<ReasoningInput, Flux<AgentEvent>> next) {
System.out.println("Before reasoning, session=" + ctx.getSessionId());
return next.apply(input)
.doOnComplete(() -> System.out.println("After reasoning"));
}
};
`
核心精讲Deep dive
MiddlewareBase：响应式钩子MiddlewareBase: reactive hooks
MiddlewareBase 以 Flux 链的方式包装智能体执行，提供 onAgent、onReasoning、onActing、onModelCall 与 onSystemPrompt 等钩子。order 控制多个中间件的嵌套顺序。
MiddlewareBase wraps agent execution as a Flux chain, exposing hooks such as onAgent, onReasoning, onActing, onModelCall and onSystemPrompt. order controls how multiple middlewares nest.
- 每个钩子接收 agent、RuntimeContext、输入对象与 next 函数。Every hook receives the agent, RuntimeContext, an input object and the next function.
- 调用 next.apply(input) 才会继续；可在此记录、改写或短路。Calling next.apply(input) continues the chain; here you can observe, rewrite or short-circuit.
- order 越小越靠外层，适合把日志与追踪放在最外层。A smaller order means an outer layer, which suits logging and tracing.
记录模型调用Log model calls
import io.agentscope.core.agent.Agent;
import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.event.AgentEvent;
import io.agentscope.core.middleware.MiddlewareBase;
import io.agentscope.core.middleware.ModelCallInput;
import java.util.function.Function;
import reactor.core.publisher.Flux;
public final class LoggingMiddleware implements MiddlewareBase {
@Override
public Flux<AgentEvent> onModelCall(
Agent agent,
RuntimeContext ctx,
ModelCallInput input,
Function<ModelCallInput, Flux<AgentEvent>> next) {
System.out.println("model call for " + agent.getName());
return next.apply(input);
}
}方法摘要Method Summary
方法详情Method Detail
order
default public int order()返回此中间件's 执行顺序。
Returns this middleware's execution order.
intio/agentscope/core/middleware/MiddlewareBase.java:71–73onAgent
default public Flux<AgentEvent> onAgent(Agent agent, RuntimeContext ctx, AgentInput input, Function<AgentInput, Flux<AgentEvent>> next)处理智能体事件。
Intercept the entire agent invocation.
| 名称Name | 类型Type | 说明Description |
|---|---|---|
agent | Agent | 智能体实例。the agent instance |
ctx | RuntimeContext | 运行时上下文（类型 `RuntimeContext`）。per-call runtime context (session, user, attributes) |
input | AgentInput | 输入消息（类型 `AgentInput`）。agent input (messages) |
next | Function<AgentInput, Flux<AgentEvent>> | 下一个（类型 `Function >`）。calls the next middleware or the core agent logic |
Flux<AgentEvent>io/agentscope/core/middleware/MiddlewareBase.java:84–90onReasoning
default public Flux<AgentEvent> onReasoning(Agent agent, RuntimeContext ctx, ReasoningInput input, Function<ReasoningInput, Flux<AgentEvent>> next)处理推理事件。
Intercept the reasoning phase (LLM call + streaming output parsing).
| 名称Name | 类型Type | 说明Description |
|---|---|---|
agent | Agent | 智能体实例。the agent instance |
ctx | RuntimeContext | 运行时上下文（类型 `RuntimeContext`）。per-call runtime context (session, user, attributes) |
input | ReasoningInput | 输入消息（类型 `ReasoningInput`）。reasoning input (messages, tools, options) |
next | Function<ReasoningInput, Flux<AgentEvent>> | 下一个（类型 `Function >`）。calls the next middleware or the core reasoning logic |
Flux<AgentEvent>io/agentscope/core/middleware/MiddlewareBase.java:101–107onActing
default public Flux<AgentEvent> onActing(Agent agent, RuntimeContext ctx, ActingInput input, Function<ActingInput, Flux<AgentEvent>> next)处理执行事件。
Intercept the tool-call execution phase.
| 名称Name | 类型Type | 说明Description |
|---|---|---|
agent | Agent | 智能体实例。the agent instance |
ctx | RuntimeContext | 运行时上下文（类型 `RuntimeContext`）。per-call runtime context (session, user, attributes) |
input | ActingInput | 输入消息（类型 `ActingInput`）。acting input (the tool calls) |
next | Function<ActingInput, Flux<AgentEvent>> | 下一个（类型 `Function >`）。calls the next middleware or the core acting logic |
Flux<AgentEvent>io/agentscope/core/middleware/MiddlewareBase.java:118–124onModelCall
default public Flux<AgentEvent> onModelCall(Agent agent, RuntimeContext ctx, ModelCallInput input, Function<ModelCallInput, Flux<AgentEvent>> next)处理模型调用事件。
Intercept the raw model API call.
| 名称Name | 类型Type | 说明Description |
|---|---|---|
agent | Agent | 当前智能体。the agent instance |
ctx | RuntimeContext | 本次调用上下文。per-call runtime context (session, user, attributes) |
input | ModelCallInput | 模型调用输入。model-call input (messages, tools, options, model) |
next | Function<ModelCallInput, Flux<AgentEvent>> | 继续执行后续中间件与模型调用。calls the next middleware or the actual model invocation |
Flux<AgentEvent>io/agentscope/core/middleware/MiddlewareBase.java:139–145onSystemPrompt
default public Mono<String> onSystemPrompt(Agent agent, RuntimeContext ctx, String currentPrompt)处理系统提示词事件。
Transform the system prompt string (pipeline pattern).
| 名称Name | 类型Type | 说明Description |
|---|---|---|
agent | Agent | 智能体实例。the agent instance |
ctx | RuntimeContext | 运行时上下文（类型 `RuntimeContext`）。per-call runtime context (session, user, attributes) |
currentPrompt | String | 当前系统提示词。the current system prompt |
Mono<String>io/agentscope/core/middleware/MiddlewareBase.java:158–160