所有已知实现类:: GenericRAGHook, JsonlTraceExporter, SkillHook, StaticLongTermMemoryHook, StreamingHook

@Deprecated(forRemoval=true, since="2.0.0") public interface Hook

已过时, 待删除: 此 API 元素将从以后的版本中删除。

since 2.0.0. Use MiddlewareBase instead. Middleware exposes onAgent, onReasoning, onActing, onModelCall, and onSystemPrompt hook points and replaces this entire hook system.

Hook interface for monitoring and intercepting agent execution.

All agent execution events are delivered through a single onEvent(HookEvent) method. This unified event model provides a clean, type-safe way to intercept and modify agent behavior.

Hook Priority: Hooks are executed in priority order (lower value = higher priority). Default priority is 100. Hooks with the same priority execute in registration order.

Event Modifiability: Whether an event is modifiable is indicated by the presence of setter methods:

Events with setters (e.g., PreReasoningEvent.setInputMessages(java.util.List<io.agentscope.core.message.Msg>)) allow modification
Events without setters are notification-only

Example Usage:


 // Basic hook with default priority
 Hook loggingHook = new Hook() {
     @Override
     public <T extends HookEvent> Mono<T> onEvent(T event) {
         return switch (event) {
             case PreReasoningEvent e -> {
                 System.out.println("Reasoning with model: " + e.getModelName());
                 yield Mono.just(e);
             }
             case ReasoningChunkEvent e -> {
                 // Display streaming output
                 System.out.print(extractText(e.getIncrementalChunk()));
                 yield Mono.just(e);
             }
             default -> Mono.just(event);
         };
     }
 };

 // High priority hook (executes first)
 Hook authHook = new Hook() {
     @Override
     public int priority() {
         return 10;  // High priority
     }

     @Override
     public <T extends HookEvent> Mono<T> onEvent(T event) {
         return switch (event) {
             case PreActingEvent e -> {
                 // Inject auth token before any other hook
                 ToolUseBlock toolUse = e.getToolUse();
                 // ... add auth
                 e.setToolUse(toolUse);
                 yield Mono.just(e);
             }
             default -> Mono.just(event);
         };
     }
 };

 // Modifying events
 Hook hintInjector = new Hook() {
     @Override
     public <T extends HookEvent> Mono<T> onEvent(T event) {
         return switch (event) {
             case PreReasoningEvent e -> {
                 // Modify messages before LLM reasoning
                 List<Msg> msgs = new ArrayList<>(e.getInputMessages());
                 msgs.add(0, Msg.builder()
                         .role(MsgRole.SYSTEM)
                         .content(new TextBlock("Think step by step"))
                         .build());
                 e.setInputMessages(msgs);
                 yield Mono.just(e);
             }
             case PostActingEvent e -> {
                 // Modify tool result
                 ToolResultBlock result = e.getToolResult();
                 // ... process result
                 e.setToolResult(result);
                 yield Mono.just(e);
             }
             default -> Mono.just(event);
         };
     }
 };

另请参阅:

方法概要

修饰符和类型

方法

说明

<T extends HookEvent> reactor.core.publisher.Mono<T>

onEvent(T event)

已过时, 待删除: 此 API 元素将从以后的版本中删除。

Handle a hook event.

default int

priority()

已过时, 待删除: 此 API 元素将从以后的版本中删除。

The priority of this hook (lower value = higher priority).

default List<Object>

tools()

已过时, 待删除: 此 API 元素将从以后的版本中删除。

Optional tools installed together with this hook.

方法详细资料
- onEvent
  
  <T extends HookEvent> reactor.core.publisher.Mono<T> onEvent(T event)
  
  已过时, 待删除: 此 API 元素将从以后的版本中删除。
  Handle a hook event.
  This method is called for all agent execution events. Use pattern matching to handle specific event types.
  Modifiable Events: For events with setters, you can modify the context and the changes will affect agent execution:
  
  PreReasoningEvent - Modify messages before LLM reasoning
  
  PostReasoningEvent - Modify reasoning results
  
  PreActingEvent - Modify tool parameters before execution
  
  PostActingEvent - Modify tool results
  
  PreCallEvent - Modify messages before agent starts
  
  PostCallEvent - Modify final agent response
  
  Notification Events: Events without setters are read-only:
  
  ReasoningChunkEvent - Streaming reasoning chunks
  
  ActingChunkEvent - Streaming tool execution chunks
  
  ErrorEvent - Errors during execution
  类型参数:
  
  T - The concrete event type
  
  参数:
  
  event - The hook event
  
  返回:
  
  Mono containing the potentially modified event
- tools
  
  default List<Object> tools()
  
  已过时, 待删除: 此 API 元素将从以后的版本中删除。
  
  Optional tools installed together with this hook.
  During ReActAgent.Builder.build(), the framework copies the builder Toolkit and then registers each non-null element from every hook's tools() list on the agent-local copy using Toolkit.registerTool(Object).
  Return AgentTool instances and/or objects that declare @Tool methods. The default implementation returns an empty list so existing hooks need no change.
  If this method returns null, it is treated as an empty list.
  
  返回:
  
  tool instances to register for this hook (may be immutable)
- priority
  
  default int priority()
  
  已过时, 待删除: 此 API 元素将从以后的版本中删除。
  The priority of this hook (lower value = higher priority).
  Hooks are executed in ascending priority order. Hooks with the same priority execute in their registration order.
  Common Priority Ranges:
  
  0-50: Critical system hooks (auth, security)
  
  51-100: High priority hooks (validation, preprocessing)
  
  101-500: Normal priority hooks (business logic)
  
  501-1000: Low priority hooks (logging, metrics)
  返回:
  
  The priority value (default: 100)

接口 Hook

方法概要

方法详细资料

onEvent

tools

priority