Part 1: Foundations | Garage Education

Chapter 1: Why a harness?

Sat, 10 Oct 2026 00:00:00 +0000

A model reads text and writes text. It cannot run code, read files, or remember past calls. The harness adds those abilities. It does five jobs. It sends the prompt. It reads the reply. It runs the tools the model asks for. It returns the tool results. It decides when the run stops.

Figure 1.1. One harness run, with each of the five jobs labelled. Use Previous and Next to step through it. The count of 412 is the fake data from Chapter 4.

Example. Asked alone, a model can only guess whether checkout is slow. With a harness, the model calls a countErrors tool, reads the real count, and answers from that data.

Objectives: describe a model call, name the five harness jobs, and explain what the course builds.

Chapter 2: Project setup

Sat, 10 Oct 2026 00:00:00 +0000

Create a Spring Boot 4.1.1 project with Java 17 or later. Add the Spring AI BOM 2.0.1, the Session BOM 0.6.0, the Temporal starter, and the OpenAI starter for LM Studio.

Figure 2.1. The project and the local model server. The OpenAI starter reaches LM Studio through the base URL below. The figure leaves out PostgreSQL and the Temporal dev server, which later chapters connect.

spring.ai.openai.base-url=http://localhost:1234
spring.ai.openai.api-key=lm-studio
spring.ai.openai.chat.options.model=YOUR-GEMMA-IDENTIFIER
spring.ai.openai.embedding.options.model=YOUR-BGE-M3-IDENTIFIER

Before the course, send one request with a tool definition to the Gemma model. Confirm the response contains a tool call.

Figure 2.2. The pre-flight check. Every chapter from Chapter 4 on depends on the model returning tool calls.

Chapter 3: The model call

Sat, 10 Oct 2026 00:00:00 +0000

@Service
public class Assistant {

 private final ChatClient chat;

 public Assistant(ChatClient.Builder builder) {
 this.chat = builder.build();
 }

 public String ask(String question) {
 return chat.prompt()
 .system("You are a careful assistant. Answer in two sentences or fewer.")
 .user(question)
 .call()
 .content();
 }
}

The ChatClient.Builder is created by Spring Boot when a model starter is on the classpath. The model replies in text. The client hides the request format.

Figure 3.1. One model call. Your code never builds the HTTP request; the client does. No tools are attached yet, so the model can only answer from its own text.

Chapter 4: Tools

Sat, 10 Oct 2026 00:00:00 +0000

A tool is a Java method. The model chooses tools using only their names and descriptions. A vague description causes wrong choices.

@Component
public class LogTools {

 @Tool(description = "Count error log events for one service in the last N minutes. Use this to check for a current error spike.")
 public int countErrors(
 @ToolParam(description = "Service name, for example checkout") String service,
 @ToolParam(description = "Look-back window in minutes, from 1 to 1440") int minutes) {
 return "checkout".equals(service) ? 412 : 3; // fake data
 }
}

Figure 4.1. A tool, as the model sees it. A vague description on the left means a wrong choice, however good the code on the right is.

Attach the tool with .tools(logTools) on the prompt. Exercise: rename the tool, then remove its description. Compare the model’s choices each time.