程序包 io.agentscope.core.hook

接口 Hook

所有已知实现类:

GenericRAGHook, GracefulShutdownHook, JsonlTraceExporter, PendingToolRecoveryHook, SkillHook, StaticLongTermMemoryHook, TTSHook

public interface Hook

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

另请参阅:

• HookEvent
• HookEventType

方法概要

修饰符和类型	方法	说明
<T extends HookEvent> reactor.core.publisher.Mono<T>	onEvent(T event)	Handle a hook event.
default int	priority()	The priority of this hook (lower value = higher priority).

方法详细资料

onEvent

<T extends HookEvent>
reactor.core.publisher.Mono<T> onEvent(T event)

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

priority

default int priority()

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)