Spring AI 1.0.0 M8 Released

Releases | Mark Pollack | April 30, 2025 | ...

After reviewing our API design and deprecations post M7, we determined that several significant changes would become breaking changes in an RC1 release. Therefore, we've introduced this additional milestone to provide developers with a transitional release where deprecated APIs coexist alongside their replacements, enabling a smoother upgrade experience before RC1.

Here are the key changes in this release.

Important Links

Upgrade Notes
You can automate the upgrade process to 1.0.0-M8 using an OpenRewrite recipe. This recipe helps apply many of the necessary code changes for this version. Find the recipe and usage instructions at Arconia Spring AI Migrations.

Breaking Changes

When upgrading from Spring AI 1.0 M7 to 1.0 M8, users who previously registered tool callbacks are encountering breaking changes that cause tool calling functionality to silently fail. This is specifically impacting code that used the deprecated tools() method.

Example

Here's an example of code that worked in M7 but no longer functions as expected in M8:

// Old code in M7 - no longer works correctly in M8
chatClient.prompt("What day is tomorrow?")
    .tools(toolCallback)
    .call()
    .content();

How to Adapt Your Code

To fix this issue when upgrading to M8, you need to update your code to use the new toolCallbacks() method:

// Updated code for M8
chatClient.prompt("What day is tomorrow?")
    .toolCallbacks(toolCallback)
    .call()
    .content();

Why This Change Was Made

The Spring AI team renamed the overloaded tools() methods to improve clarity and prevent ambiguity in method dispatching. The previous API design led to confusion when the Java compiler needed to select between multiple overloaded methods based on parameter types.

Method Mapping from M7 to M8

Here's how the old methods map to their new counterparts:

tools(String... toolNames) → toolNames(String... toolNames)
- Use when referring to tools registered elsewhere (e.g., via @Bean with @Description)
tools(ToolCallback... toolCallbacks) → toolCallbacks(ToolCallback... toolCallbacks)
- Use for inline tool callback registration
tools(List<ToolCallback> toolCallbacks) → toolCallbacks(List<ToolCallback> toolCallbacks)
- Use when you have a collection of tool callbacks
tools(ToolCallbackProvider... toolCallbackProviders) → toolCallbacks(ToolCallbackProvider... toolCallbackProviders)
- Use for objects implementing the ToolCallbackProvider interface
tools(Object... toolObjects) remains unchanged
- Use only for objects with methods annotated with @Tool

Improved Error Handling

In the latest PR (spring-projects/spring-ai#2964), the tools(Object... toolObjects) method will now throw an exception when no @Tool methods are found on the provided objects, rather than silently failing. This helps developers identify migration issues immediately.

Migration Summary

If you're upgrading from M7 to M8:

Replace all calls to .tools(toolCallback) with .toolCallbacks(toolCallback)
Replace all calls to .tools(toolCallbackProvider) with .toolCallbacks(toolCallbackProvider)
Replace all calls to .tools("toolName") with .toolNames("toolName")

These changes will ensure your tool calling functionality continues to work correctly after upgrading to Spring AI 1.0 M8.

New Features

Chat Memory Enhancements

Enhanced Chat Memory Architecture
- Improved ChatMemory API for more flexible conversation history management
- New ChatMemoryRepository interface allows different storage strategies
- Added MessageWindowChatMemory for maintaining a window of messages
- Improved property naming for consistency across implementations
- Support for various storage backends:
  - InMemoryChatMemoryRepository (default)
  - JdbcChatMemoryRepository for relational databases
- Refer to Memory Types and Memory Storage for more details on chat memory configurations.

Template Rendering*

Introduce TemplateRenderer for prompt templating
- A flexible new API for template rendering that provides a consistent interface across different template engines
- Includes the new StTemplateRenderer with support for built-in functions and custom validation options. See how to use it here.
- Integrated directly into the ChatClient for streamlined prompt templating
- Added NoOpTemplateRenderer for cases where templating is not needed
- Related: "Configure TemplateRenderer in ChatClient", "Update docs to mention NoOpTemplateRenderer"

MCP Improvements

Enhanced MCP tool callback configuration
- Added tool callback configuration to MCP client properties
- Support for completion specifications in MCP server
- Added instructions support to MCP server
- Added SSE endpoint parameter to WebFlux and WebMvc transport providers

Prompt Engineering Patterns

Add Prompt Engineering Patterns documentation
- New comprehensive documentation on advanced prompt engineering techniques
- Provides developers with best practices for effective prompt design
- Includes examples and patterns for various use cases

Vector Store Enhancements

Cosmos DB Entra ID support and fixes
- Added Azure Entra ID (formerly Azure AD) authentication for Cosmos DB
- Improves security and authentication options for Azure deployments
Cassandra Vector Store improvements
- Fixed message order in Cassandra chat memory
- Added better error messages and fixed various issues

Deprecations

The important deprecations to take note of are:

Chat Client Enhancements:
- The ChatClient has been updated to ensure user and system prompts are always rendered before advisor execution. This change replaces the AdvisedRequest and AdvisedResponse APIs with ChatClientRequest and ChatClientResponse.
Prompt Templating and Advisors:
- Classes and methods related to prompt creation and advisor customization are deprecated in favor of the builder pattern and the TemplateRenderer interface.
QuestionAnswerAdvisor Deprecations:
- Deprecated constructors and builder methods that relied on a simple userTextAdvise string.
Chat Memory Configuration:
- The spring.ai.chat.memory.jdbc.initialize-schema property is deprecated in favor of spring.ai.chat.memory.repository.jdbc.initialize-schema.
Document Processing:
- The DocumentPostProcessor API replaces deprecated APIs like DocumentCompressor, DocumentRanker, and DocumentSelector.
Chat Memory Deprecations:
- @Deprecated List<Message> get(String conversationId, int lastN); is deprecated in ChatMemory.

Contributors

There were other refactoring, bug fixing, documentation enhancements across the board by a wide range of contributors. If we haven't gotten to your PR yet, we will, please be patient. Thanks to

Spring blog