Ontwerppatronen: patroon 4 en 5 verwijzen naar 07 en 08; link naar de Engelse editie
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Guido van Dijk
@@ -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?
|
||||
|
||||
Binary file not shown.
@@ -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".
|
||||
|
||||
|
||||
|
||||
2. Klik op **registreren**. Vul je e-mailadres in en klik op **Registreren**. De sleutel komt binnen een minuut per mail.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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**.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
7. Klik op **Save**. Er staan nu twee eigen tools.
|
||||
|
||||
|
||||
|
||||
### Aan de agent koppelen
|
||||
|
||||
8. Ga naar de agent, klik bij **TOOLS** op **Add**, tabblad **Swagger API**, klik op **SLO leerdoelen** en **Add all**.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
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 (`<html ...`) in plaats van JSON | De header Accept ontbreekt of staat niet op application/json (stap 8, punt 4 en 6) |
|
||||
| SLO-test geeft 401 | De base64-regel klopt niet: ander mailadres dan bij de registratie, of een spatie te veel. Maak hem opnieuw (stap 8, punt 3) |
|
||||
| De agent noemt bronnen die niet in de RESPONSE staan | Het model vult aan uit eigen geheugen. De regel "verzin geen bronnen" staat in de instructie; controleer de links altijd zelf |
|
||||
| De agent maakt geen bestanden, alleen tekst | Het woord "sandbox" ontbreekt in punt 4 van de instructie, of het model is niet compatibel (handleiding 4, stap 2) |
|
||||
| De leerlingversie laat stukken weg | De zin "Laat geen inhoud weg; vereenvoudig de vorm, niet de stof" ontbreekt |
|
||||
@@ -465,7 +383,7 @@ De lesbrief is verzonnen en de zes behoeften zijn een voorbeeld. Dit hoofdstuk h
|
||||
| Alleen Wikiwijs, of juist alle bronnen van Edurep | Stap 4, punt 5 (het stuk `AND meta.repository.id ...` weglaten) | makkelijk | Meer of minder zoekresultaten |
|
||||
| Een score per UDL-principe in plaats van zeven losse punten | Stap 4, punt 3 | gemiddeld | Een rapport dat aansluit bij de UDL-taal van jullie school |
|
||||
| Een vierde bestand: ouderbrief over de aangepaste versie | Stap 4, punt 4 | gemiddeld | Communicatie erbij, in dezelfde beurt |
|
||||
| Alleen eindtermen uit SLO, of niveau en vak per doel | Stap 8, punt 6 van de prompt of een tweede pad in het schema | gemiddeld | Een rapport dat past bij bovenbouw en examenprogramma |
|
||||
| Kerndoelen en leerdoelen erbij (SLO) | Stap 3, tweede eigen tool op opendata.slo.nl (sleutel aanvragen) | gemiddeld | De agent zegt welke leerdoelen het materiaal dekt en wat ontbreekt |
|
||||
| De agent als stap in een workflow | Toegangspunt → Workflowtoegang; of de agent aanroepen vanuit een Chatflow | moeilijk | Een intake-formulier vooraf en een vaste opmaak achteraf |
|
||||
| Koppeling met de ELO of het leerlingvolgsysteem via MCP | Stap 2, tabblad MCP, in de SOML-omgeving | moeilijk | Materiaal rechtstreeks uit en naar de plek waar het gebruikt wordt |
|
||||
|
||||
@@ -473,7 +391,7 @@ De lesbrief is verzonnen en de zes behoeften zijn een voorbeeld. Dit hoofdstuk h
|
||||
|
||||
1. **Zoek de fout.** Laat de agent jouw eigen lesbrief beoordelen en lees het rapport kritisch: welke score klopt niet? Pas de zin bij dat punt in de instructie aan tot het rapport klopt. Zo leer je dat de zeven punten van jou zijn, niet van het model.
|
||||
2. **Controleer de bronnen.** Open de vijf Wikiwijs-links die de agent gaf en beoordeel ze zelf op niveau en bruikbaarheid. Hoeveel had je zelf gekozen? Schrijf in de instructie erbij wat een bron voor jou bruikbaar maakt.
|
||||
3. **Maak een derde tool.** Beschrijf een andere openbare API in een schema (de KNMI, het CBS, een woordenboek) en voeg hem toe. Laat de agent hem gebruiken en kijk bij REQUEST en RESPONSE wat er heen en weer gaat. Daarna begrijp je elke tool die je ooit tegenkomt.
|
||||
3. **Maak een tweede tool.** Beschrijf een andere openbare API in een schema (de KNMI, het CBS, een woordenboek) en voeg hem toe. Laat de agent hem gebruiken en kijk bij REQUEST en RESPONSE wat er heen en weer gaat. Daarna begrijp je elke tool die je ooit tegenkomt.
|
||||
|
||||
**Checklist voordat je eigen materiaal gebruikt**
|
||||
|
||||
@@ -494,6 +412,6 @@ De lesbrief is verzonnen en de zes behoeften zijn een voorbeeld. Dit hoofdstuk h
|
||||
|
||||
**De eigen tool.** Edurep is een openbare dienst van Kennisnet zonder sleutel. Verandert de zoekingang, dan faalt de tool; je merkt dat aan een RESPONSE met een foutmelding in plaats van XML. Het schema in `edurep-zoeken.openapi.json` is dan het enige wat je hoeft aan te passen. Meer over de zoektaal: developers.wiki.kennisnet.nl (Edurep).
|
||||
|
||||
**De SLO-sleutel.** De sleutel staat in de tool, niet in de agent. Vervang je hem (nieuwe registratie), dan pas je alleen het veld Authorization van de tool aan. Exporteer je de agent (DSL), dan gaat de sleutel niet mee; in het andere account maakt de eigenaar de tool opnieuw met een eigen sleutel. De data van SLO is CC BY: noem SLO als bron als je de doelen in materiaal overneemt.
|
||||
**Kerndoelen erbij.** SLO stelt kerndoelen, leerdoelen en examenprogramma's open via opendata.slo.nl, met een gratis sleutel. Daarmee kan de agent bij elke lesbrief zeggen welke doelen hij dekt. Dat is de tweede eigen tool uit Maak hem van jou; het schema volgt hetzelfde patroon als dat van Edurep, met een sleutel in het veld Authorization.
|
||||
|
||||
**Van prototype naar de Experimenteerruimte.** Via **Export DSL** gaat de agent als bestand mee; de eigen tool moet in het andere account opnieuw aangemaakt worden (Integraties → Swagger API as Tool, hetzelfde schema).
|
||||
|
||||
@@ -75,3 +75,5 @@ Opmaak in de bronnen: genummerde lijst = handelingen, tabel "Wat je intypt" = ve
|
||||
codeblok = letterlijk overtypen (label "Intypen"), oranje kader = valkuil, groen kader = "Zelf kiezen"
|
||||
(blockquote die met **Zelf kiezen** begint). Opmaak en logo's staan in `_gereedschap/build_handleiding.py`;
|
||||
vervang de logo's door die van je eigen school of netwerk.
|
||||
|
||||
Engelse editie (LeX Consultancy, internationale open bronnen): https://git.lexconsultancy.nl/guido/dify-guides
|
||||
|
||||
Reference in New Issue
Block a user