Tutorials¶

These nine tutorials walk you from creating a single tool to composing chains over the bundled default catalog, with one bonus deep-dive into the MCP protocol surface. They follow the natural product workflow: build → validate → ground → compose, plus one optional MCP-primitive walkthrough.

The shipped chat default is qwen3.5:2b — fast, fine for the early tutorials. Switch to qwen3.5:latest or gemma4:latest 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"]
  T1 --> T2
  T2 --> T4
  T3 --> T5
  T4 --> T6
  T5 --> T6
  T6 --> T7
  T7 --> T8
  T2 -. deep dive .-> T9
  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 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 Catalog and exercise every Inspector primitive (Tools / Resources / Prompts / Ping / Notifications / Roots / Sampling / Elicitation) end-to-end. Each tutorial is independently runnable in 3–20 minutes; the full main sequence takes about 50 minutes, plus 12 minutes for the deep dive.

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:latest and qwen3-embedding:0.6b pulled.

ollama pull qwen3.5
ollama pull gemma4
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 Catalog'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

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:latestgemma4:latestgpt-oss:latest

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¶