Agent harness: waarom de software rond het model bepaalt of je AI-agent werkt

Jarenlang draaide bijna elke AI-discussie om één vraag: welk model is het beste? Sneller, slimmer, een groter contextvenster. Maar wie agents bouwt die echt werk doen, merkt dat iets anders vaak de doorslag geeft: de software om het model heen.

Die laag heet de agent harness. Hij bepaalt wat het model te zien krijgt, wat het onthoudt, welke tools het mag gebruiken en wat er gebeurt als iets misgaat. Mijn stelling: of een agent betrouwbaar werkt, hangt minstens zo veel af van de harness als van het model. En de beste harnesses zijn vaak verrassend kaal.

Wat is een agent harness?

Een agent harness is alle code rond een taalmodel die er een werkende agent van maakt: contextbeheer, geheugen, tools, foutafhandeling en logging. Het model redeneert en schrijft; de harness beslist wat het model ziet, wat het mag doen en hoe het resultaat wordt gecontroleerd. Claude Code, Codex CLI en Mistral Vibe zijn voorbeelden van harnesses rond een model.

Vergelijk het met een auto. Een motor van 800 pk, perfect afgesteld, die op de grond ligt zonder chassis, stuur, remmen en dashboard. Een indrukwekkend stuk techniek, waar je nergens mee komt.

Zo is een taalmodel zonder goede infrastructuur. Het kan redeneren, tekst schrijven en plannen maken. Maar uit zichzelf kan het niet:

• bijhouden wat het gisteren deed;
• beslissen wat bewaard moet blijven;
• fouten systematisch herstellen;
• over meerdere sessies consistent blijven;
• veilig omgaan met tools en externe systemen.

De harness is de rest van de auto: stuur, remmen, navigatie, brandstoftoevoer, onderhoudsboekje en veiligheidssystemen.

Wat doet een harness concreet?

Een harness bestaat meestal uit vijf onderdelen. Elk onderdeel beantwoordt een vraag die het model zelf niet kan beantwoorden.

• Contextbeheer: wat krijgt het model wel en niet te zien? Alles in de prompt stoppen lijkt handig, maar levert ruis op.
• Extern geheugen: in plaats van alles in het contextvenster te bewaren, gebruik je bestanden, een Git-repo of een database als langetermijngeheugen.
• Tools: welke tools mag de agent gebruiken, hoe zien die eruit, en wat gebeurt er bij een mislukte aanroep?
• Foutherstel: wat als een test faalt of een API een timeout geeft? Een goede harness vangt dat op en stuurt bij, in plaats van de agent te laten doorbouwen op een fout.
• Logging en observability: zonder logs weet je niet waarom een agent faalde. De harness maakt elke stap na te lopen.

Denk aan een slimme stagiair. Zonder begeleiding doet hij van alles, met begeleiding en duidelijke afspraken levert hij werk op dat je kunt gebruiken. Het is dezelfde stagiair.

Waarom minder tools vaak beter werken

Je zou denken: hoe meer gespecialiseerde tools een agent heeft, hoe beter. In de praktijk werkt het vaak andersom.

Bij tientallen tools moet het model eerst de juiste kiezen, dan de parameters goed invullen, en dan de foutmeldingen van die specifieke tool begrijpen. Elke stap is een kans op een misverstand. Beperk je de agent tot een paar eenvoudige, voorspelbare hulpmiddelen, zoals gewone shell-commando's als ls, cat en grep, dan wordt het gedrag vaak consistenter.

Vercel beschreef in december 2025 precies dit. Hun interne agent d0 zet vragen in gewone taal om in SQL. Die had meer dan vijftien gespecialiseerde tools en veel promptwerk, en was volgens het team kwetsbaar, traag en onderhoudsgevoelig. Ze gooiden het grootste deel weg en gaven de agent (op Claude Opus 4.5) in plaats daarvan een shell, toegang tot de bestanden die hun datalaag beschrijven en de mogelijkheid om SQL uit te voeren. Op hun testset ging het slagingspercentage van 80 naar 100 procent. De agent was 3,5 keer zo snel, gebruikte 37 procent minder tokens en had 42 procent minder stappen nodig.

Twee kanttekeningen. De testset bestond uit vijf vragen, dus dit is een sterke aanwijzing en geen bewijs. En het werkte omdat hun datalaag al goed gedocumenteerd was, met consequent benoemde YAML-bestanden. Hun eigen waarschuwing: als je datalaag een rommeltje is, redt ruwe bestandstoegang je niet.

De valkuil: te veel tools

Overengineering is verleidelijk. Je bouwt routers, speciale API-wrappers, ingewikkelde schema's en evaluatiemodules. Dat voelt professioneel. Maar voor een taalmodel wordt het een doolhof.

Wat er dan gebeurt:

1. De agent kiest de verkeerde tool.
2. De uitvoer wordt verkeerd geïnterpreteerd.
3. De volgende stap bouwt voort op die fout.
4. Fouten stapelen zich op.

Er zit ook een verraderlijke kant aan. Veel van die extra constructies zijn gebouwd om een zwakte van een ouder model op te vangen. Wordt het model beter, dan staat die constructie het model in de weg. Vercel noemt het zelf zo: ze verwijderden beperkingen die beschermden tegen modelzwaktes die er niet meer waren.

Langlopende agents: het voortgangsbestand

Een van de lastigste problemen bij agents is geheugen. Een model onthoudt niets buiten het huidige contextvenster. Stop je er alles in, dan wordt het rommelig. Stop je er te weinig in, dan weet het in de volgende sessie niet meer waar het was.

Een eenvoudige oplossing is een voortgangsbestand, bijvoorbeeld progress.md.

De werkwijze:

1. De agent leest bij elke start het voortgangsbestand.
2. Hij voert één concrete taak uit.
3. Hij werkt het bestand bij met de nieuwe stand van zaken.

Anthropic beschreef in november 2025 een uitgewerkte versie hiervan voor agents die over veel sessies aan één project werken. Een eerste "initializer"-agent zet de omgeving klaar. Die maakt een lijst met ongeveer 200 features (in JSON, allemaal beginnend als "niet af"), een init.sh om de ontwikkelserver te starten, een bestand claude-progress.txt en een eerste Git-commit. Elke volgende sessie leest de voortgang en de Git-geschiedenis, pakt één feature op, test die end-to-end en sluit af met een commit.

Die opzet lost twee fouten op die Anthropic steeds zag. De agent verklaarde het project te vroeg af, en hij probeerde alles in één keer te bouwen. De featurelijst voorkomt het eerste, de regel "één feature per sessie" het tweede.

Voorbeeld van een voortgangsbestand

Een minimale versie, als schets in Python (call_model staat voor je eigen aanroep van het model):

# Lees de voortgang
with open("progress.md", "r") as f:
    state = f.read()

response = call_model(task, state)

# Schrijf de bijgewerkte stand terug
with open("progress.md", "w") as f:
    f.write(response.updated_state)

Het is bijna schokkend hoe goed zo'n eenvoudige techniek werkt.

Een groot contextvenster lost het niet op

Grote contextvensters zijn indrukwekkend, maar ze lossen niet alles op. Chroma testte in juli 2025 achttien modellen, waaronder GPT-4.1, Claude 4, Gemini 2.5 en Qwen3. De conclusie: de prestaties gaan achteruit naarmate de invoer langer wordt, "often in surprising and non-uniform ways", ook bij simpele taken als iets terugvinden of tekst overnemen.

Met extern geheugen in bestanden, een repo of een database zet je alleen de relevante stukken in de prompt. De rest blijft buiten het model bewaard, en jij kunt het gewoon openen en lezen. Een voortgangsbestand kun je controleren. Wat een model "onthoudt" in een lange context, kun je niet controleren.

The Bitter Lesson toegepast op agents

In 2019 schreef AI-onderzoeker Richard Sutton het essay The Bitter Lesson. De openingszin, in vertaling:

"De grootste les die je uit zeventig jaar AI-onderzoek kunt trekken, is dat algemene methoden die rekenkracht benutten uiteindelijk het effectiefst zijn, en met grote afstand."

Zijn punt: methoden die meeschalen met rekenkracht winnen op de lange termijn van slimme, door mensen bedachte kunstgrepen.

Voor agents vertaal ik dat zo. Bouw niet steeds ingewikkeldere prompts, en stapel geen regels en speciale tools op om de zwaktes van het huidige model te maskeren. Ontwerp infrastructuur die eenvoudig, herhaalbaar en controleerbaar is: een shell, bestanden, Git, tests en logs. Met zo'n harness profiteer je van elk beter model. Een harness vol kunstgrepen moet je bij elk nieuw model weer uit elkaar halen.

Wie bouwt de beste auto?

Het model blijft ertoe doen. Maar het model is ook het onderdeel waar je als bouwer het minst over te zeggen hebt: je kiest er een, en over een paar maanden is er een betere. De harness is van jou. Daar zit het verschil tussen een demo die één keer werkt en een agent die je een week kunt laten draaien.

De motor wordt steeds krachtiger. De race win je met de auto.