Spring AI 2.0 RC Released: Migration Guide, New Features, and LangChain4j Comparison

Release Announcement

Spring AI 2.0.0‑RC1 published to Maven Central on 2026‑06‑06 (RC2 is the latest). The API is locked for stabilization and can be used for pre‑production validation.

RC Meaning

Although labeled pre‑release, the API is stable and suitable for validation. The original GA date (2025‑05‑28) was postponed to June 2026.

Upgrade Barrier

Spring AI 2.0 is rebuilt on Spring Boot 4.0; upgrading requires moving to Boot 4.0. Baseline: Java 17 (Java 21 strongly recommended), Jakarta EE 11, Spring Boot 4.0 GA, Spring Framework 7.0. Spring Boot 3.5 and Spring Framework 6.2 reach EOL on 2026‑06‑30, so long‑term security support requires the upgrade.

Typical migration path for Java 17 + Spring Boot 3.x projects: first upgrade to Boot 3.5 to resolve deprecated APIs, then jump to Boot 4.0. Direct version jumps may cause compile‑time API removal surprises.

Key breaking changes :

Jackson 3 replaces Jackson 2; package moves from com.fasterxml.jackson to tools.jackson. Default date format and property order change, requiring full integration testing.

All setter methods are deprecated; configuration now uses a Builder pattern (e.g., options.setTemperature(0.7) no longer compiles).

MessageWindowChatMemory eviction now stops at the nearest user‑message boundary instead of cutting in‑mid‑conversation.

JdbcChatMemoryRepository exposes the timestamp field for programmatic access.

Core Updates

Tool‑Calling Reconstruction

In 1.x each ChatModel contained its own tool‑execution loop (methods like internalToolExecutionEnabled and toolNames()), causing tangled code and poor reuse. 2.0 extracts the loop to an external mechanism and recommends ToolCallingAdvisor for handling tool execution.

All ChatModel implementations drop the internal loop flag; tools must be passed explicitly via ToolCallback. The former ToolCallAdvisor is renamed ToolCallingAdvisor. A new ToolSearchToolCallingAdvisor supports on‑demand discovery of VectorStore, Lucene, or Regex tools.

// 1.x style (does not compile in 2.0)
public class MyService {
    @Autowired private OpenAiChatClient client;
    public String callWithTools(String q) {
        return client.call(q); // tool loop inside model
    }
}

// 2.0 RC recommended style
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.tool.ToolCallback;
import org.springframework.ai.tool.ToolCallingAdvisor;
@Service
public class MyAIAgent {
    private final ChatClient chatClient;
    private final ToolCallingAdvisor toolCallingAdvisor;
    public MyAIAgent(ChatClient.Builder builder, ToolCallingAdvisor advisor) {
        this.chatClient = builder.build();
        this.toolCallingAdvisor = advisor;
    }
    public String askWithTools(String q) {
        ToolCallback orderTool = ToolCallback.from("queryOrder", (id) -> myOrderService.queryOrder(id));
        return chatClient.prompt()
            .user(q)
            .tools(orderTool)
            .advisors(toolCallingAdvisor)
            .call()
            .content();
    }
}

MCP (Model Context Protocol) Native Integration

MCP, previously a separate dependency, is now part of Spring AI core. Adding @McpTool to any bean method automatically exposes the tool via a zero‑boilerplate HTTP endpoint ( POST /mcp) without writing a controller.

Supported transport protocols: Stdio, Streamable HTTP (default), and SSE. The default registers the endpoint at startup.

@Component
public class OrderMCPTools {

    @McpTool(description = "Query order by number")
    public Order queryOrderByNumber(@McpToolParam(description = "Order number (ORD-123)") String orderNumber) {
        return orderRepository.findByOrderNumber(orderNumber);
    }

    @McpTool(description = "Get current stock count")
    public int getStockCount(@McpToolParam(description = "SKU code") String skuCode) {
        return inventoryService.getStock(skuCode);
    }

    @McpTool(description = "Create new order")
    public Order createOrder(@McpToolParam(description = "List of items") List<OrderItem> items,
                             @McpToolParam(description = "Shipping address") String address) {
        return orderService.create(items, address);
    }
}

After starting the application, http://localhost:8080/mcp lists all registered tools and resources.

Structured‑Output Enhancement

RC1 adds EntityParamSpec to ChatClient.entity(), enabling native structured output and schema validation.

OrderInfo orderInfo = chatClient.prompt()
    .user("Extract order info from the following text: " + orderText)
    .options(ChatOptions.builder().model("gpt-4o").build())
    .entity(OrderInfo.class, spec -> spec
        .withNativeStructuredOutput(true)
        .withValidation(true));

Record definition example:

public record OrderInfo(
    @JsonPropertyDescription("Order number, format ORD-123") String orderNumber,
    @JsonPropertyDescription("Total amount") BigDecimal totalAmount,
    @JsonPropertyDescription("Order status") OrderStatus status) {}

Hands‑On Code Walkthrough

Step 1: Create a Spring Boot 4 project (start.spring.io) with dependencies Spring Web and Spring AI OpenAI Starter.

Step 2: Add the MCP server starter dependency:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
</dependency>

Step 3: Configure application.yml with API key and model settings.

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
    chat:
      model: gpt-4o
      options:
        temperature: 0.7
        max-tokens: 2048

Step 4: Minimal controller:

@RestController
@RequiredArgsConstructor
public class AIChatController {
    private final ChatClient chatClient;

    @GetMapping("/chat")
    public String chat(@RequestParam String question) {
        return chatClient.prompt()
            .user(question)
            .call()
            .content();
    }

    @GetMapping(value = "/stream", produces = "text/html;charset=utf-8")
    public Flux<String> streamChat(@RequestParam String question) {
        return chatClient.prompt()
            .user(question)
            .stream()
            .content();
    }
}

Running the app and calling http://localhost:8080/chat?question=Write+quick+sort+in+Java returns annotated Java code within seconds.

Pros and Cons

Advantages

Seamless Spring ecosystem integration; low learning curve for Spring‑experienced teams.

MCP is a first‑class citizen with support for 50+ models.

Type‑safe, record‑based structured output replaces fragile JSON parsing.

Cloud‑native and AOT‑friendly, leading to faster startup and lower memory usage.

Limitations

High migration cost: Java 21, Boot 4, Builder‑only setters, Jackson 3 serialization changes require full regression testing.

Domestic model support narrowed; some Chinese providers were removed, requiring OpenAI‑compatible adapters.

Advanced features such as multi‑agent collaboration and edge‑runtime support are still on the roadmap.

Comparison with LangChain4j

API style : Spring AI uses fluent Builder and DI; LangChain4j uses declarative interface proxy (AiServices). Choose LangChain4j for declarative simplicity, Spring AI for Spring consistency.

Framework binding : Spring AI tightly binds to Spring Boot; LangChain4j is framework‑agnostic. Choose LangChain4j when decoupling from Spring is desired.

Technical baseline : Spring AI requires Java 21 + Spring Boot 4; LangChain4j works with Java 17 and flexible boot versions. New greenfield projects favor Spring AI; legacy projects favor LangChain4j.

MCP support : Spring AI provides native integration; LangChain4j needs separate configuration. For exposing tools to MCP clients, Spring AI wins.

Ecosystem maturity : Spring AI is at RC stage; LangChain4j has 68 % Java developer adoption (JetBrains 2025 Q1). For stability and community resources, LangChain4j is ahead.

Model coverage : Spring AI offers 50+ official integrations; LangChain4j offers 30+ community‑driven models. Both are strong.

Recommendations

Start a new Spring Boot 4 + Java 21 project and use Spring AI 2.0 RC for native MCP.

For an existing Spring Boot 3.x codebase that cannot upgrade the baseline, LangChain4j offers a less invasive path.

For non‑Spring stacks, LangChain4j’s framework‑neutral design is preferable.

Conclusion

Spring AI 2.0 unifies Spring Boot 4, Java 21 virtual threads, MCP, and externalized tool‑calling, providing a production‑ready way for Java developers to build AI‑enhanced applications.