Spring AI Alibaba: a Java framework for agents, graphs and multi-agent workflows

The gap Spring AI Alibaba fills for Java teams

Spring AI gives Java developers a model abstraction: chat clients, tool calling, MCP. What it does not give you is a runtime for an agent that runs for minutes, calls tools, branches on results, and stops to ask a human. That is the space Spring AI Alibaba occupies. The README describes it as "a production-ready framework for building Agentic, Workflow, and Multi-agent applications", and the repository splits that claim across three artifacts: an Agent Framework, a Graph runtime, and an Admin platform.

The audience is narrow and specific. You are writing Spring Boot services in Java, you already depend on Spring AI for model access, and you need more than a request-response chat call. The built-in patterns named in the README are SequentialAgent, ParallelAgent, RoutingAgent and LoopAgent. Those are orchestration shapes, not model wrappers, and they are the reason to pick this over plain Spring AI.

The project is Apache-2.0 and the last push to main was on 2026-09-16, so the repository is not dormant. Note the release cadence, though: the most recent release is v2.0.0-M1.1 from 2026-06-25, and the line before it is v1.1.2.2 from 2026-03-10. A milestone release sitting at the top of the list is a signal to check which line you are pinning.

Agent Framework, Graph runtime and Admin: how the pieces relate

The README is explicit about the dependency direction: "Spring AI Alibaba Graph serves as the underlying runtime of the Agent Framework". So the Agent Framework is the convenient surface, and Graph is the machinery underneath. If you use ReactAgent or one of the four orchestration patterns, you are still running on the graph runtime, which supplies persistence, workflow orchestration and streaming for long-running stateful agents.

Graph is also a public API in its own right. The README points to a separate Graph quick-start and says users can build "more flexible multi-agent workflows based on the Graph API", with conditional routing, nested graphs, parallel execution and state management. Export to PlantUML and Mermaid is listed as a feature, which matters more than it sounds: a workflow you can render is a workflow you can review in a pull request.

The third piece, Spring AI Alibaba Admin, is a separate concern. The README calls it "a one-stop Agent platform that supports visualized Agent development, observability, evaluation, and MCP management", and says it integrates with low-code platforms like Dify so DSL can be migrated into a Spring AI Alibaba project. It can also export a standalone Java project. Treat Admin as an optional layer, not a prerequisite: the chatbot path in the README never touches it.

Context engineering is where the framework makes its most opinionated choices. The README lists human-in-the-loop, context compaction, context editing, model and tool call limits, tool retry, planning and dynamic tool selection as built-in policies. In practice this means the framework has decided that long-running agents fail because of context growth and unbounded tool loops, and it ships defaults for both. Whether those defaults match your workload is something you will only learn by reading the hooks documentation.

Installing Spring AI Alibaba and running the chatbot example

The prerequisites are short: JDK 17 or newer, plus an API key from the model provider you choose. The README's walkthrough uses DashScope, so the first step is getting a key from Aliyun Bailian and exporting it. The environment variable name is fixed by the starter.

export AI_DASHSCOPE_API_KEY=your-api-key

With the key in place, clone the repository shallowly and run the community chatbot example. The README notes that a local Maven installation is optional because the wrapper is included.

git clone --depth=1 https://github.com/alibaba/spring-ai-alibaba.git
cd spring-ai-alibaba
./mvnw -pl examples/chatbot spring-boot:run

Once the application is up, the README points you at http://localhost:8080/chatui/index.html in a browser. That page is the chat UI for the example, and it is the fastest way to confirm your API key works and the starter is wired correctly.

If you are adding the framework to an existing project rather than running an example, the README shows a Maven dependency block. It uses two artifacts: the agent framework and a model starter. The version numbers in that block are worth reading carefully, because the two entries do not match.

<dependencies>
  <dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-agent-framework</artifactId>
    <version>1.1.2.0</version>
  </dependency>
  <dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
    <version>1.1.2.1</version>
  </dependency>
</dependencies>

The README's own comment says the DashScope starter is an assumption and directs you to the docs for choosing a different model. Related search terms like spring ai alibaba starter dashscope and spring ai alibaba openai map onto that choice: the starter is what binds the framework to a provider. The README does not document a rollback procedure for a failed agent run, so plan for that gap before you put anything stateful in production.

Where Spring AI Alibaba is the wrong tool

The framework assumes a Spring context. The quick start runs through spring-boot:run and the dependency block is Spring-managed. If your service is plain Java without Spring Boot, the starters and auto-configuration are overhead you would be fighting, and the Graph runtime is the only piece you could reasonably pull in alone.

Version churn is a real cost. The README's dependency example pairs 1.1.2.0 with 1.1.2.1, the Maven Central badge points at 1.1.2.2, and the newest release is a 2.0.0 milestone. A milestone at the head of the release list means the API surface on the 2.x line is not settled. If you need a stable contract for a long-lived service, pin to the 1.1.2.x line and read the CHANGELOG before moving.

There is also a scope trap. The repository contains an admin platform, a studio, a sandbox, a BOM, boot starters and a tools directory. The README's architecture section describes Admin as a platform with visualization, observability and evaluation. If what you actually want is a hosted agent-building UI, you are adopting a much larger surface than the agent framework, and the README does not document the operational requirements of running Admin. The docs site is the place to check that, not the README.

Finally, the README is thin on failure semantics. It lists tool retry and call limits as context engineering policies but does not describe what happens when a retry budget is exhausted, or how a partially completed graph run is recovered. For a framework whose selling point is long-running stateful agents, that is the documentation gap to probe first.

Spring AI Alibaba compared with LangChain4j and plain Spring AI

The most useful comparison is against Spring AI itself, because they are not competitors so much as layers. Spring AI gives you the model abstraction and tool calling. Spring AI Alibaba adds orchestration (SequentialAgent, ParallelAgent, RoutingAgent, LoopAgent), a graph runtime with persistence and streaming, and context engineering policies. If your application is one prompt in, one answer out, plain Spring AI is the smaller dependency and you should stay there.

Against LangChain4j the difference is architectural. LangChain4j is a general Java LLM library with its own abstractions for chains, tools and memory. Spring AI Alibaba is built on Spring AI's concepts and exposes its orchestration through a graph runtime, with the Agent Framework as the ergonomic layer. The README frames the graph as the substrate for stateful, long-running agents and offers PlantUML and Mermaid export from the workflow definition. That export is a concrete difference: workflows you can render as diagrams are easier to review than imperative chain code.

The AgentScope example in the repository is worth noting for a different reason. Its presence suggests the project treats other agent frameworks as something to interoperate with or learn from, not only to replace. If you are already running AgentScope elsewhere, the examples directory is where to look before assuming a rewrite is required.

Licence, maintenance and the cost of upgrading

The project is Apache-2.0, the same licence as Spring AI and most of the Spring portfolio. That generally means you can use it commercially and modify it, subject to the usual notice and attribution conditions. This is not legal advice; read LICENSE in the repository root and your own counsel's guidance if you redistribute modified sources.

On maintenance, the evidence in the repository is concrete: the last push to main was on 2026-09-16, and the repository is not archived. The release history shows v1.1.2.2 on 2026-03-10 and v2.0.0-M1.1 on 2026-06-25. The governance files in the root, GOVERNANCE.md, COMMITTERS.md and PMC_MEMBERS.md, indicate an Apache-style project structure rather than a single-vendor dump.

Upgrade cost is dominated by the 1.x to 2.x transition. A milestone release means you should expect the 2.x API to move, and the README does not document a migration path between the two lines. The CHANGELOG.md in the repository root is the artifact to read before any upgrade, and the BOM module (spring-ai-alibaba-bom) is the mechanism to keep artifact versions aligned once you pick a line. The practical cost is not the dependency swap; it is auditing your agent definitions and graph topologies against whatever changed in the runtime.

Editorial conclusion

Adopt Spring AI Alibaba if your stack is Java and Spring Boot, and you need orchestration patterns, graph state or human-in-the-loop rather than a single chat endpoint. Do not adopt it if you want a Python-first agent ecosystem or you cannot run JDK 17 and pull artifacts from Maven Central. Before committing, verify the artifact versions you will actually pin, since the README mixes 1.1.2.0 and 1.1.2.1 in the same dependency block, and check the CHANGELOG for what changed between v1.1.2.2 and v2.0.0-M1.1.

Frequently asked questions

Official sources

1. alibaba/spring-ai-alibaba on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases