237 lines
10 KiB
Markdown
237 lines
10 KiB
Markdown
# Les 13 — Docenttekst (normale versie)
|
||
|
||
Dit document is de gewone docenthandleiding bij Les 13: Agents. Voor de **letterlijke voorleesversie** zie `Les13-Docenttekst-Autocue.md`.
|
||
|
||
**Vorige les:** Les 12 — Tool Calling
|
||
**Volgende les:** Les 14 — Externe APIs + Cursor + Vercel deploy
|
||
|
||
**Lesvorm:** fysiek, demo-driven, ±1 uur presenteren → pauze → ±1,5 uur "Nu jullie"
|
||
|
||
---
|
||
|
||
## Voorbereiding (de dag voor de les)
|
||
|
||
Loop dit door voor je morgen begint. Drie groepen: accounts, code-deployment, en presentatie-omgeving.
|
||
|
||
### 0. Supabase — geen nieuwe tabel nodig
|
||
|
||
De bestaande `user_favorites` tabel uit Les 11/12 gebruiken we (kolommen `id`, `user_email`, `band_id`, `created_at`). De `addToFavorites` tool doet eerst een band-lookup en plaatst dan een rij met `user_email = "demo@polderwave.app"` en de juiste `band_id`.
|
||
|
||
Tussen demos resetten kan met `supabase-reset-user-favorites.sql` (zit in de zip).
|
||
|
||
### 1. Accounts en API-keys
|
||
|
||
| Service | Account nodig? | Voor wat |
|
||
|---------|---------------|---------|
|
||
| **Supabase** | Ja — bestaat al uit Les 11/12 | Polderfest-database met `bands`-tabel |
|
||
| **OpenAI** | Ja — bestaat al uit Les 11 | API key voor `gpt-5.2` in `.env.local` en Vercel |
|
||
| **Vercel** | Ja — bestaat al uit Les 11 | Hosting van Polderfest-with-agent |
|
||
| **GitHub** | Ja | Repo voor Polderfest-with-agent |
|
||
| **Open-Meteo (weer-API)** | **NEE** — geen account, geen API key | Externe API als demo voor de derde tool |
|
||
|
||
> Open-Meteo expliciet noemen tijdens de les — studenten merken vaak dat het gratis kan zonder registratie en dat is een heerlijk moment om aan te kondigen.
|
||
|
||
### 2. Code en deploy klaarzetten
|
||
|
||
- [ ] Pak `polderfest-with-agent.zip` uit (uit `lesbestanden/`)
|
||
- [ ] `npm install`, `npm run dev` — check dat de app lokaal draait
|
||
- [ ] Open `localhost:3000` — de gewone chat moet werken
|
||
- [ ] Klik door naar `localhost:3000/agent` — de agent-pagina moet werken
|
||
- [ ] Push naar een nieuwe GitHub-repo `polderfest-with-agent`
|
||
- [ ] Importeer op Vercel, vul de env vars in:
|
||
- `NEXT_PUBLIC_SUPABASE_URL`
|
||
- `NEXT_PUBLIC_SUPABASE_ANON_KEY`
|
||
- `SUPABASE_SERVICE_ROLE_KEY`
|
||
- `OPENAI_API_KEY`
|
||
- [ ] Deploy. Wacht tot live. Check beide URLs werken in productie.
|
||
- [ ] **Bewaar de productie-URL** — die ga je tijdens de demo gebruiken.
|
||
|
||
### 3. Presentatie klaarzetten
|
||
|
||
- [ ] Cursor open in de Polderfest-with-agent-map (voor code-walkthrough)
|
||
- [ ] Browser tabs vooraf openen:
|
||
- de gedeployde agent-URL (productie)
|
||
- Vercel dashboard van de polderfest-with-agent
|
||
- github.com — de repo
|
||
- `Les13-Stap-voor-stap.md` open in een tweede editor-window
|
||
- [ ] Beamer-test — slides goed leesbaar, code-grootte oké
|
||
- [ ] `Les13-Slides.pdf` of `.pptx` klaargezet
|
||
- [ ] De drie demo-prompts copy-paste klaar (zie eind van dit document)
|
||
|
||
### 4. Mentaal klaarzetten
|
||
|
||
Twee dingen om scherp te houden tijdens deze les:
|
||
|
||
1. **Tool calling vs Agent is een continuüm.** Wees eerlijk hierover — er is geen harde lijn. Studenten waarderen die nuance meer dan een "deze is goed, die is fout"-uitleg.
|
||
2. **Externe APIs konden ook in Les 12.** Niet doen alsof dit een agent-feature is. Het verschil bij agents zit in *meerdere bronnen door elkaar combineren*.
|
||
|
||
---
|
||
|
||
## Lesopzet
|
||
|
||
| Blok | Onderwerp | Slides |
|
||
|------|-----------|--------|
|
||
| 1 | Welkom + Terugblik tool calling | 1–3 |
|
||
| 2 | Wat is een agent? Wanneer waarde? | 4–6 |
|
||
| 3 | AI SDK basics: tool, stopWhen, externe API | 7–9 |
|
||
| 4 | Drie agent-extra's: prepareStep + hasToolCall/finishPlan + write-tool | 10 |
|
||
| 5 | Roadmap + code-walkthrough (6 STEP-slides) | 11–17 |
|
||
| 6 | Stappenplan visueel (recap) | 18 |
|
||
| 7 | LIVE DEMO — gedeployde agent | 19 |
|
||
| – | Pauze | – |
|
||
| 8 | Nu jullie — zelf bouwen | 20 |
|
||
| 9 | Afsluiting | 21 |
|
||
|
||
---
|
||
|
||
## Blok 1: Welkom + Terugblik tool calling (slides 1-3)
|
||
|
||
**Doel:** studenten warmlopen + de stap zetten van "tool calling" (vorige les) naar "agent" (vandaag).
|
||
|
||
Open met de vraag *"Wie heeft thuis nog gespeeld met de Polderfest-app?"* om aan te haken bij de vorige les.
|
||
|
||
Belangrijke punten:
|
||
- Tool calling werkt prima voor enkelvoudige vragen ("welke bands op zaterdag?")
|
||
- Complexe vragen vragen meerdere stappen ("plan een avond met indie + techno + geen overlap")
|
||
- Vandaag voegen we één route toe — `/api/agent` — die dat aan kan
|
||
|
||
**Cruciaal op slide 3:** vermeld expliciet dat er **geen harde lijn** is tussen tool calling en agents. In AI SDK v6 is het dezelfde syntax. Het verschil zit in mindset en in hoeveel stappen je toelaat.
|
||
|
||
**Wat veel docenten verkeerd doen:** zeggen dat "tool calling maar 1 stap kan". Niet waar — ook met tool calling kun je `stopWhen` gebruiken. Het verschil is subtieler: bij tool calling is het pad voorspelbaar (jij beschrijft de stappen), bij een agent is het pad open (AI plant zelf).
|
||
|
||
---
|
||
|
||
## Blok 2: Wat is een agent? (slides 4-6)
|
||
|
||
**Doel:** wanneer is een agent echt zinvol, wanneer overkill.
|
||
|
||
Goede voorbeelden om te noemen:
|
||
- Plan-vragen ("plan een dag", "vergelijk twee opties", "vind het beste")
|
||
- Onderzoek-vragen met meerdere bronnen
|
||
- Vragen waarbij het eerste antwoord een vervolgvraag triggert
|
||
|
||
Geef ook **slechte** voorbeelden om te illustreren dat agent niet altijd het antwoord is:
|
||
- "Wat speelt er op zaterdag?" → één DB-call, geen agent nodig
|
||
- "Wie maakt account X aan?" → één auth-call, geen agent nodig
|
||
|
||
Slide 5 toont de agent-loop visueel. Loop dit langs en benadruk dat de LLM in elk loopje opnieuw beslist: "ben ik klaar, of moet ik nog een tool?".
|
||
|
||
Slide 6 noemt de 5 stappen om een agent te bouwen — dit is de teaser voor het stappenplan op slide 10.
|
||
|
||
---
|
||
|
||
## Blok 3: De drie AI SDK basics (slides 7-9)
|
||
|
||
**Doel:** de bekende AI SDK functies opnieuw uitleggen + bredere context.
|
||
|
||
- Slide 7: `tool()` — bekend uit Les 12, herhalen voor zekerheid
|
||
- Slide 8: `stopWhen` — DIT is de agent-knop. Zonder `stopWhen` doet de AI één tool-call. Met `stopWhen` mag-ie blijven doorlopen.
|
||
- Slide 9: externe API als tool — Open-Meteo voorbeeld. Benoem expliciet:
|
||
- **Geen account, geen API key** (perfect voor onderwijs)
|
||
- **Dit kon ook al in Les 12** — niet doen alsof dit een agent-feature is
|
||
- **Echte verschil bij agents:** meerdere bronnen door elkaar combineren
|
||
|
||
---
|
||
|
||
## Blok 4: Drie agent-extra's bovenop Les 12 (slide 10)
|
||
|
||
**Doel:** hier wordt het écht agent-werk. Drie features die NIET in Les 12 zaten.
|
||
|
||
- **`prepareStep`** — wissel model per stap. Stap 0 = krachtig (planning), stap 1+ = goedkoop (uitvoering). Lagere kosten zonder kwaliteitsverlies. Verkoop dit als production-feature.
|
||
- **`hasToolCall("finishPlan")`** + `finishPlan` tool — speciale tool met Zod-schema die de agent **moet** aanroepen als laatste stap. `hasToolCall` zorgt dat de loop direct stopt. Resultaat: gegarandeerd gestructureerd eindplan dat je in de UI mooi kunt renderen.
|
||
- **`addToFavorites`** — eerste write-tool. Schrijft naar Supabase-tabel. Tot nu toe lazen alle tools alleen. Dit is een grote stap — de agent verandert nu de wereld. Benoem productie-risico's kort (veiligheid: RLS, audit-logging).
|
||
|
||
Combinatie maakt het tot een échte agent: plant met krachtig model → voert uit met goedkoop → schrijft favoriet als gebruiker dat vraagt → sluit af met gestructureerd plan.
|
||
|
||
---
|
||
|
||
## Blok 5: Stappenplan Polderfest → Polderfest-met-agent (slide 11)
|
||
|
||
Korte intro op het stappenplan — nu 15 stappen ipv 11 omdat we de drie agent-features hebben toegevoegd. Wijs naar `lesbestanden/Les13-Stap-voor-stap.md` voor het zelf-bouwen straks.
|
||
|
||
---
|
||
|
||
## Blok 6: LIVE DEMO (slide 12)
|
||
|
||
**Doel:** studenten laten zien hoe een werkende agent zich gedraagt, voor ze zelf gaan bouwen.
|
||
|
||
Volgorde:
|
||
|
||
1. **Open de gedeployde agent-URL** in de browser (productie).
|
||
2. **Prompt 1**: `Plan een avond met indie en techno voor zaterdag.`
|
||
- Studenten zien meerdere tool-calls verschijnen (searchBands × 2 + getStageSchedule)
|
||
- Wijs naar de details-tags in de UI — die expanden om te zien wat de tool deed
|
||
3. **Prompt 2**: `Wat speelt er op zondag en hoe is het weer dan?`
|
||
- Hier zien ze de externe weer-API in actie
|
||
4. **Prompt 3**: `Welke band moet ik NIET missen op vrijdag?`
|
||
- Open vraag, AI moet creatief combineren
|
||
|
||
5. **Code-walkthrough** in Cursor:
|
||
- `app/api/agent/route.ts` — wijs naar de drie tools + `stopWhen`
|
||
- `app/agent/page.tsx` — wijs naar `m.parts.map` met de tool-call-weergave
|
||
- Vergelijk kort met `app/api/chat/route.ts` van Les 11 — "kijk hoe weinig code het is voor zoveel functionaliteit"
|
||
|
||
---
|
||
|
||
## Blok 6: Nu jullie (slide 12)
|
||
|
||
**Doel:** zelfstandig werken, ±1,5 uur.
|
||
|
||
Studenten kiezen tussen:
|
||
- Eigen Polderfest-app uit Les 12 als startpunt
|
||
- `polderfest-original.zip` uit `lesbestanden/`
|
||
|
||
Met `Les13-Stap-voor-stap.md` als 11-stappen-gids. `polderfest-with-agent.zip` is referentie als ze vastlopen.
|
||
|
||
Loop rond, laat ze in eigen tempo werken. Geef ruimte voor vragen via chat én fysiek.
|
||
|
||
Doel-deliverable: live productie-URL in de groeps-chat plakken.
|
||
|
||
---
|
||
|
||
## Blok 7: Afsluiting (slide 13)
|
||
|
||
Korte samenvatting + vooruitblik Les 14. Vragen-ronde.
|
||
|
||
---
|
||
|
||
## De drie demo-prompts — copy-paste-klaar
|
||
|
||
**Prompt 1 — basis multi-step**
|
||
```
|
||
Plan een avond met indie en techno voor zaterdag.
|
||
```
|
||
|
||
**Prompt 2 — externe API gebruiken**
|
||
```
|
||
Wat speelt er op zondag en hoe is het weer dan?
|
||
```
|
||
|
||
**Prompt 3 — write-tool + finishPlan**
|
||
```
|
||
Welke band moet ik NIET missen op vrijdag? Zet hem in mijn favorieten.
|
||
```
|
||
|
||
---
|
||
|
||
## Veelvoorkomende fouten — wat tegen studenten te zeggen
|
||
|
||
| Probleem student | Wat te zeggen |
|
||
|------------------|---------------|
|
||
| "Mijn agent stopt na 1 tool-call" | "Heb je `stopWhen: stepCountIs(8)` toegevoegd?" |
|
||
| "Tool wordt nooit aangeroepen" | "Description is te vaag. Maak 'm heel concreet." |
|
||
| "Open-Meteo geeft niets terug" | "ISO datum-format checken: `YYYY-MM-DD`" |
|
||
| "Vercel deploy faalt" | "Env vars in Vercel toegevoegd?" |
|
||
| "Hydration error" | "`use client` bovenaan page.tsx vergeten?" |
|
||
|
||
---
|
||
|
||
## Voor jezelf: 4-zinnen kernverhaal
|
||
|
||
Voor de afsluiting, samenvattend in vier zinnen:
|
||
|
||
1. Tool calling en agents zijn geen verschillende technologieën — het is een schaal.
|
||
2. `stopWhen` is wat een agent mogelijk maakt: zonder doet de AI één stap, met mag-ie doorlopen.
|
||
3. Wanneer een agent echt zinvol is: open vragen, meerdere bronnen, onvoorspelbaar pad.
|
||
4. Externe APIs als tool is geen nieuwe functionaliteit — wel iets dat agents vaker echt benutten.
|