Context engineering voor AI-agents: waarom je agent faalt in productie

De meeste AI-agents die falen in een productieomgeving, falen niet omdat het model niet slim genoeg was. Ze falen omdat niemand heeft ontworpen wat het model mocht zien. Dat werk heeft een naam: context engineering voor AI-agents. Het bepaalt of je een demo krijgt of een systeem dat je kunt toevertrouwen aan echte klanten.

Dat onderscheid is belangrijk, omdat het bepaalt wat je moet repareren. Wanneer een agent verkeerde antwoorden begint te geven, is de gebruikelijke reactie om over te stappen op een nieuwer model, een framework toe te voegen of de systeemprompt voor de vijfde keer te herschrijven. Die acties helpen zelden, en teams verspillen een kwartaal om daarachter te komen. De werkelijke fout ligt bijna altijd stroomopwaarts: de agent kreeg een beleidsdocument dat in tegenspraak is met een ander beleidsdocument, een databaseveld dat drie verschillende dingen betekent, afhankelijk van welk team het heeft ingevuld, en geen manier om te bepalen welke van toepassing is op de vraag die voorligt.

Het doelbewust ontwerpen van die input, als een systeem in plaats van een prompt, is nu het grootste en minst begrepen onderdeel van het bouwen van een agent die bestand is tegen de praktijk.

Dit artikel is geschreven voor oprichters, CTO's en operationeel leiders die al een agent in productie hebben of een pilot die is vastgelopen, en die moeten beslissen wat ze als volgende gaan repareren. Het gaat ervan uit dat je de demofase voorbij bent. Als je nog aan het beslissen bent of je überhaupt een LLM wilt proberen, dan gaat dit dieper dan je op dit moment nodig hebt.

Je krijgt een werkbare definitie van context engineering voor AI-agents, de 5 lagen waaruit de context van een agent bestaat, de 6 manieren waarop context kapotgaat zodra echte gebruikers arriveren, wat dit werk daadwerkelijk kost en waar het budget naartoe gaat, hoe je dit specificeert in een project zodat een leverancier hierop kan worden aangesproken, en wie er na de lancering verantwoordelijk voor moet zijn.

‍

Belangrijkste punten

• Context engineering is de praktijk van het bepalen welke informatie, tools en geschiedenis een AI-agent bij elke stap ontvangt, en het bouwen van de systemen die dat pakket betrouwbaar samenstellen.

• Prompt engineering vraagt hoe een verzoek moet worden geformuleerd. Context engineering vraagt wat het model moet weten, waar het vandaan komt en wat er moet worden weggelaten.

• Modelupgrades repareren zelden een falende agent, omdat de beperking meestal ligt bij de kwaliteit van de opgevraagde gegevens, tegenstrijdige brongegevens of ontbrekende status, en niet bij het redeneervermogen.

• Meer context is niet beter. De nauwkeurigheid van een agent neemt af naarmate het contextvenster voller raakt, dus relevantie is belangrijker dan volume.

• De context van een agent bestaat uit 5 lagen: instructies, opgehaalde kennis, tools, geheugen en status, en vangrails. De meeste productiefouten zijn terug te voeren op een van deze lagen.

• Bij onze builds gaat ongeveer 60 tot 70 procent van de inspanning naar contextwerk, niet naar model- of interface-werk. Budgetteer hiernaar.

• Context vervalt. Beleid verandert, schema's veranderen, producten worden gelanceerd. Zonder een eigenaar en een evaluatiesuite wordt een nauwkeurige agent stilletjes een onnauwkeurige.

‍

Wat is context engineering voor AI-agents?

Context engineering is de praktijk van het bepalen welke informatie, tools en gespreksgeschiedenis een AI-agent bij elke stap van een taak ontvangt, en het bouwen van de systemen die dat pakket elke keer correct samenstellen. Het omvat retrieval, datamodellering, toolontwerp, geheugen en de regels voor wat er wordt uitgesloten.

De eenvoudigste manier om het verschil met prompt engineering te zien, is door te kijken naar wat elk van beide vraagt. Prompt engineering vraagt hoe een verzoek moet worden geformuleerd. Context engineering vraagt wat het model nodig heeft om correct te antwoorden, waar die informatie vandaan komt, hoe actueel deze is, hoe deze is geformatteerd en wat er buiten beschouwing moet worden gelaten. Het een is een schrijftaak. Het ander is een engineering- en dataprobleem, en dat verdwijnt niet wanneer er een beter model uitkomt.

Het gaat ook in tegen een instinct dat de meeste teams hebben, namelijk dat meer context betere antwoorden oplevert. Dat is niet zo. Het engineeringteam van Anthropic beschrijft context als een eindige hulpbron met afnemende meeropbrengst, waarbij de prestaties van het model afnemen naarmate het aantal tokens groeit, een effect dat vaak context-rot wordt genoemd. Hun richtlijn in effectieve context-engineering voor AI-agents is om het contextvenster te behandelen als een aandachtbudget en dit te besteden aan de kleinste set tokens met een hoge informatiewaarde die de klus klaart. Een volledige kennisbank in elke aanroep dumpen is geen grondigheid. Het is ruis, en het kost je geld bij elk verzoek.

Het doel is dus niet om de agent alles te geven. Het doel is om hem het juiste te geven, op het juiste moment, in een vorm waar hij iets mee kan.

‍

Waarom een beter model een falende agent niet zal redden

Neem een agent voor terugbetalingen; dat is het verzoek dat we het vaakst zien en het foutpatroon is altijd hetzelfde.

In de demo ziet het er uitstekend uit. Iemand verzamelt 20 nette tickets, schrijft een strakke prompt, koppelt het model, en de agent lost er 19 correct op. Iedereen is het erover eens dat het klaar is. Dan gaat het live in de echte wachtrij.

Nu komt hij een document van 90 pagina's met voorwaarden tegen, een apart restitutiebeleid dat marketing vorig jaar heeft gepubliceerd, en een derde set regels die de supportmanager in een spreadsheet bijhoudt omdat het officiële beleid nooit is bijgewerkt voor de nieuwe abonnementsvormen. Alle drie zijn technisch gezien van kracht. Twee ervan spreken elkaar tegen. Het CRM heeft een statusveld dat engineering gebruikt voor de betalingsstatus en dat support gebruikt voor de casusstatus. Niemand heeft dat opgeschreven, omdat iedereen het al wist.

De agent begint terugbetalingen goed te keuren die hij zou moeten afwijzen, en wijst verzoeken af die hij zou moeten goedkeuren. Het eerste instinct van het team is om over te stappen op een krachtiger model. Het krachtigere model produceert vloeiender dezelfde foute antwoorden, omdat geen enkele hoeveelheid redeneervermogen het vertelt welk van de drie restitutiebeleidsregels geldt voor een klant die in maart halverwege de cyclus is geüpgraded. Dat is geen denkprobleem. Het is ontbrekende input.

Dit is waarom datagereedheid, en niet de keuze voor een model, bepaalt of een agent-project overleeft. Gartner heeft voorspeld dat organisaties tot 2026 60 procent van de AI-projecten die niet worden ondersteund door AI-ready data zullen staken, in hun analyse van hoe een gebrek aan AI-ready data AI-projecten in gevaar brengt. Lees dat cijfer zorgvuldig. De projecten falen niet op het niveau van het model. Ze falen omdat het materiaal waar het model mee moest werken nooit geschikt was voor de taak.

De ongemakkelijke versie hiervan, en de versie waar je naar moet handelen: een agent is een zeer snelle lezer van je interne informatie. Als die informatie tegenstrijdig, verouderd of dubbelzinnig is, strijkt de agent dat niet glad. Hij vergroot de chaos uit en past deze op machinesnelheid toe op elke klant.

‍

De 5 lagen van de context van een agent

De context van een agent is niet één ding. Het zijn 5 lagen die tijdens runtime worden samengevoegd, en een productiefout is bijna altijd terug te voeren op precies één daarvan. Weten welke laag kapot is, is hoe je stopt met gissen.

1. Instructies

De systeemprompt bepaalt de rol van de agent, zijn grenzen en hoe hij zich moet gedragen als hij het niet zeker weet. De veelgemaakte fout is om dit op het verkeerde niveau in te steken. Te vaag en de agent verzint zijn eigen beleid. Te rigide, met een hardgecodeerde regel voor elk denkbaar geval, en het wordt broos: de eerste situatie waar niemand op had gerekend levert onzin op, en de prompt verandert in een document van 4.000 woorden dat niemand durft te bewerken. Streef naar duidelijke principes plus escalatieregels, en laat retrieval de details leveren.

2. Kennis

Dit is het opgehaalde materiaal: documenten, records, beleidsregels, eerdere casussen. De ontwerpbeslissing die ertoe doet, is wanneer dit wordt opgehaald. Alles vooraf laden is duur en verwatert de aandacht. Net op tijd ophalen, op het moment dat de agent het nodig heeft, houdt het venster schoon en maakt het gedrag van de agent veel gemakkelijker te debuggen, omdat je precies kunt zien waar hij om vroeg. Deze laag is ook waar de bronkwaliteit zichtbaar wordt. Retrieval kan een tegenstrijdigheid die in je documenten staat niet oplossen.

3. Tools

Tools zijn acties die de agent kan aanroepen: een zoekopdracht in je kennisbank, een CRM-opzoeking, een prijsberekening of een schrijfactie. Twee factoren bepalen of ze nuttig zijn. Ten eerste: zijn de beschrijvingen van de tools eenduidig genoeg zodat de agent onder druk de juiste kiest? Ten tweede, en dat wordt vaak over het hoofd gezien: de vorm van de output. Een tool die een onbewerkte API-respons van 12.000 tokens teruggeeft, verbruikt het grootste deel van het aandachtbudget aan velden die de agent nooit zal gebruiken. Tool-outputs moeten doelbewust worden ingekort en gestructureerd, precies zoals je een interne API zou ontwerpen.

4. Geheugen en status

Voor taken met meerdere stappen is persistentie nodig: wat is er al geprobeerd, wat heeft de gebruiker drie stappen geleden bevestigd, welke records zijn er aangepast? Zonder dit herhalen agents voltooide acties of verliezen ze een beperking die de gebruiker aan het begin heeft opgegeven. De praktische patronen hiervoor zijn 'compaction', waarbij de agent de voortgang samenvat en doorgaat in een nieuw venster, en gestructureerde notities die buiten het contextvenster worden bewaard en op verzoek worden uitgelezen.

5. Guardrails

De laatste laag betreft wat nooit in de context mag komen en wat de agent er nooit mee mag doen. Dit omvat toegangsbeheer zodat de agent alleen ophaalt wat de gebruiker mag zien, het anonimiseren van persoonsgegevens voordat ze het model bereiken, en harde stops voor onomkeerbare acties. Onder de EU AI-verordening brengt deze laag ook je documentatieverplichtingen met zich mee, dus behandel dit vanaf dag één als een ontwerpvereiste in plaats van als iets dat je vlak voor de lancering nog even toevoegt.

‍

6 manieren waarop context faalt zodra echte gebruikers het systeem gebruiken

Dit zijn de foutmodi die we herhaaldelijk zien bij agents in productie. Het is de moeite waard om ze te onthouden, omdat ze elk een andere oplossing vereisen en ze gemakkelijk met elkaar verward kunnen worden.

• Overbelasting. Het venster zit vol met marginaal relevante informatie, waardoor de nauwkeurigheid daalt, ook al ontbreekt er technisch gezien niets. Los dit op door de retrieval aan te scherpen, niet door meer instructies toe te voegen.

• Verouderde retrieval. De agent citeert vol vertrouwen een beleid dat acht maanden geleden is vervangen, omdat de index ooit is opgebouwd en nooit is ververst.

• Tegenstrijdige bronnen. Twee documenten spreken elkaar tegen en niets vertelt de agent welke de juiste is. Dit is een probleem van contentbeheer in een AI-jasje.

• Te uitgebreide tool-output. Een enkele, breedsprakige API-respons verdringt al het andere in het venster, inclusief de eigenlijke vraag van de gebruiker.

• Verloren status. Bij een langdurige taak vergeet de agent een eerder ingestelde beperking of voert een stap opnieuw uit die al voltooid was.

• Lekkage van rechten. De agent toont in een antwoord informatie die de vragende persoon nooit mocht inzien. Dit is een beveiligingsincident, geen kwaliteitsprobleem.

Terug naar de refund-agent. Het werkelijke probleem was een combinatie van drie factoren: tegenstrijdige bronnen omdat niemand het oude beleid had ingetrokken, verouderde retrieval omdat de index dateerde van vóór de nieuwe abonnementsvormen, en een onduidelijk schema waardoor het CRM-statusveld onleesbaar was voor iedereen zonder specifieke voorkennis. Het oplossen hiervan vereiste geen enkele wijziging aan het model. Het vergde het intrekken van één beleidsdocument, het toevoegen van een filter op ingangsdatum aan de retrieval zodat de agent alleen regels zag die geldig waren op de transactiedatum, en het hernoemen van twee velden. De nauwkeurigheid steeg van ongeveer twee derde naar ruim negentig procent, met hetzelfde model dat voorheen de schuld kreeg van het falen.

Dat is de kern van het meeste werk op dit gebied. Het is niet glamoureus, het lijkt op het opschonen van data en documentatie, en het is precies waar het resultaat vandaan komt.

Als je dit soort build aan het verkennen bent, dan helpt onze AI-blueprint voor SaaS-founders je door het structureren van een AI-functie zodat deze standhoudt in productie, inclusief de datavragen die je moet beantwoorden voordat iemand een prompt schrijft. Het is gratis en het lezen duurt ongeveer 20 minuten.

‍

Context engineering versus prompt engineering

Prompt engineering is niet achterhaald, en wie beweert van wel, heeft meestal nog nooit een agent opgeleverd. Het is een echte vaardigheid en nog steeds de snelste manier om resultaat te boeken bij een afgebakende taak. Wat wel is veranderd, is het aandeel ervan in het totale probleem. Zodra een agent meerstapsopdrachten uitvoert in live systemen, is de formulering slechts een klein onderdeel van het succes; de rest zit in de techniek erachter.

‍

‍

De praktische test om te bepalen waar het probleem ligt: als hetzelfde verzoek werkt wanneer iemand handmatig het juiste document invoert, maar faalt wanneer de agent het zelfstandig doet, dan is je prompt in orde en je context-pipeline niet. We voeren die check vroeg uit bij bijna elk project, omdat het een uur kost en een discussie beslecht waar teams anders weken over doen.

‍

Waar het budget echt naartoe gaat

De eerste verrassing voor de meeste kopers is hoe weinig van het budget voor een agent naar het model gaat. Inference is een reële operationele kostenpost, maar als aandeel van het project is het meestal marginaal vergeleken met de engineering eromheen. Het werk dat het budget opslokt, is de contextlaag.

Bij de agent-projecten die wij hebben opgeleverd, verdeelt de inspanning zich doorgaans ongeveer zo. Ongeveer 30 procent gaat naar discovery en datavoorbereiding: in kaart brengen waar de waarheid zich bevindt, tegenstrijdigheden opsporen en bepalen wat als bron van waarheid dient. Nog eens 30 procent gaat naar retrieval en tool-ontwerp; de code die tijdens runtime de context samenstelt. Ongeveer 20 procent gaat naar evaluatie en guardrails, oftewel de testsuite die bewijst dat de agent vaak genoeg gelijk heeft om hem te vertrouwen, en de controles die voorkomen dat hij schade aanricht als hij het mis heeft. De resterende 20 procent dekt de integratie en de interface die mensen daadwerkelijk gebruiken.

Die verhoudingen verschuiven per project. Een agent die werkt met een schoon, goed beheerd datawarehouse vereist minder discovery. Een agent die moet werken met 6 verouderde systemen en een gedeelde schijf vereist juist heel veel discovery. Dat is precies het scenario waarbij een vaste prijsopgave die wordt gegeven voordat iemand naar de data heeft gekeken, je zorgen zou moeten baren.

De nuttige conclusie: als een voorstel voor een AI-agent vooral draait om modelselectie, prompt-design en UI, met databewerking als een kleine post onderaan, dan is het geprijsd voor de demo en niet voor productie. Vraag wat er in week 6 gebeurt als de eerste beleidstegenstrijdigheid opduikt, en kijk of er een plan ligt of dat er een wijzigingsverzoek volgt.

‍

Hoe je context engineering opneemt in een AI-agentproject

Je hoeft de retrieval-architectuur niet zelf te ontwerpen. Je moet de contextlaag wel expliciet opnemen in de scope, zodat het een concrete oplevering wordt in plaats van een discovery-fase waar niemand budget voor heeft uitgetrokken. Dit zijn de 7 vragen die je op papier moet hebben voordat het werk begint.

• Welke bronnen zijn leidend voor elke beslissing die de agent neemt, en wie keurt die lijst goed?

• Hoe weet de agent of een document actueel is, en wat gebeurt er als beleid wordt vervangen?

• Wat is de retrieval-strategie en hoe wordt de nauwkeurigheid daarvan gemeten voordat de agent live gaat?

• Wat levert elke tool op, en wie is verantwoordelijk voor het beknopt en gestructureerd houden van die antwoorden?

• Wat wordt meegenomen tussen stappen en sessies, en wat wordt bewust vergeten?

• Wat mag de agent nooit zien en hoe wordt dit per gebruiker in plaats van per systeem afgedwongen?

• Wat is de evaluatiesuite, welke nauwkeurigheidsdrempel bepaalt of de lancering doorgaat en hoe vaak wordt deze na de lancering uitgevoerd?

Het laatste punt is belangrijker dan het lijkt. Een agent zonder evaluatiesuite kan niet veilig worden verbeterd, omdat je anders niet weet of de oplossing van vandaag het gedrag van vorige maand heeft verstoord. Wij beschouwen de evaluatieset als een op zichzelf staand product, opgebouwd uit praktijkgevallen, inclusief de gevallen die fout gingen. Voor een uitgebreidere versie hiervan, zie onze gids over AI-agent-evaluatie en bepalen wanneer deze klaar is voor productie waarin wordt uitgelegd hoe je er een bouwt en welke drempelwaarde verdedigbaar is.

‍

Wie is na de lancering verantwoordelijk voor de context

Context veroudert, en dit is het onderdeel waar bijna niemand budget voor vrijmaakt. Je prijzen veranderen. Een beleid wordt herschreven. Een product wordt gelanceerd met voorwaarden die de agent nog nooit heeft gezien. Iemand hernoemt een veld in het CRM tijdens een niet-gerelateerde migratie. Geen van deze gebeurtenissen heeft invloed op de code van de agent, maar ze veranderen allemaal de antwoorden.

Een agent die bij de lancering voor 95 procent nauwkeurig was en die niemand onderhoudt, faalt niet op een opvallende manier. De prestaties nemen stilletjes af, en je komt er pas drie maanden later achter via een klacht van een klant. Dat is erger dan een storing, omdat er geen moment was waarop er iets overduidelijk kapotging.

Wijs daarom een eigenaar aan. Iemand moet verantwoordelijk zijn voor de informatie van de agent, zoals een data-eigenaar verantwoordelijk is voor een tabel in een database. In de praktijk betekent dit een aangewezen persoon, een beoordelingsfrequentie die gekoppeld is aan gebeurtenissen die de context daadwerkelijk veranderen (zoals beleidswijzigingen en productlanceringen), en een evaluatiesuite die automatisch wordt uitgevoerd wanneer een brondocument of schema wijzigt. Dit is een bescheiden, doorlopende inspanning, meestal een paar uur per maand, en het is het verschil tussen een agent die in waarde toeneemt en een agent die in het tweede jaar een blok aan je been wordt.

‍

Hoe Codelevate context engineering aanpakt

We beginnen elk agent-traject met de data, niet met het model. Voordat er iets wordt gebouwd, brengen we de beslissingen in kaart die de agent moet nemen, herleiden we elke beslissing naar de bron die deze zou moeten sturen en leggen we tegenstrijdigheden bloot. Die eerste ronde is vaak ongemakkelijk voor de klant, omdat het procesonduidelijkheden blootlegt die al bestonden vóór de interesse in AI, en het is steevast de week van het project die de meeste waarde oplevert.

Van daaruit bouwen we de context-pipeline als echte software: versiebeheer bij het ophalen van data met inachtneming van ingangsdata, tools die strakke, gestructureerde antwoorden geven, expliciete status en toegangsrechten die worden afgedwongen bij het ophalen in plaats van dat dit aan de prompt wordt overgelaten. Elke build wordt geleverd met een evaluatiesuite op basis van praktijkgevallen en een nauwkeurigheidsdrempel die vóór de lancering is afgesproken, zodat de beslissing om live te gaan gebaseerd is op metingen in plaats van op een onderbuikgevoel.

We wijzen ook een behoorlijk aantal verzoeken voor agents af, meestal omdat het onderliggende proces niet goed genoeg gedefinieerd is om door welk systeem dan ook betrouwbaar te worden geautomatiseerd. Een klant dat als eerste vertellen is goedkoper voor hen dan er in de vierde maand achter komen. Als je wilt dat die beoordeling grondig wordt uitgevoerd voor jouw specifieke use case, dan is dat waar onze AI-ontwikkeldiensten om draaien.

‍

‍

De kernboodschap

Als je agent niet naar behoren werkt, ligt het probleem waarschijnlijk niet bij het model. Kijk eens naar wat het model krijgt aangeleverd: komen de bronnen overeen, zijn ze actueel, leveren de tools bruikbare resultaten op en wordt er onthouden wat er drie stappen geleden is gebeurd? Daar ligt de oplossing, en daar ligt ook je duurzame voorsprong. Een concurrent kan morgen overstappen op hetzelfde model, maar kan niet zomaar jaren aan schone, beheerde en goed gestructureerde context kopiëren die de basis vormt van jouw agent.

De essentiële verschuiving is om een agent niet langer te zien als een slim stukje software, maar als een systeem dat draait op jouw informatie. Zodra je het zo bekijkt, wordt de routekaart logisch en het budget realistisch.

Als je een praktisch startpunt zoekt, is de AI-blauwdruk voor SaaS-oprichters een gratis download die beschrijft hoe je een AI-functie van begin tot eind afbakent, bouwt en valideert. Het sluit naadloos aan op alles wat hierboven staat.

En heb je al een agent die niet goed presteert en wil je een second opinion over de oorzaak? Boek een gratis gesprek met ons team. Neem de voorbeelden mee waar het misgaat. Wij vertellen je eerlijk of het een probleem is met de context, het proces, of dat het eigenlijk helemaal geen agent had moeten zijn.