Spring AI 2.0.0-M5 Release Notes

🎯 Highlights

This release includes 13 new features, 36 bug fixes, 14 documentation improvements, 41 other improvements.

⏪ Breaking Changes

• The MCP Java SDK has been upgraded to version 2.0.0-M2. This upgrade includes breaking API changes that require migration. Review the documented breaking changes before upgrading. #5879
• The spring-ai-azure-openai module has been removed from Spring AI. Azure OpenAI functionality is now available through the standard spring-ai-openai module, which provides full Azure OpenAI deployment support. Users must migrate their dependencies from spring-ai-azure-openai to spring-ai-openai and update their configuration accordingly. 3f5255f
• The ModelOptionsUtils.merge() method has been removed from non-chat model implementations. Applications relying on this utility method for options merging in non-chat models (e.g., audio, embedding, image models) will need to update their code to handle options merging directly. #5789
• Several ModelOptionsUtils.merge() calls have been removed from chat model implementations as part of the options management refactoring. This may affect custom integrations that depend on the previous options merging behavior. #5766
• The MCP JSON dependency has been removed from the spring-ai-client-chat module. Projects that relied on this transitive dependency will need to add it explicitly if still required. #5773 via #5760
• The ChatClient options merging behavior has been redesigned and moved to the ChatClient level via a new builder combineWith() method. This changes how model options are combined and may require updates to existing code that relies on the previous merging behavior. #5725
• The Vertex AI model and autoconfiguration modules for non-embedding use cases have been removed from Spring AI. Only the spring-ai-vertex-ai-embedding module remains. Users relying on Vertex AI chat or other non-embedding functionality must migrate to alternative model providers. Documentation has also been updated to reflect these removals. #5714
• The ZhipuAI model has been removed from the main Spring AI repository. Users currently using the ZhipuAI integration should check for alternative community-maintained modules or migrate to other supported model providers. #5700
• Oracle Cloud Infrastructure (OCI) GenAI support has been removed from the main Spring AI repository. Users relying on OCI GenAI will be able to migrate to a separate integration that will be released and documented shortly. #5695
• The SpringAiTestAutoConfigurations class has been removed. Projects that depend on this auto-configuration for testing will need to update their test setup accordingly. #5684

⚠️ Upgrading Notes

• Users integrating with the Model Context Protocol (MCP) must review the breaking changes introduced in the 2.0.0-M2 SDK upgrade. Update your MCP-related code and configuration according to the migration documentation added in this release. #5879
• Users of the Anthropic module should review the newly added migration documentation to ensure their configurations and code are compatible with the latest module changes. #5881
• If you were using the spring-ai-azure-openai dependency, you must remove it and replace it with spring-ai-openai. Update your Spring configuration to use the OpenAI auto-configuration with Azure-specific properties (endpoint, API key, deployment name). The spring-ai-openai module now fully supports Azure OpenAI deployments. Refer to the updated documentation and release notes for the OpenAI Java SDK transition for detailed migration instructions. 3f5255f
• The Pixtral 12B model has been removed and Pixtral Large is now deprecated. Update your configuration to use the currently recommended Mistral/Pixtral models to avoid disruptions. d479ced
• The spring-ai-openai-sdk module has been merged into spring-ai-openai and no longer exists as a separate artifact. If your project had a direct dependency on spring-ai-openai-sdk, remove it — all functionality is now provided by spring-ai-openai via the official openai-java SDK. No changes to existing spring.ai.openai.* configuration properties are required. #5779
• If your application or custom model integration calls ModelOptionsUtils.merge(), you will need to refactor to handle options merging without this utility. Review PRs #5789 and #5766 for guidance on the new options management approach. #5789
• If your project depends on MCP JSON functionality through the spring-ai-client-chat module, you must now declare this dependency explicitly in your build configuration following its removal as a transitive dependency. #5773 via #5760
• If your application relied on the previous options merging behavior at the model level, you should migrate to using the new combineWith() builder method on ChatClient. Review the updated documentation for the new merging semantics. #5725
• If you are using Vertex AI for chat, text generation, or other non-embedding use cases, you must migrate to an alternative model provider. The spring-ai-vertex-ai-embedding module for embeddings is still available. Remove any dependencies on spring-ai-vertex-ai-gemini or related non-embedding autoconfiguration modules from your project. #5714
• If your project uses the ZhipuAI model or its auto-configuration from Spring AI, you must migrate to an alternative. The integration has been removed from the main repository as of this release. #5700
• If your project uses OCI GenAI support from Spring AI, you must migrate to an alternative. The integration has been removed from the main repository. Users relying on OCI GenAI will be able to migrate to a separate integration that will be released and documented shortly. #5695
• Projects using SpringAiTestAutoConfigurations for test setup must update their test configuration. Review your test context setup and replace any usage of this removed class with appropriate alternatives. #5684

⭐ New Features

• Custom StructuredOutputConverter implementations can now participate in the native structured output pipeline, giving users greater flexibility to plug in their own output conversion logic alongside built-in converters. #5659
• The ToolCallAdvisor.Builder now exposes a getter for the conversationHistoryEnabled property, allowing users to inspect the current configuration state when building ToolCallAdvisor instances. #5869
• Added unified cache usage metrics to the Usage interface, providing consistent access to cache hit/miss statistics across all AI model providers. 7cfad45
• The spring-ai-openai module now uses the official openai-java SDK, replacing the previously internal implementation. All OpenAI models (Chat, Embedding, Image, Audio, Moderation) are migrated. The spring-ai-openai-sdk module has been merged and removed. Existing spring.ai.openai properties, builders, and chat options remain fully compatible — no migration required for most users. The extraBody configuration is transparently mapped to additionalBodyProperties. #5779
• Added AudioTranscription model support using the OpenAI SDK, enabling audio-to-text transcription capabilities through the standardized Spring AI model abstraction. 4aaca6d
• MCP Server now supports filtering which tools are exposed via the new spring.ai.mcp.server.expose-mcp-client-tools configuration property, providing fine-grained control over tool visibility in MCP client-server scenarios. #5755
• Added a new Moderation Model implementation using the OpenAI SDK, enabling content moderation capabilities through the standard Spring AI model abstraction. #5730
• OpenAI SDK-based models now support passing extra body parameters, providing more flexibility for advanced API usage and custom request configurations. #5734
• Options merging has been moved to the ChatClient level with a new combineWith() builder method, offering a more intuitive and composable API for combining chat options. #5725
• Added built-in web search tool support for the Anthropic integration, enabling models to search the web as part of their response generation. #5689
• Added support for configuring thinking display settings in the Anthropic module, allowing control over how extended thinking is surfaced in responses. bdcfd25
• Added service tier support to the Anthropic integration, enabling priority capacity selection for workloads that require dedicated throughput. b1c6375
• Added support for Anthropic inference geo configuration, enabling users to control geographic data residency when using Anthropic models. This is important for organizations with data sovereignty requirements. #5666

🪲 Bug Fixes

• The default cache directory for transformer models is now secured with proper permissions, preventing unauthorized access to cached model files. ce38bfe
• The CosmosDB vector store's delete method now properly parameterizes queries instead of using string interpolation, preventing potential injection vulnerabilities. 7b7a605
• Fixed a vulnerability where a specially crafted malformed PDF could cause excessive memory allocation. Processing of malformed PDFs is now handled defensively. 413a138
• Properly handles the conversationId when filtering in VectorStoreChatMemoryAdvisor, ensuring chat memory is correctly scoped to the right conversation context. 12e1e3d
• Corrected key handling in the vector store filter expression converter to ensure filter expressions are properly translated and applied. 029173f
• The stopSequences list is now defensively copied when combining chat options, preventing unintended mutation of the original list. dd820e6
• Fixed an issue where the outputSchema field was not correctly propagated through BedrockChatOptions, ensuring structured output schemas are properly passed to the Bedrock Converse API. feb6fe2
• Resolved a validation exception thrown by the Bedrock Converse API caused by extra input fields being included in the request payload. 91e923d
• Corrected the buildRequestPrompt method in BedrockProxyChatModel to properly construct request prompts for Bedrock proxy interactions. 2113222
• Added null-safety improvements throughout the spring-ai-bedrock-converse module to prevent NullPointerExceptions and improve robustness. 4ebf453
• Resolved intermittent test failures in BedrockProxyChatModelIT to improve test reliability for the Bedrock proxy integration. 15bf14f
• Corrected deployment handling logic in the Audio and Moderation OpenAI model implementations to ensure proper operation when using deployment-based configurations. 023a8c1
• The spring-ai-bedrock module has been updated to be null-safe, preventing potential NullPointerExceptions and improving overall stability when working with AWS Bedrock integrations. d4c6389
• Addressed flakiness in OllamaChatModelObservationIT and improved OllamaWithOpenAiChatModelIT with dynamic port mapping and configurable timeouts, resulting in more reliable integration test execution. d7ae7c9
• Pins Spring Framework to 7.0.7 to resolve a flushing regression that could affect streaming and reactive response handling. #5844
• Corrects the dependency management configuration for the spring-ai-autoconfigure-vector-store-qdrant module to ensure proper resolution. 150c885
• Resolves dependency management issues in the BOM for Qdrant and Weaviate vector store integrations. 43a1743
• Resolves gRPC dependency resolution issues in the Milvus vector store integration. c66a3c5
• Fixes a bug in MistralAiChatModel.buildRequestPrompt() that could cause incorrect prompt construction. e3e8cca
• Fixes JSON parsing to correctly handle raw string values for Java date/time types (JSR-310), preventing parse errors when date/time fields are provided as strings. #5834
• Fixed failing ToolCallingManager tests to ensure reliable test execution. ecea549
• Fixed MCP server auto-configuration test setup to resolve test failures. f0ed1a2
• Resolved code formatting issues to maintain code style consistency. 388b25b
• Corrected typos in Javadoc comments to improve documentation accuracy. #5799
• Jackson-related annotations have been removed from various options classes as part of a cleanup removing ModelOptionsUtils.merge calls. This improves consistency and reduces unnecessary serialization dependencies in options handling. #5789
• Multiple fixes were applied to OpenAI integration test configurations to ensure tests correctly set required properties such as default model settings and response format configurations. 05a781a
• Fixed incorrect options in OllamaWithOpenAiChatModelIT#listOutputConverter, response format in beanOutputConverterRecords, and addressed flakiness in functionCallTest to improve test reliability for the Ollama-with-OpenAI-compatibility path. 8db5c71
• Corrected the OpenAI vector store integration tests to properly configure the default model, resolving test failures in that suite. 72479b3
• Fixed the PgVectorStoreWithChatMemoryAdvisorIT integration test to ensure proper validation of PgVector store interactions with the chat memory advisor. 7628729
• Fixed Ollama autoconfiguration integration tests that were broken following changes to options management, ensuring test coverage remains accurate after the options refactoring. #5777
• Fixed failing Ollama Kotlin integration tests to restore proper test coverage for Kotlin-based Ollama usage. d605172
• Fixed incorrect string parsing of the toolChoice parameter in OpenAiSdkChatModel, which could cause errors when specifying tool choice as a string value. This fix has been backported to the 1.1.x branch. #5735
• Special parameters are now correctly filtered from the @McpPrompt schema, preventing invalid schema entries from appearing in MCP prompt definitions. #5751 via #5750
• Resolved a regression in Anthropic's native structured output functionality that caused incorrect behavior in structured response generation. #5729
• Fixed an issue where the extra_body parameter was incorrectly being sent as part of OpenAI API requests, which could cause request rejections from the OpenAI API when unknown parameters are present. b635aee
• Corrected the condition used to skip tests when required API keys are not configured in the environment, preventing false test failures in environments without credentials. #5699

📓 Documentation

• New migration documentation for the Anthropic module helps users transition their existing code to the updated API and configuration patterns. #5881
• Documentation for breaking changes introduced in the MCP Java SDK 2.0.0-M2 upgrade, providing guidance on how to migrate existing MCP integrations. #5879
• Corrected formatting issues in the advisors documentation page to improve readability. a78bdf5
• Release notes have been updated to document the transition to the OpenAI Java SDK, providing guidance for users migrating their integrations. 63f321c
• Documentation has been updated to remove Azure OpenAI references following the module removal, keeping the documentation aligned with the current supported modules. 40122da
• The README has been updated with a note about CPU architecture requirements or compatibility information. d199dbc
• Updated documentation to reflect the new options merging behavior introduced by the ChatClient combineWith() builder method. #5725
• Updated spring-ai-integration-tests to use OpenAI SDK instead of the legacy OpenAI client, aligning tests with the current SDK-based implementation. #5725
• Fixed issues with Javadoc documentation generation and configuration to improve developer experience and API documentation accuracy. #5715
• Updated documentation to clarify how the extra_body parameter should be used with OpenAI integrations, helping developers understand the correct configuration approach. b635aee
• Updated documentation to reflect the removal of Vertex AI non-embedding support, ensuring users are not misled by outdated references. #5714
• Documentation has been updated to remove references to the ZhipuAI model following its removal from the main repository. #5700
• Getting started documentation has been updated to reflect recent changes and improvements to the project. 7aa42e5
• Documentation has been updated to remove references to OCI GenAI, reflecting its removal from the main repository. #5695

🔨 Dependency Upgrades

• The Model Context Protocol (MCP) Java SDK has been upgraded from a prior version to 2.0.0-M2. See breaking changes and upgrading notes for migration details. #5879
• Updated the Model Context Protocol (MCP) SDK dependency to version 2.0.0-M1, incorporating the latest MCP API improvements and milestone features. #5874
• Updated the Spring Boot dependency to version 4.1.0-RC1, bringing in the latest Spring Boot release candidate improvements and fixes. 7538183
• Updates the Spring Boot dependency to version 4.1.0-M4. ed2c7c7
• Updates Kotlin to version 2.3.20. 48b7e7e
• Updated Infinispan vector store dependency to version 16.0.9 with the latest fixes and improvements. de8ad9c
• Updated document parsing dependencies: Apache Tika to 3.3.0, jsoup to 1.22.1, and Apache PDFBox to 3.0.7 for improved document processing capabilities. #5796
• The Anthropic SDK dependency has been updated to version 2.24.0, bringing the latest upstream improvements and fixes from Anthropic's Java client library. 6a2716e

🔩 Build Updates

• The PostgreSQL integration test class has been renamed with the proper IT suffix convention, ensuring it runs as part of the integration test phase rather than unit tests. #5853
• The outdated MCP Spring migration guide file has been removed as it has been replaced or superseded by updated documentation. d939c37
• Intermediate upgrade of the MCP SDK to 2.0.0-SNAPSHOT with corresponding test fixes to align with API changes in the snapshot build, ahead of the M1 release. #5873
• Azure OpenAI integration tests have been moved from the removed spring-ai-azure-openai module into the spring-ai-openai module, ensuring continued test coverage for Azure OpenAI deployment scenarios. 888292c
• Enables JSpecify null-safety checks in the spring-ai-mistral-ai models module to improve code correctness. 53abacf
• Enables JSpecify null-safety checks in the spring-ai-openai models module to improve code correctness. a3c58c5
• Updated CI/CD workflows to use the latest versions of GitHub Actions for improved security and compatibility. de8ad9c
• Removed no longer needed checkstyle suppression rules for the OpenAI SDK integration, improving code quality enforcement. a0506f1
• Cleaned up an unused import in the codebase as part of general code quality maintenance. ee16fc5
• Removed an Anthropic integration test that was no longer relevant following recent API or options management changes. da8db65
• Integration tests are now skipped in CI pipelines to speed up build times, and the automated release notes generation workflow has been removed. #5688
• The PR check workflow has been updated to use 'mvn package' instead of 'mvn test', improving CI consistency and build performance. b04c4ed

🔐 Security

• Transformer model cache directories are now created with restricted permissions to prevent other users or processes from reading cached model data. ce38bfe
• Protection against a potential denial-of-service vector where processing a malformed PDF could cause excessive heap allocation. 413a138
• Parameterized the CosmosDB delete query to prevent potential injection attacks through document ID values. 7b7a605

🙏 Contributors

Thanks to all contributors who made this release possible:

• Christian Tzolov (@tzolov)
• Daniel Garnier-Moiroux (@Kehrlann)
• Dariusz Jędrzejczyk (@chemicL)
• David Frizelle (@dafriz)
• Emmanuel Essien-nta (@essien)
• Eric Bottard (@ericbottard)
• Filip Hrisafov (@filiphr)
• Ilayaperumal Gopinathan (@ilayaperumalg)
• Michael Minella (@mminella)
• Nicolas Krier (@nicolaskrier)
• Soby Chacko (@sobychacko)
• Stefano Cordio (@scordio)
• Sébastien Deleuze (@sdeleuze)