Spring AI Installation Guide

Spring AI transforms Spring Boot applications into intelligent, AI-powered services by providing a consistent, portable programming model across multiple large language model (LLM) providers. Whether you are building a simple chatbot, a retrieval-augmented generation (RAG) pipeline, or an autonomous agent, Spring AI lets you integrate AI capabilities without leaving the Spring ecosystem you already trust.

This guide walks you through installing Spring AI, configuring your first AI provider, and verifying that everything works correctly. By the end, you will have a running Spring Boot application that can communicate with models like OpenAI GPT, Azure OpenAI, Ollama, Anthropic Claude, or Google Gemini.

Spring AI supports a wide range of AI providers and typical enterprise use cases:

Chat completions and streaming conversations
Embedding generation for semantic search
Vector store integration for RAG
Tool calling and function execution
AI agents and Model Context Protocol (MCP)

Prerequisites

Before you begin, ensure your development environment meets the following requirements:

Java 21 or later – Spring AI takes advantage of modern Java features. Java 21 LTS is recommended for production workloads.
Spring Boot 3.x – Spring AI is designed for Spring Boot 3.3.x and above. Always use the latest stable release for full compatibility.
Maven (3.6+) or Gradle (7.x+) – Depending on your build tool preference.
IDE – IntelliJ IDEA, VS Code with Spring extensions, or Eclipse.
Git – For version control and cloning example repositories.

Additionally, you will need an API key for your chosen AI provider. If you plan to use a local model through Ollama, you must have Ollama installed and a model pulled.

Installing Spring AI

Spring AI provides a Bill of Materials (BOM) to manage dependency versions and ensure compatibility. The BOM is the recommended way to add Spring AI to your project because it centralizes version alignment for all Spring AI modules.

Maven

Add the Spring AI BOM to your pom.xml inside the <dependencyManagement> section:

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

Then add the starter for your desired AI provider. For OpenAI:

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

For Ollama (local models):

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-ollama-spring-boot-starter</artifactId>
</dependency>

For Azure OpenAI:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-azure-openai-spring-boot-starter</artifactId>
</dependency>

For Anthropic Claude:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-anthropic-spring-boot-starter</artifactId>
</dependency>

For Google Gemini:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-vertex-ai-gemini-spring-boot-starter</artifactId>
</dependency>

Note: At the time of writing, Spring AI milestone releases are not in Maven Central. You must add the Spring Snapshot or Milestone repository to your pom.xml:

<repositories>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/milestone</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

Gradle

For Gradle, add the BOM to your build.gradle:

dependencyManagement {
    imports {
        mavenBom "org.springframework.ai:spring-ai-bom:1.0.0-M6"
    }
}

Then add the starter:

dependencies {
    implementation 'org.springframework.ai:spring-ai-openai-spring-boot-starter'
}

For the Milestone repository, add:

repositories {
    mavenCentral()
    maven { url 'https://repo.spring.io/milestone' }
}

Using the BOM ensures that you can add additional Spring AI modules later without worrying about version conflicts.

Creating a Spring AI Project

You can create a Spring AI project using any of the following methods.

Spring Initializr (Recommended)

Go to start.spring.io
Choose Maven or Gradle, Java 21, and Spring Boot 3.3.x or later.
Add dependencies: Spring Web (for REST endpoints) and Spring AI (select the OpenAI or Ollama starter if available; otherwise, add the dependency manually as described above).
Download and extract the project.

IntelliJ IDEA

IntelliJ IDEA Ultimate supports Spring Initializr directly:

File → New → Project → Spring Initializr.
Follow the same steps as the web version.

Adding to an Existing Spring Boot Project

If you already have a Spring Boot application, simply add the BOM and starter dependency to your build configuration. The auto-configuration will activate based on your application.yml settings.

Project Structure

A minimal Spring AI project structure looks like this:

src/
├── main/
│   ├── java/
│   │   └── com/
│   │       └── example/
│   │           └── demo/
│   │               ├── DemoApplication.java
│   │               ├── controller/
│   │               │   └── ChatController.java
│   │               └── service/
│   │                   └── ChatService.java
│   └── resources/
│       ├── application.yml
│       └── static/
└── test/

This structure separates configuration, service logic, and web endpoints, which scales well as you add RAG pipelines, agents, or enterprise features.

Configuring AI Providers

Spring AI uses auto-configuration based on properties. You can configure your provider in application.yml or application.properties. Never hardcode API keys; use environment variables or external configuration.

OpenAI

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      base-url: https://api.openai.com
      chat:
        options:
          model: gpt-4o
          temperature: 0.7

For embeddings:

spring:
  ai:
    openai:
      embedding:
        options:
          model: text-embedding-ada-002

Azure OpenAI

spring:
  ai:
    azure:
      openai:
        api-key: ${AZURE_OPENAI_API_KEY}
        endpoint: https://your-resource-name.openai.azure.com
        chat:
          options:
            deployment-name: gpt-4o
            temperature: 0.7

Ollama (Local Models)

spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        options:
          model: llama3
          temperature: 0.7

Make sure you have pulled the model: ollama pull llama3

Anthropic Claude

spring:
  ai:
    anthropic:
      api-key: ${ANTHROPIC_API_KEY}
      chat:
        options:
          model: claude-3-5-sonnet-20241022
          temperature: 0.7

Google Gemini

spring:
  ai:
    vertex:
      ai:
        gemini:
          project-id: your-gcp-project-id
          location: us-central1
          chat:
            options:
              model: gemini-1.5-pro

Set GOOGLE_APPLICATION_CREDENTIALS environment variable to point to your service account key file.

Running Your First Spring AI Application

Let's create a minimal chat endpoint that uses the OpenAI provider.

1. Configuration

src/main/resources/application.yml

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        options:
          model: gpt-4o

2. Service Layer

package com.example.demo.service;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.stereotype.Service;

@Service
public class ChatService {

    private final ChatClient chatClient;

    public ChatService(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    public String chat(String userMessage) {
        return chatClient.prompt()
                .user(userMessage)
                .call()
                .content();
    }
}

3. REST Controller

package com.example.demo.controller;

import com.example.demo.service.ChatService;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/chat")
public class ChatController {

    private final ChatService chatService;

    public ChatController(ChatService chatService) {
        this.chatService = chatService;
    }

    @PostMapping
    public String chat(@RequestBody String message) {
        return chatService.chat(message);
    }
}

4. Run and Test

Start your application and send a POST request:

curl -X POST http://localhost:8080/api/chat \
  -H "Content-Type: text/plain" \
  -d "Hello, Spring AI!"

You should receive a response from the AI model.

Verify Installation

To confirm that Spring AI is properly installed and configured:

Check startup logs – Look for logs indicating that the ChatClient bean was created successfully.
Call the endpoint – Use the curl command above or a tool like Postman.
Inspect the response – Ensure it returns meaningful AI-generated content, not an error or empty string.
Enable debug logging – Add logging.level.org.springframework.ai=DEBUG to application.yml for detailed request/response traces.

Common Installation Problems

Missing API Key

Symptom: 401 Unauthorized or ApiKeyNotFoundException.

Solution: Verify that the environment variable is set and that the property key matches the provider. For OpenAI, the property is spring.ai.openai.api-key.

Dependency Conflicts

Symptom: NoClassDefFoundError or version mismatch errors.

Solution: Use the Spring AI BOM to align all module versions. Do not mix milestone and release versions manually.

Java Version Mismatch

Symptom: Unsupported class file major version errors.

Solution: Spring AI requires Java 21. Ensure your JAVA_HOME points to a compatible JDK and your build tool is configured for Java 21.

Spring Boot Compatibility

Symptom: Beans not created or auto-configuration not triggered.

Solution: Use Spring Boot 3.3.x or later. Check your starter dependencies; each provider has its own starter (e.g., spring-ai-openai-spring-boot-starter).

Timeout

Symptom: ReadTimeoutException or long response delays.

Solution: Adjust timeouts in your configuration. For OpenAI, you can set spring.ai.openai.chat.options.timeout (in seconds).

SSL Issues

Symptom: SSLHandshakeException when connecting to local Ollama.

Solution: Ensure your Ollama base URL uses http:// for local development. For production, configure HTTPS properly.

Model Not Found

Symptom: ModelNotFoundException or 404 from provider.

Solution: Double-check the model name in your configuration. For Ollama, pull the model first (ollama pull model-name). For cloud providers, ensure the model is available in your region/tier.

Recommended Project Structure

As your application grows beyond a simple chat endpoint, a clean package structure becomes essential. Below is a recommended layout for enterprise Spring AI projects:

src/main/java/com/example/
├── Application.java
├── controller/          // REST and WebSocket controllers
├── service/             // Business logic, orchestration
├── ai/                  // AI-specific abstractions
│   ├── chat/
│   └── advisor/
├── config/              // Spring configuration classes
├── rag/                 // RAG pipeline components
│   ├── ingestion/
│   ├── retrieval/
│   └── store/
├── model/               // Domain entities, DTOs
├── repository/          // Data access (JPA, VectorStore)
└── dto/                 // Request/response objects

This separation helps you:

Isolate AI concerns from business logic
Swap out RAG components without rewriting controllers
Test each layer independently
Scale the project with new features like agents or MCP

Best Practices

Use the latest Spring Boot version – Spring AI tracks Spring Boot closely; newer versions include performance and security fixes.
Use the Spring AI BOM – It prevents version drift between the various AI modules.
Externalize configuration – Store API keys, model names, and endpoint URLs outside the codebase. Use environment variables or a secrets manager.
Never hardcode API keys – Commit application.yml files with placeholder references, not real keys.
Use profiles – Create application-dev.yml, application-prod.yml to switch between local (Ollama) and cloud (OpenAI) providers.
Enable logging – Add structured logging to trace prompts, responses, and token usage for debugging and cost control.
Prepare for production – Design your service with observability, retry, and circuit breakers from the start. The Enterprise AI section covers these in detail.

What's Next

Now that you have a running Spring AI application, continue your learning path:

Spring AI Architecture – Deepen your understanding of the core framework.
ChatClient Guide – Master the fluent API for building advanced prompts.
ChatModel and Providers – Learn how to switch and configure different AI models.
Prompt Engineering – Design effective prompts with templates and system messages.
Tool Calling – Let the model invoke your Java methods.
Retrieval Augmented Generation (RAG) – Ground AI responses in your own data.
Vector Databases – Integrate vector stores for semantic search.
Enterprise AI Patterns – Build secure, observable, and scalable AI systems.
Spring AI Tutorials – Follow complete project walkthroughs.

Each section builds on the fundamentals you have just configured.

Key Takeaways

Spring AI integrates into any Spring Boot 3.x project with a simple starter dependency.
Use the Spring AI BOM for consistent version management.
Configure providers via application.yml with externalized secrets.
Start with a minimal ChatClient to verify your setup.
Common pitfalls include version mismatches, missing API keys, and provider-specific model names.
Organize your project to separate AI logic, business logic, and infrastructure.
Follow best practices (profiles, external config, observability) from day one to ease the path to production.

You have successfully installed and configured Spring AI. Happy building!

Prerequisites​

Installing Spring AI​

Maven​

Gradle​

Creating a Spring AI Project​

Spring Initializr (Recommended)​

IntelliJ IDEA​

Adding to an Existing Spring Boot Project​

Project Structure​

Configuring AI Providers​

OpenAI​

Azure OpenAI​

Ollama (Local Models)​

Anthropic Claude​

Google Gemini​

Running Your First Spring AI Application​

1. Configuration​

2. Service Layer​

3. REST Controller​

4. Run and Test​

Verify Installation​

Common Installation Problems​

Missing API Key​

Dependency Conflicts​

Java Version Mismatch​

Spring Boot Compatibility​

Timeout​

SSL Issues​

Model Not Found​

Recommended Project Structure​

Best Practices​

What's Next​

Key Takeaways​