spring-ai

name: spring-ai description: >- Build Spring AI application features with ChatClient, prompt templates, structured output, tool calling, advisors, chat memory, embeddings, vector stores, RAG, and MCP integration. Use when configuring chat models, wiring vector store backends, designing RAG pipelines, or integrating AI tool calling into Spring services.

Spring AI

Boundaries

Use spring-ai for model-facing application seams, retrieval flow, Spring-managed AI integration, and provider-neutral model abstractions.

• Non-AI message routing, adapters, and Enterprise Integration Patterns are outside this skill's scope.
• Keep provider SDK details at the configuration edge. Application services should depend on Spring AI abstractions such as ChatClient, EmbeddingModel, VectorStore, ImageModel, TranscriptionModel, TextToSpeechModel, or ModerationModel.
• Keep business rules outside prompts and outside tool implementations. Spring AI should orchestrate model interaction, not replace core domain logic.

Official surface map

Use this map to keep the official Spring AI surface visible without pushing the common path into references/.

Common path

The ordinary Spring AI job is:

1. Pin one Spring AI BOM version and add only the starters needed for the first production use case.
2. Start with one provider-neutral ChatClient seam around an application service.
3. Use prompt templates and structured output before adding tools, memory, or retrieval.
4. Expose only narrow, side-effect-safe tools when the plain prompt path is already correct.
5. Add advisors or chat memory only when the use case needs request decoration or multi-turn continuity.
6. Add RAG only after the non-RAG path is testable and the retrieval boundary is explicit.
7. Add image, audio, moderation, MCP, or effective-agent workflows only for concrete blockers, not by default.
8. Validate prompt assembly, output mapping, tool safety, conversation scoping, retrieval behavior, token usage, and production telemetry before rollout.

Dependency baseline

Spring AI 2.0.x supports Spring Boot 4.0.x and 4.1.x.

Import the Spring AI BOM and add only the starters needed for the current model and optional retrieval path.

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

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

Add retrieval, image, audio, moderation, or MCP starters only when that surface is part of the current job. Open references/upgrade-notes-and-migration-branches.md when the target Spring AI version differs from the version pinned here.

First safe setup

Minimal provider properties

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

Start with one provider, one model, and one environment-backed secret. Open references/provider-selection-and-model-capability-fit.md when model family, context window, latency, cost, or provider fit is still unclear.

Provider-neutral ChatClient seam

@Configuration
class AssistantAiConfiguration {
    @Bean
    ChatClient releaseChatClient(ChatClient.Builder builder) {
        return builder.defaultSystem("You summarize release changes for backend engineers.").build();
    }
}

Keep the application seam on ChatClient or another Spring AI abstraction. Do not let controllers or domain code depend directly on a provider SDK.

Prompt templating and structured output

Use prompt templates before introducing tools, memory, or retrieval. Keep variables explicit and keep prompt text reviewable in code.

record ReleaseSummary(String version, List<String> breakingChanges, List<String> actions) {}

@Service
class ReleaseSummaryService {
    private final ChatClient chatClient;

    ReleaseSummaryService(ChatClient chatClient) {
        this.chatClient = chatClient;
    }

    ReleaseSummary summarize(String releaseNotes) {
        return chatClient.prompt()
            .user(user -> user.text("Summarize the release notes and list required migration actions. Notes: {notes}").param("notes", releaseNotes))
            .call()
            .entity(ReleaseSummary.class);
    }
}

• Keep prompt variables named and explicit.
• Put reusable system instructions on the ChatClient builder or a dedicated service seam.
• Start with Spring AI mapping such as .entity(...) so the application stays on Spring AI's portable output contract instead of binding ordinary flows to one provider's JSON mode.
• Keep provider-native JSON modes as an optimization, not the default path, and open references/upgrade-notes-and-migration-branches.md when version or provider changes threaten the output contract.

Tool boundary

Add tools only when the model genuinely needs a bounded application capability.

@Component
class InventoryTools {
    private final InventoryRepository inventoryRepository;

    InventoryTools(InventoryRepository inventoryRepository) {
        this.inventoryRepository = inventoryRepository;
    }

    @Tool(description = "Look up available inventory for a SKU")
    InventorySnapshot inventoryForSku(String sku) {
        return inventoryRepository.findSnapshotBySku(sku);
    }
}

@Service
class ShippingAssistantService {
    private final ChatClient chatClient;
    private final InventoryTools inventoryTools;

    ShippingAssistantService(ChatClient chatClient, InventoryTools inventoryTools) {
        this.chatClient = chatClient;
        this.inventoryTools = inventoryTools;
    }

    String answer(String question) {
        return chatClient.prompt()
            .user(question)
            .tools(inventoryTools)
            .call()
            .content();
    }
}

record InventorySnapshot(String sku, int availableQuantity) {}

• Start with read-only or otherwise side-effect-safe tools.
• Treat tool selection as an application contract.
• ToolCallingAdvisor is auto-registered when tools are configured (2.0.0+). Disable globally with spring.ai.chat.client.tool-calling.enabled=false or per-call with AdvisorParams.toolCallingAdvisorAutoRegister(false).
• Open references/advanced-tool-orchestration.md when one tool call must explicitly feed the next.
• Open references/tool-set-curation.md when the blocker is exposing only a curated tool set.
• Open references/tool-failure-and-fallback.md when the blocker is explicit fallback behavior after tool failure.
• Open references/mcp-client-server-boundaries.md when the tool boundary may need MCP instead of an in-process Spring bean.

Memory and retrieval escalation

Use advisors when the request or response must be decorated around the model call. Use ChatMemory through an advisor instead of manually appending prior turns.

Spring AI ships built-in advisors: MessageChatMemoryAdvisor (message history), VectorStoreChatMemoryAdvisor (vector store-backed memory retrieval), QuestionAnswerAdvisor (naive RAG), RetrievalAugmentationAdvisor (modular RAG with query transformation, document post-processing, and context augmentation), ReReadingAdvisor (re-reading reasoning improvement), and SafeGuardAdvisor (content safety gate). Use in-memory MessageWindowChatMemory for demos and tests; use repository-backed memory for production multi-session workloads.

@Bean
ChatClient supportChatClient(ChatClient.Builder builder, ChatMemory chatMemory) {
    return builder.defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory).build()).build();
}

String answer(ChatClient chatClient, String conversationId, String question) {
    return chatClient.prompt()
        .advisors(advisors -> advisors.param(ChatMemory.CONVERSATION_ID, conversationId))
        .user(question)
        .call()
        .content();
}

@Service
class KnowledgeSearchService {
    private final VectorStore vectorStore;

    KnowledgeSearchService(VectorStore vectorStore) {
        this.vectorStore = vectorStore;
    }

    List<Document> search(String question) {
        return vectorStore.similaritySearch(SearchRequest.builder()
            .query(question)
            .topK(4)
            .similarityThreshold(0.75)
            .build());
    }
}

• Keep the conversation identifier explicit at the call site.
• Use in-memory chat memory only for demos, tests, or single-instance transient flows.
• Add RAG only after the non-RAG path is correct and testable.
• Keep EmbeddingModel as the portable seam for vector generation and treat the concrete VectorStore implementation as a deployment decision.
• Open references/advisors-memory-and-conversation-state.md when advisor ordering, persistent memory repositories, token buffering, or conversation isolation becomes the blocker.
• Open references/rag-pipeline-and-vector-store-decisions.md when chunking, embeddings, metadata filters, vector-store choice, or advanced retrieval tuning is the blocker.

Secondary official surfaces

These surfaces are part of official Spring AI scope, but they are not on the ordinary path unless the use case requires them.

• Open references/image-generation-and-vision-inputs.md when the feature must attach single-image vision input to a chat request.
• Open references/multiple-image-comparison.md when the blocker is comparing or cross-referencing several images in one request.
• Open references/image-generation.md when the blocker is producing generated image artifacts instead of text.
• Open references/audio-transcription-and-speech-output.md when the feature must transcribe audio or synthesize speech.
• Open references/moderation-and-safety-gates.md when input or output moderation is required.
• Open references/routing-workflow.md when routing is the blocker.
• Open references/chain-workflow.md when one bounded model step must explicitly feed the next.
• Open references/planning-and-stepwise-execution.md when the task is too large for one safe pass and needs a bounded plan first.
• Open references/loop-bounds-and-iteration-control.md when iterative refinement needs an application-level bound.

Usage handling and observability

Treat token accounting as part of the application contract, not as an afterthought.

• Read Usage from the final ChatResponse when cost, token budgets, or provider drift matter.
• Record prompt, completion, and total token counts together with latency and tool or retrieval activity.
• Open references/observability-and-production-debugging.md when usage accounting, tracing, or production debugging becomes the blocker.

Minimal validation

Verify the first Spring AI path before expanding scope.

• Verify prompt assembly without a live provider where possible.
• Verify structured-output mapping for one valid and one invalid response shape.
• Verify tool methods behave like normal application APIs, including validation and authorization boundaries.
• Verify advisor and chat-memory scoping with an explicit conversation ID.
• Verify retrieval returns the expected documents and that empty-context behavior is explicit.
• Verify token usage, latency, and tool-call identity are observable in the final path.

Open references/testing-and-evaluation-harnesses.md when the task needs repeatable evaluation datasets, regression checks, or infrastructure-backed integration tests. Open references/observability-and-production-debugging.md when adding usage accounting, tracing, or production incident diagnostics.

Production guardrails

• Externalize provider credentials, endpoints, model names, moderation settings, and retrieval settings.
• Keep prompts, tool contracts, retrieval settings, and structured-output types versioned and reviewable.
• Put timeouts, retries, fallback behavior, and provider switching at the provider edge.
• Log latency, token usage, retrieval count, and tool usage without leaking secrets or personal data.
• Treat image, audio, and moderation model choices as explicit configuration, not ambient defaults.