Spring AI Alibaba 23｜Hooks 与 Interceptors · 自定义 Hooks 和 Interceptors：MessagesModelHook

MessagesModelHook 是一个专门用于操作消息列表的 Hook，使用更简单，更推荐。它直接接收和返回消息列表，无需处理复杂的 OverAllState。

适用场景：

• 消息修剪、过滤或转换；
• 添加系统提示或上下文消息；
• 消息压缩和摘要；
• 简单的消息操作需求。

import com.alibaba.cloud.ai.graph.agent.hook.messages.MessagesModelHook;
import com.alibaba.cloud.ai.graph.agent.hook.messages.AgentCommand;
import com.alibaba.cloud.ai.graph.agent.hook.messages.UpdatePolicy;
import com.alibaba.cloud.ai.graph.agent.hook.HookPosition;
import com.alibaba.cloud.ai.graph.agent.hook.HookPositions;
import com.alibaba.cloud.ai.graph.RunnableConfig;
import org.springframework.ai.chat.messages.Message;

@HookPositions({HookPosition.BEFORE_MODEL})
public class MessageTrimmingHook extends MessagesModelHook {
  private static final int MAX_MESSAGES = 10;

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

  @Override
  public AgentCommand beforeModel(List<Message> previousMessages, RunnableConfig config) {
      // 如果消息数量超过限制，只保留最后 MAX_MESSAGES 条消息
      if (previousMessages.size() > MAX_MESSAGES) {
          List<Message> trimmedMessages = previousMessages.subList(
              previousMessages.size() - MAX_MESSAGES,
              previousMessages.size()
          );
          // 使用 REPLACE 策略替换所有消息
          return new AgentCommand(trimmedMessages, UpdatePolicy.REPLACE);
      }
      // 如果消息数量未超过限制，返回原始消息（不进行修改）
      return new AgentCommand(previousMessages);
  }
}

AgentCommand 和 UpdatePolicy：

MessagesModelHook 通过 AgentCommand 返回操作结果：

• REPLACE 策略：替换所有现有消息；
• APPEND 策略：将新消息追加到现有消息列表。

import com.alibaba.cloud.ai.graph.agent.hook.messages.MessagesModelHook;
import com.alibaba.cloud.ai.graph.agent.hook.messages.AgentCommand;
import com.alibaba.cloud.ai.graph.agent.hook.messages.UpdatePolicy;
import com.alibaba.cloud.ai.graph.agent.hook.HookPosition;
import com.alibaba.cloud.ai.graph.agent.hook.HookPositions;
import com.alibaba.cloud.ai.graph.RunnableConfig;
import org.springframework.ai.chat.messages.Message;
import org.springframework.ai.chat.messages.SystemMessage;
import org.springframework.ai.chat.messages.UserMessage;
import java.util.ArrayList;
import java.util.List;

@HookPositions({HookPosition.BEFORE_MODEL})
public class ContextEnhancementHook extends MessagesModelHook {

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

  @Override
  public AgentCommand beforeModel(List<Message> previousMessages, RunnableConfig config) {
      // 示例 1: 使用 REPLACE 策略替换所有消息
      List<Message> newMessages = new ArrayList<>();
      newMessages.add(new SystemMessage("你是一个专业的助手"));
      newMessages.addAll(previousMessages);
      return new AgentCommand(newMessages, UpdatePolicy.REPLACE);

      // 示例 2: 使用 APPEND 策略追加消息
      // List<Message> additionalMessages = List.of(
      //     new UserMessage("请记住：保持友好和专业")
      // );
      // return new AgentCommand(additionalMessages, UpdatePolicy.APPEND);
  }
}

支持跳转控制：

MessagesModelHook 也支持通过 JumpTo 实现提前退出：

import com.alibaba.cloud.ai.graph.agent.hook.JumpTo;
import com.alibaba.cloud.ai.graph.agent.hook.messages.MessagesModelHook;
import com.alibaba.cloud.ai.graph.agent.hook.messages.AgentCommand;
import com.alibaba.cloud.ai.graph.agent.hook.HookPosition;
import com.alibaba.cloud.ai.graph.agent.hook.HookPositions;
import com.alibaba.cloud.ai.graph.RunnableConfig;
import org.springframework.ai.chat.messages.Message;
import java.util.List;

@HookPositions({HookPosition.BEFORE_MODEL})
public class EarlyExitHook extends MessagesModelHook {

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

  @Override
  public List<JumpTo> canJumpTo() {
      return List.of(JumpTo.end);
  }

  @Override
  public AgentCommand beforeModel(List<Message> previousMessages, RunnableConfig config) {
      // 检查某些条件，如果满足则提前退出
      if (shouldExit(previousMessages)) {
          return new AgentCommand(JumpTo.end, previousMessages);
      }
      return new AgentCommand(previousMessages);
  }

  private boolean shouldExit(List<Message> messages) {
      // 实现你的退出逻辑
      return false;
  }
}

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