Spring AI 2.0.0-M6 Release Notes

🎯 Highlights

This release includes 7 new features, 18 bug fixes, 5 documentation improvements, 30 other improvements.

⏪ Breaking Changes

• PromptChatMemoryAdvisor has been removed. Chat memory advisors now require an explicit conversation ID to be provided, improving predictability and eliminating ambiguous implicit state management. Applications using PromptChatMemoryAdvisor or relying on implicit conversation IDs must be updated. c3c7c86, 59ab752
• The class OpenAiConnectionProperties has been renamed to OpenAiCommonProperties to better reflect its purpose as shared configuration across OpenAI integrations. 01400e2
• OpenAI properties classes (e.g., OpenAiChatProperties, OpenAiEmbeddingProperties) no longer extend AbstractOpenAiOptions. This changes the class hierarchy and may affect code that relied on the options being available directly on properties classes. 7b2b436
• Setter methods have been removed from OpenAI options classes in favor of the builder pattern. Code that called setters directly on options (e.g., OpenAiChatOptions) will need to be updated to use the builder API. f119b2f
• The @NestedConfigurationProperty annotations have been removed from OpenAI options fields. This may affect IDE auto-completion and Spring Boot configuration metadata for nested OpenAI properties. 5f82cdd
• The SAP HANA DB vector store module has been removed from Spring AI. Users relying on this integration must migrate to an alternative vector store provider. 35b659e
• The Infinispan vector store module has been removed from Spring AI. Users relying on this integration must migrate to an alternative vector store provider. 195d418
• Mutable setter methods have been removed from Mistral AI options classes. Configuration must now be done through constructors or builders, enforcing immutability. 06015b7
• Mutable setter methods have been removed from MiniMax GenAI options classes. Configuration must now be done through constructors or builders, enforcing immutability. 222bc7d
• Mutable setter methods have been removed from Google GenAI options classes. Configuration must now be done through constructors or builders, enforcing immutability. 047f9a8
• Mutable setter methods have been removed from ElevenLabs options classes. Configuration must now be done through constructors or builders, enforcing immutability. 304fe1b
• Mutable setter methods have been removed from Bedrock options classes. Users must now use the immutable builder pattern or constructor-based initialization for Bedrock model options. 2b0b45b
• Mutable setter methods have been removed from DeepSeek options classes. Users must now use the immutable builder pattern or constructor-based initialization for DeepSeek model options. a4e99c5
• Anthropic configuration properties have been refactored and mutable setter methods removed from Anthropic options classes. Users must update to use the new property structure and immutable builder patterns. 556b5f2
• Several utility methods have been removed from the ModelOptionsUtils class. Users relying on these methods need to update their code to use alternative approaches. #5941
• Unnecessary Jackson annotations have been removed from OpenAiChatOptions. This may affect custom serialization/deserialization if users relied on these annotations. 6ed5928
• Setter methods have been removed from OllamaChatOptions as part of an API cleanup. Users must now configure options using the builder pattern instead of calling setters directly. #5923

⚠️ Upgrading Notes

• PromptChatMemoryAdvisor has been removed. Replace usages with the appropriate alternative chat memory advisor implementation and ensure all chat memory advisors are configured with an explicit conversation ID rather than relying on implicit identification. c3c7c86, 59ab752
• OpenAiConnectionProperties is now OpenAiCommonProperties. OpenAi*Properties classes no longer extend AbstractOpenAiOptions — options are now configured separately. Setters have been removed; use the builder pattern instead (e.g., OpenAiChatOptions.builder()...build()). Review upgrade-notes.adoc for detailed migration guidance. 52c952e
• If you use Tanzu bindings, the TanzuBindingsPropertiesProcessor has been upgraded to work with the new OpenAI configuration properties structure. Ensure your Tanzu bindings configuration is updated accordingly. d27f6fd
• If you were using setter methods on PostgresMlEmbeddingOptions, StabilityAiImageOptions, or calling options.setInternalToolExecutionEnabled() / options.setOutputSchema() on ChatOptions, you must migrate to the builder pattern. Use the respective builder class (e.g., PostgresMlEmbeddingOptions.builder().build()) to construct options immutably. a0ad1c7, 741a6cc, #5957
• If using the SAP HANA DB or Infinispan vector store integrations, you must migrate to an alternative supported vector store (e.g., pgvector, Redis, Chroma, Pinecone, etc.). Remove the corresponding starter dependencies from your build configuration. 35b659e
• Setter methods have been removed from Mistral AI, MiniMax GenAI, Google GenAI, and ElevenLabs options classes. Update your code to use the builder pattern or constructor-based configuration instead of calling setter methods directly. 06015b7
• With setters removed from Bedrock, DeepSeek, and Anthropic options classes, users must migrate to the builder pattern. Replace calls like options.setTemperature(0.7) with the equivalent builder method: Options.builder().temperature(0.7).build(). Review Anthropic property names as they have been refactored. 2b0b45b
• If your application directly calls any of the removed ModelOptionsUtils methods, you will need to update your code. Review the PR for details on which methods were removed and what alternatives are available. #5941
• With setters removed from OllamaChatOptions, users must update their code to use the builder API. Replace any direct setter calls (e.g., options.setModel(...)) with the equivalent builder methods (e.g., OllamaChatOptions.builder().model(...).build()). #5923
• If you were previously using string values for OpenAiEmbeddingOptions#encodingFormat, update your code to use the new enum type. This provides compile-time safety and ensures only valid encoding formats are used. de1824f

⭐ New Features

• Enhanced observability support for chat models, providing better monitoring and tracing capabilities for AI model interactions. c3bdbb0
• OpenAI options classes now use an improved builder pattern, providing a cleaner and more consistent API for constructing option objects programmatically. 5568c7b
• Enhanced observability for tool/function calling, providing better monitoring and tracing capabilities when AI models invoke tools. #5927
• A new default buildRequestPrompt method has been added to the ChatModel interface, removing the need for duplicate implementations across individual model providers. This also adds the missing GoogleGenAiChatOptions.responseMimeType mutation and improves ChatOptions handling for vendor-specific requirements. #5841
• OpenAiEmbeddingOptions#encodingFormat has been refined to use an enum type instead of a plain string, providing better type safety and IDE support when configuring embedding encoding formats. The OpenAI SDK default for encoding format is now preserved. de1824f
• The OpenAI embedding encoding format option has been restored, ensuring users can once again configure this parameter when working with OpenAI embedding models. 984e8b6
• An MCP (Model Context Protocol) integration test tool with date functionality has been enabled, improving test coverage for MCP-based workflows. #5843

🪲 Bug Fixes

• Fixed a bug in MilvusVectorStore where string IDs were not properly escaped during deletion operations, which could cause failures when deleting vectors with special characters in their IDs. 0146f25
• Resolved an issue where calling getOutputSchema() on OllamaChatOptions would throw an unexpected exception, restoring correct structured output schema retrieval behavior. #5976
• Fixed incorrect tool options handling when merging ToolCallingChatOptions into OpenAiChatOptions, ensuring tool configurations are correctly propagated during option merging. bb5d2f0
• Fixed the MistralAiChatModelIT#chatClientEntityWithStructuredOutput integration test to ensure reliable validation of structured output functionality with the Mistral AI provider. 0cf8f99
• Fixed the OllamaChatModelIT#chatClientEntityWithStructuredOutput integration test to ensure reliable validation of structured output functionality with the Ollama provider. a9f5966
• Fixed an issue where OpenAI configuration properties were not being resolved correctly, restoring proper Spring Boot auto-configuration behavior. 1eed6d3
• Updated the Qdrant vector store Docker image to version 1.17.0 for integration tests and fixed the spring-boot-testcontainers configuration, resolving test failures in QdrantVectorStoreAutoConfigurationIT. db336ff, b811799, 32d43e9
• Replaced string concatenation with proper Filter.Expression usage in DefaultSemanticCache for more robust and type-safe filter expression handling. 095f65f
• Session ID is now included in error handler log messages for WebFluxMcpSessionTransport, improving debuggability of MCP session errors. 7b0f3db via #5858
• Fixed a failing integration test for MistralAI chat model observation to improve CI reliability. e9fb7f3
• Fixed an issue in the MCP integration where SpringAiSchemaModule was not being reused correctly, and improved detection of @nullable annotated types. d4ba465
• The provider name used in OpenAI observability telemetry was incorrect. This fix ensures the correct provider name is reported in tracing and metrics. #5925 via #5924
• Resolved an issue where some configured options were not being included in the request sent to the MistralAI API. fea7a63
• Fixed incorrect handling of the tool call ID field in AssistantMessage when used with the Ollama integration. 7d155ec
• Model auto-configurations are now null-safe, preventing potential NullPointerExceptions during application startup when optional configuration properties are absent. c81bdfd
• The spring-ai-minimax module has been made null-safe, improving stability when optional fields or configurations are not provided. 5cc5914
• The spring-ai-google-genai-embedding module has been made null-safe, preventing runtime errors when optional configuration values are absent. 3fc5f19
• The spring-ai-google-genai, spring-ai-google-genai-embedding, spring-ai-transformers, spring-ai-vertex-ai-embedding, and spring-ai-elevenlabs modules have all been made null-safe, reducing the risk of NullPointerExceptions in applications using these providers. d9606f8 0698010 3735c64 e051b86 3c3af1c

📓 Documentation

• Added documentation in upgrade-notes.adoc to guide users through the options and properties refactoring introduced in this release. 52c952e
• Added documentation clarifying the observability gap at the HTTP layer for Anthropic and OpenAI chat models, helping users understand current monitoring limitations. db95798 via #5916
• Updated outdated Javadoc references and corrected syntax errors in the documentation to improve accuracy and developer experience. #5938
• Corrected typos found in the MCP (Model Context Protocol) documentation. ddca1d9
• Resolved broken cross-reference anchors throughout the documentation, improving navigation and link integrity. #5918 via #1812

🔨 Dependency Upgrades

• Updated the OpenAI Java SDK dependency to version 4.34.0, bringing the latest API improvements and bug fixes. Test assertions updated to align with the new SDK's credential API (apiKey() method). faffedb, f81f3b3
• The Anthropic SDK dependency has been upgraded to version 2.30.0, bringing the latest API features and improvements. 7a29af5
• The Anthropic Java SDK dependency has been upgraded to version 2.27.0, bringing the latest improvements and fixes from Anthropic. 5199e5e
• The Qdrant vector store dependency has been upgraded to version 1.17, incorporating the latest features and performance improvements. b304094

⚡ Performance

• Internal refactoring to improve algorithmic time complexity and reduce unnecessary memory allocations, resulting in better runtime efficiency. #5601
• The OllamaApi implementation now uses RestClient.requiredBody, simplifying the code and improving reliability of response handling. 112d118

🔩 Build Updates

• Disabled Ollama container reuse in OllamaWithOpenAiChatModelIT to improve test isolation and reliability in CI environments. f90ebb9
• Resolved NullAway static analysis violations to improve code correctness and build hygiene. c3c7c86
• The project now builds with JDK 17.0.19 to ensure compatibility and stability improvements from this version. 935d79d
• Fixed the MCP integration tests CI/CD workflow by adding the missing -am (also-make) flag to ensure proper module dependency resolution during builds. 3f8ed35
• Removed unused version properties from the root POM file, reducing maintenance overhead and avoiding confusion over stale dependency declarations. 4008b57
• Removed unused or redundant entries from the Spring AI Bill of Materials (BOM), keeping dependency management lean and accurate. 2ac65b9
• The integration test for Google GenAI Chat Model has been updated to use a currently supported model, ensuring CI reliability. a927370
• OpenAI embedding tests have been polished and improved for better reliability and coverage. 6772ff7
• Spring AI starter modules have been reorganized into a dedicated starters/ directory, improving the project structure and making it easier to navigate and maintain the starter configurations. 02d3b03

🙏 Contributors

Thanks to all contributors who made this release possible:

• Arpan Chakraborty (@ArpanC6)
• chabinhwang (@chabinhwang)
• Christian Tzolov (@tzolov)
• Daniel Garnier-Moiroux (@Kehrlann)
• Eddú Meléndez (@eddumelendez)
• Emile Plas (@emileplas)
• Eric Bottard (@ericbottard)
• Ilayaperumal Gopinathan (@ilayaperumalg)
• KoreaNirsa (@KoreaNirsa)
• Nicolas Krier (@nicolaskrier)
• Soby Chacko (@sobychacko)
• Sébastien Deleuze (@sdeleuze)
• Thomas Vitale (@ThomasVitale)
• Yaner (@yaner-here)