Spring AI 2.1

When upgrading to Spring AI 2.1, refer to the Upgrade Notes for newly introduced APIs, deprecated APIs, and breaking changes. Spring AI 2.1 is the release line for Spring Boot 4.2, and the Spring Boot 4.2 upgrade recipe chains this recipe.

The io.arconia.rewrite.spring.ai2.UpgradeSpringAi_2_1 recipe automates the changes introduced in Spring AI 2.1. You can use it to update your project to the latest Spring AI 2.1.x release.

The recipe will:

  • Upgrade all org.springframework.ai dependencies to the 2.1.x release line.

  • Rename Spring AI configuration properties that changed, and comment out those removed so you can address them manually, such as the MCP server SSE endpoint properties.

  • For Anthropic: remove the temperature, topP, and topK calls from AnthropicChatOptions builders, since Anthropic API version 2026-10-21 rejects these options and Spring AI discards their values.

  • For DeepSeek: replace the DeepSeekAssistantMessage.prefixAssistantMessage() factory methods, removed in Spring AI 2.1, with the equivalent DeepSeekAssistantMessage.builder() chain. The builder keeps the code compiling, but DeepSeekAssistantMessage is itself deprecated for removal, so plan to move to a plain AssistantMessage.

  • For MCP (Model Context Protocol): drop the toolCallExceptionClass argument from the constructors of the MCP tool method callbacks, which is ignored since exception dispatch became type-based in Spring AI 2.0.1 and is removed in Spring AI 2.1.

Spring AI 2.1 introduces message parts without requiring source changes: the message constructors and builders keep working, and getText(), getMedia(), and getToolCalls() are now views over the parts. The protected textContent, media, and responses fields of the message classes are deprecated, so subclasses that read them directly should switch to the accessors.

Spring AI 2.1 also deprecates the ChatMemory API in favor of session memory. The upgrade recipe leaves chat memory in place, since it keeps working until Spring AI 3.0. To move an application to session memory, follow the Spring AI migration guide.

See its entry in the Recipe Catalog for the full list of recipes this upgrade applies, each with its options and a before/after example.

Run the Recipe

You can apply this recipe with any OpenRewrite-compatible tool. The tabs below show three of them: the Arconia CLI, the OpenRewrite Gradle plugin, and the OpenRewrite Maven plugin. See Running Recipes for a comparison of when to pick each one.

  • Arconia CLI

  • Gradle

  • Maven

arconia update spring-ai --to-version 2.1

First, create an init.gradle file in your project root with the following content.

initscript {
    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath("org.openrewrite:plugin:latest.release")
    }
}

rootProject {
    plugins.apply(org.openrewrite.gradle.RewritePlugin)
    dependencies {
        rewrite("io.arconia.migrations:rewrite-spring:latest.release")
    }

    // Remove when project repositories are disabled
    afterEvaluate {
        if (repositories.isEmpty()) {
            repositories {
                mavenCentral()
            }
        }
    }

    configurations.named("rewrite") {
        canBeConsumed = false
    }
}

Then, run the following command.

./gradlew rewriteRun \
    --init-script init.gradle \
    --no-parallel \
    -DactiveRecipe=io.arconia.rewrite.spring.ai2.UpgradeSpringAi_2_1

You can remove the init.gradle file afterwards.

./mvnw -U org.openrewrite.maven:rewrite-maven-plugin:run \
  -Drewrite.recipeArtifactCoordinates=io.arconia.migrations:rewrite-spring:LATEST \
  -Drewrite.activeRecipes=io.arconia.rewrite.spring.ai2.UpgradeSpringAi_2_1