dify-handleidingen/02-agent-kennisbank/handleiding-dify-agent.md

Bouwen in Dify: een agent met eigen kennisbank

Handleiding 2 bij de workshop AI Agents
LeX Consultancy B.V. · 20 september 2026

In handleiding 1 bouwde je een workflow: jij bepaalde elke stap. Nu bouw je een agent. Die krijgt een doel, een instructie en een kennisbank met jouw eigen document, en beslist zelf wanneer hij daarin gaat zoeken. Aan het eind heb je een chatbot met een eigen webadres die vragen over jouw document beantwoordt en eerlijk zegt wanneer het antwoord er niet in staat.

Deze handleiding volgt de cloudversie van Dify zoals die er op 20 september 2026 uitziet. Dify verandert snel: wijkt je scherm af, volg dan wat je ziet en niet wat hier staat.

Zo lees je deze handleiding

Vorm	Betekenis
1. 2. 3.	Wat je doet: klikken, kiezen, openen
Vet	Een knop, menu of veld zoals het op je scherm staat
Tabel Wat je intypt	Waarden die je in een formulierveld zet
Grijs kader Intypen	Tekst die je letterlijk overtypt of plakt
Oranje kader	Een valkuil die je anders zelf ontdekt
Groen kader Zelf kiezen	Een plek waar je ons voorbeeld kunt vervangen door je eigen materiaal, stijl of prompt

Over credits: een agent is duurder dan een workflow. In onze test kostte het aanmaken van de kennisbank plus één zoektest 26 credits, en elk antwoord van de agent 6 à 7 credits (met gpt-5-mini). Met de 200 credits van een sandbox-account kun je deze handleiding dus één keer volgen en daarna nog zo'n twintig vragen stellen. Test dus gericht, niet voor de lol.

---

Voorbereiding

• Je hebt handleiding 1 gedaan, of je weet in elk geval waar Studio en Create zitten.
• Je hebt een document klaarstaan dat de agent moet kennen: PDF, Word, tekst of markdown, maximaal 15 MB en één bestand per keer in de sandbox. Kies een document met echte tekst, geen gescande afbeeldingen.
• Zet er geen persoonsgegevens in. Alles wat je uploadt, staat op de servers van Dify.

In deze handleiding gebruiken we een fictieve schoolgids van twee pagina's: schoolgids-voorbeeldcollege.pdf. Die zit bij deze handleiding. Neem hem gerust, dan kloppen alle voorbeeldvragen.

Zelf kiezen: je eigen document. Wil je meteen met eigen materiaal werken, kies dan een document waar collega's of leerlingen nu al vragen over stellen: het examenreglement, de studiewijzer van een vak, het protocol voor excursies, de handleiding van het leerlingvolgsysteem. Voorwaarden: echte tekst (geen scan), geen persoonsgegevens, en liefst met kopjes; die helpen bij het knippen in stap 2. De vragen in stap 5 en 10 pas je dan aan op jouw document.

---

Deel A. De kennisbank

Stap 1. Maak een kennisbank aan

1. Klik in het linkermenu op Knowledge.

2. Klik op Een gebruiksklare kennisbank maken (met het label AANBEVOLEN).
3. Laat Import from file geselecteerd staan.

4. Klik op Browse en kies je document, of sleep het in het vak.

5. Klik op Next.

Stap 2. Controleer hoe het document geknipt wordt

Dify knipt je document in stukken ("chunks"). De agent zoekt straks in die stukken, niet in het hele document. Te kleine stukken bevatten geen bruikbaar antwoord; dat controleer je hier.

1. Klik op Preview Chunk. Rechts verschijnen de stukken.

Zie je veel stukken van één regel, zoals "1. Lestijden" of "1 8.30 - 9.20"? Dan knipt Dify op elke regeleinde. Dat gebeurt vaak bij PDF's. Een stuk van twaalf tekens kan geen vraag beantwoorden.

2. Klik in het veld Delimiter en vervang de inhoud.

Veld op het scherm	Wat je intypt
Delimiter	\n\n

3. Klik opnieuw op Preview Chunk. Rechts staan nu een paar stukken van een alinea of langer.

4. Laat Maximum chunk length (1024) en Chunk overlap (50) staan.
5. Laat bij Index Method de keuze High Quality staan.
6. Scroll naar beneden. Embedding Model en Retrieval Setting laat je op de standaardwaarden.

7. Klik op Save & Process.

Stap 3. Wacht tot de verwerking klaar is

Bij een document van twee pagina's duurt dit een paar seconden. De status springt van EMBEDDING PROCESSING naar EMBEDDING COMPLETED met een groen vinkje achter je bestand.

1. Klik op Go to document. Je ziet je document in de lijst met status Available.

Stap 4. Geef de kennisbank een naam en een beschrijving

De beschrijving is niet alleen voor jou. De agent leest hem om te beslissen of hij deze kennisbank moet raadplegen. Een goede beschrijving zegt dus waar de kennisbank over gaat.

1. Klik in het linkermenu op Settings.
2. Vul de twee velden in.

Veld op het scherm	Wat je intypt
Name & Icon	Schoolgids Voorbeeldcollege
Description	zie het kader hieronder

Gebruik deze kennisbank voor vragen over de schoolregels van Het Voorbeeldcollege: lestijden, ziek melden, verzuim en verlof, huiswerk en toetsen, telefoons en laptops, mentoraat en contactgegevens.

3. Scroll helemaal naar beneden en klik op Save.

Stap 5. Test of de kennisbank het juiste stuk vindt

Dit is het moment waarop je ziet wat een kennisbank doet: je stelt een vraag en krijgt geen antwoord, maar de stukken tekst die het beste bij je vraag passen. Straks maakt de agent daar een antwoord van.

1. Klik in het linkermenu op Retrieval Testing.

2. Klik in het veld SOURCE TEXT en typ een vraag.

Hoe laat moet ik mijn kind ziek melden?

3. Klik op Test.

Rechts staan de gevonden stukken met een score. Het stuk met de ziekmeldregels staat bovenaan met 0,86; de andere twee scoren laag. Zo hoort het. Staat het juiste stuk er niet bij, ga dan terug naar stap 2 en kijk of de stukken wel groot genoeg zijn.

---

Deel B. De agent

Stap 6. Maak de agent

1. Klik in het linkermenu op Studio.
2. Klik rechtsboven op Create en kies Create from Blank.
3. Klik op MORE BASIC APP TYPES.
4. Klik op Agent.
5. Vul de naam in.

Veld op het scherm	Wat je intypt
App Name & Icon	Schoolgids-assistent

6. Klik op Create.

Naast "Orchestrate" staat een oranje label LEGACY AGENT. Schrik daar niet van; de agent werkt gewoon. Wat het betekent, lees je in het kader "Over het label LEGACY AGENT" aan het eind van deze handleiding.

Stap 7. Zet het model op gpt-5-mini

Ook hier staat het model standaard op gpt-5, en ook hier is dat vijf keer zo duur als nodig.

1. Klik rechtsboven op de modelnaam gpt-5.

2. Kies gpt-5-mini.

Stap 8. Schrijf de instructie

Bij een workflow schreef je per stap een prompt. Een agent krijgt één instructie: wie hij is, wat hij mag en wat hij niet mag. De regels over "alleen uit de kennisbank" en "zeg het als je het niet weet" zijn de belangrijkste; zonder die regels verzint hij er vrolijk op los.

1. Klik in het veld INSTRUCTIONS.
2. Typ de instructie over.

Je bent de schoolgids-assistent van Het Voorbeeldcollege. Je beantwoordt vragen van ouders en leerlingen over de schoolregels.

Regels:
- Baseer je antwoord alleen op de schoolgids in je kennisbank.
- Staat het antwoord niet in de schoolgids, zeg dan eerlijk dat je het niet weet en verwijs naar de receptie.
- Antwoord kort en in gewoon Nederlands, maximaal vijf zinnen.
- Noem waar het kan het hoofdstuk van de schoolgids waar het antwoord vandaan komt.

Zelf kiezen: rol, regels en toon. De eerste zin bepaalt de rol ("schoolgids-assistent", "examenhulp", "onboardingbuddy voor nieuwe collega's"), de regels bepalen het gedrag. Hou de twee regels over de kennisbank en over "zeg dat je het niet weet" altijd; verander de rest. Wil je dat de agent leerlingen met je aanspreekt en ouders met u? Zeg dat. Wil je dat hij altijd eindigt met "Klopt dit, of wil je meer weten?" Zeg dat. Wil je Engelse antwoorden op Engelse vragen? Eén regel erbij.

Stap 9. Koppel de kennisbank

1. Klik bij Knowledge op Add.
2. Klik op Schoolgids Voorbeeldcollege. Onderin verschijnt "1 Knowledge selected".

3. Klik op Add.

Stap 10. Test de agent

Rechts staat Debug & Preview: een chatvenster waarin je met de agent praat voordat hij live is. Stel twee soorten vragen: een die in het document staat, en een die er niet in staat.

1. Klik onderin op Talk to Bot en typ de eerste vraag.

Mijn dochter heeft een toets gemist. Wanneer kan ze die inhalen?

2. Druk op Enter en wacht. Boven het antwoord verschijnt het label Used Knowledge.

3. Klik op Used Knowledge om het open te klappen.

Kijk bij REQUEST. Daar staat de zoekopdracht die de agent zelf heeft geformuleerd, iets als "toets gemist inhalen wanneer kan ze die inhalen". Jij hebt hem niet gezegd dat hij moest zoeken en ook niet waarnaar. Hij besloot dat zelf op basis van je vraag en de beschrijving van de kennisbank. Dat is het verschil met de workflow van handleiding 1.

4. Klik het label weer dicht en typ de tweede vraag.

Wat kost het schoolkamp van de brugklas?

5. Druk op Enter.

De agent zegt dat het niet in de schoolgids staat en verwijst naar de receptie. Dat komt door de tweede regel in je instructie. Haal die regel weg en probeer het opnieuw: dan krijg je een keurig verzonnen bedrag.

Stap 11. Publiceer de agent

1. Klik rechtsboven op Publish.

Het menu zegt "Latest Published, published een paar minuten geleden", terwijl je nog niets gepubliceerd hebt. Dify publiceert een Agent-app namelijk al bij het aanmaken, dus leeg. De versie met jouw instructie en kennisbank staat onder Current Draft. Sla je Publish Update over, dan opent de webapp een agent zonder kennis.

2. Klik op Publish Update. De melding "Success" verschijnt en onder de knop staat nu "Up-to-date".

3. Klik op Webapp openen.

4. Typ een vraag om te controleren of de gepubliceerde versie de kennisbank gebruikt.

Mag mijn zoon zijn telefoon gebruiken in de pauze?

Onder het antwoord staat CITATIONS met de naam van je document. Dat is de link die je aan je testpartner geeft; hij werkt zonder inloggen, ook op een telefoon.

De agent uit deze handleiding staat op https://udify.app/chat/cvLAmpk60m9HUXUy.

---

Controleren of het gelukt is

• Bij Knowledge staat je kennisbank met status Available en een preview van hooguit een handvol stukken per pagina
• Retrieval Testing zet bij een vraag uit het document het juiste stuk bovenaan
• De agent beantwoordt een vraag uit het document met Used Knowledge erboven
• De agent zegt bij een vraag buiten het document dat hij het niet weet
• De webapp-link toont CITATIONS onder het antwoord

Als het misgaat

Wat je ziet	Wat er aan de hand is
Preview Chunk toont tientallen stukken van één regel	De Delimiter staat op \n. Zet hem op \n\n (stap 2)
Retrieval Testing vindt het juiste stuk niet	Stukken te klein of te groot. Terug naar stap 2; bij een groot document Maximum chunk length verhogen
De agent antwoordt zonder Used Knowledge, ook bij vragen uit het document	Kennisbank niet gekoppeld (stap 9) of de Description van de kennisbank is leeg of nietszeggend (stap 4)
De agent verzint antwoorden	De regel "Staat het antwoord niet in de schoolgids..." ontbreekt in de instructie
De webapp antwoordt zonder kennis, terwijl Debug & Preview het wel doet	Publish Update niet geklikt; de webapp draait nog de lege versie van bij het aanmaken
Je credits lopen hard terug	Model staat nog op gpt-5. Zet hem op gpt-5-mini (stap 7). Een agent-antwoord kost sowieso 6 à 7 credits
Bij uploaden: "Maximaal 1 bestanden"	Sandbox-limiet. Eén bestand per keer; een tweede voeg je daarna toe met Add file
Melding dat de parameter temperature verwijderd is	Het model ondersteunt die niet. Negeren

---

Over het label LEGACY AGENT

Dify bouwt op dit moment aan een nieuwe manier om agents te maken: de Agent Console, in het linkermenu te vinden als Agents met het label BETA. De Agent-app die je in deze handleiding bouwde, heet daarom "legacy": Dify wil dat je op termijn de nieuwe route neemt.

We hebben die nieuwe console op 20 september 2026 bekeken en bewust niet voor deze handleiding gekozen:

• gpt-5-mini is er niet beschikbaar; wel gpt-5.6-luna, Claude Opus 4 en Gemini 3.5, allemaal duurder in credits;
• er is geen koppeling met een kennisbank, de agent leest losse bestanden in een sandbox-omgeving;
• de pagina rendert nog niet stabiel en de teksten wisselen tussen Nederlands en Engels.

Voor een workshop met sandbox-accounts is de Agent-app in Studio de betrouwbare route. Wat je erin leert, instructie, kennisbank, testen en publiceren, blijft gelden in de nieuwe console; alleen de knoppen verschuiven.

---

Maak hem van jou

De schoolgids is verzonnen, de assistent is een voorbeeld. Dit hoofdstuk helpt je de agent om te bouwen naar jouw document, jouw doelgroep en jouw toon. Van makkelijk naar moeilijk.

Aanpassing	Waar	Moeilijkheid	Wat je ervoor terugkrijgt
Een ander document	Deel A, stap 1 tot 4	makkelijk	Een agent over iets waar bij jou echt vragen over komen
Naam en beschrijving van de kennisbank	Stap 4	makkelijk	Een agent die weet wanneer hij moet zoeken
Rol, toon en aanspreekvorm	Stap 8, instructie	makkelijk	Een assistent die klinkt als jouw school
Een openingszin en voorbeeldvragen in de webapp	Debug & Preview → Manage (onderaan) → Conversation Opener	makkelijk	Gebruikers weten meteen wat ze kunnen vragen
Een tweede document in dezelfde kennisbank	Deel A opnieuw, via Add file	gemiddeld	Meer vragen goed beantwoord; let op de beschrijving
Twee kennisbanken (bijvoorbeeld leerlingen en personeel apart)	Stap 9, twee keer Add	gemiddeld	Duidelijke scheiding; in de instructie zeg je wanneer welke
Bronvermelding afdwingen ("noem altijd het hoofdstuk")	Stap 8, instructie	gemiddeld	Antwoorden die je kunt controleren
Gereedschap toevoegen (datum, rekenen, webzoeken)	Tools in hetzelfde scherm	moeilijk	Een agent die meer kan dan lezen; zie handleiding 4

Drie opdrachten

1. Jouw document, jouw vragen. Maak een kennisbank van een document van jouw school. Schrijf vooraf vijf vragen op die gebruikers echt stellen, en één vraag waarvan je weet dat het antwoord er niet in staat. Test alle zes in stap 10. Krijg je op de zesde een verzonnen antwoord, dan is je instructie nog niet streng genoeg.
2. Twee doelgroepen, één agent. Laat de agent anders antwoorden voor leerlingen (je, kort) en ouders (u, iets uitgebreider). Los het eerst op in de instructie ("Als de vraag van een ouder lijkt te komen..."). Werkt dat niet betrouwbaar, voeg dan een Variable toe (het blok Variables onder de instructie) waarmee de gebruiker zelf kiest.
3. Laat een collega hem slopen. Geef de link aan iemand die het document goed kent en vraag om de agent te betrappen op fouten. Lees de Logs. Ligt het aan het knippen (stap 2), aan de beschrijving (stap 4) of aan de instructie (stap 8)? Pas één ding aan, Publish Update, en test opnieuw.

Checklist voordat je eigen materiaal gebruikt

• Het document bevat geen namen, adressen, cijfers of andere gegevens van personen
• Het document is van de school en mag bij een externe verwerker staan (Dify draait in de cloud)
• Het document is de actuele versie, en er is één eigenaar die een nieuwe versie uploadt als het verandert
• Je hebt besloten wie de link krijgt; bij leerlingen of ouders eerst de privacyfunctionaris erbij
• Het model staat op gpt-5-mini en je weet dat een antwoord 6 à 7 credits kost zonder eigen sleutel
• De instructie zegt wat de agent moet doen als hij het niet weet, en je hebt dat getest

---

En verder

Je agent kan nu lezen. De volgende stap is dat hij iets kan doen: het web doorzoeken, rekenen, de datum weten, of een workflow uit handleiding 1 aanroepen als gereedschap. Dat regel je onder Tools in hetzelfde scherm. Dat is handleiding 3.