01
Foundations
Models, tokens, prompts, starters and your first ChatClient call.
Tutorials coming soon
Free Spring AI Course
Spring AI Tutorial
Spring AI is a Spring project that lets Java applications work with AI models through one consistent API. You keep writing normal Spring beans, and it handles prompts, responses, tool calls and connections to providers such as OpenAI or Ollama. This Spring AI tutorial shows you how to build those features and how to explain them in an interview.
- ChatClient API
- Tool calling
- RAG with your data
- MCP support
What Is Spring AI?
Spring AI brings AI model integration into the Spring ecosystem. Instead of writing HTTP calls and JSON parsing for each provider, you inject a ChatClient, describe what you want, and receive text or a Java object. Providers are added as Spring Boot starters and configured through properties, the same way you would add a database.
Main APIChatClient
Stable versionSpring AI 2.0.2
Runs onSpring Boot 4, Java 17+
LicenceApache 2.0
What You Will Learn
- How models, prompts and tokens work
- Calling models with the ChatClient API
- Turning answers into Java records
- Remembering context with chat memory
- Letting a model call your Java methods
- Answering from your own data with RAG
- Connecting tools through MCP
- Security, cost and testing in production
Who this is for
Java beginners curious about AI, Spring Boot and microservices developers with 3 to 15 years of experience, and engineers preparing for product-company interviews.
Prerequisites
Core Java and basic Spring Boot. Start with the Spring Boot tutorial if you are new, and see building a REST API for the web layer used here.
How Spring AI Works
Your service builds a request through ChatClient. The request passes through a chain of advisors, small interceptors that can add conversation history, attach relevant documents or run the tool loop. A model client then sends it to the provider and converts the reply back into Java. Advisors work much like servlet filters, so you can add behaviour without changing business code.
Your Code
Controller
Service
@Tool methods
Spring AI
ChatClient and advisor chain
Memoryhistory
RAGdocuments
Toolstool loop
Connected To
AI model
Vector store
MCP servers
Core Spring AI Concepts
| Concept | What it does |
|---|---|
ChatClient | Fluent API for sending prompts and reading replies. |
| Advisor | Intercepts a request or reply to add memory, documents or tool handling. |
@Tool | Marks a Java method that a model may ask your application to run. |
EmbeddingModel | Turns text into numeric vectors so similar meanings can be found. |
VectorStore | Stores those vectors and runs similarity searches. |
| RAG | Retrieval-augmented generation: adds relevant documents to the prompt. |
| MCP | Model Context Protocol: a standard way to share tools between applications and AI clients. |
Build Your First Spring AI App
Let us add a support assistant to an online bookshop. Start with a Spring Boot 4 project, import the Spring AI BOM and add a model starter.
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-bom</artifactId>
<version>2.0.2</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webmvc</artifactId>
</dependency>
</dependencies>spring.ai.openai.api-key=${OPENAI_API_KEY}Boot now provides a ChatClient.Builder bean. Inject it and build a client with a system message, which sets the assistant's role for every request.
package com.javabytechie.bookshop.support;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class SupportController {
private final ChatClient chatClient;
public SupportController(ChatClient.Builder builder) {
this.chatClient = builder
.defaultSystem("You help customers of an online bookshop. Keep answers short.")
.build();
}
@GetMapping("/support/ask")
public String ask(@RequestParam String question) {
return chatClient.prompt()
.user(question)
.call()
.content();
}
}Get a Java Record Instead of Text
Calling entity asks the model for data in a matching shape and converts the reply into your type. Here each incoming ticket is sorted automatically. Binding the ticket as a template parameter keeps its text separate from your instruction wording.
package com.javabytechie.bookshop.support;
public record TicketTriage(String category, int urgency, String summary) {
}package com.javabytechie.bookshop.support;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.stereotype.Service;
@Service
public class TriageService {
private final ChatClient chatClient;
public TriageService(ChatClient.Builder builder) {
this.chatClient = builder.build();
}
public TicketTriage triage(String ticket) {
return chatClient.prompt()
.user(u -> u.text("Classify this support ticket: {ticket}")
.param("ticket", ticket))
.call()
.entity(TicketTriage.class);
}
}Let the Model Call Your Code
A model cannot see your orders, but it can ask for them. Annotate a method with @Tool and pass the bean to the request. Spring AI runs the requested method and sends the result back so the model can finish its answer.
package com.javabytechie.bookshop.support;
import java.util.Map;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.stereotype.Component;
@Component
public class OrderTools {
private final Map<String, String> statuses = Map.of("BK-1042", "Out for delivery");
@Tool(description = "Get the delivery status of a bookshop order")
public String orderStatus(@ToolParam(description = "The order id, such as BK-1042") String orderId) {
return statuses.getOrDefault(orderId, "No order found with that id");
}
}package com.javabytechie.bookshop.support;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.stereotype.Service;
@Service
public class OrderAssistant {
private final ChatClient chatClient;
private final OrderTools orderTools;
public OrderAssistant(ChatClient.Builder builder, OrderTools orderTools) {
this.chatClient = builder.build();
this.orderTools = orderTools;
}
public String answer(String question) {
return chatClient.prompt()
.user(question)
.tools(orderTools)
.call()
.content();
}
}Spring AI vs Calling a Model API Directly
| Concern | Direct HTTP or vendor SDK | Spring AI |
|---|---|---|
| Switching provider | Rewrite the integration | Change the starter and properties |
| Structured output | Parse JSON yourself | entity(MyRecord.class) |
| Tool loop | Write and maintain it | Handled by an advisor |
| Spring integration | Build it yourself | Auto-configured beans and properties |
| Newest vendor features | Available immediately | May arrive after the vendor releases them |
A direct SDK is reasonable for one small call or a very new vendor feature. Spring AI pays off once you need memory, tools, RAG or more than one provider.
Spring AI Learning Path
This is the order we recommend. Each track will be linked here as its tutorials are published.
02
Prompts and Output
Prompt templates, streaming and mapping answers to Java records.
Tutorials coming soon
03
Chat Memory
Keeping conversation context across requests with memory advisors.
Tutorials coming soon
04
Tool Calling and Agents
Letting a model call your Java methods, safely and in loops.
Tutorials coming soon
05
RAG and Vector Stores
Embeddings, document ingestion and answers grounded in your own data.
Tutorials coming soon
06
MCP and Production
Model Context Protocol, evaluation, observability and cost control.
Tutorials coming soon
Production Mistakes to Avoid
AI features fail differently from normal code. These risks come up in design reviews and senior interviews.
Prompt Injection
Text from users or documents can try to override your instructions. Enforce permissions in your code, never in the prompt.
Trusting Output
Models can be confidently wrong. Validate structured replies and check any action before it changes data.
Unbounded Cost
Long histories and large documents raise token usage. Set limits, trim context and track usage per feature.
Exact-Match Tests
Replies vary between runs. Test your parsing and tools with fakes, and judge answer quality with evaluations.
Preparing for interviews? Pair this with our Spring Boot interview questions and the Java 21 features used in modern services.
Frequently Asked Questions
Q1. What is Spring AI used for?
Spring AI connects Spring applications to AI models. Teams use it to add chat assistants, document summaries, data extraction, search over company documents and agents that call application code, while keeping the usual Spring configuration, testing and deployment.
Q2. Is Spring AI free?
The framework is open source under the Apache 2.0 licence. Hosted model providers such as OpenAI charge for usage, so your bill depends on the tokens you send and receive. You can also run models on your own hardware with Ollama.
Q3. Which versions does Spring AI 2.0 need?
Spring AI 2.0 is built for Spring Boot 4 and Spring Framework 7, and needs Java 17 or newer. The examples here use Java 21 and Spring AI 2.0.2. Applications still on Spring Boot 3 should stay on the Spring AI 1.x line until they migrate.
Q4. Do I need to know Python or machine learning?
No. You call models through Java APIs, so your existing Java and Spring skills are enough to start. It does help to understand tokens, prompts and embeddings, which are explained in plain terms on this page.
Q5. Does the AI model run my code during tool calling?
No. The model only asks for a tool to be called and supplies the arguments. Your application runs the method and returns the result, so your normal validation and permission checks still apply and should be enforced in that method.
Q6. What is the difference between RAG and tool calling?
RAG finds relevant text in your documents and adds it to the prompt before the model answers, which suits knowledge questions. Tool calling lets the model request a live action or lookup, such as checking an order. Many assistants use both.
Q7. Can Spring AI switch between AI providers?
Mostly, yes. ChatClient code stays the same when you change the starter and its properties, because it works through a common model interface. Provider-specific options and differences in model behaviour still need testing after a switch.
Start Learning Spring AI
Spring AI lets Java teams add AI features with the tools and habits they already trust. Use this Spring AI tutorial to build the bookshop assistant above, then add structured output and tools one step at a time, keeping security and cost checks in your own code.
Was this tutorial helpful?