Spring AI: From Beginner to Expert, Course Overview

What you'll learn: how this 7-lesson course is organised, what you will be able to build after each lesson, which Java and Spring knowledge you need first, and the handful of Spring AI terms that every later lesson relies on.

Most AI tutorials are written in Python, but a large share of enterprise backends run on the JVM. Those teams do not want a second stack just to call a language model. They want the AI feature to look like the rest of their service: configured through application.yml, injected as a bean, tested with the usual tools, observed with the metrics they already collect.

Spring AI is the Spring project that aims at exactly that. It gives a Spring Boot application a portable programming model for chat models, embeddings, vector stores, tool calling, retrieval, chat memory and the Model Context Protocol (MCP). This course takes you from a first ChatClient call to a design you could defend in an architecture review.

The core idea

Think of Spring AI the way you think of Spring Data or JdbcTemplate. You do not write raw socket code to talk to PostgreSQL. You depend on an abstraction, the vendor-specific part lives in a driver and a few properties, and your service code stays the same when the database changes.

Spring AI applies the same idea to AI providers. Your code talks to a small set of interfaces: a chat model, an embedding model, a vector store. A starter on the classpath supplies the implementation for a particular provider, and properties choose the model. The surrounding features (prompt templates, structured output, advisors, tools, memory) work against the interfaces, so they are reusable across providers.

That abstraction is not magic, and it does not remove the hard parts. A model is still a probabilistic remote service: it can be slow, wrong, expensive or unavailable. Spring AI gives you good places to handle that. This course teaches you where those places are.

The course at a glance

The course has seven lessons. This page is the first; the other six build on each other, so take them in order.

The first four lessons are about building a feature. The last three are about connecting it to the wider world and keeping it healthy. Each lesson ends with exercises at three levels, so you can stop early and still have a working artefact.

What you can do after each lesson

What Spring AI is made of

Before you meet the code, it helps to see all the parts on one map. The request path runs from your application code, through the ChatClient and its advisors, to a model provider, with side branches to a vector store and to your own tools.

The vector store in the diagram may be a separate database such as PostgreSQL with pgvector; the box sits in the JVM zone because the client code and the retrieval advisor run there.

A request, step by step

Here is the life of one chat call. Nothing about it is exotic, which is the point: it is ordinary request handling with a remote call in the middle.

Read it left to right. Advisors wrap the call: they can add context (a retrieved document, earlier messages) on the way in and inspect or record the answer on the way out. The ChatModel is the only part that knows a provider's wire format.

Prerequisites

You can start this course if you can do the following without looking it up:

• Java. Records, generics, lambdas, streams, and reading a stack trace. The examples use records heavily for typed model output.
• Spring Boot. Create a project, add a starter, write a @RestController or @Service, bind application.yml properties, and run a test with @SpringBootTest or plain JUnit.
• Build tools. Maven or Gradle dependency management, including importing a BOM (a bill of materials that pins consistent versions).
• HTTP basics. What a timeout, a retry and a 429 response are.

You do not need machine-learning knowledge, and you do not need to understand how transformers work. Where a concept matters for design, for example why an embedding has a fixed number of dimensions, the lesson explains it in one paragraph.

You do need two things outside the code: an account and API key with at least one model provider, or a local model runner such as Ollama, and a habit of keeping the key out of source control. Lesson 2 shows how to read the key from an environment variable.

Spring AI vocabulary

These terms appear throughout the course. Every name in the table comes from the reference documentation.

Choosing whether you need Spring AI at all

Spring AI is a good fit for many services, but it is not the only way to call a model. Use the flowchart as a first filter; the full comparison with another Java library is in Spring AI vs LangChain4j.

A single, rarely changing call to one provider can live behind a small interface of your own. The value of the framework grows with each extra moving part: a second provider, a vector store, a tool, a conversation history, a need for metrics.

Use cases the course keeps returning to

Three examples recur so that you can see the same building block from different angles.

1. Support assistant. A chatbot that answers customers' questions from a product knowledge base. It needs retrieval (lesson 4), conversation memory (lesson 2) and guardrails (lesson 7).
2. Document extraction. A service that reads free-text claims, emails or contracts and returns structured fields for downstream systems. It needs structured output and validation (lesson 3).
3. Operations helper. An internal assistant that can look up an order status or open a ticket by calling existing services. It needs tool calling (lesson 3), possibly MCP (lesson 5), and strict limits on what it may do (lessons 3 and 7).

How to work through the course

Keep one scratch project for the whole course and grow it lesson by lesson: lesson 2 creates it, lesson 3 adds a typed extraction endpoint and a tool, lesson 4 adds a document ingestion and a question endpoint. By lesson 7 you will have a small but realistic service to review.

Do the exercises. Reading about prompts and retrieval is far less useful than seeing your own retrieval return the wrong chunk and then fixing it. The starter exercises take about half an hour each, so there is no reason to skip them.

Keep the official documentation open in another tab. The framework moves, and the version you build against decides which property names and class names are correct.

In practice: planning an AI feature for a claims team

The situation. A platform team owns a Spring Boot claims service. Business users want two things: a summary of long claim notes, and an assistant that answers questions about the internal claims handbook. The team has never used a language model in production and has three weeks before a pilot with a small group of adjusters.

Starting architecture. The claims service exposes REST endpoints backed by a relational database. There is no AI code, and the handbook lives as documents on a shared drive.

What changes. The team uses the course order as its plan.

1. Lesson 2 steps: add the model starter, a ChatClient bean and an endpoint that summarises a note. A stubbed ChatModel in the unit tests keeps the build free of paid calls.
2. Lesson 3 steps: replace the free-text summary with a Java record (ClaimSummary with fields for parties, dates and next action), and validate it before it reaches the UI. Anything that changes data stays out of the model's reach.
3. Lesson 4 steps: load the handbook through a document reader, split it into chunks, store them in a vector store and add a question endpoint with retrieval. Each answer returns the source chunks so adjusters can check them.
4. Lessons 6 and 7 steps: compare two or three candidate models on twenty real questions, then add metrics, a timeout, a budget alarm and a kill switch before the pilot.

Result. After the pilot period the team should be able to say, with evidence, which questions the assistant answers well, which retrieval failures remain, what each answer costs on average (assumed to be a small, measurable amount per request), and what happens when the provider is down. The architecture grows by one boundary, a model provider, and one data store, with the rest of the service unchanged.

Architect's notes

• The provider boundary is the new risk. An AI call is a network dependency with variable latency and cost, and a response you cannot fully predict. Put it behind your own service interface so you can add timeouts, caching, fallbacks and tests in one place.
• Do not let the model own business rules. Use the model for language tasks (summarise, extract, classify, draft) and keep decisions, calculations and permissions in ordinary code.
• Portability has limits. The interfaces are portable, but models differ in quality, context size, tool support and structured-output behaviour. Plan to re-test prompts and evaluation sets when you change models, even if the code compiles unchanged.
• Start with the simplest feature that could work. A prompt with a good template often beats a complex agent. Add retrieval, tools and memory only when a concrete failure justifies them.
• Budget for operations from day one. Token usage, latency, error rates and answer quality all need numbers. Lesson 7 covers what Spring AI emits and what you must add yourself.
• Data handling is a design decision. Anything in a prompt leaves your process. Decide early what may be sent to which provider, and read your provider's terms on retention.

Common mistakes

• Starting with an agent. Teams jump to multi-step autonomous flows before a single reliable call works. Fix: build the one-shot version first, measure it, and add steps only when needed.
• Copying code from a different release line. Starter names, property prefixes and some classes changed between lines. Fix: check the documentation page for your version; if a class does not resolve, look at the upgrade notes before blaming your setup.
• Hard-coding the API key. Keys in source control are leaked keys. Fix: read the key from an environment variable or your secret manager through a property placeholder.
• Treating model output as trusted. A reply may be malformed, off-topic or manipulated by content inside a retrieved document. Fix: parse into types, validate, and keep sensitive actions behind your own authorisation.
• Skipping tests because "it is AI". Most of the surrounding code is plain Java and is easy to test. Fix: stub the model for unit tests and keep a small, separate evaluation set for quality.
• Ignoring cost until the invoice arrives. Long prompts and chatty tool loops multiply tokens. Fix: log token usage per feature from the first prototype.

Key takeaways

• Spring AI gives Spring Boot applications portable interfaces for chat, embeddings and vector stores, plus tools, advisors, memory and MCP support.
• ChatClient is the everyday entry point; ChatModel is the provider-facing layer underneath.
• Starters and properties choose the provider and model; your business code should not change when they change.
• Advisors wrap each call, which is where retrieval, memory and logging plug in.
• The abstraction does not make models predictable. Timeouts, validation, tests and measurement are still your job.
• Check the documentation for your exact version, because names and defaults differ between release lines.
• Work through the lessons in order and build one project as you go.

Practice exercises

Starter (about 30 minutes). List three features in a system you know that a language model could help with. For each, write one sentence naming the building block you would use first (plain chat call, structured output, tool, or retrieval) and one sentence on what could go wrong. Then open the Spring AI reference site, find the page for the version you plan to use, and note which Spring Boot versions it supports.

Intermediate (about 2 hours). Create an empty Spring Boot project with Spring Initializr and add exactly one model starter. Without writing any AI code yet, read the auto-configuration properties for that provider and write a short application.yml with the API key read from an environment variable, an explicit model name and a request timeout if the provider's page lists one. Start the application and confirm it boots.

Advanced (half a day). Draw the architecture for the support-assistant use case on one page: the request path, where the knowledge base lives, where conversation history is stored, which parts call out over the network, and where you would measure latency, cost and answer quality. List the five riskiest assumptions in the design and the cheapest experiment that would test each. Keep the document; you will revise it after lessons 4 and 7.

Related reading

• Spring AI: Getting started — the next lesson, with the first working call.
• Spring AI: Prompting and tools — typed output and tool calling.
• Spring AI: RAG and vector stores — retrieval over your own documents.
• Spring AI: MCP and agents — sharing tools across processes.
• Spring AI: Choosing LLMs — selecting and integrating models.
• Spring AI: Production architecture — running the feature safely.
• Spring AI enterprise integration guide — a single-post tour of the same ground.
• Spring AI vs LangChain4j — a balanced comparison of two Java options.

Official documentation

• Spring AI reference — the starting point and version selector.
• Getting started — BOM, repositories and Spring Initializr.
• ChatClient API — the fluent API used in every lesson.
• Upgrade notes — what changed between release lines.