Spring AI in Practice: From Love Guru to ReAct Autonomous Planning Agent Development Guide

Project Overview: A Java AI Practical Tutorial with 2000+ Stars

As AI application development is rapidly becoming an essential skill for Java developers, an open-source project called yu-ai-agent has quickly gained traction on GitHub, accumulating over 2,199 Stars and 508 Forks in a short period. Initiated by well-known tech blogger Yupi (liyupi), the project is built on the Spring Boot 3 + Java 21 + Spring AI tech stack, featuring two complete AI applications — AI Love Guru and YuManus, a ReAct-pattern autonomous planning agent — providing Java developers with a comprehensive learning path from beginner to hands-on AI development.

Spring AI Technical Architecture and Core Features

Modern Technology Stack

The project adopts the most cutting-edge technology combination in the Java ecosystem:

• Spring Boot 3: The latest generation Spring framework with native GraalVM support and significantly improved performance
• Java 21: LTS version supporting virtual threads, pattern matching, and other modern language features
• Spring AI: The official Spring AI integration framework, providing Java developers with a unified abstraction layer for LLM integration

This technology stack selection is remarkably forward-looking. As Spring ecosystem's response to the AI era, Spring AI is iterating rapidly with a design philosophy consistent with Spring's longstanding approach — reducing development complexity through abstraction and standardization, allowing developers to build AI applications using the familiar Spring programming model.

Deep Dive into the Spring AI Framework

Spring AI is the official AI integration framework launched by Spring in late 2023, inspired by LangChain in the Python ecosystem but fully adhering to Spring's programming paradigms. It provides core abstraction interfaces such as ChatClient and EmbeddingClient, supporting seamless switching between multiple LLM backends including OpenAI, Anthropic, Ollama, and Alibaba Tongyi Qianwen. Developers can migrate between different models by simply changing configurations without modifying business code. Spring AI also has built-in support for vector stores (such as PGVector, Milvus, Chroma), as well as advanced features like structured output parsing and function calling. This means Java developers finally have a native Spring ecosystem AI development framework that rivals LangChain.

Java 21 Virtual Threads Empowering AI Applications

Virtual Threads introduced in Java 21 (Project Loom) hold significant importance for AI application development. AI applications typically involve substantial network I/O operations — calling LLM APIs, querying vector databases, accessing external tool interfaces — all of which are I/O-intensive. Under the traditional platform thread model, each blocking I/O operation occupies an OS thread, limiting concurrency. Virtual threads allow millions of lightweight threads to run on a single platform thread, dramatically improving throughput for AI applications under high concurrency, making them particularly suitable for Agent systems that need to handle large numbers of simultaneous user conversation requests. Combined with Spring Boot 3's native support for virtual threads, developers can enable this feature with just a single configuration line.

Core Knowledge System Covered

The project covers virtually all key technical aspects of AI application development:

• LLM Integration: Connecting to various large language models through Spring AI's unified interface
• Prompt Engineering & Optimization: Systematic prompt design and tuning methodology
• RAG (Retrieval-Augmented Generation): Enhancing model response quality by combining external knowledge bases
• Vector Databases: Providing efficient semantic retrieval capabilities for RAG
• Tool Calling: Enabling AI to invoke external tools and APIs
• MCP (Model Context Protocol): Anthropic's standardized model interaction protocol
• AI Agent Development: Building intelligent agents with autonomous planning and execution capabilities

RAG Technical Principles

RAG (Retrieval-Augmented Generation) is a key technology for addressing LLM "hallucination" issues and knowledge timeliness problems. Its workflow consists of two phases: during the indexing phase, external documents are split into text chunks, converted into high-dimensional vectors via embedding models, and stored in a vector database; during the retrieval-generation phase, user queries are similarly converted to vectors, similarity searches are performed in the vector database (typically using cosine similarity or inner product) to find the most relevant text chunks, which are then injected as context into the prompt before being passed to the LLM for answer generation. This ensures the model's responses have reliable knowledge sources, significantly reducing the probability of fabricated answers. In enterprise applications, RAG is commonly used for customer service Q&A, document retrieval, and knowledge management scenarios.

Vector Database Technical Details

Vector databases are database systems specifically designed for storing and performing similarity searches on high-dimensional vectors. Unlike traditional relational databases based on exact matching, vector databases support Approximate Nearest Neighbor (ANN) searches, capable of finding the most semantically similar results from millions of vectors at millisecond latency. Popular vector databases include Milvus (open-source distributed), Pinecone (cloud-native), Chroma (lightweight), and PGVector (PostgreSQL extension). Their underlying indexing algorithms include HNSW (Hierarchical Navigable Small World graphs) and IVF (Inverted File Index), balancing retrieval accuracy and speed. Spring AI provides a unified VectorStore abstraction for these vector databases, allowing developers to flexibly choose based on project scale and deployment environment.

Tool Calling Mechanism

Tool Calling (also known as Function Calling) is the core mechanism for LLMs to interact with the external world. It works as follows: when calling the model, developers pass in not only user messages but also a set of tool descriptions (including tool name, function description, and parameter JSON Schema). When generating a response, if the model determines that a tool is needed, it outputs a structured tool call request (rather than natural language text) containing the tool name and parameter values. The application layer receives this request, executes the actual tool call (such as querying a database or calling an API), returns the result to the model, which then generates the final answer based on the tool's return value. OpenAI pioneered this feature in June 2023, and it has since become an industry standard. In Spring AI, developers can register methods as tools callable by the model simply by annotating them with @Tool.

MCP (Model Context Protocol) Explained

MCP (Model Context Protocol) is an open standard protocol proposed by Anthropic in November 2024, designed to address the fragmentation of connections between AI models and external data sources and tools. Before MCP, each AI application needed custom integration code for each external service, creating M×N complexity. MCP reduces this to M+N complexity by defining a unified client-server architecture. MCP Servers expose Tools, Resources, and Prompt templates, while MCP Clients discover and invoke these capabilities through the standard protocol. Similar to how the USB protocol unified peripheral interfaces, MCP is unifying tool calling interfaces for AI applications. Numerous MCP Server implementations already exist, covering common services like file systems, databases, search engines, and code repositories, and Spring AI has already provided native support for the MCP protocol.

Detailed Breakdown of Two AI Projects

AI Love Guru: Spring AI Getting Started Project

As an entry-level project, the AI Love Guru application demonstrates how to quickly build a vertical-domain AI conversational application using Spring AI. While such projects may seem lighthearted and fun, the underlying technical elements — prompt engineering, conversation management, context maintenance, and RAG knowledge augmentation — are all core capabilities in enterprise AI application development.

Through this project, developers can master Spring AI basics, understand how to shape AI behavior and personality through carefully designed System Prompts, and learn how to use RAG technology to inject domain knowledge for improved response professionalism. System Prompt design is one of the most critical aspects of prompt engineering — it defines the model's role positioning, response style, knowledge boundaries, and behavioral constraints, directly determining the user experience quality of the AI application.

YuManus: An Autonomous Planning Agent Based on the ReAct Pattern

YuManus is the project's centerpiece — a Java implementation of the popular AI Agent framework Manus. This intelligent agent adopts the ReAct (Reasoning + Acting) pattern, one of the most mainstream Agent architecture paradigms today.

Manus Agent Framework Background

Manus is a general-purpose AI Agent product launched by a Chinese team in early 2025, attracting widespread attention for its demonstrated powerful autonomous task execution capabilities. Manus can autonomously browse web pages, write code, manipulate file systems, deploy applications, and more, regarded as an important exploration toward AGI. Its core architecture employs a multi-agent collaboration model, combining the ReAct reasoning loop with a rich tool set. Since Manus itself is not fully open-sourced, the community has produced numerous reproduction projects, such as OpenManus (Python implementation) and YuManus (Java implementation) introduced in this article, helping developers understand the core architectural design of Agents.

ReAct Pattern: Academic Background and Working Principles

The ReAct pattern originates from the 2022 paper "ReAct: Synergizing Reasoning and Acting in Language Models" jointly published by Google Research and Princeton University. The paper demonstrates that having language models alternately generate reasoning traces and task-specific actions significantly improves model performance on complex tasks. Compared to pure reasoning (Chain-of-Thought), ReAct can interact with external environments to obtain information; compared to pure action (Act-only), ReAct's reasoning steps provide interpretability and error correction capabilities. This pattern has become the theoretical foundation for mainstream Agent frameworks like AutoGPT, BabyAGI, and LangChain Agent.

The core idea of the ReAct pattern is to have AI alternate between "reasoning" and "acting" during task execution:

1. Reasoning: Analyzing the current state and formulating the next step
2. Acting: Calling tools or executing operations
3. Observation: Obtaining action results as input for the next reasoning cycle

This cycle enables AI Agents to handle complex multi-step tasks with autonomous planning and dynamic adjustment capabilities. For example, when a user requests "help me research a technical solution and generate a report," the Agent autonomously decomposes the task into multiple sub-steps — searching for relevant materials, reading documents, comparing solutions, and writing the report — with each step dynamically adjusting strategy based on previous results. Through Tool Calling and the MCP protocol, YuManus can invoke various external tools, achieving a truly "autonomous planning intelligent agent."

Why Java Developers Should Learn Spring AI Agent Development

Filling the Gap in Java's AI Ecosystem

For a long time, Python has been the dominant language for AI application development, with frameworks like LangChain and LlamaIndex nearly monopolizing the AI development toolchain. Java developers were once in a passive position during the AI wave. The emergence of Spring AI and hands-on projects like yu-ai-agent are changing this landscape.

For the vast community of Java/Spring developers, being able to enter the AI development field without switching tech stacks undeniably lowers the learning barrier significantly. Statistics show there are over 9 million Java developers worldwide, with a large proportion engaged in enterprise application development. These developers are already familiar with Spring's dependency injection, AOP, declarative transactions, and other programming models. Spring AI allows them to build AI applications using the exact same mindset, without having to learn Python ecosystem concepts like async programming and package management from scratch.

Reference Architecture for Enterprise AI Applications

Compared to the abundance of script-style demos in the Python ecosystem, AI applications built on Spring Boot inherently possess enterprise-grade characteristics — dependency injection, configuration management, security frameworks, and monitoring systems can all be seamlessly reused. This makes the path from prototype to production much smoother.

Specifically, Spring Boot's Actuator provides out-of-the-box health checks and metrics monitoring, Spring Security can add authentication and authorization to AI interfaces, Spring Cloud's service governance capabilities can manage call chains across multiple AI microservices, and the Micrometer + Prometheus + Grafana observability stack can monitor model call latency, token consumption, and error rates. These capabilities that are indispensable in production environments often require introducing multiple independent components in the Python ecosystem.

Recommended Spring AI Learning Path

For Java developers looking to get started with AI application development, the following progressive learning path is recommended:

1. Foundation Stage: First understand Spring AI's core abstractions (ChatClient, Prompt, Message concepts), complete the AI Love Guru project, and master basic model invocation and conversation management
2. Intermediate Stage: Deep dive into RAG architecture, understanding document chunking strategies, embedding model selection, vector database deployment, and Tool Calling registration and invocation mechanisms
3. Advanced Stage: Study the ReAct pattern and Agent architecture, understanding reasoning loop implementation, tool orchestration, error handling, and timeout control, and complete the YuManus project
4. Extension Stage: Learn MCP protocol server and client implementations, explore multi-agent collaboration (such as Supervisor pattern, hierarchical agents) and production deployment solutions (including streaming responses, token rate limiting, cost control, etc.)

Conclusion

The value of the yu-ai-agent project lies not only in providing two runnable AI application demos but more importantly in systematically connecting the complete knowledge chain of AI application development. In an era where AI capabilities are transitioning from "nice-to-have" to "core competitive advantage," mastering Spring AI and Agent development technologies holds significant strategic importance for Java developers' career growth. While the Spring AI ecosystem is still in its early stages, it is backed by the strong Spring community, and its future development is worth anticipating. As Spring AI 1.0 reaches general availability and more enterprises adopt it, Java's position in AI application development will continue to strengthen — and now is the optimal time for Java developers to invest in AI skills.