Spring AI Alibaba 28｜Hooks 与 Interceptors · 实际示例

示例 1：内容审核 Interceptor

public class ContentModerationInterceptor extends ModelInterceptor {

  private static final List<String> BLOCKED_WORDS =
      List.of("敏感词1", "敏感词2", "敏感词3");

  @Override
  public ModelResponse interceptModel(ModelRequest request, ModelCallHandler handler) {
      // 检查输入
      for (Message msg : request.getMessages()) {
          String content = msg.getText().toLowerCase();
          for (String blocked : BLOCKED_WORDS) {
              if (content.contains(blocked)) {
				return ModelResponse.of(AssistantMessage.builder().content("检测到不适当的内容，请修改您的输入").build());
              }
          }
      }

      // 执行模型调用
      ModelResponse response = handler.call(request);

      // 检查输出
      String output = response.getContent();
      for (String blocked : BLOCKED_WORDS) {
          if (output.contains(blocked)) {
              // 清理输出
              output = output.replaceAll(blocked, "[已过滤]");
              return response.withContent(output);
          }
      }

      return response;
  }

  @Override
  public String getName() {
      return "ContentModerationInterceptor";
  }
}

示例 2：性能监控 – 使用 Interceptor

使用 ModelInterceptor 和 ToolInterceptor 监控模型和工具调用的性能：

// 模型调用性能监控
public class ModelPerformanceInterceptor extends ModelInterceptor {

  @Override
  public ModelResponse interceptModel(ModelRequest request, ModelCallHandler handler) {
      // 请求前记录
      System.out.println("发送请求到模型: " + request.getMessages().size() + " 条消息");

      long startTime = System.currentTimeMillis();

      // 执行实际调用
      ModelResponse response = handler.call(request);

      // 响应后记录
      long duration = System.currentTimeMillis() - startTime;
      System.out.println("模型响应耗时: " + duration + "ms");

      return response;
  }

  @Override
  public String getName() {
      return "ModelPerformanceInterceptor";
  }
}

// 工具调用性能监控
public class ToolPerformanceInterceptor extends ToolInterceptor {

  @Override
  public ToolCallResponse interceptToolCall(ToolCallRequest request, ToolCallHandler handler) {
      String toolName = request.getToolName();
      long startTime = System.currentTimeMillis();

      System.out.println("执行工具: " + toolName);

      try {
          ToolCallResponse response = handler.call(request);

          long duration = System.currentTimeMillis() - startTime;
          System.out.println("工具 " + toolName + " 执行成功 (耗时: " + duration + "ms)");

          return response;
      } catch (Exception e) {
          long duration = System.currentTimeMillis() - startTime;
          System.err.println("工具 " + toolName + " 执行失败 (耗时: " + duration + "ms): " + e.getMessage());

          return ToolCallResponse.of(
              request.getToolCallId(),
              request.getToolName(),
              "工具执行失败: " + e.getMessage()
          );
      }
  }

  @Override
  public String getName() {
      return "ToolPerformanceInterceptor";
  }
}

// 使用示例
ReactAgent agent = ReactAgent.builder()
  .name("monitored_agent")
  .model(chatModel)
  .tools(tools)
  .interceptors(new ModelPerformanceInterceptor())
  .interceptors(new ToolPerformanceInterceptor())
  .build();

示例 3：工具缓存 Interceptor

public class ToolCacheInterceptor extends ToolInterceptor {

  private Map<String, ToolCallResponse> cache = new ConcurrentHashMap<>();
  private final long ttlMs;

  public ToolCacheInterceptor(long ttlMs) {
      this.ttlMs = ttlMs;
  }

  @Override
  public ToolCallResponse interceptToolCall(ToolCallRequest request, ToolCallHandler handler) {
      String cacheKey = generateCacheKey(request);

      // 检查缓存
      ToolCallResponse cached = cache.get(cacheKey);
      if (cached != null && !isExpired(cached)) {
          System.out.println("缓存命中: " + request.getToolName());
          return cached;
      }

      // 执行工具
      ToolCallResponse response = handler.call(request);

      // 缓存结果
      cache.put(cacheKey, response);

      return response;
  }

  @Override
  public String getName() {
      return "ToolCacheInterceptor";
  }

  private String generateCacheKey(ToolCallRequest request) {
      return request.getToolName() + ":" +
             request.getArguments();
  }

  private boolean isExpired(ToolCallResponse response) {
      // 实现 TTL 检查逻辑
      return false;
  }
}

在 Spring AI Alibaba 中，Hook 和 Interceptor 都可以用于干预 Agent 执行：

• Agents 文档 – 了解 ReactAgent 的核心概念
• Messages 文档 – 了解消息类型和使用
• Models 文档 – 了解模型配置和使用

本文整理自 Spring AI Alibaba 官方文档《Hooks 与 Interceptors》：https://java2ai.com/docs/frameworks/agent-framework/tutorials/hooks