About Spring AI Zero To Hero
Spring AI Zero To Hero is an MCP server in the Other category: spring AI workshop content.
Install
git clone https://github.com/andrlange/spring-ai-zero-to-heroThis server has no ConduID identity, so agent calls to it are not receipted. Pin the version you install and review the source before granting it credentials.
Ask AI
Ask AI about Spring AI Zero To Hero
Powered by Claude · Grounded in docs
Security checks
- ✓README presentThe repository ships documentation.
5 checks have not been run yet.
README
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 throughspring-ai-openaiin "Microsoft Foundry" mode), an internal switch to the officialopenai-javaSDK that changes how request URLs are constructed, and aChatClientoptions-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. |
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
- Chat Fundamentals — ChatModel, ChatClient, prompt templates, structured output, tool calling, streaming
- Embeddings — vector generation, similarity, chunking, document readers (JSON, Text, PDF)
- Vector Stores — pgvector, similarity search, in-memory vs persistent
- AI Patterns — stuff-the-prompt, RAG (manual + advisor), chat memory
- Advanced Agents — chain-of-thought, self-reflection (writer + critic)
- 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 - Agentic Systems — inner monologue, model-directed loop, Spring Shell CLIs
- 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 |
| 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
README copy captured when this server was indexed; it may lag the repository. The original is authoritative.