Spring AI 2.0

When upgrading to Spring AI 2.0, refer to the Upgrade Notes to find out about newly introduced APIs, deprecated APIs, and information about breaking changes.

The io.arconia.rewrite.spring.ai.UpgradeSpringAi_2_0 recipe automates most of the changes introduced in Spring AI 2.0. You can use it to update your project to the latest Spring AI 2.0.x release.

The recipe will:

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

  • Rename Spring AI configuration properties to match the new property names.

  • Migrate to the new ChatOptionsBuilder API.

  • Rename ChatClient.ChatClientRequestSpec.toolCallbacks(…​) to tools(…​) to align with the new tool-calling API.

  • Apply the dependency rename from spring-ai-advisors-vector-store to spring-ai-vector-store-advisor.

  • Update type references such as PromptChatMemoryAdvisor → MessageChatMemoryAdvisor and OpensearchContainer → OpenSearchContainer.

  • For Anthropic: migrate to the new AnthropicChatModelBuilder, and relocate Anthropic types (AnthropicCacheOptions, AnthropicCacheStrategy, AnthropicCacheTtl, CacheEligibilityResolver, CitationDocument → AnthropicCitationDocument) from org.springframework.ai.anthropic.api to org.springframework.ai.anthropic.

  • For MCP (Model Context Protocol): adopt the new spring-ai-mcp-annotations artifact in place of org.springaicommunity:mcp-annotations; move the MCP Spring WebFlux and WebMvc artifacts from io.modelcontextprotocol.sdk to org.springframework.ai; relocate the community MCP packages under org.springaicommunity.mcp (annotation, context, method, provider) to the corresponding sub-packages of org.springframework.ai.mcp.annotation; and move MCP transport types from io.modelcontextprotocol to the corresponding org.springframework.ai.mcp.{client,server}.{webflux,webmvc}.transport packages.

  • For OpenAI: rename the spring-ai-openai-sdk and spring-ai-starter-model-openai-sdk artifacts to drop the -sdk suffix, and remove the Azure OpenAI artifacts (spring-ai-azure-openai, spring-ai-starter-model-azure-openai, spring-ai-autoconfigure-model-azure-openai), which have been discontinued in Spring AI 2.0.

  • For Google: relocate GoogleGenAiEmbeddingConnectionDetails to the org.springframework.ai.google.genai.embedding sub-package.

  • Remove the discontinued spring-ai-hanadb-store and spring-ai-spring-cloud-bindings artifacts.

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

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

initscript {
    repositories {
        maven { url "https://plugins.gradle.org/m2" }
    }
    dependencies {
        classpath("org.openrewrite:plugin:latest.release")
    }
}

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

    afterEvaluate {
        if (repositories.isEmpty()) {
            repositories {
                mavenCentral()
            }
        }
    }

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

Then, run the following command.

./gradlew rewriteRun \
    --init-script init.gradle \
    -DactiveRecipe=io.arconia.rewrite.spring.ai.UpgradeSpringAi_2_0

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.ai.UpgradeSpringAi_2_0