Front matter

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

Oct 10, 2026 · @Ahmed Hassanien

This book teaches Java engineers to build an agent harness with Spring AI. The running example is the Log Incident Watcher. Read the chapters in order. Each chapter adds one idea. Run the code in each chapter before you read the next one. All examples use fake data and run offline.

Versions: Spring Boot 4.1.1, Spring AI 2.0.1, Spring AI Session 0.6.0, Temporal 1.35.0. Use released versions only.

Local services: PostgreSQL 17 with VectorChord, BM25, and AGE. LM Studio with Gemma for chat and BGE-M3 for embeddings. A reranker container for bge-reranker-v2-m3. A Temporal dev server.

Figure 0.1. The local stack. Everything runs on one machine with fake data. The figure leaves out the embedding and Temporal connections from the app; later chapters draw each one where it is used.

Glossary

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

Figure 0.2. How the core terms fit together. Retrieval, evaluation, and durable-execution terms are left out; each has its own part of the course.

Model. A large language model. It takes text in and returns text out.
Harness. The code around a model. It sends requests, runs tools, keeps state, and decides when to stop.
Agent. A model plus a harness plus a goal.
Tool. A Java method the model can ask the harness to run.
Tool call. The model’s request to run a tool. It names the tool and gives arguments.
Loop. The cycle of model call, tool execution, and result. It ends when the run stops.
Termination. The rule that ends a run.
Context window. The text the model can read in one call. It is measured in tokens.
Token. A small piece of text. Providers bill by token.
Skill. A file of instructions for one task. The harness loads it only when needed.
Sub-agent. An agent that a parent agent calls as a tool.
Memory. Information kept across model calls. Short-term memory is the recent conversation. Long-term memory is stored outside it.
Embedding. A list of numbers that represents the meaning of a text.
Vector store. A database that finds texts with similar embeddings.
BM25. A keyword scoring method. It rewards rare words that appear often in a document.
Hybrid search. Keyword search and vector search, merged into one result list.
RRF (Reciprocal Rank Fusion). A way to merge ranked lists by rank position, not by score.
Reranker. A model that scores a query and each candidate together, then reorders the candidates.
RAG (retrieval-augmented generation). The harness fetches relevant documents before the model answers.
HITL (human-in-the-loop). A run that pauses until a person approves an action.
Graph. A flow of nodes and edges. A knowledge graph stores relationships between things.
Durable execution. A run that survives crashes and restarts because its state is stored.
Workflow (Temporal). The durable definition of one run.
Activity (Temporal). A unit of work with side effects, such as a model call. Temporal retries it.
Signal (Temporal). A message sent to a running workflow, such as an approval.
Eval. A fixed set of test inputs with expected properties. Run it before each change.
Prompt caching. The provider reuses work for a stable part of the prompt. It lowers cost.

Start here | Garage Education

Front matter

Glossary