Master Spring AI Alibaba 1.0: Upgrade Guide, New Features & Real‑World Code

What is Spring AI Alibaba?

Spring AI is an AI development framework maintained by the official Spring team that lets you build AI applications with less code. Spring AI Alibaba extends Spring AI by deeply integrating Alibaba's large‑model platform and various components, and adds support for workflows and multi‑agent applications.

Because it is compatible with Spring AI, richer in features, updated quickly, and has clearer documentation, it is a good choice for Chinese developers.

The official project provides a ready‑made intelligent‑agent debugging sandbox with open‑source code, allowing you to run a demo project via a Docker command and experience core capabilities such as chat bots, multi‑turn dialogue, image generation, tool calling, RAG knowledge base, and MCP integration.

What are the major updates in the new version?

The Spring AI Alibaba 1.0 release can be summed up with one word: breakthrough . The most notable updates are:

1. Graph Multi‑Agent Framework

This is the headline feature. With the Graph framework, developers can quickly build complex workflows and multi‑agent applications without dealing with low‑level orchestration or context‑memory management.

For example, a "media auto‑posting tool" can be created using a visual AI agent platform. The following code shows a simple workflow definition:

// Create workflow
StateGraph stateGraph = new StateGraph("Content Generation Workflow", stateFactory)
    .addNode("start", node_async(new StartNode()))
    .addNode("topic_generation", node_async(new TopicGenerationNode()))
    .addNode("content_collection", node_async(new ContentCollectionNode()))
    .addNode("content_integration", node_async(new ContentIntegrationNode()))
    .addNode("api_publish", node_async(new ApiPublishNode()))
    .addNode("result_output", node_async(new ResultOutputNode()))
    .addEdge(START, "start")
    .addEdge("start", "topic_generation")
    .addEdge("topic_generation", "content_collection")
    .addEdge("content_collection", "content_integration")
    .addEdge("content_integration", "api_publish")
    .addEdge("api_publish", "result_output")
    .addEdge("result_output", END);

The example is simple, but the underlying agent workflow concepts involve collaboration, task decomposition, routing strategies, and state management.

2. Ecosystem Integration

Spring AI Alibaba 1.0 further blends traditional backend development with emerging AI capabilities by integrating more components and cloud services, helping legacy systems adopt AI faster.

Typical integration cases include:

1) Nacos for MCP management

Nacos is a popular service‑registry center. By registering MCP services in Nacos, AI projects can discover and invoke them dynamically, achieving centralized management and hot‑updates.

2) Nacos for Prompt management

Instead of hard‑coding prompts, developers can store prompt templates in Nacos. The application pulls the latest prompt at startup, and any change in Nacos is reflected in real time without restarting the service.

3) AI model and cloud knowledge‑base integration

Seamless connection to Alibaba Cloud Bailei enables one‑click access to large models such as Tongyi Qianwen, and the cloud knowledge‑base platform lets you upload and split documents, then query the knowledge base with just a few lines of code.

4) Observability support

Spring AI provides observability out of the box, exposing metrics like request count, latency, and token consumption. These can be fed into Alibaba Cloud ARMS, Zipkin, or other monitoring tools.

3. Cutting‑edge Use Cases

Recent projects showcase the framework’s versatility:

JManus – a Java version of the OpenManus general‑purpose agent platform.

NL2SQL – a natural‑language‑to‑SQL tool for Java developers.

DeepResearch – a multi‑agent research assistant that automates web search, crawling, data analysis, and report writing.

4. Detail Optimizations

Session memory now supports JDBC, Redis, Elasticsearch, and other storage plugins, enabling persistent conversation histories.

How to upgrade the framework version?

The upgrade process is demonstrated with a personal open‑source AI super‑agent project, moving from 1.0.0‑M6.1 to 1.0.0.2.

Step 1: Dependency updates

Both the main project and the MCP service sub‑project need their Maven dependencies refreshed.

Main project dependency update

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.alibaba.cloud.ai</groupId>
      <artifactId>spring-ai-alibaba-bom</artifactId>
      <version>1.0.0.2</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
  </dependency>
</dependencies>

Also add the Spring AI repositories (snapshot and central portal) to the repositories section and ensure the version number does not include the SNAPSHOT suffix.

MCP service dependency update

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

Step 2: Code fixes

Because of breaking changes, several code areas must be adapted:

Advisor fixes

Update custom advisors such as MyLoggerAdvisor and ReReadingAdvisor to match the new interfaces. Example for MyLoggerAdvisor:

@Slf4j
public class MyLoggerAdvisor implements CallAdvisor, StreamAdvisor {
    @Override
    public String getName() { return this.getClass().getSimpleName(); }
    @Override
    public int getOrder() { return 0; }
    private ChatClientRequest before(ChatClientRequest request) {
        log.info("AI Request: {}", request.prompt());
        return request;
    }
    private void observeAfter(ChatClientResponse response) {
        log.info("AI Response: {}", response.chatResponse().getResult().getOutput().getText());
    }
    @Override
    public ChatClientResponse adviseCall(ChatClientRequest req, CallAdvisorChain chain) {
        req = before(req);
        ChatClientResponse resp = chain.nextCall(req);
        observeAfter(resp);
        return resp;
    }
    @Override
    public Flux<ChatClientResponse> adviseStream(ChatClientRequest req, StreamAdvisorChain chain) {
        req = before(req);
        Flux<ChatClientResponse> flux = chain.nextStream(req);
        return new ChatClientMessageAggregator().aggregateChatClientResponse(flux, this::observeAfter);
    }
}

Similarly adjust ReReadingAdvisor to rewrite prompts and add context parameters.

Tool‑calling fixes

Change the import from org.springframework.ai.tool.ToolCallbacks to org.springframework.ai.support.ToolCallbacks and update the tool registration code to use .toolCallbacks(toolCallbackProvider). Also modify ToolCallAgent to disable the built‑in tool execution and configure options via the builder pattern.

RAG knowledge‑base fixes

Update the package of RetrievalAugmentationAdvisor to org.springframework.ai.rag.advisor, adjust the DashScopeApi construction to the builder style, and add the spring-ai-advisors-vector-store dependency for vector‑store support.

Conversation memory fixes

Switch to the new builder‑based memory configuration, e.g.:

MessageWindowChatMemory chatMemory = MessageWindowChatMemory.builder()
    .chatMemoryRepository(new InMemoryChatMemoryRepository())
    .maxMessages(20)
    .build();

chatClient = ChatClient.builder(dashscopeChatModel)
    .defaultSystem(SYSTEM_PROMPT)
    .defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory).build())
    .build();

Update conversation‑ID keys and adjust the file‑based memory implementation to match the new ChatMemory.get(String conversationId) signature.

Other minor fixes

Update the import for KeywordMetadataEnricher to

org.springframework.ai.model.transformer.KeywordMetadataEnricher

.

Conclusion

The Spring AI Alibaba upgrade touches many areas—dependency versions, advisor APIs, tool‑calling, RAG, and memory handling—requiring thorough testing. All changes have been open‑sourced on GitHub with clear commit history for reference.