Introduction to Spring AI

Large language models (LLMs) such as GPT, Claude, Gemini, Llama and Mistral have become a normal part of business applications: support chatbots, document search, summarisation, data extraction, code assistants and autonomous agents. Java teams no longer need a separate Python service to use them. Spring AI brings AI capabilities into Spring Boot with the same patterns you already know — starters, auto-configuration, properties, beans and portable APIs.

This lesson explains what Spring AI is, the core building blocks (chat models, ChatClient, embeddings, vector stores, advisors, tools and MCP), which providers it supports, and walks you through building and running your first AI-powered endpoint with Spring AI 2.0 and Spring Boot 4.

Why Spring AI?

Every AI provider has its own HTTP API, request format, streaming protocol and error handling. If you call them directly, your code becomes tied to one vendor and full of boilerplate. Spring AI provides portable abstractions: you write code against ChatClient, EmbeddingModel and VectorStore, and switch between OpenAI, Anthropic, Google, Mistral, Amazon Bedrock or a local Ollama model by changing a dependency and a few properties.

It also solves the application-level problems that appear as soon as you go beyond a demo: mapping answers to Java objects, remembering conversations, letting models call your code, retrieving your own documents (RAG), observability, and evaluation.

Core Building Blocks

You will meet these concepts throughout the Spring AI module:

• ChatModel — the low-level interface to a chat LLM provider. Auto-configured by the provider starter.
• ChatClient — the fluent, high-level API you use in application code, similar in style to RestClient.
• Prompt and messages — system, user, assistant and tool messages sent to the model; PromptTemplate fills placeholders.
• Structured output — converting model text into Java records and lists with .entity(...).
• Advisors — interceptors around each call, used for chat memory, RAG, logging, tool calling and safety.
• Tools — Java methods annotated with @Tool that the model can ask to call.
• EmbeddingModel and VectorStore — turn text into vectors and search by meaning; the basis of RAG.
• MCP — the Model Context Protocol, a standard for sharing tools and data between AI applications.

Supported Providers

Spring AI 2.0 includes chat support for OpenAI, Anthropic Claude, Google GenAI (Gemini), Amazon Bedrock, Mistral AI, DeepSeek and Ollama, with further providers in the community. Embedding models and more than twenty vector databases are supported, including PGVector, Redis, MongoDB Atlas, Elasticsearch, Qdrant, Chroma, Milvus, Pinecone and Weaviate. Each has its own starter, named spring-ai-starter-model-<provider> or spring-ai-starter-vector-store-<store>.

Versions and Setup

Spring AI 2.0 (GA June 2026) requires Spring Boot 4.0 or 4.1 and Spring Framework 7, uses Jackson 3, and needs Java 17 or newer. Import the spring-ai-bom so all Spring AI modules use matching versions, then add one model starter. You can also select "OpenAI", "Anthropic" or "Ollama" under the AI section on start.spring.io and the BOM is added for you.

Never hard-code API keys. Put them in an environment variable (for example OPENAI_API_KEY) and reference it from application.yml.

Costs, Limits and Responsible Use

Hosted models charge per token (roughly ¾ of an English word) for both input and output, so long prompts and large documents cost money on every call. Providers also apply rate limits. Models can produce incorrect but confident answers ("hallucinations"), so AI features need validation, grounding in your own data, and human review where decisions matter. Treat anything a user types as untrusted input that may try to override your instructions (prompt injection).

Examples

<properties>
    <java.version>21</java.version>
    <spring-ai.version>2.0.1</spring-ai.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webmvc</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-openai</artifactId>
    </dependency>
</dependencies>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>${spring-ai.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

(Gradle: implementation platform("org.springframework.ai:spring-ai-bom:2.0.1") and implementation "org.springframework.ai:spring-ai-starter-model-openai")

spring:
  application:
    name: webnest-ai
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        model: gpt-5-mini
        temperature: 0.3

# Set the key before running (never commit it):
# PowerShell:  $env:OPENAI_API_KEY="sk-..."
# bash/zsh:    export OPENAI_API_KEY=sk-...

package com.webnest.ai;

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 AskController {

    private final ChatClient chatClient;

    // Spring AI auto-configures a ChatClient.Builder for the model on the classpath
    public AskController(ChatClient.Builder builder) {
        this.chatClient = builder
            .defaultSystem("You are a concise tutor for Java and Spring Boot learners.")
            .build();
    }

    @GetMapping("/ask")
    public String ask(@RequestParam String question) {
        return chatClient.prompt()
            .user(question)
            .call()
            .content();
    }
}

curl "http://localhost:8080/ask?question=What+does+@SpringBootApplication+do"

@SpringBootApplication combines three annotations: @Configuration (the class can define beans),
@EnableAutoConfiguration (Spring Boot configures beans based on your classpath) and
@ComponentScan (scans the package and sub-packages for components).