Hoe schrijf je systeem-prompts voor AI-agenten die niet falen in productie

Inhoudsopgave

Bijgewerkt juli 2026.

TL;DR: Een productie systeem-prompt heeft vijf lagen: identiteit (wie de agent is en wat hij niet kan doen), context (wat hij weet over de omgeving), taak (hoe succes er stap voor stap uitziet), uitvoerformaat (de meest onderschatte laag) en randgevallen (wat te doen als invoer faalt). De meeste prompts falen omdat ze lagen 4 en 5 overslaan. Schrijf het uitvoerformaat eerst — het dwingt je precies te zijn over wat je echt wilt.

[Operatorperspectief] Ik beheer meer dan 30 AI-agenten in productie voor mijn consultingmerk en Pickleland, een pickleballfaciliteit in Pflugerville, TX. Ik heb meer systeem-prompts herschreven dan ik er geschreven heb — meestal omdat de eerste versie goed leek te werken in tests en dan stil achteruitging in productie. Dit is wat ik heb geleerd over het schrijven van prompts die stand houden.

Het systeem-prompt probleem dat niemand toegeeft

De meeste systeem-prompts voor agenten worden in ongeveer 20 minuten geschreven, getest met twee of drie voorbeelden en dan nooit meer aangeraakt. Het model gaat live. Een tijdlang werkt het. Dan verandert er iets — de invoer wordt rommelig, het model wordt bijgewerkt, een nieuw randgeval verschijnt — en de agent begint slechte output te produceren. Still. Op schaal.

Het probleem is niet dat de oorspronkelijke prompt slecht was. Het is dat de meeste prompts geschreven worden om het gelukkige pad te demonstreren. Ze zijn ontworpen voor de invoer die je in gedachten had toen je de agent bouwde, niet voor de volledige verdeling van invoer die de agent daadwerkelijk zal zien.

De vijf lagen van een productie systeem-prompt

Ik denk aan elke systeem-prompt die ik schrijf in vijf lagen. Ze hoeven niet in deze volgorde te verschijnen — maar ze moeten allemaal aanwezig zijn.

Laag 1: Identiteit

Identiteit vertelt het model wie het is en wat zijn operationele beperkingen zijn. Niet een rollenspelfiguur — een functionele definitie van wat deze agent doet en niet doet.

Een sterke identiteitslaag beantwoordt drie vragen:

• Waarvoor is deze agent verantwoordelijk?
• Waarvoor is hij expliciet NIET verantwoordelijk (en moet hij escaleren of weigeren)?
• Welke normen handhaaft hij?

Het expliciete buiten-bereik is het deel dat de meeste operators overslaan. Zonder het zal het model proberen nuttig te zijn buiten zijn terrein — en dat is waar het misgaat.

Laag 2: Context

Context is wat de agent weet over zijn omgeving dat niet in het bericht van de gebruiker staat. Dit omvat de huidige datum en tijd (dynamisch injecteren — vertrouw nooit het interne tijdsbesef van het model), relevante toestand van externe systemen en bedrijfsregels die niet voor de hand liggen vanuit de taakomschrijving.

De meeste agenten die ik bekijk zijn contextarm. Neem niets aan. Injecteer het.

Laag 3: Taak

De taaklaag beschrijft wat de agent stap voor stap doet. Niet “klanten helpen” — de werkelijke beslissingsstroom. Schrijf het als een stroomdiagram, niet als een directief. Stroomdiagrammen zijn robuuster omdat ze de behoefte van het model verminderen om te infereren wat je wilt in ambigue gevallen.

Laag 4: Uitvoerformaat

Dit is de meest onderschatte laag, en degene die het meest verantwoordelijk is voor stille fouten.

Als je het uitvoerformaat niet precies specificeert, produceert het model output die correct lijkt voor een menselijke lezer maar inconsistent genoeg is om de downstream verwerking te breken. Schrijf het uitvoerformaat eerst. Voor gestructureerde output specificeer je het exacte schema. Voor proza-output specificeer je structuur, lengte en toonbeperkingen.

Voor hoge-risico agenten gebruik ik de gestructureerde output van Claude met een gedefinieerd JSON-schema.

Laag 5: Randgevallen

De randgevallenlaag beantwoordt: wat doet de agent als de invoer ambigu, onvolledig, in de verkeerde taal, vijandig of duidelijk onjuist is? Geef het model voor elk randgeval een expliciet antwoordpad.

Hoe ik systeem-prompts in de loop van de tijd onderhoud

Een productie systeem-prompt is een levend document:

1. Wekelijkse steekproef. Ik bekijk vijf tot tien willekeurige outputs van elke hoge-risico agent ten opzichte van de verwachte output.
2. Revisie na modelupdate. Elke keer dat de onderliggende modelversie verandert, voer ik de agent uit tegen de volledige gouden set van mijn evaluatiekader.
3. Randgevallenlog. Ik houd een doorlopend log bij van invoer die de agent slecht heeft afgehandeld. Wanneer drie of meer items een patroon delen, voeg ik een expliciete regel toe.
4. Prompt-versiebeheer. Elke significante wijziging krijgt een versiecommentaar.

Veelgestelde vragen

Hoe lang moet een productie systeem-prompt zijn?

Lang genoeg om alle vijf lagen te dekken. Kort genoeg zodat je het in twee minuten kunt lezen en afwijking kunt herkennen. Voor de meeste van mijn agenten is dat 200-600 woorden.

Wanneer moet ik een complexe taak opsplitsen in meerdere agenten in plaats van één lang prompt?

Wanneer de taak twee of meer duidelijk verschillende modi heeft die verschillende context, verschillende uitvoerformaten of verschillende foutafhandeling vereisen. Zie event-gestuurde vs. geplande agenten voor het patroon.

Wat is de meest voorkomende reden waarom een prompt die in tests werkte, faalt in productie?

De testinvoer was niet representatief voor de productieverdeling. Bouw een testset op basis van echt productieverkeer, niet op basis van bedachte invoer.