Spring AI 2.0: Java Agents, MCP & Migration Guide

Spring AI 2.0 is a meaningful upgrade for Java teams building AI applications—not because it adds another model wrapper, but because it moves tool execution, progressive tool discovery, structured-output repair, and MCP integration into a more composable Spring-native architecture. The release is built for Spring Boot 4.x and Spring Framework 7, and the migration from Spring AI 1.1.x includes breaking changes that should be treated as an application upgrade project.

The short version: use Spring AI 2.0 when your team already operates Spring Boot services and wants portable model access, agent tool loops, RAG, MCP servers, or durable AI memory without creating a separate Python platform. Start with a small vertical slice, pin the 2.0 dependencies, migrate tool execution to ToolCallingAdvisor, and test memory behavior explicitly.

What Spring AI 2.0 changes

Spring AI 2.0 reached GA on June 12, 2026. The official Spring announcement sets a new baseline around Spring Boot 4.0/4.1, Spring Framework 7, Jackson 3, JSpecify null-safety annotations, immutable option builders, and a narrower set of core provider integrations. The project’s official GitHub release confirms the GA tag, MCP SDK 2.0.0 upgrade, Spring Boot 4.1.0 dependency update, and fixes for tool-call metadata and chat-memory repositories.

This is not a drop-in patch for every 1.x application. The official upgrade notes document renamed modules, moved classes, removed options, and changed advisor behavior. Teams should budget for compilation fixes plus behavioral tests around tool loops, memory, streaming, and provider configuration.

Why the new tool loop matters for agents

An agent is not just a chat endpoint with a system prompt. It is a loop that may select a tool, execute application code, inspect the result, and continue until it can answer or must stop. In Spring AI 1.x, the loop was coupled to individual chat-model implementations. That made it difficult to add consistent authorization, tracing, retries, evaluation, or a custom stopping policy.

Spring AI 2.0 lifts the loop into the advisor chain. ChatClient can auto-register ToolCallingAdvisor, which owns the round trip between the model and tool callbacks. An application can opt out when it needs to drive the loop manually through ChatModel and ToolCallingManager.

That separation is useful operationally. A team can place logging or approval logic around the advisor, set a custom ToolExecutionEligibilityChecker, or disable automatic tool calling globally with spring.ai.chat.client.tool-calling.enabled=false. The model still receives tool definitions when automatic execution is disabled; the application decides what happens after a tool-call response.

1var advisor = ToolCallingAdvisor.builder()
2    .toolExecutionEligibilityChecker(response ->
3        response != null
4            && response.hasToolCalls()
5            && !"stop".equals(
6                response.getResult().getMetadata().getFinishReason()))
7    .build();

The code above follows the official 2.0 upgrade documentation’s extension point. In production, the checker is only one control: tools still need application-level authorization, input validation, rate limits, idempotency, and audit logging.

Progressive tool discovery for large catalogs

Registering every business capability on every request can inflate prompts and make tool selection less reliable. Spring AI 2.0 adds ToolSearchToolCallingAdvisor for this case. It indexes the available tools once per session and exposes relevant definitions on demand through keyword, Lucene, or vector indexing.

The official upgrade notes show the new starter and property model:

1<dependency>
2  <groupId>org.springframework.ai</groupId>
3  <artifactId>spring-ai-starter-tool-search-advisor</artifactId>
4</dependency>

1spring.ai.chat.client.tool-search-advisor.enabled=true
2spring.ai.chat.client.tool-search-advisor.tool-index-type=regex

Use the regex index first because it adds no search dependency. Move to Lucene or vector indexing only after measuring tool-catalog size, retrieval precision, and latency. Progressive disclosure reduces the number of definitions sent to the model; it does not guarantee correct tool selection. Build an evaluation set containing ambiguous names, dangerous tools, and authorization boundaries.

MCP becomes a first-class Spring integration

Spring AI 2.0 ships with MCP Java SDK 2.0.0 and brings MCP annotations into the Spring AI project. @McpTool, @McpResource, and @McpPrompt let Spring services expose capabilities through annotated methods. The official Spring announcement also describes unified request contexts for logging, progress reporting, sampling, and elicitation.

Transport choice now matters. Streamable HTTP is the default for remote MCP servers, while stateless Streamable HTTP can improve horizontal scalability by removing server-side session affinity. Stateless deployment can also reduce access to bidirectional session features, so it is not automatically the right choice for every interactive workflow. STDIO remains appropriate for local process integrations.

A practical architecture is to keep the MCP boundary narrow: expose domain operations rather than raw database access, authenticate the caller before executing a tool, and return structured errors that the agent can interpret without leaking internal stack traces.

Visual credit: original diagram by the author; based on Spring AI 2.0 official architecture and upgrade documentation.

Memory and structured output require new tests

Two changes deserve special attention during migration.

First, the default tool loop now manages conversation history internally across iterations. The memory advisor normally stores the final user/assistant exchange rather than every intermediate tool-call message, because many repositories do not support tool message types. If your application needs memory inside the loop, the upgrade notes show that you must explicitly change advisor ordering, disable internal conversation history, and use a repository that supports the message types safely.

Second, structured output can self-correct through StructuredOutputValidationAdvisor, but retries are not free. A malformed response may trigger another model call, increasing latency and cost. Record validation failures, cap retries, and return a safe fallback when the model cannot produce a valid domain object.

For teams using Azure, Microsoft separately documents vendor-maintained Azure Cosmos DB modules for Spring AI 2.0: a vector store, auto-configuration, durable chat memory, and memory auto-configuration. Its stated requirements include Java 21+, Spring Boot 4.1+, Spring AI 2.0+, and an Azure Cosmos DB NoSQL account. Treat those modules as an optional persistence path—not a reason to couple every Spring AI application to Cosmos DB.

A safer migration sequence

1. Freeze the current behavior. Capture tests for provider calls, tool execution, memory persistence, streaming, and structured-output parsing.
2. Upgrade the platform baseline. Confirm the application’s Spring Boot, Spring Framework, Java, Jackson, and provider SDK compatibility before changing agent behavior.
3. Resolve compilation changes. Follow the official upgrade notes for renamed modules, moved ToolSearchToolCallingAdvisor, removed internalToolExecutionEnabled, and removed streamToolCallResponses.
4. Make tool execution explicit. Decide whether ChatClient auto-registration is acceptable. Otherwise, drive the loop manually and add policy checks around execution.
5. Control the tool catalog. Start with the default advisor for a small catalog. Add progressive discovery only after measuring prompt size, retrieval accuracy, and latency.
6. Re-test memory. Verify what is stored before, during, and after a tool loop. Test restarts, concurrent conversations, and repository-specific message support.
7. Add MCP incrementally. Expose one read-only, least-privilege capability first. Test authentication, timeouts, error mapping, and transport behavior before adding writes.
8. Measure real workloads. Track model latency, tool latency, validation retries, token usage, and cost per completed task—not just time to first token.

For a broader systems view, compare this approach with the site’s MCP stateless migration guide, production MCP and multi-agent architecture guide, and AI agent stacks guide. Teams evaluating agent safety should also read the StepSecurity Dev Machine Guard analysis.

Spring AI 2.0 compared with a Python-first stack

Spring AI does not make Python frameworks obsolete. Python remains attractive for experimentation, data-science workflows, and teams already invested in Python-native agent libraries. Spring AI’s advantage is architectural continuity: an enterprise Java team can reuse Spring Security, dependency injection, observability, transaction boundaries, deployment practices, and existing domain services.

The choice should follow the system around the model. If the important work happens in Java services and enterprise data, Spring AI reduces integration distance. If the work depends on Python-specific research libraries or rapidly changing experimental orchestration, a Python service may be the better boundary. A hybrid system is often sensible: keep model experimentation separate, then expose stable capabilities through authenticated APIs or MCP.

Common migration errors

Leaving 1.x tool flags in the codebase

internalToolExecutionEnabled was removed. Delete the old option and choose either advisor-managed execution or a manually controlled loop.

Assuming stateless MCP means feature parity

Stateless Streamable HTTP can scale more easily, but session-dependent or bidirectional interactions may need a stateful transport. Test the protocol capabilities your client actually uses.

Storing every intermediate message by default

Tool-call messages can be unsupported or noisy in a repository. Decide deliberately whether intermediate history is needed and use a compatible memory implementation.

Treating retries as reliability without a budget

Structured-output repair and agent loops can multiply model calls. Set maximum iterations, timeout budgets, and per-request cost limits.

FAQ

Is Spring AI 2.0 production-ready?

The 2.0.0 GA release is available from Maven Central and is positioned by the Spring team as a stable foundation. Production readiness still depends on provider, tool, memory, and security testing in your application.

Does Spring AI 2.0 require Spring Boot 4?

The release is designed for Spring Boot 4.0/4.1 and Spring Framework 7. Check the compatibility matrix and your application dependencies before upgrading.

Should every application use ToolSearchToolCallingAdvisor?

No. It is aimed at large tool catalogs. For a small, stable set of tools, ordinary ToolCallingAdvisor is simpler and may be faster.

Is MCP required to use Spring AI agents?

No. Spring AI can call Java tool callbacks without MCP. MCP is useful when capabilities must be shared across clients, runtimes, or agent products.

What should teams monitor first?

Monitor end-to-end task latency, model and tool-call counts, validation retries, failed tool executions, authorization denials, token usage, and the percentage of tasks requiring human intervention.

Conclusion

Spring AI 2.0 gives Java developers a more credible foundation for agentic applications by separating model access from the tool loop, adding progressive tool discovery, improving structured-output recovery, and making MCP a first-class integration. The upgrade is worthwhile when the application already lives in Spring—but it should be approached as a behavioral migration, not a dependency bump.

The safest path is narrow and measurable: migrate one agent, make authorization and tool execution observable, test memory semantics, and add MCP or large-catalog discovery only when the workload justifies it.

Sources

• Spring AI 2.0.0 GA announcement — official Spring primary source.
• Spring AI 2.0.0 GitHub release — official release record and changelog.
• Spring AI 2.0 upgrade notes — official migration and API details.
• Spring AI 2.0 and Azure Cosmos DB — Microsoft engineering coverage of vendor-maintained modules.
• Spring AI 2.0 coverage — independent secondary reporting by Visual Studio Magazine.

Visual credits: Mermaid diagram is original. No third-party screenshots or unverified media used.

Visual: Integration request flow

This original architecture diagram shows how the components described in this article fit together. It is a practical reference for deciding where authentication, validation, retries, and observability belong.

Visual reading: keep the client, policy boundary, external service, and result validation separate. This prevents an AI-generated tool call from becoming an unchecked side effect.