Spring AI — From Zero To Hero

Spring Boot 4.0.6 | Spring AI 2.0.0-M5 | Java 25

A hands-on workshop for building AI-powered applications with Spring AI. Covers chat, embeddings, vector stores, RAG, tool calling, MCP, agentic patterns, and observability — across 6 AI providers.

⚠️ Recently upgraded Spring AI 2.0.0-M4 → 2.0.0-M5. Several breaking changes affect anything depending on Spring AI 2.x — most notably the removal of spring-ai-azure-openai (Azure now goes through spring-ai-openai in "Microsoft Foundry" mode), an internal switch to the official openai-java SDK that changes how request URLs are constructed, and a ChatClient options-API signature change. Full breakdown with diffs, pitfalls, and per-provider checklist: SPRING_AI_M4_TO_M5_MIGRATION.md.

What You'll Learn — 8 Stages

Every stage builds on the previous one. You can follow them linearly, or jump straight to a stage via the dashboard.

Stage	Topic	What you take away
1	Chat Fundamentals	The Spring AI chat API, layer by layer — from a one-line ChatModel.call() through ChatClient, structured output, tool calling, multimodal input, and streaming responses.
2	Embeddings	Turn text into dense float vectors. Measure similarity, understand dimensionality, and see why similar meanings cluster in vector space — the foundation of semantic search.
3	Vector Stores	Persist embeddings and run similarity queries through Spring AI's VectorStore abstraction. Same code runs against SimpleVectorStore (in-memory) or PgVectorStore (PostgreSQL).
4	AI Patterns	Three production-relevant patterns: Stuff-the-Prompt (manual context injection), RAG (manual + advisor-based retrieval), and Chat Memory (conversation history via advisors).
5	Advanced Agent Patterns	Chain-of-Thought flows that decompose a task into sequential LLM calls, and a Self-Reflection Agent (Writer + Critic loop) that iteratively improves its own output.
6	Model Context Protocol (MCP)	The open protocol that lets models discover and invoke external tools at runtime. Five runnable demos: stdio server, HTTP server, client, dynamic tool calling, and full capabilities (tools + resources + prompts + completions).
7	Agentic Systems	Agents that control their own execution flow via forced tool calling. Two patterns: Inner Monologue (think-aloud reasoning) and Model-Directed Loop (agent decides when it's done).
8	Observability	Full-stack traces through the LGTM stack (Grafana + Loki + Tempo + Mimir). @TracedEndpoint/@TracedService/@TracedRepository spans, OTel logs, metrics, and trace-to-log correlation.

Dashboard — overview of all 5 stages with endpoint counts	Stage 1 — try endpoints interactively with "Try it" buttons
Grafana — Spring Boot application metrics and statistics	Grafana — distributed trace with spans and log correlation

Getting Started

Audience	Guide
Workshop attendee (live session)	Quickstart — 5 minutes to your first AI call
Self-paced learner	Full Guide — complete walkthrough of all 8 stages

Fastest Path

./workshop.sh check                                    # Verify prerequisites
./workshop.sh setup                                    # Pull models, images, build
./workshop.sh start ollama --profiles pgvector,observation,ui  # Start everything

Then open:

• Workshop Dashboard — http://localhost:8080/dashboard
• Workshop Slides — http://localhost:8080/slides.html
• Swagger UI — http://localhost:8080/swagger-ui.html
• Grafana — http://localhost:3000

Tip: Use both the Dashboard UI and curl/httpie on the command line to explore endpoints. The dashboard formats responses for readability (JSON pretty-printing, chat bubbles, similarity charts), while curl shows you the raw API responses — seeing both gives you a clearer picture of what Spring AI actually returns.

# Try the same endpoint in both:
http localhost:8080/chat/01/joke topic==spring        # raw response
# ... and click "Try it" in the Dashboard UI          # formatted view

Resources

• Provider Setup — comparison matrix, API keys, model requirements
• Troubleshooting — common issues and solutions
• Chat Examples — all chat endpoint examples
• Embedding Examples — all embedding endpoint examples

Prerequisites

• Java 25+ — sdk install java 25.0.2-librca
• Docker — for PostgreSQL/pgvector and Grafana LGTM
• Ollama (optional) — only needed for local provider: ollama pull qwen3 && ollama pull nomic-embed-text && ollama pull llava. No local install? Use the dockerized alternative.
• Cloud provider (alternative to Ollama) — configure API keys with ./workshop.sh creds
• tmux (optional) — enables a split-pane TUI with live logs on the right: brew install tmux (macOS), sudo apt-get install tmux (Debian/Ubuntu), sudo dnf install tmux (Fedora/RHEL). If not installed, the plain menu works identically.

16 GB macOS with Ollama: qwen3 + nomic-embed-text = ~10 GB active RAM. llava loads on-demand.

Interactive mode: split-pane TUI (optional)

If tmux is installed, ./workshop.sh auto-launches a split layout:

• Left pane (50%): the menu you already know.
• Right pane (50%): live tail of every provider/gateway/MCP/agentic log — cleared on each launch.

Press q in the menu to tear down both panes cleanly. Opt out with WORKSHOP_NO_TMUX=1 ./workshop.sh.

Without tmux, everything still works — provider/gateway output appears inline in the terminal as before, and MCP/agentic logs are always file-backed (view them via menu options 14/18).

Workshop Stages

1. Chat Fundamentals — ChatModel, ChatClient, prompt templates, structured output, tool calling, streaming
2. Embeddings — vector generation, similarity, chunking, document readers (JSON, Text, PDF)
3. Vector Stores — pgvector, similarity search, in-memory vs persistent
4. AI Patterns — stuff-the-prompt, RAG (manual + advisor), chat memory
5. Advanced Agents — chain-of-thought, self-reflection (writer + critic)
6. MCP — Model Context Protocol (stdio, HTTP, dynamic tools, resources, prompts) — runnable from the workshop dashboard at /dashboard/stage/6. 👉 New: What's new in Stage 6 (MCP) — attendee + trainer walkthrough
7. Agentic Systems — inner monologue, model-directed loop, Spring Shell CLIs
8. Observability — distributed tracing, metrics, logs with OpenTelemetry + Grafana LGTM

AI Provider Options

Provider	Chat	Embedding	Multimodal	Tool Calling	Local	Test Status
Ollama	qwen3 (8B)	nomic-embed-text	llava (auto)	Yes	Yes	44/44 PASS
OpenAI	gpt-4o-mini	text-embedding-3	gpt-4o	Yes	No	44/44 PASS
Anthropic	Claude (direct API)	-	Claude 3+	Yes	No	14/14 PASS
Azure OpenAI	gpt-4.1-mini	text-embedding-3	gpt-4o	Yes	No	8/8 PASS
Google	Gemini 2.5 Flash	text-embedding-004	Gemini	Yes	No	13/13 PASS
AWS Bedrock	Amazon Nova Lite	-	-	Yes	No	8/8 PASS

Spring Profiles

Profile	Purpose
pgvector	PostgreSQL vector store (instead of in-memory)
observation	Full observability (traces + metrics + logs to LGTM)
ui	Workshop dashboard at /dashboard
spy	Route traffic through gateway for inspection

Spring AI Deep Dive Documentation

In-depth technical documentation covering Spring AI internals, AI model fundamentals (LLMs, tool calling, multimodal architecture), and detailed analysis of every demo across all 8 stages. Each document includes Spring AI component descriptions, Mermaid flow diagrams, and annotated code examples.

Document	Topic
Introduction	Spring AI architecture, ChatModel vs ChatClient, provider portability, AI model capabilities (tool calling, vision, audio, structured output), provider compatibility matrix
Stage 1: Chat	ChatModel, ChatClient, prompt templates, structured output, tool calling, system roles, multimodal, streaming
Stage 2: Embeddings	EmbeddingModel, cosine similarity, TokenTextSplitter, document readers (JSON, Text, PDF)
Stage 3: Vector Stores	VectorStore abstraction, SimpleVectorStore vs PgVectorStore, ETL pipeline
Stage 4: AI Patterns	Stuff-the-prompt, manual and advisor-based RAG, chat memory, advisor architecture
Stage 5: Advanced Agents	Chain-of-thought pipeline, self-reflection Writer/Critic loop, TikaDocumentReader
Stage 6: MCP · What's New	MCP servers (STDIO, HTTP), clients, dynamic tools, resources, prompts, completions
Stage 7: Agentic Systems	Inner monologue, model-directed loop, forced tool calling, Spring Shell CLIs
Stage 8: Observability	Custom tracing annotations, OpenTelemetry, LGTM stack, trace-log-metric correlation

Repo Organization

• /components/apis/ — provider-independent API demos (chat, embedding, vector-store, audio, image)
• /components/patterns/ — AI patterns (RAG, chat memory, stuff-prompt, chain-of-thought, self-reflection, distributed tracing)
• /components/config-openapi/ — OpenAPI/Swagger UI configuration
• /components/config-dashboard/ — Workshop dashboard UI (Thymeleaf + Bootstrap 5 + htmx)
• /components/config-pgvector/ — PgVector auto-configuration (profile-based)
• /components/data/ — shared datasets (bikes, customers, products, orders)
• /applications/ — provider-specific Spring Boot apps (ollama, openai, anthropic, azure, google, aws, gateway)
• /mcp/ — Model Context Protocol demos (stdio, HTTP, client, dynamic tools, capabilities)
• /agentic-system/ — agentic AI patterns (inner monologue, model-directed loop)
• /docker/ — infrastructure (PostgreSQL/pgvector, Grafana LGTM observability stack)
• /docs/ — workshop documentation