Spring AI Agentic Patterns (Part 7): Session API

原文地址： https://spring.io/blog/2026/04/15/spring-ai-session-management

系列： Spring AI Agentic Patterns · Part 7/7

作者： Christian Tzolov · 2026-04-15

关键词： Session API、事件溯源、上下文压缩、多智能体分支

Spring AI Agentic Patterns (Part 7): Session API

Event-Sourced Short-Term Memory with Context Compaction — 事件溯源的短期记忆与上下文压缩

Spring AI Agentic Patterns 系列的第 7 篇完善了记忆的画面。在涵盖了 https://spring.io/blog/2026/01/13/spring-ai-generic-agent-skills、https://spring.io/blog/2026/01/16/spring-ai-ask-user-question-tool、https://spring.io/blog/2026/01/20/spring-ai-agentic-patterns-3-todowrite/、https://spring.io/blog/2026/01/27/spring-ai-agentic-patterns-4-task-subagents、https://spring.io/blog/2026/01/29/spring-ai-agentic-patterns-a2a-integration 以及用于长期跨会话记忆的 https://spring.io/blog/2026/04/07/spring-ai-agentic-patterns-6-memory-tools 之后，我们现在添加补充的短期层：Spring AI Session。

路线图：在 https://github.com/spring-ai-community/spring-ai-session 中孵化；目标是 Spring AI 2.1（2026 年 11 月），届时 ChatMemory 将被弃用并被它取代。

ChatMemory 以无轮次安全性、无事件身份、无多智能体支持、无丢弃记录的方式淘汰最旧的消息。Spring AI Session 以事件溯源的日志、可插拔的压缩策略、分支隔离、关键字可搜索的回忆存储取代了它。

🚀 想直接上手？跳转到 Getting Started 部分。

Session API 架构

Session 与 SessionEvent

Session：是一个不可变的、仅含元数据的值对象——它保存会话 ID、用户 ID、TTL 和任意元数据。事件日志单独存放在仓库中，按需获取。
SessionEvent：包装一个 Spring AI Message，并添加了 Message故意省略的内容：UUID、sessionId、时间戳、可选的用于多智能体层级的分支标签，以及框架标志如 METADATA_SYNTHETIC。

轮次（Turns）

轮次是对话的原子单位：一个 UserMessage 加上所有后续事件——助手回复、工具调用、工具结果——直到下一个 UserMessage。所有压缩策略都在轮次粒度上运作，因此保留的窗口总是从 USER 消息开始。模型永远不会看到孤立的工具结果或拆分的交换。

上下文压缩（Context Compaction）

压缩通过在保留连贯性的同时减少事件历史来适配上下文窗口。它由两个可组合的抽象驱动：触发器（triggers） 和 策略（strategies）。

触发器（Triggers）

策略（Strategies）

策略	LLM 调用？	最适合
SlidingWindowCompactionStrategy	否	成本敏感、短期上下文
TurnWindowCompactionStrategy	否	轮次结构化的对话
TokenCountCompactionStrategy	否	严格的上下文窗口限制
RecursiveSummarizationCompactionStrategy	是	长时间运行、上下文丰富的会话

前三种策略保留一个逐字的事件后缀（按消息计数、轮次计数或 token 预算）。所有三种都将切割点对齐到最近的轮次边界——绝不会保留部分轮次。

递归摘要（Recursive Summarization） 是最强大的：它使用 LLM 来摘要正在归档的事件，并将结果存储为一个合成的 user + assistant 轮次。每次后续的压缩过程都建立在前一次摘要的基础上——创建一个滚动的压缩历史，它永远不必从零开始：

注意：触发器和策略必须始终一起配置——只设置一个而另一个不设置会在构建时抛出 IllegalArgumentException。

ChatClient 集成

SessionMemoryAdvisor 将会话管理以透明方式接入到 ChatClient 流水线。在每个请求中，它加载历史、将其前置到提示中、追加新的用户和助手消息，并在触发器触发时运行压缩——所有这些都无需应用中的任何手动代码。

通过 advisor 上下文在调用时传递会话 ID：

如果给定 ID 不存在会话，advisor 会自动创建一个。

多智能体分支隔离

当协调器向并行的子智能体扇出时，所有智能体可以共享同一个 Session——但每个智能体只能看到自己的事件加上其祖先的事件。SessionEvent.branch 是一个点分隔的路径，记录产生事件的智能体在层级中的位置：

branch = null 的事件是根级别的——对每个智能体可见。通过传递 EventFilter.forBranch() 在 advisor 内部自动应用隔离：

RecursiveSummarizationCompactionStrategy 的合成摘要事件总是带有 branch = null，因此压缩摘要对会话中的每个智能体都可见。

回忆存储（Recall Storage）

压缩提升了提示效率，但较旧的事件会从活动上下文窗口中移除。SessionEventTools 实现了 MemGPT Recall Storage 模式：完整的逐字事件日志始终被保留并可按关键字搜索，即使在压缩已将其从提示中剪除之后。

conversation_search 工具由 Spring AI 自动发现。当模型需要回忆先前的交换时，它使用关键字和可选的页索引调用该工具；结果以按时间顺序排列的 JSON 返回。

JDBC 持久化

spring-ai-session-jdbc 在两个表（AI_SESSION 和 AI_SESSION_EVENT，一个仅追加的事件日志）中存储会话数据，支持 PostgreSQL、MySQL、MariaDB 和 H2。Spring Boot starter 自动配置一切：

对于 PostgreSQL 或 MySQL，启用 schema 初始化：

无需额外的 bean 声明。

快速上手

要求：Java 17+、Spring AI 2.0.0-M4+、Spring Boot 4.0.2+

Step 1. 导入 BOM

Step 2. 添加一个 starter —— 生产环境使用 JDBC，或单独使用 spring-ai-session-management 进行内存开发

Step 3. 接入 advisor 并使用它

从 ChatMemory 到 Session API

Session API 旨在取代 ChatMemory，成为 Spring AI 的主要对话持久化抽象：

维度	ChatMemory → Spring AI Session
存储单元	消息（扁平列表）→ SessionEvent（不可变、有时间戳、有标识）
压缩	淘汰最旧的消息 → 四种可插拔策略，包括 LLM 摘要
轮次安全性	未强制 → 所有策略都对齐到轮次边界
多智能体	不支持 → 使用点分隔标签的分支隔离
回忆搜索	不可用 → 通过 SessionEventTools 的 conversation_search 工具
并发性	取决于实现 → 所有实现中都采用乐观 CAS 写入

结论

Spring AI Session 为 Spring AI 生态系统带来了一个结构化的、事件溯源的短期记忆层——具有轮次安全的压缩、LLM 驱动的摘要、多智能体分支隔离以及关键字可搜索的回忆存储。

与 https://spring.io/blog/2026/04/07/spring-ai-agentic-patterns-6-memory-tools 的 AutoMemoryTools 配对，你现在拥有了一个完整智能体记忆栈的两半：一个持久的长期层，用于在会话之外存活的事实；以及一个连贯的短期层，用于活动对话。

系列导航：

Part 1：https://spring.io/blog/2026/01/13/spring-ai-generic-agent-skills — 模块化、可复用的能力
Part 2：https://spring.io/blog/2026/01/16/spring-ai-ask-user-question-tool — 交互式工作流
Part 3：https://spring.io/blog/2026/01/20/spring-ai-agentic-patterns-3-todowrite/ — 结构化规划
Part 4：https://spring.io/blog/2026/01/27/spring-ai-agentic-patterns-4-task-subagents — 分层智能体架构
Part 5：https://spring.io/blog/2026/01/29/spring-ai-agentic-patterns-a2a-integration — Agent2Agent 协议
Part 6：https://spring.io/blog/2026/04/07/spring-ai-agentic-patterns-6-memory-tools — 跨会话长期记忆

资源

GitHub：https://github.com/spring-ai-community/spring-ai-session
文档：https://spring-ai-community.github.io/spring-ai-session/
Spring AI 参考：https://docs.spring.io/spring-ai/reference/
ChatMemory API（当前）：https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/chat-memory.html