Spring AI 2.0.0-M3 Release Notes

🎯 Highlights

This release includes 23 new features, 45 bug fixes, 16 documentation improvements, 67 other improvements.

📢 Noteworthy

MCP Annotations are now moved from spring-ai-community/mcp-annotations (org.springaicommunity.mcp) into Spring AI core (org.springframework.ai.mcp.annotation). 585d618
Spring-specific MCP transport implementations are now moved from the MCP Java SDK (io.modelcontextprotocol.sdk) into the Spring AI project (org.springframework.ai.mcp). 0045513
The OpenAI SDK integration now uses the new builder pattern for OpenAiSdkChatOptions, providing a more fluent API for configuration. 3508cc1
A deprecated shim has been added for the disableMemory() method. Users should migrate to disableInternalConversationHistory() as the preferred API 9893de6
The OpenAiChatModel#internalCall method and other internal methods have had their access control scope optimized to private, improving code encapsulation and reducing unintended usage of internal APIs. e86b8d7
Reverted a breaking API change that made ModelRequest#getOptions non-null, restoring backward compatibility #5403
Simplified tool context management by removing automatic tool call history inclusion 8ab7f7e

⚠️ Breaking Changes

Breaking Changes: 2.0.0-M3 includes several breaking changes, including MCP annotation package renames, MCP transport artifact relocations, Jackson 2 → Jackson 3 migration, and removal of conversation history from ToolContext. Review the Upgrade Notes before upgrading.

MCP Annotations are now moved from spring-ai-community/mcp-annotations (org.springaicommunity.mcp) into Spring AI core (org.springframework.ai.mcp.annotation). 585d618. Follow the migration instructions.
McpAsyncClientCustomizer and McpSyncClientCustomizer have been removed and replaced by a single generic interface McpClientCustomizer<B>. 272c736. Follow the migration instructions.
Spring-specific MCP transport implementations are now moved from the MCP Java SDK (io.modelcontextprotocol.sdk) into the Spring AI project (org.springframework.ai.mcp). 0045513. Follow the migration instructions.
Spring AI now uses Jackson 3 (tools.jackson package) instead of Jackson 2 (com.fasterxml.jackson package) 42043bc which is used by default in Spring Boot 4, if you were using previous milestone make sure to refine your Jackson dependencies accordingly.
Conversation History Removed from ToolContext Migration Instructions
Builders exposed to users no longer require explicit generics, simplifying the API surface. This affects MiniMaxChatOptions and potentially other model provider option builders. 7470fd8. Code using explicit generics should be updated to use simplified builder syntax.
The Anthropic integration has been replaced from a RestClient-based implementation to use the official Anthropic Java SDK, which may require code changes for applications using the Anthropic model provider. b0ce25a. If you are using the Anthropic model provider, review your code as the internal implementation has changed from RestClient to the official Anthropic Java SDK. The public API should remain compatible, but custom configurations may need adjustment.
The disableMemory() method has been renamed to disableInternalConversationHistory() for better clarity about its purpose 657252a. Replace calls to disableMemory() with disableInternalConversationHistory(). A deprecated shim is provided for backward compatibility.
Huggingface model and autoconfiguration have been moved out of the main Spring AI repository f21b082
DeepSeekChatOptions has been updated to use the modern builder pattern for consistency with other chat model options in Spring AI. Existing code using the old constructor pattern will need to be updated. #5552. Update your code to use the new builder pattern instead of direct constructor calls. Example: DeepSeekChatOptions.builder().temperature(0.7).build()
BedrockChatOptions has been updated to use the modern builder pattern for consistency with other chat model options in Spring AI. Existing code using the old constructor pattern will need to be updated. #5550
MistralAiChatOptions now uses builder pattern for configuration, replacing direct constructor/setter usage #5551. Update code using MistralAiChatOptions to use the new builder pattern instead of constructors or setters.
AzureOpenAiChatOptions now uses builder pattern for configuration, replacing direct constructor/setter usage #5544. Update code using AzureOpenAiChatOptions to use the new builder pattern instead of constructors or setters.
AnthropicChatOptions now uses builder pattern for configuration, replacing direct constructor/setter usage #5541. Update code using AnthropicChatOptions to use the new builder pattern instead of constructors or setters.
Refactored ChatOptions builders to introduce builder merging pattern, which may affect custom implementations extending ChatOptions builders 3db5c2b. If you have custom implementations extending ChatOptions builders, review the new builder merging pattern and update your code accordingly. The new pattern is demonstrated in the OllamaChatOptions implementation.
Claude 3 Opus, Sonnet, and Haiku models have been removed. Applications must migrate to Claude 4.x model variants. 628b020
Internal methods in model implementations have been changed from protected/package-private to private access, improving encapsulation. This affects OpenAI and other model provider implementations. If you were extending these classes and accessing internal methods, you'll need to use public APIs instead. da3bec4
The ModelRequest#getOptions method now returns a non-null value. Code expecting null return values will need to be updated. e4a4723. If your code checks for null returns from ModelRequest#getOptions, update it to handle the non-null guarantee. The method now always returns a valid options object.
Previously deprecated constants in Mistral model enums have been removed. Update code to use the current model enum values. 96b408d. If your code references deprecated Mistral model enum constants, update to use the current enum values as the deprecated constants have been removed.
If your application uses Claude 3 Opus, Sonnet, or Haiku models, update model identifiers to their Claude 4.x equivalents (e.g., claude-sonnet-4-5-20250929). 628b020
If you extended model implementation classes and accessed internal methods, verify that you're using public APIs only. Internal methods are now private and no longer accessible from subclasses. da3bec4

⭐ New Features

New abstraction for customizing MCP (Model Context Protocol) clients, providing a hook for modifying client behavior before initialization. #5606
Improvements and bug fixes to the filter expression converter used across vector store implementations for more reliable query filtering. 4602c23
Added native structured output support to BedrockProxyChatModel for better integration with AWS Bedrock services 3003316
Improved ZhiPuAiChatOptions to use a generic builder pattern for more flexible configuration 7df9b16
Introduced a new mcp-annotations module to enhance Model Context Protocol (MCP) integration capabilities #5567
Implemented notification logic for Model Context Protocol (MCP) server transports, enabling better communication patterns with MCP-enabled services. 99c3bfa
Introduced new builder pattern for OllamaChatOptions providing more flexible configuration options with builder merging support 5f09a8f
Enhanced TokenTextSplitter with better EncodingType support for more accurate text tokenization 045e8c1
Adds support for OpenAI's audio speech capabilities through the OpenAI SDK integration 7c45de8
Adds Spring Boot Docker Compose support for Milvus vector database service connections fe7104f
Enhances OpenAiSdkChatModel with builder pattern support for improved configuration flexibility fbcb8a8
The filterExpressionConverter can now be configured via the builder pattern in Neo4jVectorStore, providing greater flexibility for custom filter implementations. 9210ded
TokenTextSplitter can now accept EncodingType directly, providing more control over text tokenization strategies. cfbe546
Added support for the latest Claude 4.6 models from Anthropic, providing access to improved performance and capabilities. 628b020
The Model Context Protocol (MCP) integration modules for Spring WebFlux and Spring WebMVC have been migrated into the main Spring AI project, providing better integration and maintenance. MCP version updated to 1.0.0-SNAPSHOT. #5475
Enhanced OpenAI SDK integration with a fluent Builder pattern for easier configuration and instantiation of chat models e58dd56
Added support for isolating system prompts in semantic cache, improving cache accuracy and preventing unintended cache hits across different system contexts 7b30b50
ToolCallAdvisor now supports streaming responses, enabling real-time tool call execution and response handling 19c606a
Added support for custom embedding dimensions via '/embedding/embedding-model-dimensions.properties' configuration for OpenAiEmbeddingModel 47cdb08
Enhanced Anthropic integration with support for SIGNATURE_DELTA streaming events #5282
Added support for model-specific thinking levels with Google GenAI SDK 1.37.0 b1535b9
Added filtering capability to SimpleVectorStore delete operations, allowing more granular control over vector deletion. c013f8d
Added a new workflow to monitor and display the health of Spring AI ecosystem projects with configurable alert thresholds and last run date tracking f359765

🪲 Bug Fixes

Corrected autoconfiguration dependency to properly require spring-ai-mcp module, preventing runtime configuration errors. #5613
Resolved issues with HTTP header handling in Model Context Protocol WebMvc transports for proper request/response processing. #5605
Fixed builder implementation to use the full arguments constructor, ensuring all options are properly initialized. 45e1882
Resolved issues where global RestClient and WebClient builders were being mutated, which could cause unexpected behavior in Spring applications. 009f7e6
Additional fix for RestClient and WebClient builder mutation issues contributed by the community. 4cb9c79
Replaced disabled Azure OpenAI image model with the latest available model 5591bb8
Fixed support for nullable types in OpenAPI 3.0.3 schema generation f7ccb10
Corrected GoogleGenAiTextEmbeddingModelName configuration 902811a
Resolved integration test failures for Google GenAI and Vertex AI model providers c7ca6bc
Corrected the prefixAssistantMessage method in DeepSeekAssistantMessage to properly handle message formatting 622f087
Resolved a regression where DeepSeek integration failed when handling null content in responses 19d4963
Ensured PropertiesMcpSseClientConnectionDetails bean is only enabled when McpSseClientConnectionDetails bean is missing, preventing configuration conflicts 597cab4
Corrected an issue where the token count of the first document in a new batch was not being properly tracked. #5528
Improved type safety by adding proper nullable annotation to the context value parameter in ChatClientResponse.Builder. #5547
Fixed missing @Override annotation in AnthropicChatOptions to ensure proper method overriding. 0f9f276
Corrected the output schema returned by OpenAi(Sdk)ChatOptions to properly reflect configured options 0f91e21
Resolves compatibility issues with Jackson 3.x in the Elasticsearch vector store integration #5502
Fixes integration tests for Azure OpenAI chat client 48a346f
Ensures document names comply with AWS Bedrock Converse API requirements by sanitizing invalid characters 6a28b39
Adds test coverage for custom filter expression converter configuration in Neo4j vector store 2b8320f
Adds test coverage to verify metadata is properly preserved in Qdrant vector store operations df0b8f0
Ensured CosmosDB chat memory auto-configuration is applied first, preventing initialization issues. d57da4b
Resolved issues in MCP (Model Context Protocol) auto-configuration integration tests. d75845b
Added ambiguity validation and improved authentication logic for Google GenAI, preventing configuration errors. c974b21
Addressed breaking API changes introduced in the mcp-core 1.0.0 release to restore compilation compatibility. 8becad0
Resolved issue with metadata handling when using Ollama in streaming mode 14d6032
Improved null safety handling in the OpenAI SDK module 73f020f
Resolved port conflict issues in Model Context Protocol integration tests 0790f76
OpenAI integration tests now properly handle null delta values in streaming responses, preventing potential NullPointerExceptions during streaming operations. 6ab3325
Resolved issues with JsonMapper configuration in BeanOutputConverter to ensure proper JSON serialization and deserialization of model outputs. b6b073a
Corrected integration test issues in Ollama auto-configuration for tool callback functionality, ensuring proper testing coverage. ae29ec2
MetadataMode configuration is now properly respected when processing embeddings in batch mode, ensuring consistent metadata handling across all embedding operations. 15e39fe
Corrected the auto-configuration ordering to ensure observation and metrics beans are properly initialized in Spring Boot 4 environments. c5d96da
Corrected filter expression grouping logic in OpenSearch vector store to ensure proper query construction 85931ca
Enhanced null-safety in DeepSeek integration to prevent potential NullPointerExceptions #5421
Resolved issue where Bedrock cache metrics were not properly included in the native Usage object, now with backward compatibility and comprehensive test coverage b678c30
Corrected the syntax for IN and NIN (not-in) filter expression grouping in Elasticsearch vector store 3d68ffc
Resolved issue GH-5255 where SemanticCacheAdvisor was not streaming tokens incrementally as expected. 9785cb2
Corrected index name configuration for Cassandra vector store auto-configuration 3dd593c
Resolved issues with metadata handling during Ollama thinking operations f297a73
Improved null-safety for Anthropic integration to prevent potential NPEs #5282
Enhanced null-safety throughout the Ollama integration module 463293f
Corrected message ordering in the MongoDB-based chat memory repository to ensure proper conversation flow c65cb21
Updated CI status detection to use the workflow runs API for more accurate build status reporting 4d2db40
Resolved Maven deployment metadata issues for newly added modules to ensure proper artifact publishing 5a43624

📓 Documentation

Enhanced migration documentation for M3 release including updated OpenRewrite recipes for automated code upgrades. #5611
Updated documentation to remove HuggingFace from the model provider comparison table. 3b0a15d
Clarified supported content types for requests (string or list of media content) and responses (string only) in Mistral AI API documentation cb967d1
Improved and corrected the migration guide documentation for upgrading to version 2.0.0-M3, including multiple refinements to instructions and examples 06f03b8, bb801d1, 908067f
Updated documentation and examples to demonstrate the new builder pattern for configuring GoogleGenAiChatOptions #5554
Cleaned up and improved the upgrade-notes.adoc documentation c1c41b6
Updates Docker Compose documentation to include Milvus vector database setup instructions #5504
Adds documentation on code formatting requirements and checks for project contributors a3508ac
Added migration documentation for Model Context Protocol Spring transport in Spring AI 2.0 544cee7
Added comprehensive design document serving as a TLDR guide for using JSpecify annotations in the project #5407
New documentation explaining how to access and work with HTTP headers when implementing MCP (Model Context Protocol) servers 779b0a9
Enhanced README documentation with detailed explanations about Java code formatting requirements and conventions 868866b
Corrected API reference errors in the documentation guide. 30a0e12
Corrected various typos in documentation and common module comments for improved clarity. 216901a
Added documentation explaining message ordering behavior in MongoChatMemoryRepository dbde175
Added dependency information to the ETL pipeline documentation for easier setup and configuration 9d81051

🔨 Dependency Upgrades

Upgraded dependencies for vector store implementations to their latest versions. ff1de86
Updated the GemFire vector store image used in integration tests. 3b34551
Upgraded Model Context Protocol (MCP) dependency to version 1.1.0. dd799f5
Upgraded the Google GenAI SDK version to support new capabilities and features for Google AI model integrations. 54ca5ed
Updated Spring Boot dependency to milestone version 4.1.0-M2, bringing latest framework enhancements and fixes. ce91f4c
Upgraded Qdrant container image to version 1.13.0 for improved performance and features. 694ff0c
Updated Spring Boot dependency to 4.1.0-M1 milestone release 81188c9
Model Context Protocol (MCP) dependency updated to version 1.0.0-SNAPSHOT following the migration of MCP modules into the core project. 336c911
Updated OpenAI Java client library to version 4.17.0 for latest API support and improvements c7fd804
Updated Azure SDK dependencies for improved security, stability, and feature support b9ac30c
Upgraded Google GenAI SDK with support for Gemini 3 model-specific thinking levels b1535b9
Updated dependencies in the Spring AI Bill of Materials to latest compatible versions 65fc665

🔩 Build Updates

Updated source control management configuration across Maven POM files for proper repository references. c45e654
Improved logging performance by replacing string concatenation with SLF4J parameterized logging throughout codebase. 802be8a
Applied consistent generic builder pattern to MiniMaxChatOptions for alignment with other chat model options. #5583
Temporarily disabled Azure OpenAI image model integration test until the test environment is properly configured. a43a376
General code cleanup and refactoring improvements. 4745b71
Updated AzureOpenAiImageModelIT to use existing deployment name for improved test reliability fef3a73
Updated Checkstyle configuration to support the new copyright header pattern bae7b9d
Updated copyright headers to use consistent "2023-present" format across all source files. fdaac3f
Re-enabled previously flaky WebFlux MCP integration tests and updated CI pipeline for better reliability 0196a0c
Added pull_request event trigger to mcp-integration-tests.yaml workflow for earlier validation e2886c5
Toggled MCP integration test enablement between WebMVC and WebFlux implementations for improved CI stability c19be1a
Added temporary MCP integration tests CI workflow to improve test stability and coverage 490a5cf
Multiple improvements to MCP integration tests including WebFlux transport tests, flaky test fixes, and temporary test disabling for stability dd6e77c
Updated integration test configuration for Google GenAI chat auto-configuration. 7072c08
Recategorized Model Context Protocol tests as integration tests for better test organization 89e1dad
Improved test reliability by configuring automatic retry for flaky MCP transport tests c5bdd86
Updated MCP integration tests to use explicit IP address for improved reliability 9840656
Temporarily disabled failing WebFlux server transport security tests 46bfe77
Disabled problematic test to unblock CI pipeline 9842308
Improved test execution controls for running individual integration tests more efficiently 9f9b779
Enhanced integration test coverage for chat client entity handling with structured outputs #5422
Refined Kotlin test implementation for better code quality and consistency #5428
Improved test coverage and documentation for Bedrock cache metrics functionality a8d1142
Enhanced type safety by adding JSpecify annotations to chat client, repository/memory, observation, embedding, image observation, and model-tool autoconfiguration modules. Narrowed suppression scope for better null-safety checking. a9976c0, 3f6689a, c9beb98, 7b1d65f, 1232e4a, 71db299, 04a1fa8
Restructured MCP auto-configuration classes for better organization by web framework e2dcb23
Added code style enforcement to Redis semantic caching auto-configuration module c1d645d
Updated CI/CD to use the official Spring backport bot action #5389
Reorganized ANTLR grammar files for better project structure 2184c92
Updated test naming convention for consistency with integration test standards ee42e23
Enhanced null-safety support by adding JSpecify annotations to Huggingface, PostgresML, Spring AI Transformers, Mistral AI, and multiple vector store autoconfiguration modules (Weaviate, Typesense, S3, Redis, Redis semantic cache, QDrant). This improves static analysis, IDE support, and code reliability. 0948347, 3032521, 72e7518, 3e660ad, a82b031, c9fce68, f926ea8, e88164c, 56b03b6, 2f3dd8c
Enhanced null-safety across autoconfiguration modules for Pinecone, PGVector, Oracle, OpenSearch, VS Observation, Neo4j, MongoDB, Milvus, MariaDB, and Infinispan vector stores by adding JSpecify annotations f741152, dca93e5, 584b267, 9c24071, e42233f, d699896, 6c9169a, 72733ab, 0d857c6, 7ec6012
Enhanced type safety by adding JSpecify annotations to GemFire, Elasticsearch, Couchbase, Chroma, Cassandra, Azure Cosmos DB, and Azure Vector Store autoconfiguration modules a8daef7, c979815, d5f7064, f11341f, ac17aff, f6fd15a, 36ba44c
Enhanced type safety by adding JSpecify annotations to Spring AI MCP Server WebMVC, WebFlux, and common autoconfiguration modules 5431a35, 38a85a5, c85e994
Added JSpecify annotations to MCP WebFlux client, MCP HTTP client, MCP common auto-configuration, Spring AI Retry, and Stability AI model modules to improve compile-time null-safety checking. 2ae5f95
Moved swagger files out of resources directory for better project organization. c85105c
Moved OllamaEmbeddingOptionsTests to integration test classification for more appropriate test execution 95850e8
Changed ecosystem CI dashboard alert threshold from 3 to 2 days for faster issue detection ea7c736
Enhanced ecosystem CI dashboard with a last run date column for better visibility into project build status 3c615ab
Updated documentation-upload workflow to use the aggregate:jar approach for proper artifact building and deployment 678b30b

🙏 Contributors

Thanks to all contributors who made this release possible:

spring-projects/spring-ai v2.0.0-M3 Spring AI 2.0.0-M3 on GitHub

Spring AI 2.0.0-M3 Release Notes

🎯 Highlights

📢 Noteworthy

⚠️ Breaking Changes

⭐ New Features

🪲 Bug Fixes

📓 Documentation

🔨 Dependency Upgrades

🔩 Build Updates

🙏 Contributors

spring-projects/spring-ai v2.0.0-M3
Spring AI 2.0.0-M3

on GitHub