diff --git a/00-ontwerppatronen/ontwerppatronen-voor-agents.md b/00-ontwerppatronen/ontwerppatronen-voor-agents.md index 2d0baa4..6ea833a 100644 --- a/00-ontwerppatronen/ontwerppatronen-voor-agents.md +++ b/00-ontwerppatronen/ontwerppatronen-voor-agents.md @@ -13,7 +13,7 @@ Codeblokken met taal "schema" worden als tekstschema gezet (gestippeld kader, ge **Bijlage bij de workshop AI Agents** LeX Consultancy B.V. · 20 september 2026 -Wie "een agent" wil bouwen, moet eerst één vraag beantwoorden: hoeveel mag het model zelf beslissen? Het antwoord bepaalt hoe je bouwt, wat het kost en hoeveel er fout kan gaan. In het vak worden vijf patronen onderscheiden, van "helemaal niets beslissen" tot "beslissen, maar onder toezicht". Je hebt er in de handleidingen al drie gebouwd zonder dat ze zo heetten. +Wie "een agent" wil bouwen, moet eerst één vraag beantwoorden: hoeveel mag het model zelf beslissen? Het antwoord bepaalt hoe je bouwt, wat het kost en hoeveel er fout kan gaan. In het vak worden vijf patronen onderscheiden, van "helemaal niets beslissen" tot "beslissen, maar onder toezicht". Je hebt ze in de handleidingen allemaal gebouwd zonder dat ze zo heetten. **De vuistregel:** kies het eenvoudigste patroon dat het probleem oplost. Elk stapje omhoog kost meer tijd, meer credits en meer kans op een verrassing. @@ -22,8 +22,8 @@ Wie "een agent" wil bouwen, moet eerst één vraag beantwoorden: hoeveel mag het | 1. Eén aanroep | Jij, vooraf; het model doet één ding | Tekst op niveau (één LLM-stap) | 1 | | 2. Redeneren en handelen (ReAct) | Het model, stap voor stap, met gereedschap | Schoolgids-assistent, Ouderbrief-assistent (agent met kennisbank) | 2, 3 | | 3. Plannen en uitvoeren | Eerst een plan, dan losse uitvoerders | Schoolnieuws (drie kanalen uit één boodschap), Toetsweekplanner | 3, 4 | -| 4. Zelfkritiek | Het model beoordeelt en verbetert zijn eigen werk | Nog niet; past bij handleiding 6 | 6 | -| 5. Poortwachter | Een onafhankelijke controle laat het resultaat wel of niet door | Nog niet; hoort bij alles wat naar buiten gaat | 6 en verder | +| 4. Zelfkritiek | Het model beoordeelt en verbetert zijn eigen werk | De Controleur in Schoolnieuws met controle; de Lesmateriaal-check | 7, 6 | +| 5. Poortwachter | Een onafhankelijke controle laat het resultaat wel of niet door | De Poortwachter (code) in Schoolnieuws met controle; de mens in de lus van de Studiecoach | 7, 8 | --- @@ -162,6 +162,6 @@ Voor de school betekent dat: ## Om te onthouden - Het patroon bepaalt hoeveel het model zelf beslist. Kies het laagste dat werkt. -- Jij hebt al patroon 1 (handleiding 1), 2 (handleiding 2 en 3) en 3 (Schoolnieuws, Toetsweekplanner) gebouwd. +- Jij hebt patroon 1 (handleiding 1), 2 (handleiding 2, 3, 4, 6), 3 (Schoolnieuws, Toetsweekplanner), 4 (de Controleur) en 5 (de Poortwachter, de mens in de lus) gebouwd. - Zelfkritiek verbetert vorm, geen waarheid. Een poortwachter dwingt af, een prompt vraagt alleen. - Geen enkel patroon garandeert een goed antwoord. Ontwerp voor de fout: wat gebeurt er als het misgaat, en wie ziet dat? diff --git a/00-ontwerppatronen/ontwerppatronen-voor-agents.pdf b/00-ontwerppatronen/ontwerppatronen-voor-agents.pdf index 1bc6087..eefc2d2 100644 Binary files a/00-ontwerppatronen/ontwerppatronen-voor-agents.pdf and b/00-ontwerppatronen/ontwerppatronen-voor-agents.pdf differ diff --git a/06-inclusief-lesmateriaal/handleiding-dify-lesmateriaal-check.md b/06-inclusief-lesmateriaal/handleiding-dify-lesmateriaal-check.md index bf2d9c3..01de3a4 100644 --- a/06-inclusief-lesmateriaal/handleiding-dify-lesmateriaal-check.md +++ b/06-inclusief-lesmateriaal/handleiding-dify-lesmateriaal-check.md @@ -20,7 +20,6 @@ Bestanden in deze map: lesbrief-ecologie.pdf fictieve lesbrief biologie 3 havo (zelfde als in handleiding 8) stercollectie-voedselweb-hv3.pdf voorbeeld van wat de zoektool vindt (VO-content, CC BY-SA 4.0) edurep-zoeken.openapi.json het schema van de zoektool, om te plakken bij stap 3 - slo-leerdoelen.openapi.json het schema van de tweede tool (stap 8); de sleutel staat er niet in Gepubliceerde voorbeeld-app: https://udify.app/agent/lkWKedkSW2d3nqBV --> @@ -29,7 +28,7 @@ Gepubliceerde voorbeeld-app: https://udify.app/agent/lkWKedkSW2d3nqBV **Handleiding 6: lesmateriaal toegankelijk maken voor alle leerlingen** Experimenteerruimte ICT SOML · LeX Consultancy B.V. · 20 september 2026 -Je bouwt een agent die een docent helpt zijn lesmateriaal toegankelijk te maken voor leerlingen met een ondersteuningsbehoefte. De agent leest de lesbrief, vraagt welke behoeften in de klas voorkomen, beoordeelt het materiaal op zeven punten, maakt aangepaste versies voor de docent en voor leerlingen, zoekt op Wikiwijs naar open leermateriaal dat erbij past, met licentie, en zegt (stap 8) welke leerdoelen van SLO het materiaal dekt. +Je bouwt een agent die een docent helpt zijn lesmateriaal toegankelijk te maken voor leerlingen met een ondersteuningsbehoefte. De agent leest de lesbrief, vraagt welke behoeften in de klas voorkomen, beoordeelt het materiaal op zeven punten, maakt aangepaste versies voor de docent en voor leerlingen, en zoekt op Wikiwijs naar open leermateriaal dat erbij past, met licentie. Twee dingen zijn nieuw ten opzichte van handleiding 4. Ten eerste de didactiek: de agent werkt volgens **Universal Design for Learning** (UDL), het kader dat zegt dat je niet per leerling een uitzondering maakt, maar het materiaal zo ontwerpt dat het voor iedereen werkt. Ten tweede de techniek: je maakt een **eigen tool**. Dify heeft geen tool die Wikiwijs doorzoekt, dus je beschrijft de zoekmachine van Kennisnet (Edurep) in een klein schema, en daarmee kan de agent hem aanroepen. Dat is de stap van "tools kiezen uit een lijst" naar "elke website met een API als tool". @@ -345,84 +344,6 @@ Wie de link krijgt, kan zijn eigen lesbrief meesturen via het paperclipje en kri --- -## Stap 8. Tweede eigen tool: kerndoelen en leerdoelen van SLO - -De agent zegt nu wat er in het materiaal staat en waar je meer vindt. Wat hij nog niet zegt: welke **leerdoelen** het materiaal dekt. Die staan in de curriculumdatabase van SLO (kerndoelen, tussendoelen, eindtermen, vakbegrippen), open onder CC BY, met een API. Het patroon is hetzelfde als bij Edurep, met één verschil: deze API vraagt een sleutel. Zo leer je meteen hoe je een sleutel in een tool zet. - -### De sleutel aanvragen (twee minuten) - -1. Ga naar **opendata.slo.nl** en klik links op **Hoe werkt de API?** → **Curriculum API**. Daar staat hoe de API werkt: JSON krijg je alleen met een Accept-header en je sleutel als "basic authentication". - -![De uitleg van de Curriculum API, met de link registreren](beelden/26-slo-curriculum-api.jpg) - -2. Klik op **registreren**. Vul je e-mailadres in en klik op **Registreren**. De sleutel komt binnen een minuut per mail. - -![API Key registreren: alleen een e-mailadres](beelden/27-slo-api-key-registreren.jpg) - -3. Maak van je e-mailadres en de sleutel één regel, gescheiden door een dubbele punt, en codeer die als base64. Dat is wat "basic authentication" is. In een terminal: - -``` -printf 'jouw@mailadres.nl:jouw-sleutel' | base64 -w0 -``` - -Bewaar de uitkomst even; die gaat straks in Dify. Gebruik het mailadres waarmee je registreerde, precies zo. - -> De sleutel is persoonlijk. Zet hem nergens in een document, een prompt of een chat; alleen in het veld Authorization van de tool (hieronder). Wie de tool in Dify kan bewerken, kan de sleutel gebruiken; dat is de reden dat een tool aan een workspace hangt en niet aan een app. - -### De tool maken - -4. Ga naar **Integraties** → **Swagger API as Tool** → **Add Swagger API as Tool**. Naam: `SLO leerdoelen`. Plak bij Schema de inhoud van `slo-leerdoelen.openapi.json` uit de map. - -![Het schema van SLO leerdoelen, één actie zoekLeerdoelen](beelden/28-slo-tool-schema.jpg) - -Nieuw in dit schema, vergeleken met Edurep: een parameter `Accept` met `"in": "header"` en standaardwaarde `application/json`. Zonder die header stuurt SLO een webpagina terug in plaats van gegevens; de agent leest dan HTML en vindt niets. - -5. Klik onderaan bij **Authorization method** op het tandwiel. Kies **Header**, bij Auth Type **Basic**, bij Key `Authorization`, en plak bij Value de base64-regel uit punt 3. Klik op **Save**. - -![Authorization method: None, Header of Query Param](beelden/29-slo-authorization.jpg) - -6. Klik bij de actie **zoekLeerdoelen** op **Test**, vul bij text `voedselweb` in en bij Accept `application/json`, en klik op **Test**. Onder Test Results verschijnt een JSON-lijst: vakbegrippen (`SyllabusVakbegrip`, `LdkVakbegrip`) en doelen (`Doel`) met de letterlijke formulering. - -![Het testresultaat: JSON met vakbegrippen en doelen](beelden/30-slo-test-resultaat.jpg) - -7. Klik op **Save**. Er staan nu twee eigen tools. - -![Edurep zoeken en SLO leerdoelen](beelden/31-twee-tools.jpg) - -### Aan de agent koppelen - -8. Ga naar de agent, klik bij **TOOLS** op **Add**, tabblad **Swagger API**, klik op **SLO leerdoelen** en **Add all**. - -![SLO leerdoelen in de toolkiezer, met de actie zoekLeerdoelen](beelden/32-slo-tool-kiezen.jpg) - -![Twee tools onder de agent](beelden/33-agent-twee-tools.jpg) - -9. Voeg in de instructie (stap 4) een punt 6 toe, en maak van de afsluitende vraag punt 7: - -``` -6. Koppel het materiaal aan het landelijke curriculum met de tool SLO leerdoelen: zoek op twee of drie kernbegrippen (bijvoorbeeld: voedselweb, kringloop) met Accept application/json. Geef onder het kopje "Leerdoelen (SLO)" maximaal vijf doelen uit de resultaten (@type Doel of Kerndoel) die het materiaal dekt, letterlijk geciteerd, en noem één doel uit de resultaten dat het materiaal niet of nauwelijks raakt. Noem alleen doelen die in de resultaten stonden. -``` - -10. Test in **VOORBEELD** met één bericht dat alles tegelijk geeft: - -| Bericht | Wat je intypt | -| --- | --- | -| 1 | `Bekijk mijn lesbrief ecologie voor 3 havo. In de klas: dyslexie en taalzwak of NT2.` | - -Het antwoord heeft nu een extra kopje **Leerdoelen (SLO)**: vijf tussendoelen die de lesbrief dekt, letterlijk geciteerd, en één doel dat de lesbrief nauwelijks raakt (in onze test: "Je herkent dat een ecosysteem in verschillende evenwichtssituaties kan verkeren"). Dat laatste is voor een docent misschien het nuttigste zinnetje van het hele rapport. - -![Na de bronnen: het kopje Leerdoelen (SLO)](beelden/34-leerdoelen-slo-begin.jpg) - -![Vijf doelen die het materiaal dekt, en één dat het niet raakt](beelden/35-leerdoelen-slo.jpg) - -11. Klik op **Update publiceren**. - -> Deze beurt kostte ruim 500.000 tokens (de agent leest de lesbrief, schrijft drie bestanden en doet nu acht zoekopdrachten). Via een eigen sleutel is dat rond anderhalve euro. Voor een demo prima; voor dagelijks gebruik door een sectie zet je een limiet op de sleutel, of laat je de agent alleen op verzoek naar SLO kijken ("als de docent erom vraagt"). - -> **Zelf kiezen: wat je uit SLO haalt.** De zoekingang geeft alles wat het woord bevat: kerndoelen, tussendoelen, eindtermen en begrippen. Wil je alleen examenprogramma's (eindtermen), zet dan in punt 6 "@type SyllabusSpecifiekeEindterm". Wil je per doel het niveau en het vak, dan is er een tweede actie mogelijk op `/curriculum/2026/api/v1/uuid/{id}`; voeg die als tweede pad toe aan het schema. - ---- - ## Controleren of het gelukt is - Onder Integraties → Swagger API as Tool staat Edurep zoeken met één actie, en de test geeft numberOfRecords groter dan 0 @@ -430,7 +351,6 @@ Het antwoord heeft nu een extra kopje **Leerdoelen (SLO)**: vijf tussendoelen di - De agent vraagt eerst naar ondersteuningsbehoeften en beoordeelt pas daarna - Het rapport heeft zeven punten met een score - Er zijn twee bestanden (drie als hoogbegaafd is gekozen) en maximaal vijf bronnen met licentie -- Na stap 8: onder Integraties staan twee eigen tools, en het rapport eindigt met Leerdoelen (SLO) - De Toegangs-URL opent een werkende chat --- @@ -442,8 +362,6 @@ Het antwoord heeft nu een extra kopje **Leerdoelen (SLO)**: vijf tussendoelen di | Bij het plakken van het schema verschijnt geen tool onder Available Tools | Het JSON klopt niet: een komma of accolade te veel of te weinig. Plak het bestand `edurep-zoeken.openapi.json` opnieuw | | Test geeft `Query Feature Unsupported` | Zoekwoorden zonder AND ertussen (stap 3, oranje kader) | | Test geeft numberOfRecords 0 | Het zoekwoord komt niet voor, of `exact wikiwijsmaken` is verkeerd gespeld | -| SLO-test geeft een webpagina (`