Setting Up Your First Spring AI Project: Complete Step-by-Step Guide

Spring AI helps Java developers build AI-powered applications using familiar Spring Boot patterns. Instead of manually writing HTTP clients, parsing model responses, managing prompts, and handling provider-specific code, Spring AI gives developers a clean abstraction for working with AI models, prompts, embeddings, vector databases, memory, tools, and Retrieval-Augmented Generation.

This guide explains how to set up your first Spring AI project from scratch and build a simple AI chat API using Spring Boot.

What You Will Build

In this project, you will create a Spring Boot application with one REST API endpoint.

The user will send a question, and the application will return an AI-generated response.

User
 |
 v
Spring Boot REST API
 |
 v
Spring AI ChatClient
 |
 v
AI Model Provider
 |
 v
AI Response

Prerequisites

Before starting, make sure you have:

Java 17 or later
Maven
Spring Boot knowledge
IDE such as IntelliJ IDEA or Eclipse
AI provider API key
Basic REST API understanding

Spring AI supports modern Spring Boot versions and can be created from Spring Initializr by selecting required AI models and vector store dependencies. The official documentation mentions Spring Boot 3.4.x and 3.5.x support. :contentReference[oaicite:0]{index=0}

Step 1: Create Spring Boot Project

Go to Spring Initializr and create a new project with:

Project: Maven
Language: Java
Spring Boot: latest stable version
Packaging: Jar
Java: 17 or later

Recommended Dependencies

Spring Web
Spring Boot Actuator
Spring AI OpenAI Starter
Lombok optional

Project Structure

spring-ai-demo/
|
|-- src/main/java/com/example/springai/
|   |
|   |-- SpringAiDemoApplication.java
|   |-- controller/
|   |   |-- ChatController.java
|   |
|   |-- service/
|       |-- ChatService.java
|
|-- src/main/resources/
|   |-- application.properties
|
|-- pom.xml

Step 2: Add Maven Dependencies

Add the Spring AI dependency for your model provider.

Example Maven Dependency

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

Spring AI provides auto-configuration for model providers such as OpenAI, Anthropic, Ollama, Mistral, Azure OpenAI, Vertex AI, and AWS Bedrock. :contentReference[oaicite:1]{index=1}

Step 3: Configure API Key

Add your API key in application.properties.

spring.ai.openai.api-key=${OPENAI_API_KEY}
spring.ai.openai.chat.options.model=gpt-4o-mini
spring.ai.openai.chat.options.temperature=0.7

Do not hardcode API keys directly in production. Use environment variables, Kubernetes Secrets, or a secret manager.

Environment Variable Example

export OPENAI_API_KEY=your_api_key_here

On Windows PowerShell:

$env:OPENAI_API_KEY="your_api_key_here"

Step 4: Create Main Application Class

package com.example.springai;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class SpringAiDemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringAiDemoApplication.class, args);
    }
}

Step 5: Create Chat Service

Spring AI provides ChatClient, a fluent API for creating prompts and calling chat models. The official reference explains that ChatClient supports fluent prompt creation using methods such as prompt(), system messages, user messages, and structured calls. :contentReference[oaicite:2]{index=2}

package com.example.springai.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 ask(String message) {
        return chatClient.prompt()
                .system("You are a helpful Java and Spring Boot AI assistant.")
                .user(message)
                .call()
                .content();
    }
}

Step 6: Create REST Controller

package com.example.springai.controller;

import com.example.springai.service.ChatService;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ChatController {

    private final ChatService chatService;

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

    @GetMapping("/api/chat")
    public String chat(@RequestParam String message) {
        return chatService.ask(message);
    }
}

Step 7: Run the Application

mvn spring-boot:run

Open your browser or use curl:

curl "http://localhost:8080/api/chat?message=Explain Spring AI in simple words"

Expected Flow

Browser / curl
      |
      v
/api/chat endpoint
      |
      v
ChatController
      |
      v
ChatService
      |
      v
Spring AI ChatClient
      |
      v
AI Model
      |
      v
Response returned

Step 8: Improve the Prompt

A simple prompt works for testing, but production applications need better prompt structure.

public String ask(String message) {
    return chatClient.prompt()
            .system("""
                    You are an expert Java, Spring Boot, and AI assistant.
                    Answer clearly.
                    Use examples when helpful.
                    If you do not know, say you do not know.
                    """)
            .user(message)
            .call()
            .content();
}

Step 9: Create Request and Response DTOs

Instead of using query parameters, production APIs usually use request bodies.

package com.example.springai.dto;

public class ChatRequest {

    private String message;

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }
}

package com.example.springai.dto;

public class ChatResponse {

    private String answer;

    public ChatResponse(String answer) {
        this.answer = answer;
    }

    public String getAnswer() {
        return answer;
    }
}

POST Controller Example

@PostMapping("/api/chat")
public ChatResponse chat(@RequestBody ChatRequest request) {
    String answer = chatService.ask(request.getMessage());
    return new ChatResponse(answer);
}

Step 10: Add Basic Input Validation

AI APIs can become expensive if users send very large prompts. Always validate input.

public String ask(String message) {

    if (message == null || message.isBlank()) {
        return "Please enter a valid question.";
    }

    if (message.length() > 2000) {
        return "Your question is too long. Please shorten it.";
    }

    return chatClient.prompt()
            .system("You are a helpful Spring AI assistant.")
            .user(message)
            .call()
            .content();
}

Real-Time Banking Example

A banking assistant should not directly trust user input. It should validate authentication, fetch verified data, and avoid guessing.

User:
Why was â‚¹5,000 debited?

Correct flow:
1. Validate logged-in user
2. Fetch transaction from banking API
3. Build safe prompt
4. Ask model to explain only verified data
5. Return answer

Real-Time E-Commerce Example

An e-commerce assistant can help users track orders.

User:
Where is my order?

Correct flow:
1. Validate user
2. Fetch order details
3. Fetch shipment status
4. Generate user-friendly explanation

Step 11: Add Tool Calling Later

Spring AI supports tool calling, where the model can request application-defined tools. The Spring AI documentation explains that tools include a name, description, and parameter schema; when a model requests a tool call, the application executes the tool and returns results back to the model. :contentReference[oaicite:3]{index=3}

Tool Calling Flow

User asks question
      |
      v
Model decides tool is needed
      |
      v
Spring AI executes Java tool
      |
      v
Tool result returned to model
      |
      v
Final answer generated

Example Tool Use Case

User asks order status
Agent calls Order Service
Order Service returns shipment data
Agent explains result to user

Step 12: Add RAG Later

Spring AI supports Retrieval-Augmented Generation using modular RAG architecture and Advisor APIs. RAG helps overcome limitations related to factual accuracy, long-form content, and enterprise context. :contentReference[oaicite:4]{index=4}

RAG Flow

User Question
      |
      v
Generate Embedding
      |
      v
Search Vector Database
      |
      v
Retrieve Relevant Documents
      |
      v
Build Prompt with Context
      |
      v
Generate Grounded Answer

Step 13: Add Observability

Spring AI provides observability support for core components such as ChatClient, ChatModel, EmbeddingModel, ImageModel, and VectorStore. :contentReference[oaicite:5]{index=5}

Add Actuator:

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

Important Metrics

Response latency
LLM call failures
Token usage
Tool call failures
User request count
Error rate

Step 14: Basic Testing

Create tests for deterministic logic such as input validation, prompt building, and controller behavior.

@SpringBootTest
class ChatServiceTest {

    @Test
    void shouldRejectEmptyMessage() {
        // Test validation logic here
    }
}

For unit tests, avoid calling the real model every time. Mock the AI client or test only your business logic.

Common Errors and Fixes

1. API Key Missing

Error:
API key not configured

Fix:

Set OPENAI_API_KEY environment variable

2. Wrong Dependency

Use the correct starter for your chosen provider.

3. Model Not Available

Check model name and provider access.

4. Long Response Time

Reduce prompt size, use a faster model, or cache repeated answers.

5. High Cost

Track token usage and avoid sending unnecessary context.

Production Best Practices

Never hardcode API keys
Use environment variables or secret managers
Validate user input
Use structured prompts
Monitor latency and error rate
Track token usage and cost
Use RAG for factual enterprise answers
Use tool authorization for sensitive actions
Log safely without exposing sensitive data
Test prompts before production deployment

Complete Learning Flow

Start with Simple Chat API
          |
          v
Add Prompt Templates
          |
          v
Add Input Validation
          |
          v
Add Tool Calling
          |
          v
Add RAG with Vector Database
          |
          v
Add Memory
          |
          v
Add Observability
          |
          v
Deploy to Production

Interview Questions

Q1: What is Spring AI?

Spring AI is a framework that helps Java developers integrate AI models, prompts, embeddings, vector databases, tools, and RAG workflows into Spring Boot applications.

Q2: What is ChatClient in Spring AI?

ChatClient is a fluent API used to build prompts and interact with chat models.

Q3: Why should API keys not be hardcoded?

Hardcoded keys can leak through source code, logs, or repositories. Use environment variables or secret managers.

Q4: What is RAG?

Retrieval-Augmented Generation retrieves relevant documents and adds them to the prompt so the model can generate grounded answers.

Q5: What is tool calling?

Tool calling allows the AI model to request external Java methods, APIs, or services when needed.

Advanced Interview Questions

Q1: How do you make a Spring AI application production-ready?

Use secure secrets, input validation, prompt testing, observability, fallback handling, tool authorization, RAG grounding, and cost monitoring.

Q2: How do you reduce hallucinations in Spring AI?

Use RAG, verified enterprise data, strict prompts, response validation, and tool-based grounding.

Q3: How do you monitor Spring AI applications?

Use Spring Boot Actuator, Micrometer, Prometheus, Grafana, logs, traces, token usage metrics, and model error tracking.

Q4: Can Spring AI work with local models?

Yes. Spring AI supports integrations such as Ollama for local model usage. :contentReference[oaicite:6]{index=6}

Q5: Why use Spring AI instead of direct REST calls?

Spring AI provides abstraction, auto-configuration, provider portability, prompt support, tool calling, vector store integration, and observability.

Recommended Learning Path

Summary

Setting up your first Spring AI project is simple if you start with a basic Spring Boot application, add the correct Spring AI starter dependency, configure your AI provider, create a ChatClient-based service, and expose it through a REST controller.

After the basic setup, you can gradually add prompt templates, DTOs, validation, tool calling, RAG, memory, observability, and production deployment.

Spring AI is powerful because it brings AI development into the familiar Java and Spring Boot ecosystem, making it easier for enterprise developers to build reliable, secure, and scalable AI-powered applications.