Een AI-agent bouwen is één ding. Een agent bouwen die ook in productie overleeft, en niet alleen in de demo, is een ander verhaal. Dat verschil zit in negen vragen die je beantwoordt voordat je ook maar een tool opent: niet welk model je kiest, niet welk framework, maar of je scherp hebt wat je agent doet, wat 'ie mag, en hoe je weet dat 'ie werkt. In mijn werk als AI-consultant bij Digital Impact en bij UnicornAI gebruik ik hiervoor een vast raamwerk van negen dimensies. Elke dimensie wordt een concreet bestand, en pas als alle negen zijn ingevuld mag een agent live. In deze tutorial bouw je zo je eigen agent-specificatie op, dimensie voor dimensie.
De negen dimensies van een werkende AI-agent zijn job, inputs, state, tools, boundaries, failure path, evidence, evaluation en ownership. Ze beantwoorden drie vragen: wat doet je agent, wat mag 'ie, en hoe weet je dat 'ie werkt. Leg elke dimensie vast in een eigen bestand en zet de agent pas live als alle negen ingevuld zijn.
De eerste drie dimensies bepalen wat je agent doet. De volgende drie wat 'ie mag. De laatste drie hoe je weet dat 'ie werkt. Hieronder loop je ze langs, met per dimensie de keuze die je maakt en waar je die vastlegt. Daarna werk ik een complete agent voor je uit.
Wat doet je agent precies?
De eerste drie dimensies leggen vast welke taak je agent heeft, waarmee 'ie werkt en wat 'ie onthoudt.
1. Job. De job is de exacte workflow waar je agent verantwoordelijk voor is. Niet "klantenservice verbeteren", maar "retourverzoeken classificeren en naar de juiste afdeling sturen". Hoe smaller de opdracht, hoe betrouwbaarder de agent. Anthropic maakt in zijn richtlijn Building effective agents een belangrijk onderscheid: een workflow volgt vaste stappen, een agent bepaalt zelf zijn route. Begin simpel. Vaak is een goede prompt of een vaste workflow al genoeg en heb je helemaal geen autonome agent nodig. Een agent ruil je in voor flexibiliteit, tegen hogere kosten en meer kans op fouten. Een agent die alles tegelijk probeert, raakt overbelast en wordt onmogelijk te debuggen. Splits dan liever in specialisten, zoals ik deed toen ik met vijf agents tegelijk aan een project werkte.
2. Inputs. De inputs zijn wat je agent binnenkrijgt, vanwaar en in welk formaat. Krijgt 'ie een e-mail, een API-aanroep, een databaserij of vrije tekst uit een chat? Gestructureerde data is betrouwbaarder en goedkoper dan vrije tekst, die je eerst moet uitlezen en controleren. Werkt je agent met kennis uit documenten, dan haal je die op het moment zelf op en geef je ze als context mee, wat hallucinaties terugdringt. De valkuil hier is simpel maar dodelijk: verkeerde of ongecontroleerde input erin betekent een zelfverzekerd fout antwoord eruit. Valideer binnenkomende data daarom tegen een vast schema voordat je agent ermee aan de slag gaat.
3. State. State is wat je agent onthoudt binnen een run, en wat 'ie absoluut niet meeneemt naar de volgende. Geheugen binnen een sessie, zoals de lopende conversatie en tussenresultaten, is handig. Maar het contextvenster is een eindig aandachtsbudget: hoe voller het raakt, hoe slechter een model let op wat belangrijk is, en dat begint al ruim voordat het venster vol zit. Vat oude stappen samen of schrijf ze weg naar een extern geheugen in plaats van alles mee te slepen. Sommige agents leren juist bewust van eerdere runs, een aanpak die ik beschreef in hoe een AI-agent leert van zijn eigen werk. Let vooral op wat NIET vooruit mag: een klantprofiel dat per ongeluk blijft hangen tussen twee verschillende klanten is een datalek.
Wat mag je agent wel en niet?
De volgende drie dimensies bepalen wat je agent mag aanraken en wat er gebeurt als het misgaat. Hier lopen de meeste agents stuk.
4. Tools. Tools zijn wat je agent mag lezen, schrijven, aanroepen en uitvoeren. Een agent zonder tools is een chatbot, een agent met te veel tools is een risico. Werk met een allowlist: precies de tools die de baan vereist en geen enkele meer. Anthropic omschrijft tools als een contract tussen je deterministische systemen en een niet-deterministische agent, en adviseert om tools samen te voegen, heldere namen te geven en betekenisvolle antwoorden terug te sturen in plaats van cryptische codes. Geef je agent toegang tot externe diensten via MCP, de standaardstekker die werkt als een USB-C voor AI. We legden eerder uit wat MCP precies is en waarom het de stekker van je agent is. Eén ding hoort nooit in de tool-laag thuis: zet inloggegevens en API-sleutels nooit in de bestanden van je agent zelf, maar bewaar ze apart.
5. Boundaries. Boundaries leggen vast wat automatisch mag, wat goedkeuring vereist en wat verboden is. Werk met een stoplicht. Groen: informatie opzoeken, een samenvatting maken, lokaal iets wegschrijven, dat mag automatisch. Oranje: een mail naar een klant sturen of iets in het CRM wijzigen, dat laat je eerst door een mens goedkeuren. Rood: financiële toezeggingen doen of persoonsgegevens delen, dat is verboden. Bouw daarbij guardrails die elke in- en uitvoer controleren voordat die de gebruiker bereikt, en validators die de output toetsen voordat er ook maar iets externs gebeurt. Werk je met systemen die mensen raken, zoals werving of kredietbeoordeling, dan is dit ook de plek waar je je verplichtingen onder de AI Act afdwingt.
6. Failure path. Het failure path is wat je agent doet als 'ie onzeker is, data mist of een fout maakt. Schrijf dat van tevoren op. Onzeker? Vraag het de mens. Data mist? Probeer opnieuw of val terug op een alternatief. Geblokkeerd? Escaleer. Fout? Draai de actie terug en log wat er gebeurde. Bouw geen oneindige herhaal-lussen: een mislukte inlog of een geweigerde permissie lost zich niet op door het nog tien keer te proberen, dus stop daar meteen. Geef dit faalplan bij elke run aan je agent mee. Een agent zonder failure path doet bij twijfel gewoon iets, en dat is het ergste wat 'ie kan doen.
Hoe weet je of je agent werkt?
De laatste drie dimensies maken het werk van je agent controleerbaar: het bewijs van wat 'ie deed, de meting of 'ie verbetert, en wie 'm onderhoudt. Ze worden het vaakst vergeten, en ze bepalen of je agent over een half jaar nog draait.
7. Evidence. Evidence is het spoor dat bewijst waarom je agent deed wat 'ie deed. Je wilt kunnen zien wat 'ie deed én waarom, met de bron erbij en reproduceerbaar. Log elke stap: welke tool werd aangeroepen, welke data kwam terug, welke beslissing volgde. Als je achteraf niet kunt nagaan waarom een agent een verkeerde mail stuurde, kun je het ook niet voorkomen. Dit spoor is meteen je basis voor compliance en voor het debuggen als er iets misgaat.
8. Evaluation. Evaluation is hoe je meet of de workflow echt verbetert en niet alleen drukte produceert. Kijk naar twee dingen: het resultaat (is de taak gelukt?) en het traject (hoe kwam de agent daar?). Het resultaat vertelt of de taak af is, het traject vertelt waarom 'ie faalde, en je hebt allebei nodig: een goed antwoord via een toevalstreffer is geen werkende agent. Meet uitkomsten die ertoe doen, zoals klanttevredenheid, oplostijd en foutpercentage, niet "het aantal runs". Tweehonderd runs per dag zegt niets als de helft fout is. Omdat dezelfde vraag twee keer een ander antwoord kan geven, draai je elke testtaak drie tot vijf keer en kijk je naar het gemiddelde én het slechtste geval. Een grotere AI als beoordelaar inzetten kan, mits je die ijkt tegen een handvol menselijke beoordelingen.
9. Ownership. Ownership is wie de agent reviewt, onderhoudt en fixt als 'ie breekt. Een agent zonder eigenaar is een agent die rot. Let vooral op modeldrift: elke modelupdate kan het gedrag van je agent verschuiven, ook een verbetering. Toen Anthropic vandaag Claude Opus 4.8 uitbracht, veranderde het gedrag ten opzichte van 4.7, en een agent die je zorgvuldig op het oude model had afgesteld, gedraagt zich daarna net iets anders. Houd daarom bij welke prompt-versie en welk model je agent draait, en review periodiek of 'ie nog doet wat 'ie moet doen. Een agent is geen project dat af is. Het is een collega die aansturing nodig heeft.
Leg elke dimensie vast in een bestand
Elke dimensie wordt een concreet bestand, zodat een agent geen vaag idee in iemands hoofd is maar een map die je kunt lezen, reviewen en versioneren. Een nieuwe agent toevoegen is dan geen software-project meer, maar een mapje met een paar markdown- en YAML-bestanden die je aanpast en opnieuw laat inlezen.
mijn-agent/ persona.md # Job: rol, taak en toon van de agent triggers.yaml # Inputs: welke triggers, welke bronnen, welk formaat tools.yaml # Tools: de allowlist van wat 'ie mag aanroepen boundaries.yaml # Boundaries: groen / oranje / rood per actie failure-path.yaml # Failure path: wat te doen bij twijfel of fout evaluation.yaml # Evaluation: welke metrics je meet ownership.yaml # Ownership: wie reviewt, onderhoudt en fixt knowledge/ # Domein-kennis die de agent als context leest skills/ # Herbruikbare werkwijzes voor deze rol
State en evidence leg je meestal niet per agent vast maar centraal, omdat ze over al je runs heen lopen: het geheugen en het audit-spoor deel je tussen agents. De rest staat per agent in zijn eigen map. Verander je een bestand, dan pakt de volgende run automatisch de nieuwe versie op. Zo wordt "een agent specificeren" iets concreets in plaats van een vaag gesprek.
Hoe ziet een ingevulde dimensie er echt uit?
Hier moet ik eerlijk zijn: een echte agent-specificatie is niet kort. Elke dimensie groeit uit tot een eigen document, vaak een paar honderd woorden, de een langer dan de ander. De korte regels uit het vorige kopje zijn de kapstok, niet de inhoud. Om te laten zien wat "ingevuld" werkelijk betekent, werk ik er één volledig uit voor de retour-agent: de boundaries, de dimensie waar de meeste agents ontsporen.
Het gaat hier niet om één regel "geen geld terugstorten", maar om een lijst die elke situatie afdekt die de agent kan tegenkomen, met per geval de reden erbij. Zo'n boundaries-document begint ongeveer zo:
# boundaries.yaml (Boundaries) - uittreksel groen (automatisch toegestaan): - retour classificeren op reden (defect, niet bevallen, verkeerd geleverd) - ordergegevens opzoeken in het ordersysteem (alleen-lezen) - een interne samenvatting schrijven en een ticket aanmaken - een standaard retourlabel genereren binnen de retourtermijn oranje (eerst akkoord van een mens): - elke e-mail naar de klant # klantcommunicatie is merkrisico - een retour buiten de standaardtermijn accepteren - een retour koppelen aan een andere order dan op het label staat rood (verboden, nooit automatisch): - geld terugstorten of een bedrag toezeggen # financieel en juridisch - coulance beloven (gratis product, korting, cadeaubon) - persoonsgegevens buiten het ticket delen - een klant beschuldigen van fraude
En dan ben je er nog niet, want de randgevallen bepalen of je agent te vertrouwen is. Wat doet 'ie bij een boze klant? Niet sussen of coulance beloven, maar het ticket markeren als emotioneel en doorzetten naar een mens. Wat bij een retour net buiten de termijn? Niet zelf beslissen, maar voorleggen met het beleid erbij. Wat bij een vermoeden van fraude, zoals een derde retour van hetzelfde artikel binnen een maand? Markeren voor controle, nooit de klant beschuldigen. En omdat de agent klantgegevens verwerkt, leg je hier ook vast welke persoonsgegevens 'ie wel en niet in een ticket mag zetten, met de AVG en de AI Act als kader. Elke regel krijgt bovendien een validator die de output controleert voordat er iets de deur uitgaat.
Dit is één dimensie, en 'ie loopt al snel naar een paar honderd woorden. De andere acht zijn net zo uitgewerkt: de job beschrijft precies welke retourcategorieën bestaan en hoe je twijfelgevallen weegt, het failure path dekt tientallen "wat als"-situaties af, en evaluation legt vast hoe je elke week meet of de classificatie nog klopt. Bij elkaar is de specificatie van één serieuze agent al gauw een paar duizend woorden. Dat klinkt als veel, maar die diepte is precies het verschil tussen een agent die plausibel klinkt en een agent die je je klanten durft te laten zien. De korte regels van zojuist zijn waar je begint. Dit niveau is waar je eindigt voordat 'ie live mag.
De activatie-regel die alles bij elkaar houdt
Zet een agent pas live als alle negen vakken ingevuld zijn. Dit is de regel die het verschil maakt tussen een demo en een productie-agent. Boundaries leeg betekent een agent die ongecontroleerd kan handelen. Failure path leeg betekent een agent die bij de eerste hapering vastloopt. Evaluation leeg betekent een agent die blind draait, want je weet niet of 'ie goed werkt. Ownership leeg betekent dat niemand 'm fixt als 'ie breekt. Maak er een harde checklist van: negen vakken vol, of de agent blijft een schets. Geen uitzonderingen. Die discipline klinkt streng, maar het is precies wat een experiment dat indruk maakt in de demo onderscheidt van iets waar je je bedrijf op durft te laten draaien.
Waar bouw je je agent?
Je bouwt een agent zonder code of met code, en dit raamwerk werkt in beide. Zonder code stel je een agent samen via de interface van platforms als ChatGPT Agents, Claude Projects of Gemini Gems: je beschrijft in gewoon Nederlands wat 'ie moet doen, voegt kennis toe en koppelt tools. Geen programmeerkennis nodig, en voor de meeste mkb-workflows is dit genoeg. Wil je volledige controle over je infrastructuur en data, dan gebruik je een SDK zoals de Claude Agent SDK of LangGraph. In beide gevallen blijven de negen dimensies je checklist. De tool bepaalt hoe je bouwt, het raamwerk bepaalt of het werkt. Wil je gewoon snel ervaren hoe het voelt voordat je dit allemaal invult? Begin dan met de tutorial waarin je in een middag je eerste AI-agent bouwt, en pak dit raamwerk erbij zodra je het serieus inzet.
Veelgestelde vragen
Wat zijn de 9 dimensies van een AI-agent?
De negen dimensies zijn job, inputs, state, tools, boundaries, failure path, evidence, evaluation en ownership. Samen beantwoorden ze wat je agent doet, wat 'ie mag en hoe je weet dat 'ie werkt. Je legt elke dimensie vast voordat je de agent live zet.
Wat is het verschil tussen een workflow en een agent?
Een workflow volgt vaste, voorgeprogrammeerde stappen. Een agent bepaalt zelf welke stappen 'ie neemt en welke tools 'ie gebruikt. Een agent is flexibeler, maar kost meer en maakt sneller fouten, dus gebruik 'm alleen als een vaste workflow niet volstaat.
Wanneer mag een AI-agent live?
Pas als alle negen dimensies zijn ingevuld. Een lege boundaries-dimensie betekent een agent die ongecontroleerd handelt, een lege evaluation betekent dat je niet weet of 'ie werkt, en een lege ownership betekent dat niemand 'm fixt bij een storing. Maak er een harde checklist van.
Heb je programmeerkennis nodig om een AI-agent te bouwen?
Nee, niet meer. Met no-code platforms als ChatGPT Agents, Claude Projects en Gemini Gems bouw je een agent via de interface in gewoon Nederlands. Programmeerkennis heb je alleen nodig als je volledige controle over infrastructuur en data wilt, via een SDK.
Hoe voorkom je dat een AI-agent ongewenste acties uitvoert?
Via de boundaries-dimensie. Bepaal per actie of die automatisch mag, goedkeuring vereist of verboden is, en laat hoog-risico-acties zoals mails versturen of data wijzigen altijd eerst door een mens goedkeuren. Validators controleren de output voordat er iets extern gebeurt.
Welke dimensie sla jij over?
De meeste agents die stranden, stranden niet op het model. Ze stranden op een dimensie die niemand had ingevuld. Pak je eigen agent-idee erbij, loop de negen vragen langs en vul ze in als concrete bestanden. De dimensie waar je het langst over moet nadenken, is precies de dimensie die je agent anders de das om zou doen. Welke sla jij nu over?
