Spring AI

https://docs.spring.io/spring-ai/reference
Admin
Spring AI streamlines the development of artificial intelligence applications by providing portable...
Tokens:521,609
Snippets:3,937
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Complete Example

Source: https://docs.spring.io/spring-ai/reference/api/chat/anthropic-chat.html

Complete example demonstrating citation usage: creates a citation document, calls the model with it, displays the response, and processes the returned citations with a fallback message when none are present.

```java
// Create a citation document
AnthropicCitationDocument document = AnthropicCitationDocument.builder()
    .plainText("Spring AI is an application framework for AI engineering. " +
               "It provides a Spring-friendly API for developing AI applications. " +
               "The framework includes abstractions for chat models, embedding models, " +
               "and vector databases.")
    .title("Spring AI Overview")
    .citationsEnabled(true)
    .build();

// Call the model with the document
ChatResponse response = chatModel.call(
    new Prompt(
        "What is Spring AI?",
        AnthropicChatOptions.builder()
            .model("claude-sonnet-4-20250514")
            .maxTokens(1024)
            .citationDocuments(document)
            .build()
    )
);

// Display the response
System.out.println("Response: " + response.getResult().getOutput().getText());
System.out.println("\nCitations:");

// Process citations
List<Citation> citations = (List<Citation>) response.getMetadata().get("citations");

if (citations != null && !citations.isEmpty()) {
    for (int i = 0; i < citations.size(); i++) {
        Citation citation = citations.get(i);
        System.out.println("\n[" + (i + 1) + "] " + citation.getDocumentTitle());
        System.out.println("    Location: " + citation.getLocationDescription());
        System.out.println("    Text: " + citation.getCitedText());
    }
} else {
    System.out.println("No citations were provided in the response.");
}
```

--------------------------------

### Complete example: working with existing index and searching

Source: https://docs.spring.io/spring-ai/reference/api/vectordbs/azure.html

Complete example showing configuration of a SearchIndexClient and AzureVectorStore for an existing index with custom field names, followed by a similarity search using that store. The search uses a filter expression on the defined metadata fields.

```java
@Configuration
public class VectorStoreConfig {

	@Bean
	public SearchIndexClient searchIndexClient() {
		return new SearchIndexClientBuilder()
			.endpoint(System.getenv("AZURE_AI_SEARCH_ENDPOINT"))
			.credential(new AzureKeyCredential(System.getenv("AZURE_AI_SEARCH_API_KEY")))
			.buildClient();
	}

	@Bean
	public VectorStore vectorStore(SearchIndexClient searchIndexClient,
			EmbeddingModel embeddingModel) {

		return AzureVectorStore.builder(searchIndexClient, embeddingModel)
			.indexName("production-documents-index")
			.initializeSchema(false) // Use existing index
			// Map to existing index field names
			.contentFieldName("document_text")
			.embeddingFieldName("text_vector")
			.metadataFieldName("document_metadata")
			// Define filterable metadata fields from existing schema
			.filterMetadataFields(List.of(
				MetadataField.text("department"),
				MetadataField.int64("year"),
				MetadataField.date("created_date")))
			.defaultTopK(10)
			.defaultSimilarityThreshold(0.75)
			.build();
	}
}

```

```java
// Search using the existing index with custom field names
List<Document> results = vectorStore.similaritySearch(
	SearchRequest.builder()
		.query("artificial intelligence")
		.topK(5)
		.filterExpression("department == 'Engineering' && year >= 2023")
		.build());

// The results contain documents with text from the 'document_text' field
results.forEach(doc -> System.out.println(doc.getText()));

```

--------------------------------

### FileDocumentWriter usage example

Source: https://docs.spring.io/spring-ai/reference/api/etl-pipeline.html

Example of creating a FileDocumentWriter with all parameters and accepting a list of documents. Writes to 'output.txt' with document markers, all metadata, and appending.

```java
List<Document> documents = // initialize your documents
FileDocumentWriter writer = new FileDocumentWriter("output.txt", true, MetadataMode.ALL, true);
writer.accept(documents);
Copied!
```

--------------------------------

### Example response from LLaVA model

Source: https://docs.spring.io/spring-ai/reference/api/chat/ollama-chat.html

Shows a sample response generated by the LLaVA model when given the image and text prompt from the previous example.

```text
The image shows a small metal basket filled with ripe bananas and red apples. The basket is placed on a surface,
which appears to be a table or countertop, as there's a hint of what seems like a kitchen cabinet or drawer in
the background. There's also a gold-colored ring visible behind the basket, which could indicate that this
photo was taken in an area with metallic decorations or fixtures. The overall setting suggests a home environment
where fruits are being displayed, possibly for convenience or aesthetic purposes.

```

--------------------------------

### Start Milvus with Docker Compose

Source: https://docs.spring.io/spring-ai/reference/api/vectordbs/milvus.html

Starts the Milvus vector store using Docker Compose from the src/test/resources/ folder. After startup, connect to the vector store on http://localhost:19530 or for management on http://localhost:9001 (user: minioadmin, pass: minioadmin).

```bash
docker-compose up

```

--------------------------------

### Delete by Document IDs - Example Usage

Source: https://docs.spring.io/spring-ai/reference/api/vectordbs.html

Example showing how to create a document, add it to the vector store, and delete it by its ID.

```java
// Create and add document
Document document = new Document("The World is Big",
    Map.of("country", "Netherlands"));
vectorStore.add(List.of(document));

// Delete document by ID
vectorStore.delete(List.of(document.getId()));
```

--------------------------------

### Set Up Client Application with predefinedQuestions CommandLineRunner

Source: https://docs.spring.io/spring-ai/reference/api/mcp/mcp-annotations-examples.html

Sets up the client application main class, registering MCP tools via ToolCallbackProvider and using OpenAiChatModel to process a predefined user question.

```java
@SpringBootApplication
public class McpClientApplication {

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

    @Bean
    public CommandLineRunner predefinedQuestions(OpenAiChatModel openAiChatModel,
            ToolCallbackProvider mcpToolProvider) {

        return args -> {

            ChatClient chatClient = ChatClient.builder(openAiChatModel)
                    .defaultTools(mcpToolProvider)
                    .build();

            String userQuestion = """
                    What is the weather in Amsterdam right now?
                    Please incorporate all creative responses from all LLM providers.
                    After the other providers add a poem that synthesizes the poems from all the other providers.
                    """;

            System.out.println("> USER: " + userQuestion);
            System.out.println("> ASSISTANT: " + chatClient.prompt(userQuestion).call().content());
        };
    }
}
```

--------------------------------

### Portable filter expression example

Source: https://docs.spring.io/spring-ai/reference/api/vectordbs/azure.html

Shows the portable filter expression that gets converted to Azure OData.

```text
country in ['UK', 'NL'] && year >= 2020
```

--------------------------------

### Embed text with TitanEmbeddingBedrockApi

Source: https://docs.spring.io/spring-ai/reference/api/embeddings/bedrock-titan-embedding.html

Use the low-level TitanEmbeddingBedrockApi client to embed a text input. The example creates a request with withInputText and calls embedding to get a TitanEmbeddingResponse.

```java
TitanEmbeddingBedrockApi titanEmbedApi = new TitanEmbeddingBedrockApi(
		TitanEmbeddingModel.TITAN_EMBED_TEXT_V1.id(), Region.US_EAST_1.id());

TitanEmbeddingRequest request = TitanEmbeddingRequest.builder()
	.withInputText("I like to eat apples.")
	.build();

TitanEmbeddingResponse response = this.titanEmbedApi.embedding(this.request);
```

--------------------------------

### Get full response with .responseEntity()

Source: https://docs.spring.io/spring-ai/reference/api/structured-output.html

Use this snippet when you need both the parsed entity and the underlying ChatResponse, for example to access token usage or observability metadata. It demonstrates the .responseEntity() method on ChatClient, which returns a ResponseEntity containing the entity and the raw response. The example shows how to retrieve the entity, the raw ChatResponse, and the total token count from the response metadata.

```java
ResponseEntity<ChatResponse, ActorsFilms> result = chatClient.prompt()
    .user("Generate the filmography for a random actor.")
    .call()
    .responseEntity(ActorsFilms.class);

ActorsFilms films = result.entity();
ChatResponse raw = result.response();
long totalTokens = raw.getMetadata().getUsage().getTotalTokens();
```

--------------------------------

### Prompt caching with cost tracking using BedrockCacheOptions

Source: https://docs.spring.io/spring-ai/reference/api/chat/bedrock-converse.html

Complete example showing prompt caching with cost tracking. Creates a system prompt (1024+ tokens recommended) and makes two requests with the same system prompt using BedrockChatOptions with cacheOptions strategy SYSTEM_ONLY. Demonstrates reading cacheWriteInputTokens and cacheReadInputTokens from the metadata map; the second request should show cacheWrite=0 and cacheRead>0.

```java
// Create system content that will be reused multiple times
String largeSystemPrompt = "You are an expert software architect specializing in distributed systems...";
// (Ensure this is 1024+ tokens for cache effectiveness)

// First request - creates cache
ChatResponse firstResponse = chatModel.call(
    new Prompt(
        List.of(
            new SystemMessage(largeSystemPrompt),
            new UserMessage("What is microservices architecture?")
        ),
        BedrockChatOptions.builder()
            .model("us.anthropic.claude-haiku-4-5-20251001-v1:0")
            .cacheOptions(BedrockCacheOptions.builder()
                .strategy(BedrockCacheStrategy.SYSTEM_ONLY)
                .build())
            .maxTokens(500)
            .build()
    )
);

// Access cache-related token usage from metadata
Integer cacheWrite1 = (Integer) firstResponse.getMetadata()
    .getMetadata()
    .get("cacheWriteInputTokens");
Integer cacheRead1 = (Integer) firstResponse.getMetadata()
    .getMetadata()
    .get("cacheReadInputTokens");

System.out.println("Cache creation tokens: " + cacheWrite1);
System.out.println("Cache read tokens: " + cacheRead1);

// Second request with same system prompt - reads from cache
ChatResponse secondResponse = chatModel.call(
    new Prompt(
        List.of(
            new SystemMessage(largeSystemPrompt),  // Same prompt - cache hit
            new UserMessage("What are the benefits of event sourcing?")
        ),
        BedrockChatOptions.builder()
            .model("us.anthropic.claude-haiku-4-5-20251001-v1:0")
            .cacheOptions(BedrockCacheOptions.builder()
                .strategy(BedrockCacheStrategy.SYSTEM_ONLY)
                .build())
            .maxTokens(500)
            .build()
    )
);

Integer cacheWrite2 = (Integer) secondResponse.getMetadata()
    .getMetadata()
    .get("cacheWriteInputTokens");
Integer cacheRead2 = (Integer) secondResponse.getMetadata()
    .getMetadata()
    .get("cacheReadInputTokens");

System.out.println("Cache creation tokens: " + cacheWrite2); // Should be 0
System.out.println("Cache read tokens: " + cacheRead2);      // Should be > 0
```

--------------------------------

### Use JSON Pointer with JsonReader.get()

Source: https://docs.spring.io/spring-ai/reference/api/etl-pipeline.html

Example of using the get(String pointer) method with a JSON Pointer to extract a specific element. The pointer "/store/books/0" targets the first book in the store array.

```java
JsonReader jsonReader = new JsonReader(resource, "description");
List<Document> documents = this.jsonReader.get("/store/books/0");
```

--------------------------------

### SYSTEM_AND_TOOLS cache strategy example

Source: https://docs.spring.io/spring-ai/reference/api/chat/bedrock-converse.html

Java example showing how to use BedrockCacheOptions with the SYSTEM_AND_TOOLS strategy. It demonstrates cache behavior across three requests: first request creates both caches, second request (with changed system prompt) hits the tools cache but misses the system cache, and third request (with changed tools) misses both caches.

```java
// Request 1: Cache both tools and system
ChatResponse r1 = chatModel.call(
    new Prompt(
        List.of(new SystemMessage("System prompt"), new UserMessage("Question")),
        BedrockChatOptions.builder()
            .cacheOptions(BedrockCacheOptions.builder()
                .strategy(BedrockCacheStrategy.SYSTEM_AND_TOOLS)
                .build())
            .toolCallbacks(tools)
            .build()
    )
);
// Result: Both caches created

// Request 2: Change only system prompt (tools same)
ChatResponse r2 = chatModel.call(
    new Prompt(
        List.of(new SystemMessage("DIFFERENT system prompt"), new UserMessage("Question")),
        BedrockChatOptions.builder()
            .cacheOptions(BedrockCacheOptions.builder()
                .strategy(BedrockCacheStrategy.SYSTEM_AND_TOOLS)
                .build())
            .toolCallbacks(tools) // SAME tools
            .build()
    )
);
// Result: Tools cache HIT (reused), system cache MISS (recreated)

// Request 3: Change tools (system same as Request 2)
ChatResponse r3 = chatModel.call(
    new Prompt(
        List.of(new SystemMessage("DIFFERENT system prompt"), new UserMessage("Question")),
        BedrockChatOptions.builder()
            .cacheOptions(BedrockCacheOptions.builder()
                .strategy(BedrockCacheStrategy.SYSTEM_AND_TOOLS)
                .build())
            .toolCallbacks(newTools) // DIFFERENT tools
            .build()
    )
);
// Result: BOTH caches MISS (tools change invalidates everything downstream)
```

--------------------------------

### Use BeanOutputConverter to generate JSON schema and convert response (Kotlin)

Source: https://docs.spring.io/spring-ai/reference/api/chat/openai-chat.html

Kotlin version of the BeanOutputConverter example. Defines a data class MathReasoning with @get:JsonProperty annotations, generates the JSON schema, sends the prompt, and converts the response. Note that Kotlin reflection infers required fields from nullability and default values, so @get:JsonProperty(required = true) is often unnecessary.

```kotlin
data class MathReasoning(
	val steps: Steps,
	@get:JsonProperty(value = "final_answer") val finalAnswer: String) {

	data class Steps(val items: Array<Items>) {

		data class Items(
			val explanation: String,
			val output: String)
	}
}

val outputConverter = BeanOutputConverter(MathReasoning::class.java)

val jsonSchema = outputConverter.jsonSchema;

val prompt = Prompt("how can I solve 8x + 7 = -23",
	OpenAiChatOptions.builder()
		.model(ChatModel.GPT_4_O_MINI)
		.responseFormat(ResponseFormat(ResponseFormat.Type.JSON_SCHEMA, jsonSchema))
		.build())

val response = openAiChatModel.call(prompt)
val content = response.getResult().getOutput().getText()

val mathReasoning = outputConverter.convert(content)
```

--------------------------------

### Configure vLLM with reasoning parser and Spring AI

Source: https://docs.spring.io/spring-ai/reference/api/chat/openai-chat.html

Setup for using vLLM with a reasoning parser. The first block starts a vLLM server with the DeepSeek-R1-Distill-Qwen-1.5B model, enabling reasoning and using the deepseek_r1 parser. The second block configures Spring AI to point to that local server at http://localhost:8000 with the same model name.

```bash
vllm serve deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B \
    --enable-reasoning \
    --reasoning-parser deepseek_r1
```

```properties
spring.ai.openai.base-url=http://localhost:8000
spring.ai.openai.chat.model=deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B
```

--------------------------------

### Build a prompt with system and user messages

Source: https://docs.spring.io/spring-ai/reference/api/prompt.html

Shows how to create a user message and a system message using SystemPromptTemplate, then combine them into a Prompt and call the chat model to get a list of generations.

```java
String userText = """
    Tell me about three famous pirates from the Golden Age of Piracy and why they did.
    Write at least a sentence for each pirate.
    """;

Message userMessage = new UserMessage(userText);

String systemText = """
  You are a helpful AI assistant that helps people find information.
  Your name is {name}
  You should reply to the user's request with your name and also in the style of a {voice}.
  """;

SystemPromptTemplate systemPromptTemplate = new SystemPromptTemplate(systemText);
Message systemMessage = systemPromptTemplate.createMessage(Map.of("name", name, "voice", voice));

Prompt prompt = new Prompt(List.of(userMessage, systemMessage));

List<Generation> response = chatModel.call(prompt).getResults();
```

--------------------------------

### Get ToolCallbacks from Async MCP Clients

Source: https://docs.spring.io/spring-ai/reference/api/mcp/mcp-helpers.html

Gets ToolCallbacks from a list of McpAsyncClient instances using McpToolUtils.getToolCallbacksFromAsyncClients.

```java
List<McpAsyncClient> asyncClients = // obtain async clients
List<ToolCallback> asyncCallbacks = McpToolUtils.getToolCallbacksFromAsyncClients(asyncClients);
```

--------------------------------

### Sample Output from Client

Source: https://docs.spring.io/spring-ai/reference/api/mcp/mcp-annotations-examples.html

Sample output from running the client, showing the user prompt and the assistant's response with poems from OpenAI and Anthropic, followed by weather data in JSON format.

```text
> USER: What is the weather in Amsterdam right now?
Please incorporate all creative responses from all LLM providers.
After the other providers add a poem that synthesizes the poems from all the other providers.

> ASSISTANT:
OpenAI poem about the weather:
**Amsterdam's Winter Whisper**
*Temperature: 4.2°C*

In Amsterdam's embrace, where canals reflect the sky,
A gentle chill of 4.2 degrees drifts by...

Anthropic poem about the weather:
**Canal-Side Contemplation**
*Current conditions: 4.2°C*

Along the waterways where bicycles rest,
The winter air puts Amsterdam to test...

Weather Data:
{
  "current": {
    "time": "2025-01-23T11:00",
    "interval": 900,
    "temperature_2m": 4.2
  }
}
```

--------------------------------

### Get ToolCallbacks from Sync MCP Clients

Source: https://docs.spring.io/spring-ai/reference/api/mcp/mcp-helpers.html

Gets ToolCallbacks from a list of McpSyncClient instances using McpToolUtils.getToolCallbacksFromSyncClients.

```java
List<McpSyncClient> syncClients = // obtain sync clients
List<ToolCallback> syncCallbacks = McpToolUtils.getToolCallbacksFromSyncClients(syncClients);
```

--------------------------------

### Basic usage of ToolSearchToolCallingAdvisor

Source: https://docs.spring.io/spring-ai/reference/guides/dynamic-tool-search.html

Shows how to build a ChatClient with the Tool Search advisor, registering many tools but only sending relevant ones to the LLM. The example includes a MyTools class with @Tool methods.

```java
@SpringBootApplication
public class Application {

    @Bean
    CommandLineRunner demo(ChatClient.Builder builder, ToolIndex toolIndex) {
        return args -> {
            var advisor = ToolSearchToolCallingAdvisor.builder()
                .toolIndex(toolIndex)
                .build();

            ChatClient chatClient = builder
                .defaultTools(new MyTools())  // 100s of tools registered but NOT sent to LLM initially
                .defaultAdvisors(advisor)     // Activate Tool Search Tool
                .build();

            var answer = chatClient.prompt("""
                Help me plan what to wear today in Amsterdam.
                Please suggest clothing shops that are open right now.
                """).call().content();

            System.out.println(answer);
        };
    }

    static class MyTools {
        @Tool(description = "Get the weather for a given location at a given time")
        public String weather(String location,
            @ToolParam(description = "YYYY-MM-DDTHH:mm") String atTime) {
            // implementation
        }

        @Tool(description = "Get clothing shop names for a given location at a given time")
        public List<String> clothing(String location,
                @ToolParam(description = "YYYY-MM-DDTHH:mm") String openAtTime) {
            // implementation
        }

        @Tool(description = "Current date and time for a given location")
        public String currentTime(String location) {
            // implementation
        }

        // ... potentially hundreds more tools
    }
}
```

--------------------------------

### Configure runtime options with BedrockChatOptions builder

Source: https://docs.spring.io/spring-ai/reference/api/chat/bedrock-converse.html

Shows how to create a BedrockChatOptions instance with model, temperature, maxTokens, and tool callbacks, then use it in a ChatClient prompt call.

```java
var options = BedrockChatOptions.builder()
        .model("us.anthropic.claude-haiku-4-5-20251001-v1:0")
        .temperature(0.6)
        .maxTokens(300)
        .toolCallbacks(List.of(FunctionToolCallback.builder("getCurrentWeather", new WeatherService())
            .description("Get the weather in location. Return temperature in 36°F or 36°C format. Use multi-turn if needed.")
            .inputType(WeatherService.Request.class)
            .build()))
        .build();

String response = ChatClient.create(this.chatModel)
    .prompt("What is current weather in Amsterdam?")
    .options(options)
    .call()
    .content();
```

--------------------------------

### Portable filter expression example

Source: https://docs.spring.io/spring-ai/reference/api/vectordbs/gemfire.html

Example portable filter expression that is converted into the proprietary GemFire VectorDB filter format.

```text
country == 'BG' && year >= 2020
```

--------------------------------

### Using ChromaVectorStore to add documents and search

Source: https://docs.spring.io/spring-ai/reference/api/vectordbs/chroma.html

Shows how to autowire the Chroma VectorStore, add documents, and perform a similarity search with a query and topK parameter.

```java
@Autowired VectorStore vectorStore;

// ...

List <Document> documents = List.of(
    new Document("Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", Map.of("meta1", "meta1")),
    new Document("The World is Big and Salvation Lurks Around the Corner"),
    new Document("You walk forward facing the past and you turn back toward the future.", Map.of("meta2", "meta2")));

// Add the documents
vectorStore.add(documents);

// Retrieve documents similar to a query
List<Document> results = this.vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(5).build());
```

--------------------------------

### Example formatting instructions for JSON output

Source: https://docs.spring.io/spring-ai/reference/api/structured-output/converters.html

Shows the formatting instructions that a FormatProvider might supply to the AI model, requesting a JSON response matching a Java class and RFC8259 compliance.

```text
  Your response should be in JSON format.
  The data structure for the JSON should match this Java class: java.util.HashMap
  Do not include any explanations, only provide a RFC8259 compliant JSON response following this format without deviation.
```

--------------------------------

### Add standard MCP client starter dependency

Source: https://docs.spring.io/spring-ai/reference/api/mcp/mcp-client-boot-starter-docs.html

Adds the spring-ai-starter-mcp-client dependency to connect to MCP servers over STDIO, SSE, Streamable-HTTP, and Stateless Streamable-HTTP transports. Supports both SYNC and ASYNC clients, but mixing them is not allowed.

```xml
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-client</artifactId>
</dependency>
```

--------------------------------

### Delete by String Filter Expression - Example Usage

Source: https://docs.spring.io/spring-ai/reference/api/vectordbs.html

Example showing how to delete documents using a string filter and verify the remaining documents with a search.

```java
// Create and add documents
Document bgDocument = new Document("The World is Big",
    Map.of("country", "Bulgaria"));
Document nlDocument = new Document("The World is Big",
    Map.of("country", "Netherlands"));
vectorStore.add(List.of(bgDocument, nlDocument));

// Delete Bulgarian documents using string filter
vectorStore.delete("country == 'Bulgaria'");

// Verify remaining documents
SearchRequest request = SearchRequest.builder()
    .query("World")
    .topK(5)
    .build();
List<Document> results = vectorStore.similaritySearch(request);
// results will only contain the Netherlands document
```

--------------------------------

### Delete by Filter Expression - Example Usage

Source: https://docs.spring.io/spring-ai/reference/api/vectordbs.html

Example showing how to create documents with different metadata, add them, delete by a filter expression, and verify deletion with a search.

```java
// Create test documents with different metadata
Document bgDocument = new Document("The World is Big",
    Map.of("country", "Bulgaria"));
Document nlDocument = new Document("The World is Big",
    Map.of("country", "Netherlands"));

// Add documents to the store
vectorStore.add(List.of(bgDocument, nlDocument));

// Delete documents from Bulgaria using filter expression
Filter.Expression filterExpression = new Filter.Expression(
    Filter.ExpressionType.EQ,
    new Filter.Key("country"),
    new Filter.Value("Bulgaria")
);
vectorStore.delete(filterExpression);

// Verify deletion with search
SearchRequest request = SearchRequest.builder()
    .query("World")
    .filterExpression("country == 'Bulgaria'")
    .build();
List<Document> results = vectorStore.similaritySearch(request);
// results will be empty as Bulgarian document was deleted
```

--------------------------------

### Manual wiring of ToolSearchToolCallingAdvisor

Source: https://docs.spring.io/spring-ai/reference/api/tools/tool-search-tool.html

Shows how to configure a ToolIndex, build the advisor, register it with ChatClient, and make a request with a session ID. Tools are indexed but not sent to the LLM up front.

```java
// 1. Configure a ToolIndex (semantic, keyword, or regex)
@Bean
ToolIndex toolIndex(VectorStore vectorStore) {
    return new VectorToolIndex(vectorStore);
}

// 2. Build the advisor
var toolSearchAdvisor = ToolSearchToolCallingAdvisor.builder()
    .toolIndex(toolIndex)
    .maxResults(5)
    .build();

// 3. Register with ChatClient — tools are indexed but NOT sent to the LLM up front
ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultTools(new MyTools())
    .defaultAdvisors(toolSearchAdvisor)
    .build();

// 4. Make a request — supply a session ID via the advisor context
String answer = chatClient.prompt("Help me plan what to wear today in Amsterdam")
    .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, "user-42-session"))
    .call()
    .content();
```

--------------------------------

### Zero-shot sentiment classification with ChatClient

Source: https://docs.spring.io/spring-ai/reference/api/chat/prompt-engineering-patterns.html

Zero-shot prompting example that classifies a movie review sentiment without providing examples. Uses a low temperature (0.1) for deterministic results and maps the response directly to a Java enum via `.entity(Sentiment.class)`. Ideal for straightforward tasks where the model has likely seen similar examples during training.

```java
// Implementation of Section 2.1: General prompting / zero shot (page 15)
public void pt_zero_shot(ChatClient chatClient) {
    enum Sentiment {
        POSITIVE, NEUTRAL, NEGATIVE
    }

    Sentiment reviewSentiment = chatClient.prompt("""
            Classify movie reviews as POSITIVE, NEUTRAL or NEGATIVE.
            Review: "Her" is a disturbing study revealing the direction
            humanity is headed if AI is allowed to keep evolving,
            unchecked. I wish there were more movies like this masterpiece.
            Sentiment:
            """)
            .options(ChatOptions.builder()
                    .model("claude-sonnet-4-6")
                    .temperature(0.1)
                    .maxTokens(5)
                    .build())
            .call()
            .entity(Sentiment.class);

    System.out.println("Output: " + reviewSentiment);
}
```

--------------------------------

### Runtime options for OpenAiAudioSpeechModel

Source: https://docs.spring.io/spring-ai/reference/api/audio/speech/openai-speech.html

Builds an OpenAiAudioSpeechOptions instance with model, voice, response format, speed, and instructions, then creates a TextToSpeechPrompt and calls the model. The instructions option is OpenAI-specific and not portable.

```java
OpenAiAudioSpeechOptions speechOptions = OpenAiAudioSpeechOptions.builder()
    .model("gpt-4o-mini-tts")
    .voice(OpenAiAudioApi.SpeechRequest.Voice.ALLOY)
    .responseFormat(OpenAiAudioApi.SpeechRequest.AudioResponseFormat.MP3)
    .speed(1.0)
    .instructions("Friendly; warm tone; natural pauses")
    .build();

TextToSpeechPrompt speechPrompt = new TextToSpeechPrompt("Hello, this is a text-to-speech example.", speechOptions);
TextToSpeechResponse response = openAiAudioSpeechModel.call(speechPrompt);
```

--------------------------------

### Add MCP Client Starter Dependency

Source: https://docs.spring.io/spring-ai/reference/api/tools.html

Add the MCP client starter to consume tools from MCP servers.

```xml
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-client</artifactId>
</dependency>
Copied!

```

--------------------------------

### FactCheckingEvaluator example with Ollama and Bespoke-Minicheck

Source: https://docs.spring.io/spring-ai/reference/api/testing.html

Example test that sets up an Ollama API and ChatModel with the Bespoke-Minicheck model, creates a FactCheckingEvaluator, and evaluates a claim against a context, asserting that the claim is not supported.

```java
@Test
void testFactChecking() {
  // Set up the Ollama API
  OllamaApi ollamaApi = new OllamaApi("http://localhost:11434");

  ChatModel chatModel = new OllamaChatModel(ollamaApi,
				OllamaChatOptions.builder().model(BESPOKE_MINICHECK).numPredict(2).temperature(0.0d).build())


  // Create the FactCheckingEvaluator
  var factCheckingEvaluator = new FactCheckingEvaluator(ChatClient.builder(chatModel));

  // Example context and claim
  String context = "The Earth is the third planet from the Sun and the only astronomical object known to harbor life.";
  String claim = "The Earth is the fourth planet from the Sun.";

  // Create an EvaluationRequest
  EvaluationRequest evaluationRequest = new EvaluationRequest(context, Collections.emptyList(), claim);

  // Perform the evaluation
  EvaluationResponse evaluationResponse = factCheckingEvaluator.evaluate(evaluationRequest);

  assertFalse(evaluationResponse.isPass(), "The claim should not be supported by the context");

}
```

--------------------------------

### Error Handling When Calling the Delete API - Example Usage

Source: https://docs.spring.io/spring-ai/reference/api/vectordbs.html

Best practice example showing how to wrap delete operations in a try-catch block to handle exceptions, such as invalid filter expressions.

```java
try {
    vectorStore.delete("country == 'Bulgaria'");
}
catch (Exception  e) {
    logger.error("Invalid filter expression", e);
}
```

--------------------------------

### Use a Resource for the system prompt template

Source: https://docs.spring.io/spring-ai/reference/api/prompt.html

Shows how to inject a Resource using @Value and pass it to SystemPromptTemplate to load the prompt from a file.

```java
@Value("classpath:/prompts/system-message.st")
private Resource systemResource;
```

```java
SystemPromptTemplate systemPromptTemplate = new SystemPromptTemplate(systemResource);
```

--------------------------------

### Example JSON structure for JsonReader

Source: https://docs.spring.io/spring-ai/reference/api/etl-pipeline.html

Example JSON array of bike objects. When JsonReader is configured with "description" as jsonKeysToUse, it creates Document objects with the description field as content.

```json
[
  {
    "id": 1,
    "brand": "Trek",
    "description": "A high-performance mountain bike for trail riding."
  },
  {
    "id": 2,
    "brand": "Cannondale",
    "description": "An aerodynamic road bike for racing enthusiasts."
  }
]
```

--------------------------------

### Add spring-ai-starter-mcp-server-webflux dependency

Source: https://docs.spring.io/spring-ai/reference/api/mcp/mcp-stateless-server-boot-starter-docs.html

Add the WebFlux MCP server starter dependency to use stateless Streamable-HTTP with WebFlux.

```xml
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webflux</artifactId>
</dependency>
```

--------------------------------

### Custom SimpleLoggerAdvisor example

Source: https://docs.spring.io/spring-ai/reference/api/chatclient.html

Example usage of the SimpleLoggerAdvisor constructor to create a custom logger that logs a custom request and response string. Be cautious about logging sensitive information in production environments.

```java
SimpleLoggerAdvisor customLogger = new SimpleLoggerAdvisor(
    request -> "Custom request: " + request.prompt().getUserMessage(),
    response -> "Custom response: " + response.getResult(),
    0
);
```

--------------------------------

### Prompt template usage with format placeholder

Source: https://docs.spring.io/spring-ai/reference/api/structured-output/converters.html

Shows how to use a PromptTemplate to append the converter's format instructions to user input via a {format} placeholder, then create a Prompt.

```java
    StructuredOutputConverter outputConverter = ...
    String userInputTemplate = """
        ... user text input ....
        {format}
        """; // user input with a "format" placeholder.
    Prompt prompt = new Prompt(
            PromptTemplate.builder()
                    .template(this.userInputTemplate)
                    .variables(Map.of(..., "format", this.outputConverter.getFormat())) // replace the "format" placeholder with the converter's format.
                    .build().createMessage()
    );
```

--------------------------------

### Create multiple OpenAiChatModel instances for different OpenAI-compatible APIs

Source: https://docs.spring.io/spring-ai/reference/api/chatclient.html

Builds two OpenAiChatModel instances with different base URLs, API keys, models, and temperatures to connect to Groq and OpenAI. Uses ChatClient.builder to send the same prompt to both and logs each response. Requires GROQ_API_KEY and OPENAI_API_KEY environment variables.

```java
@Service
public class MultiModelService {

    private static final Logger logger = LoggerFactory.getLogger(MultiModelService.class);

    public void multiClientFlow() {
        try {
            // Create a new OpenAiChatModel for Groq (Llama3)
            OpenAiChatModel groqModel = OpenAiChatModel.builder()
                .options(OpenAiChatOptions.builder()
                    .baseUrl("https://api.groq.com/openai/v1")
                    .apiKey(System.getenv("GROQ_API_KEY"))
                    .model("llama3-70b-8192")
                    .temperature(0.5)
                    .build())
                .build();

            // Create a new OpenAiChatModel for GPT-4
            OpenAiChatModel gpt4Model = OpenAiChatModel.builder()
                .options(OpenAiChatOptions.builder()
                    .baseUrl("https://api.openai.com")
                    .apiKey(System.getenv("OPENAI_API_KEY"))
                    .model("gpt-4")
                    .temperature(0.7)
                    .build())
                .build();

            // Simple prompt for both models
            String prompt = "What is the capital of France?";

            String groqResponse = ChatClient.builder(groqModel).build().prompt(prompt).call().content();
            String gpt4Response = ChatClient.builder(gpt4Model).build().prompt(prompt).call().content();

            logger.info("Groq (Llama3) response: {}", groqResponse);
            logger.info("OpenAI GPT-4 response: {}", gpt4Response);
        }
        catch (Exception e) {
            logger.error("Error in multi-client flow", e);
        }
    }
}
```

--------------------------------

### OrchestratorWorkersWorkflow usage example

Source: https://docs.spring.io/spring-ai/reference/api/effective-agents.html

Usage example for the OrchestratorWorkersWorkflow: initializes a ChatClient, creates the workflow, processes a task, and prints the analysis and worker outputs. Demonstrates how to invoke the workflow with a concrete task description.

```java
ChatClient chatClient = // ... initialize chat client
OrchestratorWorkersWorkflow workflow = new OrchestratorWorkersWorkflow(chatClient);

WorkerResponse response = workflow.process(
    "Generate both technical and user-friendly documentation for a REST API endpoint"
);

System.out.println("Analysis: " + response.analysis());
System.out.println("Worker Outputs: " + response.workerResponses());
```

--------------------------------

### STDIO Server Configuration (spring-ai-starter-mcp-server)

Source: https://docs.spring.io/spring-ai/reference/api/mcp/mcp-stdio-sse-server-boot-starter-docs.html

YAML configuration for a synchronous STDIO MCP server using the spring-ai-starter-mcp-server starter. Sets the server name, version, and type.

```yaml
# Using spring-ai-starter-mcp-server
spring:
  ai:
    mcp:
      server:
        name: stdio-mcp-server
        version: 1.0.0
        type: SYNC

```

--------------------------------

### MariaDB Vector Store Usage Examples

Source: https://docs.spring.io/spring-ai/reference/api/vectordbs/mariadb.html

Code examples for using the MariaDB Vector Store with Spring AI, including similarity search with filters, accessing similarity scores, and using similarity thresholds.

```APIDOC
## [SDK] vectorStore.similaritySearch(SearchRequest) with Filter Expression (Text)

### Description
Performs a similarity search on the MariaDB Vector Store using a text-based filter expression to narrow results.

### Method
SDK Method Call

### Endpoint
`vectorStore.similaritySearch(SearchRequest)`

### Parameters
#### Request Body (SearchRequest)
- **query** (String) - Required - The search query text.
- **topK** (int) - Required - The number of top results to return.
- **similarityThreshold** (double) - Optional - The minimum similarity score (0.0 to 1.0) for results.
- **filterExpression** (String) - Optional - A text expression language filter, e.g., `"author in ['john', 'jill'] && article_type == 'blog'"`.

### Request Example
```java
vectorStore.similaritySearch(
    SearchRequest.builder()
        .query("The World")
        .topK(TOP_K)
        .similarityThreshold(SIMILARITY_THRESHOLD)
        .filterExpression("author in ['john', 'jill'] && article_type == 'blog'").build());
```

### Response
#### Success Response
Returns a list of `Document` objects that match the search criteria, ordered by similarity score descending.

#### Response Example
```java
List<Document> results = vectorStore.similaritySearch(...);
```
```

```APIDOC
## [SDK] vectorStore.similaritySearch(SearchRequest) with Filter.Expression DSL

### Description
Performs a similarity search on the MariaDB Vector Store using a programmatic `Filter.Expression` DSL to build the filter.

### Method
SDK Method Call

### Endpoint
`vectorStore.similaritySearch(SearchRequest)`

### Parameters
#### Request Body (SearchRequest)
- **query** (String) - Required - The search query text.
- **topK** (int) - Required - The number of top results to return.
- **similarityThreshold** (double) - Optional - The minimum similarity score (0.0 to 1.0) for results.
- **filterExpression** (Filter.Expression) - Optional - A programmatically built filter expression using `FilterExpressionBuilder`.

### Request Example
```java
FilterExpressionBuilder b = new FilterExpressionBuilder();

vectorStore.similaritySearch(SearchRequest.builder()
    .query("The World")
    .topK(TOP_K)
    .similarityThreshold(SIMILARITY_THRESHOLD)
    .filterExpression(b.and(
        b.in("author", "john", "jill"),
        b.eq("article_type", "blog")).build()).build());
```

### Response
#### Success Response
Returns a list of `Document` objects that match the search criteria, ordered by similarity score descending.

#### Response Example
```java
List<Document> results = vectorStore.similaritySearch(...);
```
```

```APIDOC
## [SDK] Document.getScore()

### Description
Retrieves the similarity score for a document returned from a similarity search. The score is a value between 0.0 and 1.0, where 1.0 indicates perfect similarity.

### Method
SDK Method Call

### Endpoint
`Document.getScore()`

### Parameters
None

### Request Example
```java
List<Document> results = vectorStore.similaritySearch(
    SearchRequest.builder()
        .query("Spring AI")
        .topK(5)
        .build());

for (Document doc : results) {
    double score = doc.getScore();  // Value between 0.0 and 1.0
    System.out.println("Document: " + doc.getText());
    System.out.println("Similarity Score: " + score);
}
```

### Response
#### Success Response
Returns a `double` representing the similarity score (0.0 to 1.0).
```

```APIDOC
## [SDK] Document.getMetadata().get("distance")

### Description
Retrieves the raw distance value from the document metadata. This is the distance used to calculate the similarity score.

### Method
SDK Method Call

### Endpoint
`Document.getMetadata().get("distance")`

### Parameters
None

### Request Example
```java
for (Document doc : results) {
    double score = doc.getScore();
    float distance = (Float) doc.getMetadata().get("distance");

    System.out.println("Score: " + score + ", Distance: " + distance);
}
```

### Response
#### Success Response
Returns a `Float` representing the raw distance value.
```

```APIDOC
## [SDK] vectorStore.similaritySearch(SearchRequest) with Similarity Threshold

### Description
Performs a similarity search with a similarity threshold specified as a score value (0.0 to 1.0). Only documents with a score greater than or equal to the threshold are returned.

### Method
SDK Method Call

### Endpoint
`vectorStore.similaritySearch(SearchRequest)`

### Parameters
#### Request Body (SearchRequest)
- **query** (String) - Required - The search query text.
- **topK** (int) - Required - The number of top results to return.
- **similarityThreshold** (double) - Optional - The minimum similarity score (0.0 to 1.0) for results.

### Request Example
```java
List<Document> results = vectorStore.similaritySearch(
    SearchRequest.builder()
        .query("Spring AI")
        .topK(10)
        .similarityThreshold(0.8)  // Only return documents with score >= 0.8
        .build());
```

### Response
#### Success Response
Returns a list of `Document` objects that match the search criteria and have a similarity score >= the threshold, ordered by score descending.
```

--------------------------------

### Example: Using SummaryMetadataEnricher to enrich documents

Source: https://docs.spring.io/spring-ai/reference/api/etl-pipeline.html

Example of using SummaryMetadataEnricher to add section summaries to a list of documents. It initializes the enricher with a ChatModel and summary types, applies it to two documents, and prints the generated metadata.

```java
ChatModel chatModel = // initialize your chat model
SummaryMetadataEnricher enricher = new SummaryMetadataEnricher(chatModel,
    List.of(SummaryType.PREVIOUS, SummaryType.CURRENT, SummaryType.NEXT));

Document doc1 = new Document("Content of document 1");
Document doc2 = new Document("Content of document 2");

List<Document> enrichedDocs = enricher.apply(List.of(this.doc1, this.doc2));

// Check the metadata of the enriched documents
for (Document doc : enrichedDocs) {
    System.out.println("Current summary: " + doc.getMetadata().get("section_summary"));
    System.out.println("Previous summary: " + doc.getMetadata().get("prev_section_summary"));
    System.out.println("Next summary: " + doc.getMetadata().get("next_section_summary"));
}
```

--------------------------------

### Capability Checking

Source: https://docs.spring.io/spring-ai/reference/api/mcp/mcp-annotations-special-params.html

Example showing how to check client capabilities before using features like elicitation and sampling.

```APIDOC
## Capability Checking

### Description
Example of a tool method that checks client capabilities (elicitation, sampling) before using them, using the McpSyncRequestContext.

### Method
@McpTool

### Endpoint
capabilityAware

### Parameters
- **context** (McpSyncRequestContext) - Automatically injected - Request context
- **data** (String) - Required - Data to process

### Request Example
```java
@McpTool(name = "capability-aware", description = "Tool that checks capabilities")
public String capabilityAware(
        McpSyncRequestContext context,
        @McpToolParam(description = "Data", required = true) String data) {

    // Check if elicitation is supported before using it
    if (context.elicitEnabled()) {
        // Safe to use elicitation
        var result = context.elicit(UserInfo.class);
        // Process result...
    }

    // Check if sampling is supported before using it
    if (context.sampleEnabled()) {
        // Safe to use sampling
        var samplingResult = context.sample("Process: " + data);
        // Process result...
    }

    // Note: Stateless servers do not support bidirectional operations
    // (roots, elicitation, sampling) and will return false for these checks

    return "Processed with capability awareness";
}
```

### Response
Returns a String result.
```
Tokens:
Raw