Waarom een agent een werkwijze nodig heeft

Geschreven op 31 juli 2026. De genoemde modellen zijn inmiddels vervangen, maar de werkafspraken hieronder gelden nog woord voor woord.

Op één dag zag ik mijn lokale agent drie keer overtuigend de mist in gaan. Hij verzon een API die niet bestaat, verzon daarna ook de data, en raadde me ten slotte aan een SSL-certificaat te installeren om een probleem op te lossen dat een ontbrekend aanhalingsteken bleek te zijn. Mijn eerste reactie was dat het model te klein was. Dat bleek niet te kloppen.

Drie fouten, één patroon

De verzonnen skill. Toen ik vroeg een document te uploaden, schreef de agent voor zichzelf een instructiebestand met GET /api/csrf/ en PUT /api/upload/. Geen van beide bestaat. Toen dat een 403 opleverde, redeneerde hij niet terug naar het pad, maar vooruit vanuit de aanname dat het pad klopte, en dan is CSRF een volkomen logische verklaring. Het advies dat volgde was om de beveiliging uit te zetten.

De verzonnen data. Toen ik vroeg om de laatste tien afleveringen die ik had gekeken, kreeg ik een nette tabel met Breaking Bad, Stranger Things en The Crown, compleet met beoordelingen en tijdstempels in keurige blokken van dertig minuten. Nul overlap met de werkelijkheid. Dit is het gevaarlijke soort fout, want je ziet hem niet zonder te controleren.

Het kapotte commando. Een curl-aanroep met vijf queryparameters raakte zijn afsluitende aanhalingsteken kwijt. Bash meldde keurig unexpected EOF. In dezelfde output stond ook de tekst van een beveiligingsscan, en het model klampte zich aan die helft vast en concludeerde dat het netwerk de schuld had.

De oorzaak was werkwijze, niet kennis

Kijk wat er in elk geval nodig was geweest. Hij kende curl prima; hij telde alleen zijn aanhalingstekens niet. Hij had een terminal; hij vroeg mij of een commando bestond in plaats van command -v uit te voeren. Hij had de foutmelding; hij las de verkeerde regel. Geen van deze problemen verdwijnt met meer parameters. Ze verdwijnen met een checklist.

En die was er niet. Het identiteitsbestand van de agent, SOUL.md, bevatte 84 woorden algemene introductie, met als enige werkinstructie: be focused and efficient in your exploration. Dat moedigt precies het verkeerde gedrag aan. Grote commerciële modellen hebben “eerst controleren, dan beweren” erin getraind gekregen. Een lokaal model van veertien miljard parameters niet.

Wat de herschrijving erin zette

Check, don't ask       -> run command -v, don't ask the user
Probe before you build -> read-only call first, code afterwards
Errors are data        -> a 404 is a wrong path, not a wall
Read the actual error   -> the line starting with bash: or curl: is the cause
Never invent data      -> no illustrative rows, ever
Private network        -> scan warnings are for you, not for me

Van 84 woorden naar ruim 900, en geen ervan beschrijft mijn servers. Het zijn werkafspraken en verder niets. Eén detail bleek cruciaal: instructies in een skill werden nooit gelezen, omdat het model die zelf moet gaan opzoeken. Instructies in het geheugenbestand komen bij elke sessie mee. Een perfect geschreven skill die niemand opent, is waardeloos.

Het resultaat, gemeten

Ik bouwde veertig tests tegen mijn eigen draaiende servers, met antwoorden die ik vooraf zelf had gecontroleerd: aantallen series, albums en films, schijfruimte, en vragen die je alleen goed kunt beantwoorden door twee bronnen te combineren. Voor de herschrijving faalde de eenvoudigste al. Daarna scoorden zowel de 14B als de 32B veertig uit veertig.

Dat identieke resultaat is het eigenlijke antwoord. Ik had een groter model gekocht om een probleem op te lossen dat nooit over het model ging. Wat ontbrak, was dat iemand opschreef hoe je werkt, en dat is precies wat een agentframework zou moeten leveren en niet doet.

Twee kanttekeningen moest ik zelf slikken. Vier van mijn vroege “fouten” zaten in mijn tests en niet in het model: het gaf een beter antwoord dan ik verwachtte en kreeg punten aftrek voor mijn eigen nauwe verwachting. En een test waar iedereen honderd procent op scoort, meet niets meer. Allebei nuttige herinneringen dat de meetlat net zo fout kan zijn als wat je ermee meet.

Hoe het er nu uitziet

Dat bestand bleef niet zoals het was. Begin augustus is het opnieuw omgewerkt en het staat nu op 448 woorden, ongeveer de helft van wat de herschrijving opleverde, ingedeeld in onderwerpen in plaats van een lijst met benoemde regels. Geen van de zes labels hierboven bestaat nog als label. De meeste bestaan nog wel als gedrag: “errors are data” is nu een sectie met de kop Errors die opent met “errors are information”, “never invent data” is uitgegroeid tot een lijst van zeven dingen die niet verzonnen mogen worden, en de clausule over het privénetwerk is een eigen sectie geworden.

Eén ding werd wel zwakker. De instructie om de specifieke regel van een foutmelding te lezen, die met bash: of curl: begint, is ingekort tot “read the error”. Dat was de regel die voor de derde fout in dit artikel was geschreven, dus ik houd in de gaten of die fout terugkomt.

Er kwamen drie afspraken bij die er in juli nog niet waren, en elk ervan leest als het restant van iets wat daarna misging. Handelingen die data wijzigen vereisen nu bevestiging, waarbij verwijderen, verplaatsen en het wijzigen van serverinstellingen expliciet genoemd worden. Drie keer achter elkaar dezelfde fout betekent stoppen, samenvatten en vragen in plaats van blijven proberen. En succes mag alleen geclaimd worden als het is waargenomen, het soort regel dat je pas schrijft nadat je te horen kreeg dat iets werkte terwijl dat niet zo was.

Er is ook een regel die het vorige artikel in deze serie lijkt tegen te spreken: vervang nooit een Hermes-tool door curl, Python of een terminalcommando, tenzij de tool al heeft gefaald. Dat leest als het tegenovergestelde van je eigen wrappers bouwen, maar dat is het niet. De wrappers zijn de tools. Zodra er voor een klus een getest commando bestaat, gooi je de hele reden waarom het geschreven is weg als je eromheen grijpt naar een geïmproviseerde shell-aanroep.

Een systeemprompt blijkt minder op een configuratiebestand te lijken dat je één keer goed zet, en meer op een stel huisregels waar elke keer dat er iets stukgaat een clausule bij komt.