Migrating Spring AI M7 to M8?

In below article I am providing the detail about the things to be considered if you are migrating. Please go through to know about the new features, deprecations and breaking changes.

Introduction

I am excited to inform about the release of Spring AI 1.0.0 Milestone 8 (M8), a pivotal step in bringing seamless artificial intelligence integration to the Spring ecosystem. As AI continues to transform software development, Spring AI empowers Java developers to incorporate advanced AI models into their applications with the simplicity and robustness that the Spring framework is known for. This milestone introduces powerful new features, refined APIs, and performance enhancements, making it easier than ever to build intelligent, scalable applications. Whether you’re a seasoned Spring developer or exploring AI for the first time, Spring AI 1.0.0 M8 is your gateway to cutting-edge innovation.

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.

New Key Features in Spring AI 1.0.0 M8

Spring AI 1.0.0 M8 delivers a host of improvements designed to streamline AI integration. Here are the highlights:

• Expanded AI Model Support: M8 adds support for additional AI providers, including enhanced compatibility with models like GPT-4o and other open-source alternatives, enabling developers to choose the best model for their use case.
• Improved Prompt Management: A new prompt templating system simplifies the creation and reuse of AI prompts, reducing boilerplate code and improving maintainability.
• Performance Optimizations: Asynchronous API enhancements reduce latency in AI model interactions, ensuring faster response times for real-time applications.
• Spring Boot Integration: Tighter integration with Spring Boot 3.3 improves auto-configuration and dependency management, making setup a breeze.
• Observability Enhancements: New metrics and tracing support for AI interactions allow developers to monitor model performance and troubleshoot issues effectively.

These features reflect community feedback and align with the project’s goal of making AI accessible within the Spring ecosystem.

Lets go thru with bit more detail.

1. 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.

2. 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”

3. 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

4. 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

6. 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

Example To Refresh: Integrating an AI Model

To illustrate the power of Spring AI 1.0.0 M8, here’s a practical example of configuring an AI client in a Spring Boot application to generate text responses using an OpenAI model.

import org.springframework.ai.client.AiClient;
import org.springframework.ai.client.OpenAiClient;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@Configuration
class AiConfig {
    @Bean
    public AiClient aiClient() {
        return new OpenAiClient("your-api-key");
    }
}

@RestController
class AiController {
    @Autowired
    private AiClient aiClient;

    @GetMapping("/generate")
    public String generateResponse(@RequestParam String prompt) {
        return aiClient.generate(prompt);
    }
}

In this example, the AiClient is configured as a Spring bean, and a simple REST endpoint allows users to submit prompts and receive AI-generated responses. With Spring AI’s auto-configuration, you can have this running in minutes. Try sending a prompt like “Write a haiku about spring” to see the AI in action!

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:

1. tools(String... toolNames) → toolNames(String... toolNames)

   • Use when referring to tools registered elsewhere (e.g., via @Bean with @Description)

2. tools(ToolCallback... toolCallbacks) → toolCallbacks(ToolCallback... toolCallbacks)

   • Use for inline tool callback registration

3. tools(List<ToolCallback> toolCallbacks) → toolCallbacks(List<ToolCallback> toolCallbacks)

   • Use when you have a collection of tool callbacks

4. tools(ToolCallbackProvider... toolCallbackProviders) → toolCallbacks(ToolCallbackProvider... toolCallbackProviders)

   • Use for objects implementing the ToolCallbackProvider interface

5. 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:

1. Replace all calls to .tools(toolCallback) with .toolCallbacks(toolCallback)
2. Replace all calls to .tools(toolCallbackProvider) with .toolCallbacks(toolCallbackProvider)
3. 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.

Deprecations

The important deprecations to take note of are:

1. 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.

2. 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.

3. QuestionAnswerAdvisor Deprecations:

   • Deprecated constructors and builder methods that relied on a simple userTextAdvise string.

4. 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.

5. Document Processing:

   • The DocumentPostProcessor API replaces deprecated APIs like DocumentCompressor, DocumentRanker, and DocumentSelector.

6. Chat Memory Deprecations:

   • @Deprecated List<Message> get(String conversationId, int lastN); is deprecated in ChatMemory.

Benefits for Developers

The advancements in Spring AI 1.0.0 M8 offer tangible benefits for developers:

• Simplified Workflows: The prompt templating system and improved auto-configuration reduce the complexity of integrating AI models, allowing developers to focus on building features.
• Scalability: Asynchronous APIs and performance optimizations ensure that AI-powered applications can handle high loads, making Spring AI suitable for enterprise-grade solutions.
• Compatibility: Enhanced integration with Spring Boot and other Spring projects ensures that Spring AI fits seamlessly into existing architectures.
• Observability: Built-in metrics and tracing provide insights into AI model performance, helping developers optimize and debug their applications.

By lowering the barriers to AI adoption, Spring AI 1.0.0 M8 enables developers to create intelligent applications with confidence.

Community Impact and Roadmap

Spring AI 1.0.0 M8 marks a significant milestone in the project’s journey toward a stable 1.0.0 release. By incorporating community feedback, this release refines the developer experience and strengthens the foundation for future innovations. Spring AI aligns with broader trends in software development, where AI is becoming a core component of applications, from chatbots to predictive analytics.

As the Spring team continues to iterate, M8 sets the stage for upcoming milestones that will introduce features like advanced model fine-tuning and deeper integration with Spring Cloud for distributed AI workloads. The project’s open-source nature ensures that developers worldwide can contribute to shaping its future, making Spring AI a community-driven effort.

Call to Action

Ready to explore Spring AI 1.0.0 M8? Download the release from the Spring AI GitHub repository, dive into the official documentation, and experiment with the new features in your projects. We encourage you to share your experiences, report issues, or contribute code to help make Spring AI even better. Join the conversation on the Spring community forums and let us know how you’re using AI in your Spring applications!

Conclusion

Spring AI 1.0.0 M8 is a testament to the Spring ecosystem’s commitment to innovation and developer productivity. With its robust feature set, seamless integration, and community-driven development, this milestone empowers developers to build the next generation of intelligent applications. We’re thrilled about the possibilities that Spring AI unlocks and look forward to seeing how the community leverages M8 to create groundbreaking solutions. Stay tuned for more exciting updates as we march toward Spring AI 1.0.0!