# 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.