当前位置：首页 > news >正文

Spring AI Alibaba 项目源码学习（十一）-Hook

news 2026/5/12 20:44:49

Hook 机制分析

请关注微信公众号：阿呆-bot

概述

本文档分析 Spring AI Alibaba Agent Framework 中的 Hook（钩子）机制，包括 Hook 接口、AgentHook、ModelHook 的设计、实现原理、执行位置、跳转机制以及具体实现类。

入口类说明

Hook - 钩子接口

Hook 是所有钩子的基接口，定义了钩子的基本能力。

核心职责：

定义钩子名称
定义钩子类型
定义执行位置
定义跳转能力

关键代码：

public interface Hook {String getName();HookType getHookType();List<JumpTo> canJumpTo();/*** Get the positions where this hook should be executed.* By default, this method checks for the @HookPositions annotation on the implementing class.** @return array of HookPosition values*/default HookPosition[] getHookPositions() {HookPositions annotation = this.getClass().getAnnotation(HookPositions.class);if (annotation != null) {return annotation.value();}// Default fallback based on hook typeif (this instanceof AgentHook) {return new HookPosition[]{HookPosition.BEFORE_AGENT, HookPosition.AFTER_AGENT};} else if (this instanceof ModelHook) {return new HookPosition[]{HookPosition.BEFORE_MODEL, HookPosition.AFTER_MODEL};}return new HookPosition[0];}
}

HookPosition - 执行位置

HookPosition 枚举定义了钩子的执行位置。

关键代码：

public enum HookPosition {/*** Hook executes before the agent starts processing*/BEFORE_AGENT,/*** Hook executes after the agent completes processing*/AFTER_AGENT,/*** Hook executes before the model is called*/BEFORE_MODEL,/*** Hook executes after the model returns a response*/AFTER_MODEL
}

AgentHook - Agent 级别钩子

AgentHook 在 Agent 执行前后插入逻辑。

关键代码：

public interface AgentHook extends Hook {default CompletableFuture<Map<String, Object>> beforeAgent(OverAllState state, RunnableConfig config) {return CompletableFuture.completedFuture(Map.of());}default CompletableFuture<Map<String, Object>> afterAgent(OverAllState state, RunnableConfig config) {return CompletableFuture.completedFuture(Map.of());}}

ModelHook - 模型级别钩子

ModelHook 在模型调用前后插入逻辑。

关键代码：

public interface ModelHook extends Hook {default CompletableFuture<Map<String, Object>> beforeModel(OverAllState state, RunnableConfig config) {return CompletableFuture.completedFuture(Map.of());}default CompletableFuture<Map<String, Object>> afterModel(OverAllState state, RunnableConfig config) {return CompletableFuture.completedFuture(Map.of());}@Overridedefault HookType getHookType() {return HookType.MODEL;}
}

JumpTo - 跳转目标

JumpTo 枚举定义了钩子可以跳转的目标。

关键代码：

public enum JumpTo {tool,model,end
}

Hook 集成机制

Graph 集成

Hook 被集成到 ReactAgent 的 Graph 中：

关键代码：

// Add hook nodesfor (Hook hook : hooks) {if (hook instanceof AgentHook agentHook) {graph.addNode(hook.getName() + ".before", agentHook::beforeAgent);graph.addNode(hook.getName() + ".after", agentHook::afterAgent);} else if (hook instanceof ModelHook modelHook) {graph.addNode(hook.getName() + ".beforeModel", modelHook::beforeModel);if (modelHook instanceof HumanInTheLoopHook humanInTheLoopHook) {graph.addNode(hook.getName() + ".afterModel", humanInTheLoopHook);} else {graph.addNode(hook.getName() + ".afterModel", modelHook::afterModel);}}else {throw new UnsupportedOperationException("Unsupported hook type: " + hook.getClass().getName());}}// Categorize hooks by positionList<Hook> beforeAgentHooks = filterHooksByPosition(hooks, HookPosition.BEFORE_AGENT);List<Hook> afterAgentHooks = filterHooksByPosition(hooks, HookPosition.AFTER_AGENT);List<Hook> beforeModelHooks = filterHooksByPosition(hooks, HookPosition.BEFORE_MODEL);List<Hook> afterModelHooks = filterHooksByPosition(hooks, HookPosition.AFTER_MODEL);// Determine node flowString entryNode = determineEntryNode(beforeAgentHooks, beforeModelHooks);String loopEntryNode = determineLoopEntryNode(beforeModelHooks);String loopExitNode = determineLoopExitNode(afterModelHooks);String exitNode = determineExitNode(afterAgentHooks);// Set up edgesgraph.addEdge(START, entryNode);setupHookEdges(graph, beforeAgentHooks, afterAgentHooks, beforeModelHooks, afterModelHooks,entryNode, loopEntryNode, loopExitNode, exitNode, true, this);return graph;

工具注入机制

Hook 可以通过 ToolInjection 接口注入工具：

关键代码：

private void setupToolsForHooks(List<Hook> hooks, AgentToolNode toolNode) {if (hooks == null || hooks.isEmpty() || toolNode == null) {return;}List<ToolCallback> availableTools = toolNode.getToolCallbacks();if (availableTools == null || availableTools.isEmpty()) {return;}for (Hook hook : hooks) {if (hook instanceof ToolInjection) {ToolInjection toolInjection = (ToolInjection) hook;ToolCallback toolToInject = findToolForHook(toolInjection, availableTools);if (toolToInject != null) {toolInjection.injectTool(toolToInject);}}}}

具体实现

ModelCallLimitHook - 模型调用限制钩子

ModelCallLimitHook 限制模型调用次数，防止过度调用。

关键代码：

@HookPositions({HookPosition.BEFORE_MODEL, HookPosition.AFTER_MODEL})
public class ModelCallLimitHook implements ModelHook {private static final String THREAD_COUNT_KEY = "__model_call_limit_thread_count__";private static final String RUN_COUNT_KEY = "__model_call_limit_run_count__";private final Integer threadLimit;private final Integer runLimit;private final ExitBehavior exitBehavior;@Overridepublic CompletableFuture<Map<String, Object>> beforeModel(OverAllState state, RunnableConfig config) {// Read current counts from stateint threadModelCallCount = state.value(THREAD_COUNT_KEY, Integer.class).orElse(0);int runModelCallCount = state.value(RUN_COUNT_KEY, Integer.class).orElse(0);// Check if limits are already exceeded (before making the call)boolean threadLimitExceeded = threadLimit != null && threadModelCallCount >= threadLimit;boolean runLimitExceeded = runLimit != null && runModelCallCount >= runLimit;if (threadLimitExceeded || runLimitExceeded) {if (exitBehavior == ExitBehavior.ERROR) {throw new ModelCallLimitExceededException(...);}else if (exitBehavior == ExitBehavior.END) {// Add message indicating limit was exceeded and jump to endString message = buildLimitExceededMessage(...);List<Message> messages = new ArrayList<>((List<Message>) state.value("messages").orElse(new ArrayList<>()));messages.add(new AssistantMessage(message));Map<String, Object> updates = new HashMap<>();updates.put("messages", messages);return CompletableFuture.completedFuture(updates);}}return CompletableFuture.completedFuture(Map.of());}@Overridepublic CompletableFuture<Map<String, Object>> afterModel(OverAllState state, RunnableConfig config) {// Read current counts from stateint threadModelCallCount = state.value(THREAD_COUNT_KEY, Integer.class).orElse(0);int runModelCallCount = state.value(RUN_COUNT_KEY, Integer.class).orElse(0);// Increment counters after the model callMap<String, Object> updates = new HashMap<>();updates.put(THREAD_COUNT_KEY, threadModelCallCount + 1);updates.put(RUN_COUNT_KEY, runModelCallCount + 1);return CompletableFuture.completedFuture(updates);}

功能：