Spring AI Getting Started

Spring AI brings the capabilities of large language models (LLMs) to the Spring ecosystem, allowing Java developers to build intelligent applications using the same programming model they trust. It provides portable abstractions for chat, embeddings, vector stores, and tool calling, making it possible to integrate AI into enterprise systems without abandoning the JVM or Spring Boot.

This section is your launchpad. It assumes you are comfortable with Java and Spring Boot but may be new to AI development. Instead of throwing you into complex RAG pipelines or provider configurations, it guides you through a structured sequence of concepts and hands-on steps that build a solid foundation. By the end of this section, you will have a working Spring AI application, an understanding of the project structure, and the mental model needed to tackle the more advanced topics in the Framework, RAG, and Enterprise AI sections.

We believe a disciplined learning path produces better engineers. Rushing into code without understanding the architecture leads to fragile implementations and missed opportunities. This section is designed to give you both the confidence and the competence to move forward correctly.

What You Will Learn

After completing the Getting Started section, you will be able to:

• Set up a Spring Boot project with the correct Spring AI dependencies and version management.
• Configure a model provider (such as OpenAI or Ollama) through Spring Boot’s auto-configuration.
• Build, run, and test a minimal chat application that sends prompts and processes responses.
• Understand the directory layout of a typical Spring AI project and the role of key configuration files.
• Recognize the core concepts—ChatClient, ChatModel, Prompt, and ChatResponse—and their relationships.
• Explain the high-level Spring AI architecture and how it fits into a larger Spring application.
• Make an informed decision about which part of the handbook to study next based on your project requirements.

These outcomes are achieved through a combination of concept articles, step-by-step guides, and explicit references to the official Spring AI documentation where deeper detail is needed. The goal is not to teach you every API, but to give you a reliable map of the territory.

Recommended Learning Path

The following sequence is the optimal path for first-time Spring AI users. Each step builds on the previous one, and skipping ahead often creates confusion that could have been avoided with a bit of groundwork.

1. Getting Started with Spring AI
   Start here for a high-level introduction to Spring AI, its design philosophy, and how it positions itself in the Java AI landscape. This article explains what Spring AI is and why it exists, giving you the motivation to continue.

2. Spring AI Installation Guide
   Set up your development environment. This guide covers dependency management for Maven and Gradle, version compatibility with Spring Boot, and the initial configuration required to connect to a model provider. It ensures your project compiles and runs before you write any AI code.

3. Your First Spring AI Application
   Write a complete, runnable Spring Boot application that sends a prompt to an LLM and prints the response. This is a “Hello, AI” experience that validates your setup and introduces you to ChatClient in its simplest form.

4. Spring AI Project Structure
   Understand the recommended project layout, configuration classes, and the separation of concerns that scales from a single-module demo to a multi-module enterprise project. This guide prevents the “where do I put this file?” questions that plague beginners.

5. Framework Fundamentals (link to Framework section)
   Once you have a working application and understand its structure, move to the Spring AI Framework section to deepen your knowledge of ChatClient, prompts, streaming, tool calling, and more.

Following this order prevents the common mistake of trying to implement RAG before understanding the basic request-response cycle. Resist the temptation to jump ahead—the Framework and RAG sections will still be there when you are ready.

Core Getting Started Guides

The table below lists the primary guides that form the Getting Started curriculum. Start from the top and work your way down.

Guide	What It Covers	Link
Getting Started with Spring AI	Overview of Spring AI, its role, and its core abstractions	getting-started
Spring AI Installation Guide	Dependency setup, version compatibility, and provider configuration basics	installation
Your First Spring AI Application	Building and running a simple chat interaction with ChatClient	first-application
Spring AI Project Structure	Recommended project layout, configuration patterns, and module organization	project-structure

Each guide is self-contained but cross-referenced. If a concept is mentioned but not explained in depth, a link will point you to the relevant section of the handbook.

Why Spring AI for Java Developers?

If you are a Java developer, you already own one of the most powerful platforms for building enterprise software. Spring AI extends that platform into the AI era without asking you to learn Python, JavaScript, or a new deployment model.

• Familiar Spring programming model – You define beans, inject dependencies, and use auto-configuration just as you would for a database or message queue. The learning curve is minimal.
• Enterprise Java ecosystem fit – Your AI code runs inside the same Spring Boot application that handles transactions, security, monitoring, and deployment. No separate microservice, no polyglot complexity.
• Vendor abstraction for AI providers – Spring AI decouples your code from a specific LLM provider. You can swap between OpenAI, Azure OpenAI, Ollama, and others with configuration changes, not code rewrites.
• Production-friendly design – Retry, observability, token tracking, and structured output are built in from the start, because the framework was created by engineers who run AI in production.
• Bridge between backend and AI – For many Java teams, AI development feels foreign. Spring AI makes it accessible by surfacing AI concepts through patterns you already understand: templates, clients, and annotated methods.

This combination means you can add AI capabilities to existing Spring applications incrementally, without a disruptive technology shift.

Before You Begin

To get the most out of this section, you should have a working knowledge of:

• Java – You are comfortable with Java 17 or later, understand basic generics, and can read and write simple Java applications.
• Spring Boot – You have created a Spring Boot project before, understand @SpringBootApplication, application.properties, and dependency injection with @Autowired or constructor injection.
• Maven or Gradle – You know how to add dependencies and build a project from the command line or your IDE.
• REST APIs – You understand the basics of HTTP and JSON, since most model providers are accessed via REST APIs.
• LLM concepts – A high-level awareness of what a large language model is and that it generates text based on prompts. You do not need deep ML expertise.

If you are missing any of these prerequisites, we recommend spending a day with the Spring Boot Getting Started guide or a Java refresher before proceeding. The investment will pay off when you can focus on AI concepts without struggling with the surrounding technology.

Spring AI in the Big Picture

This Getting Started section is the foundation of the entire Spring AI Handbook. Everything else depends on the concepts you learn here.

The diagram illustrates that Getting Started feeds directly into Framework, which in turn supports RAG, Provider integrations, and Enterprise patterns. Tutorials and Source Code analysis are best tackled after you have a solid grounding in the core abstractions. Skipping Getting Started and jumping straight to Source Code is like reading a decompiled class file before understanding the API contract—it may be possible, but it is neither efficient nor enjoyable.

What Comes Next

Once you have completed the Getting Started guides and have a running Spring AI application, you are ready to expand your knowledge. The recommended next sections depend on your immediate goals:

• If you need to understand the core APIs in detail—ChatClient, PromptTemplate, Streaming, Tool Calling—go to the Spring AI Framework section.
• If your project requires retrieval-augmented generation for document Q&A or knowledge bases, proceed to Spring AI RAG.
• If you are evaluating different LLM providers or need provider-specific configuration, visit Spring AI Providers.
• If you are a senior engineer or architect who wants to understand internals, start with Spring AI Source Code Analysis.

No matter which path you choose, the Getting Started foundation ensures you can read the advanced material with the necessary context.

Common Beginner Mistakes

Over the years, we have observed several patterns that slow down or derail newcomers. Being aware of these can save you hours of frustration.

• Jumping into RAG too early – RAG is powerful, but it assumes you understand embeddings, vector stores, and the ChatClient lifecycle. Trying to build a RAG application before mastering a simple chat request often results in a tangled mess.
• Ignoring dependency management – Spring AI has evolving versioning and compatibility with Spring Boot. Not aligning the versions or mixing snapshot and release artifacts causes cryptic startup failures.
• Confusing ChatClient and ChatModel – ChatClient is your application’s entry point; ChatModel is the lower-level abstraction for direct model invocation. Understanding this distinction prevents incorrect bean wiring and test complexity.
• Treating provider integration as the whole framework – Spring AI is not just a wrapper around OpenAI’s API. It offers prompt templating, advisors, memory, and evaluation that are provider-agnostic. Focusing solely on the provider layer misses the framework’s true value.
• Skipping architecture understanding – Reading source code without first studying the package structure and design philosophy leads to misinterpretation and wasted time. The architecture overview in the Framework section is there for a reason.

If you find yourself stuck, revisit the relevant Getting Started guide or the Framework architecture article. Often, the solution lies in a concept you glanced over.

Who This Section Is For

Java Developers

You build enterprise applications and now need to integrate AI. This section respects your existing Java skills and introduces AI concepts through analogies to databases, message queues, and templates—no Python required.

Spring Developers

You live and breathe Spring Boot, Spring Data, and Spring Security. This section shows you how Spring AI fits into that world as just another Spring module, complete with auto-configuration, @Bean definitions, and starter dependencies.

AI Engineers

You are proficient with Python AI frameworks but find yourself working in a Java shop. This section helps you translate your AI knowledge into Spring concepts, giving you a bridge to collaborate with Java teams or transition to JVM-based AI development.

Software Architects

You need to evaluate whether Spring AI is the right foundation for your organization’s AI initiatives. This section, combined with the Framework and Enterprise AI sections, provides the architectural context you need to make an informed decision.

Summary

The Getting Started section exists to remove the friction that often accompanies the adoption of a new technology. It gives you a clear, validated path from an empty IDE to a functioning Spring AI application, along with the conceptual framework to understand why things work the way they do.

A strong foundation is not a delay—it is an accelerator. Developers who invest an hour in understanding project structure and core concepts before building features consistently outperform those who copy-paste code from random tutorials. By the time you finish this section, you will not only have a working application; you will also know where to go next, what to avoid, and how to reason about the Spring AI framework as a whole.

Take your time with each guide. Run the examples. Experiment with different prompts. When you feel confident, move on to the Spring AI Framework section and begin mastering the toolkit that will carry you from simple chats to sophisticated, production-grade AI systems.