Tutorials¶

These eleven tutorials walk you from creating a single tool to composing chains over the bundled default catalog, with three optional deep-dives off the main path - the MCP protocol surface, re-publishing tools through the MCP Server Proxy, and gating tool calls behind human approval. They follow the natural product workflow: build → validate → ground → compose.

The shipped chat default is qwen3.5:2b - fast, fine for the early tutorials. Switch to qwen3.5:9b or gemma4:e4b when you reach tutorials 4-7, where tool-calling reliability matters. Embeddings use qwen3-embedding:0.6b throughout. See Picking a model for the tradeoffs.

How these tutorials connect¶

flowchart LR
  T1["1. Author a Tool<br/>Tool Studio"]
  T2["2. Connect MCP<br/>MCP Server"]
  T3["3. Index a Doc<br/>Vector Database"]
  T4["4. Chat + Tools<br/>Agentic Chat"]
  T5["5. Chat + RAG<br/>Agentic Chat"]
  T6["6. Tools + RAG<br/>Agentic Chat"]
  T7["7. Tool Chain<br/>Weather → Slack"]
  T8["8. Default Tool Recipes<br/>JS-action chains"]
  T9["9. MCP Everything<br/>All 8 Primitives"]
  T10["10. Server Proxy<br/>Re-publish a tool"]
  T11["11. Approve in Chat<br/>Human-in-the-Loop"]
  T1 --> T2
  T2 --> T4
  T3 --> T5
  T4 --> T6
  T5 --> T6
  T6 --> T7
  T7 --> T8
  T2 -. deep dive .-> T9
  T2 -. proxy .-> T10
  T4 -. approve .-> T11
  classDef build fill:#eef2ff,stroke:#3F51B5,color:#1e1b4b
  classDef validate fill:#ecfdf5,stroke:#10b981,color:#064e3b
  classDef ground fill:#fff7ed,stroke:#f59e0b,color:#7c2d12
  classDef compose fill:#fdf2f8,stroke:#e11d48,color:#831843
  classDef bonus fill:#f5f3ff,stroke:#7c3aed,color:#4c1d95
  class T1 build
  class T2 validate
  class T3 ground
  class T4,T5,T6,T7,T8 compose
  class T9,T10,T11 bonus

Tutorials 1-3 produce reusable assets (a tool, an MCP connection, an indexed document). Tutorials 4-8 compose those assets in chat (4-6) and as code-level chains over the bundled default catalog (7-8). Tutorial 9 is an optional deep dive off Tutorial 2 - activate MCP Everything from the Default MCP Servers and exercise every Inspector primitive (Tools / Resources / Prompts / Ping / Notifications / Roots / Sampling / Elicitation) end-to-end. Tutorial 10 is a second deep dive off Tutorial 2 - re-publish a connected server's tool through the built-in MCP Server Proxy so chat and external clients can call it. Each tutorial is independently runnable in 3-20 minutes; the full main sequence takes about 50 minutes, plus ~23 minutes for the three deep dives (MCP Everything, Server Proxy, and Human-in-the-Loop approval).

What you'll need

Spring AI Playground running on http://localhost:8282. Follow Getting Started first if you haven't.

Ollama running, with qwen3.5:9b and qwen3-embedding:0.6b pulled.

ollama pull qwen3.5:9b
ollama pull gemma4:e4b
ollama pull qwen3-embedding:0.6b

For Tutorial 7 only: SLACK_WEBHOOK_URL set in the launcher's Environment Variables.

Tutorial list¶

1. Author and Validate a Tool

getWeather from Starter 5 → Local Pass → MCP exposure.
8 min · ★☆☆ · Tool Studio + MCP Server
2. Connect an External MCP Server

Streamable HTTP / STDIO / SSE / OAuth 2.1, validated in the Inspector.
8 min · ★★☆ · MCP Server
3. Index a Document for RAG

Upload → chunk → embed → similarity-search validate.
6 min · ★☆☆ · Vector Database
4. Chat With Tools

Real tool call from a chat turn - see plan → call → answer.
5 min · ★★☆ · Agentic Chat
5. Chat With RAG

Grounded chat on the indexed document - no tools.
5 min · ★★☆ · Agentic Chat + Vector Database
6. Tools and RAG Together

One turn that retrieves chunks AND calls a tool - full composition.
6 min · ★★★ · Agentic Chat (full)
7. Weather to Slack - A Two-Tool Chain

getWeather → sendSlackMessage in one prompt - the agent loop.
4 min · ★★★ · Agentic Chat
8. Default Tool Recipes

Five new custom tools, each chaining default-tool helpers inside one JS action.
20 min · ★★★ · Tool Studio + Agentic Chat
9. MCP Everything - All 8 Primitives

Activate the Default MCP Servers's reference test server and exercise every Inspector primitive - Tools, Resources, Prompts, Ping, Notifications, Roots, Sampling, Elicitation - in one sitting. OS-specific Node install or Docker alternative.
12 min · ★★☆ · MCP Server (catalog + Inspector) · deep dive
10. Proxy an MCP Server

Re-publish a whole MCP server - or a curated mix of several - through the built-in server, each tool risk-capped, HITL-gated, and logged; then call it from chat and external /mcp clients.
8 min · ★★☆ · MCP Server · deep dive
11. Approve a Tool in Chat

Turn on human-in-the-loop approval, then approve or decline a tool call live in chat.
6 min · ★★☆ · Tool Studio + Agentic Chat · deep dive

Picking a model¶

Tool calling and tool chaining quality depend heavily on the model. The selectable list in Agentic Chat → Settings → Model is driven by application.yaml's playground.chat.models. The shipped default is the small one - start there, and only upgrade if a tool turn comes back empty.

qwen3.5:2b (default)qwen3.5:9bgemma4:e4bgpt-oss:20b

The shipped default. 2.7 GB. Fast on Apple Silicon. Use this for the chat sanity check before wiring up tools or RAG. Tool calling is best-effort - if a tool turn comes back empty, that is the signal to upgrade, not to rewrite the prompt.

6.6 GB. Stronger tool calling and multi-turn reasoning. The first upgrade target when qwen3.5:2b skips a tool call.

9.6 GB. Strongest natural-language quality. Pick this for tutorial 7 (multi-step tool chains) where the model has to reason about a tool result rather than just call it.

13 GB. OpenAI's open-weights reasoning model. A good cross-check when you suspect a result depends heavily on which model family you picked.

Where the model selector lives

Open Agentic Chat, click the gear icon at the top right, change Model, then click Apply & New Chat. The chat header reflects the change.

Tutorials¶

How these tutorials connect¶

Tutorial list¶

Picking a model¶

Further Reading¶