Spring AI Part-1
Spring AI Tutorial – Part 1
Build a local support-ticket draft API with Java and Spring Boot.
1What Is Spring AI?
Spring AI helps Java and Spring applications integrate with AI models and related capabilities. A ChatClient sends a prompt to a model and receives its response.
This part uses Spring AI 1.1.8, Spring Boot 3.5.16 and Java 17. Spring AI 1.1.x supports Spring Boot 3.4.x and 3.5.x.
Official references: Spring AI setup and Ollama integration.
2Enterprise Use Case
A support agent sends a short, fictional issue. The API asks a local model for a polite response draft; an agent must review and edit it before sending.
Client --POST JSON--> Spring Boot API --ChatClient--> Ollama model
Client <--draft JSON-- Spring Boot API <--model response--
3Prerequisites and Setup
- Install Java 17 or later and Maven 3.6.3 or later. The commands below use Windows PowerShell.
- Install and start Ollama. If its server is already running, do not start a second server.
- Download the model with the next command. This requires internet, sufficient disk space and memory; the download can be large.
java -version
mvn -version
ollama pull llama3.2
The Ollama server address in this example is http://localhost:11434. If it is unavailable, the model call fails.
4Maven Configuration
In an empty project folder, create the following pom.xml. The Spring AI BOM manages the starter version.
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.5.16</version>
<relativePath/>
</parent>
<groupId>com.example</groupId>
<artifactId>support-assistant</artifactId>
<version>0.0.1-SNAPSHOT</version>
<properties>
<java.version>17</java.version>
<spring-ai.version>1.1.8</spring-ai.version>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-bom</artifactId>
<version>${spring-ai.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-ollama</artifactId>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
5Spring Boot API
Create src/main/java/com/example/support/SupportApplication.java in the project folder. Requests must not be blank and may contain at most 1,500 characters.
package com.example.support;
import jakarta.validation.Valid;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.server.ResponseStatusException;
@SpringBootApplication
public class SupportApplication {
public static void main(String[] args) {
SpringApplication.run(SupportApplication.class, args);
}
}
@RestController
@RequestMapping("/api/support")
class SupportController {
private final ChatClient chatClient;
SupportController(ChatClient.Builder builder) {
this.chatClient = builder.build();
}
@PostMapping("/draft")
DraftResponse draft(@Valid @RequestBody DraftRequest request) {
String reply = chatClient.prompt()
.system("Draft a polite support reply using only the supplied issue. "
+ "Do not promise refunds or invent company policy. "
+ "Ask for clarification if needed. A human will review the draft.")
.user(u -> u.text("{ticket}").param("ticket", request.ticket()))
.call()
.content();
if (reply == null || reply.isBlank()) {
throw new ResponseStatusException(HttpStatus.BAD_GATEWAY,
"The model returned an empty response");
}
return new DraftResponse(reply);
}
record DraftRequest(@NotBlank @Size(max = 1500) String ticket) {}
record DraftResponse(String draft) {}
}
Create src/main/resources/application.properties. The API listens only on loopback; the Ollama model must already be downloaded.
server.address=127.0.0.1
server.port=8080
spring.ai.ollama.base-url=http://localhost:11434
spring.ai.ollama.chat.options.model=llama3.2
6Run and Test the API
Run this command from the project folder. After startup, send the request from another PowerShell window. Keep the Ollama server running.
mvn spring-boot:run
$body = @{ ticket = "My fictional order has not arrived." } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:8080/api/support/draft" `
-ContentType "application/json" -Body $body
A successful request returns JSON with a draft; the exact wording varies by model and run. A blank or oversized ticket returns HTTP 400. If the model is unavailable, the request fails; inspect server logs.
7Live Prompt Preview
This is only a local browser preview of the prompt, not an AI model. It makes no network request. For an actual model response, run the API instructions above. Use fictional text only.
8Production Considerations
- Add authentication, authorization, rate limiting and secure network configuration before real deployment.
- Check permissions, retention and provider policies for personal data. Do not put secrets in source code or prompts.
- Treat user text and model output as untrusted. Defend against prompt injection and retain human review; prompt instructions alone are not a security boundary.
- Plan for timeouts, failures, monitoring and model quality. Avoid unnecessary logging of sensitive prompts.
9Series Roadmap
Future parts can cover prompt design, structured output, conversation memory, RAG, tool calling, testing, observability and secure deployment using the same support-application context.
10Quick Quiz
Choose an answer for each question and check your score.
Show answer explanations
- A: ChatClient sends the prompt and receives a model response.
- B: The preview displays text locally; it does not call a model.
- A: Real security requires access controls and other safeguards.
You completed Part 1 of the Spring AI series. Continue learning in the next part. — A143MK
Spring AI Part-2
Spring AI Tutorial – Part 2
Improve the support-ticket draft with prompt design and structured output.
1From Part 1 to Part 2
Part 1 produced a text draft for a support issue. Now the same fictional enterprise support flow asks for a structured result with a category, summary and reply.
The API produces a draft for agent review only. It does not message a customer or change any business system.
2Prompt Design
System instructions describe the task and constraints. The user message contains the ticket. A template parameter inserts the ticket as data rather than treating it as another template.
Ask the model not to invent missing facts, policies or refund promises. A model can still ignore instructions, so a prompt alone is not a security control.
3Structured Output Contract
Our Java record has three strings: category, summary and reply. Category must be one of delivery, billing, account or other.
Spring AI's .entity(SupportDraft.class) attempts to convert model output into a record. Structured output is not guaranteed: parsing or field validation can fail.
See the official Structured Output Converter documentation.
4Project Setup
Use the Part 1 project with Java 17+, Maven 3.6.3+, Spring Boot 3.5.16 and Spring AI 1.1.8. Keep its pom.xml, including the web, validation and Ollama starters.
Start Ollama and download the llama3.2 model. The download requires internet, sufficient memory and disk space.
ollama pull llama3.2
Keep the Part 1 src/main/resources/application.properties:
server.address=127.0.0.1
server.port=8080
spring.ai.ollama.base-url=http://localhost:11434
spring.ai.ollama.chat.options.model=llama3.2
5Build the Java API
Replace Part 1's src/main/java/com/example/support/SupportApplication.java with this entire code. The same /api/support/draft endpoint now returns the new JSON contract.
package com.example.support;
import java.util.Set;
import jakarta.validation.Valid;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.server.ResponseStatusException;
@SpringBootApplication
public class SupportApplication {
public static void main(String[] args) {
SpringApplication.run(SupportApplication.class, args);
}
}
@RestController
@RequestMapping("/api/support")
class SupportController {
private static final Set<String> CATEGORIES =
Set.of("delivery", "billing", "account", "other");
private final ChatClient chatClient;
SupportController(ChatClient.Builder builder) {
this.chatClient = builder.build();
}
@PostMapping("/draft")
SupportDraft draft(@Valid @RequestBody DraftRequest request) {
SupportDraft result = chatClient.prompt()
.system("Classify the support issue as delivery, billing, account, "
+ "or other. Summarize the issue and draft a polite reply. "
+ "Use only the supplied issue; do not invent facts or policies "
+ "or promise refunds. Ask for clarification if needed. "
+ "A human must review the draft.")
.user(u -> u.text("{ticket}").param("ticket", request.ticket()))
.call()
.entity(SupportDraft.class);
if (result == null || result.category() == null ||
!CATEGORIES.contains(result.category()) ||
invalidText(result.summary(), 200) || invalidText(result.reply(), 1200)) {
throw new ResponseStatusException(HttpStatus.BAD_GATEWAY,
"The model returned invalid draft fields");
}
return result;
}
private static boolean invalidText(String text, int maxLength) {
return text == null || text.isBlank() || text.length() > maxLength;
}
record DraftRequest(@NotBlank @Size(max = 1500) String ticket) {}
record SupportDraft(String category, String summary, String reply) {}
}
Input validation rejects blank tickets or tickets over 1,500 characters. Separate output checks require an allowed category and non-blank summary (at most 200) and reply (at most 1,200 characters).
6Run and Test the API
Start the API from the Part 1 project folder. When the Ollama server and model are available, send a fictional ticket from another PowerShell window.
mvn spring-boot:run
$body = @{ ticket = "My fictional order has not arrived." } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:8080/api/support/draft" `
-ContentType "application/json" -Body $body
A successful response has the shape below. This is illustrative; an actual model may answer differently or return invalid JSON.
{
"category": "delivery",
"summary": "A fictional order has not arrived.",
"reply": "Sorry about the delay. Please share a reference through the official support channel."
}
Blank or oversized input returns HTTP 400. Invalid field values produce HTTP 502. An unavailable model or failed JSON conversion causes a failed request; inspect server logs.
7Live JSON Check
This independent browser exercise checks sample JSON and field limits. It does not call the API or model and sends no data over the network.
8Safety and Limitations
- Treat model output and user input as untrusted. Access controls and additional safeguards are needed against prompt injection.
- Add authentication, authorization, rate limiting, timeouts, monitoring and privacy controls before production.
- Structured fields do not make facts correct. Render safely in HTML and keep a human review before sending a reply.
- Do not silently turn model or parsing failures into successful responses; avoid logging sensitive prompts.
9Practice
- Change the category to
billingand then to an invalid value in the browser exercise. - Try malformed JSON and a blank summary. Check that the browser does not report success.
- Send several fictional issues to the local API and have a human review the category and draft. Observe the error if the model is unavailable.
10Quick Quiz
Choose an answer for each question and check your score.
Show answer explanations
- A: Entity conversion attempts to map model output to a Java type.
- B: A valid structure still needs factual and safety review.
- A: The browser exercise checks JSON locally only.
You completed Part 2 of the Spring AI series. Keep practicing responsibly. — A143MK