Repository: alibaba/spring-ai-alibaba

Stars: 9289

CLAUDE.md Copy Chapter

CLAUDE.md - AI Assistant Guide for Spring AI Alibaba

This file provides guidance for AI assistants working with the Spring AI Alibaba codebase.

Project Overview Copy Chapter

Spring AI Alibaba is a production-ready framework for building Agentic, Workflow, and Multi-agent applications. It is an implementation of the Spring AI framework tailored for Alibaba Cloud services and components. It provides a comprehensive ecosystem for developing AI-powered applications with built-in context engineering and human-in-the-loop support.

Key Features:

- Multi-Agent Orchestration with built-in patterns
- Context Engineering with human-in-the-loop, context compaction, editing, model call limits
- Graph-based workflow with conditional routing, nested graphs, parallel execution
- A2A (Agent-to-Agent) support with Nacos integration
- Rich model support (DashScope, OpenAI, DeepSeek) and MCP (Model Context Protocol)
- One-stop visual agent platform

Repository Structure Copy Chapter

spring-ai-alibaba/
├── spring-ai-alibaba-agent-framework/ # Multi-agent framework (Sequential, Parallel, Routing, etc.)
├── spring-ai-alibaba-graph-core/      # Runtime providing persistence, workflow orchestration, state mgmt
├── spring-ai-alibaba-studio/          # Embedded UI for debugging agents visually
├── spring-ai-alibaba-admin/           # One-stop Agent platform (visual dev, observability, MCP mgmt)
├── spring-ai-alibaba-bom/             # Bill of Materials for dependency management
├── spring-boot-starters/              # Spring Boot Starters
│   ├── spring-ai-alibaba-starter-a2a-nacos/     # Nacos A2A communication
│   ├── spring-ai-alibaba-starter-builtin-nodes/ # Built-in workflow nodes
│   ├── spring-ai-alibaba-starter-config-nacos/  # Dynamic config with Nacos
│   └── spring-ai-alibaba-starter-graph-observation/ # Observability
├── examples/                          # Example applications
│   ├── chatbot/                       # Chatbot example
│   ├── deepresearch/                  # Deep research agent example
│   └── documentation/                 # Documentation examples
├── tools/                             # Build and linting tools
└── docs/                              # Documentation

Build System Copy Chapter

Prerequisites Copy Section

- JDK: 17 (Required by java.version property)
- Maven: 3.6+
- Git

Common Build Commands Copy Section

Build the entire project (skip tests)

./mvnw -B package -DskipTests=true
Build a specific module

./mvnw -pl :spring-ai-alibaba-agent-framework -B package -DskipTests=true
Clean project

./mvnw clean
Run tests

./mvnw test
Run linting checks (using Makefile)

make lint
make licenses-check

Architecture & Key Concepts Copy Chapter

Core Components Copy Section

- Agent Framework: Built-in agents like SequentialAgent, ParallelAgent, RoutingAgent, LoopAgent.
- Graph Core: Underlying engine for stateful agents, supporting persistence (PostgreSQL, MySQL, Oracle, MongoDB, Redis, File).
- A2A (Agent-to-Agent): Enables agents to seek and communicate with each other using Nacos as a registry.
- Admin & Studio: Provides visual tools for developing and debugging agent workflows.

Technology Stack Copy Section

- Framework: Spring Boot 3.5.x, Spring AI 1.1.x
- Cloud Integration: Alibaba Cloud DashScope, Nacos (Service Discovery & Config)
- Observability: Spring Cloud Observation (Micrometer/OpenTelemetry)

Code Style & Conventions Copy Chapter

General Guidelines Copy Section

- Follow Spring AI standard code formatting.
- Use Apache 2.0 license headers for all Java files.
- Java 17 features are encouraged (records, switch expressions, text blocks).
- Avoid System.out.println - use SLF4J logging.
- Use final for local variables and parameters where appropriate.
- Use Lombok annotations (@Data, @Slf4j, etc.) to reduce boilerplate.

Linting & Formatting Copy Section

The project uses make for linting tasks:
- make codespell: Checks for spelling errors.
- make yaml-lint: Checks YAML file formatting.
- make licenses-check: Verifies license headers.

License Header Copy Section

/*
 * Copyright 2025-2026 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

Testing Copy Chapter

Frameworks Copy Section

- JUnit 5 (org.junit.jupiter)
- Mockito

Running Tests Copy Section

Run all tests

./mvnw test
Run a specific test class

./mvnw -pl :<module-name> -Dtest=<TestClassName> test

Tips for AI Assistants Copy Chapter

1. JDK Version: Project targets JDK 17. Use appropriate language features.
2. Spring Boot: Uses Spring Boot 3.x. Be aware of jakarta. namespace vs javax..
3. Dependencies: Check spring-ai-alibaba-bom or parent pom for version management.
4. Makefile: Use the Makefile in the root for project maintenance tasks (linting, license checks).
5. Structure: When adding new features, prefer creating or updating modules within spring-ai-alibaba-agent-framework or spring-boot-starters depending on the scope.

Important Links Copy Chapter

- Issues: https://github.com/alibaba/spring-ai-alibaba/issues
- Source: https://github.com/alibaba/spring-ai-alibaba
- Contributing: CONTRIBUTING.md

README.md Copy Chapter

Spring AI Alibaba

<img alt="gitleaks badge" src="https://img.shields.io/badge/protected%20by-gitleaks-blue">

<html>
<h3 align="center">
A production-ready framework for building Agentic, Workflow, and Multi-agent applications.
</h3>
<h3 align="center">
<a href="https://java2ai.com/docs/quick-start/" target="_blank">Agent Framework Docs</a>,
<a href="https://java2ai.com/docs/frameworks/graph-core/quick-start/" target="_blank">Graph Docs</a>,
<a href="https://java2ai.com/ecosystem/spring-ai/reference/concepts/" target="_blank">Spring AI</a>,
<a href="https://github.com/alibaba/spring-ai-alibaba/tree/main/examples" target="_blank">Examples</a>.
</h3>
</html>

Architecture Copy Chapter

<p align="center">
<img src="./docs/imgs/architecture-new.png" alt="architecture" style="max-width: 740px; height: auto" />
</p>

Spring AI Alibaba Admin is a one-stop Agent platform that supports visualized Agent development, observability, evaluation, and MCP management, etc. It also integrates with open-source low-code platforms like Dify, enabling rapid migration from DSL to Spring AI Alibaba project.

Spring AI Alibaba Agent Framework is an agent development framework that can quickly develop agents with builtin Context Engineering and Human In The Loop support. For scenarios requiring more complex process control, Agent Framework offers built-in workflows like SequentialAgent, ParallelAgent, RoutingAgent, LoopAgent.

Spring AI Alibaba Graph serves as the underlying runtime of the Agent Framework, providing essential capabilities such as persistence, workflow orchestration, and streaming required for long-running stateful agents. Compared to the Agent Framework, users can build more flexible multi-agent workflows based on the Graph API.

Core Features Copy Chapter

* Multi-Agent Orchestration: Compose multiple agents with built-in patterns including SequentialAgent, ParallelAgent, RoutingAgent, and LoopAgent for complex task execution.

* Multimodal Support: ReactAgent with text and media input (image understanding). ReactAgent with tool based image or audio generation.

* Voice Agent: WebSocket-based real-time voice agent that supports streaming audio or text input and responds with generated audio.

* Context Engineering: Built-in best practices for context engineering policies to improve agent reliability and performance, including human-in-the-loop, context compaction, context editing, model & tool call limit, tool retry, planning, dynamic tool selection.

* Graph-based Workflow: Graph based workflow runtime and api for conditional routing, nested graphs, parallel execution, and state management. Export workflows to PlantUML and Mermaid formats.

* A2A Support: Agent-to-Agent communication support with Nacos integration, enabling distributed agent coordination and collaboration across services.

* Rich Model, Tool and MCP Support: Leveraging core concepts of Spring AI, supports multiple LLM providers (DashScope, OpenAI, etc.), tool calling, and Model Context Protocol (MCP).

* One-stop Agent Platform: Build agent in a visualized way, deploy agent without code or export as a standalone java project.

<p align="center">
<img src="./docs/imgs/saa-admin.png" alt="architecture" style="max-width: 740px; height: auto" />
</p>

Getting Started Copy Chapter

Prerequisites Copy Section

* Requires JDK 17+.
* Choose your LLM provider and get the API-KEY.

Quickly Run a ChatBot Copy Section

There's a ChatBot example provided by the community at examples/chatbot.

1. Download the code.

git clone --depth=1 https://github.com/alibaba/spring-ai-alibaba.git
	cd spring-ai-alibaba

2. Start the ChatBot.

Before starting, set API-KEY first (visit <a href="https://bailian.console.aliyun.com/?apiKey=1&tab=api#/api" target="_blank">Aliyun Bailian</a> to get API-KEY):

# this example uses 'spring-ai-alibaba-starter-dashscope', visit https://java2ai.com to learn how to use OpenAI/DeepSeek.
	export AI_DASHSCOPE_API_KEY=your-api-key

# Maven installation is optional when using mvnw.
	./mvnw -pl examples/chatbot spring-boot:run

3. Chat with ChatBot.

Open the browser and visit http://localhost:8080/chatui/index.html to chat with the ChatBot.

<p align="center">
<img src="./docs/imgs/chatbot-chat-ui.gif" alt="chatbot-ui" style="max-width: 740px; height: auto" />
</p>

Chatbot Code Explained Copy Chapter

1. Add dependencies

<dependencies>
	  <dependency>
	    <groupId>com.alibaba.cloud.ai</groupId>
	    <artifactId>spring-ai-alibaba-agent-framework</artifactId>
	    <version>1.1.2.0</version>
	  </dependency>
	  <!-- Assume you are going to use DashScope Model. Refer to docs for how to choose model.-->
	  <dependency>
	    <groupId>com.alibaba.cloud.ai</groupId>
	    <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
	    <version>1.1.2.1</version>
	  </dependency>
	</dependencies>

2. Define Chatbot

For more details of how to write a Chatbot, please check the Quick Start on our official website.

📚 Documentation Copy Chapter

Project Structure Copy Chapter

This project consists of several core components:

* spring-ai-alibaba-agent-framework: A multi-agent framework designed for building intelligent agents with built-in context engineering best practices.
* spring-ai-alibaba-graph: The underlying runtime for Agent Framework. We recommend developers to use Agent Framework but it's totally fine to use the Graph API directly.
* spring-ai-alibaba-admin: A one-stop Agent platform that supports visualized Agent development, observability, evaluation, and MCP management, etc.
* spring-ai-alibaba-studio: The embedded ui for quickly debugging agent in a visualized way.
* spring-boot-starters: Starters integrating Agent Framework with Nacos to provide A2A and dynamic config features.

Spring AI Alibaba Ecosystem Copy Chapter

Contact Us Copy Chapter

* Dingtalk Group (钉钉群), search 94405033092 and join.

<img src="./docs/imgs/dingding-group.png" style="width: 260px; height: auto"/>

* WeChat Group (微信公众号), scan the QR code below and follow us.

<img src="./docs/imgs/wechat-account.jpg" style="width: 260px; height: auto"/>

Resources Copy Chapter

Star History Copy Chapter


---

<p align="center">
Made with ❤️ by the Spring AI Alibaba Team