Wie bij een LLM-feature alleen de prompt versioneert, weet niet wat hij heeft gedeployd.
Vrijdagmiddag scherpt iemand een zin aan in de prompt van de refund-agent. In het weekend schuift de provider een nieuw model achter een alias. Of de MCP-server die refund_order levert, past zijn tool description aan (dat geval hadden we al in de canary-post). In de service-repo staat daarvoor geen commit en geen release. En toch handelt de agent terugbetalingen op maandag anders af dan op vrijdag.
Welke versie van de refund-agent draaide er eigenlijk op 12 september? Het gebruikelijke antwoord is een Git-SHA. Maar die zegt alleen welke code er draaide. Welke prompt uit het prompt-CMS erbij hoorde, welk model achter de alias zat en welke tool description van de externe server kwam, staat er niet in. Zelfs als de prompt in de repo staat, zie je zijn wijzigingen nauwelijks terug in de historie: in een onderzoek naar 243 GitHub-repo’s noemde maar iets meer dan een op de vijf commits die een prompt wijzigen dat überhaupt in de commit message (21,9%, Prompting in the Wild, MSR 2025).
Op ai-systems-architecture.com noemen Michael Seel en ik het pakket dat die vraag beantwoordt het Agent Contract. Dat is onze engineeringterm, een standaard ervoor bestaat niet. In de wetenschappelijke literatuur betekent de term iets anders: bij Ye & Tan zijn Agent Contracts formele runtime-contracten met resourcebudgetten. Dat van ons is een release-artefact: wat wordt er uitgeleverd, en waartegen is het getest? Michael heeft de term uitgebreid onderbouwd. Wie de lange versie wil, vindt die hier (in het Duits):
Het voorbeeld blijft de refund-agent uit de vorige posts.
Vijf dingen, één feature
Wat deployen we als we de refund-agent deployen? In de repo staat de code, uiteraard. Maar of een klant met “Ik wil mijn geld terug” bij de juiste route uitkomt en of daar het juiste gebeurt, wordt op vijf plekken bepaald, en die staan niet allemaal in de repo.
| Onderdeel | Wat erin staat | refund-agent, Contract v1 |
|---|---|---|
| Output-schema | de vorm waarop de code vertrouwt | Routeringsbeslissing als enum (refund, lookup, faq, account, clarify), afgedwongen via de route-tool |
| Prompt | de instructies aan het model | Instructies voor orchestrator en specialistische agents in een vaste versie, bijv. NEVER call refund_order without first calling lookup_order. |
| Model + provider | gepinde model-ID | Anthropic, claude-haiku-5-5 |
| Toegestane tools | wat de agent mag aanroepen, inclusief description en input-schema | Allowlist per route: de refund-route mag lookup_order, verify_customer, refund_order (destructief, vereist approval) en faq_search aanroepen, reset_password niet. De tooldefinities zitten als hash in het contract |
| Eval-set + baseline | testgevallen met verwacht resultaat, plus de pass rate van deze versie | 32 testgevallen in 9 categorieën (o.a. positive_refund, auth_bola, idempotency) met verwachte route, verplichte en verboden tools en approval-verwachting; daarbij de pass rate die v1 daarop haalde |
In de demo-repo kun je het model nog via een instelling omschakelen. De tabel laat zien hoe v1 eruitziet met een gepinde ID.
Een output-schema heeft de refund-agent alleen voor de routeringsbeslissing. Het antwoord aan de klant blijft vrije tekst, en of dat klopt, controleren we via de tool-calls en hun bijwerkingen, bijvoorbeeld of refund_order voor de juiste bestelling liep en er eerst een lookup_order kwam. In de post over AI-systeemarchitectuur was “contract-first” al het principe, maar toen nog alleen voor het output-schema.
Waarom één pakket in plaats van vijf los geversioneerde bestanden? Omdat de onderdelen in elkaar grijpen. Elke tool description komt in de prompt terecht. Past een externe MCP-server de description van refund_order aan, dan verandert dus wat het model leest, zonder dat iemand het promptbestand heeft aangeraakt. In het contract wijkt dan de hash van de tooldefinities af.
En elk model gaat anders om met dezelfde prompt en dezelfde tools. Michael zegt het zo: “De eval-set is het onderdeel dat de andere vier bij elkaar houdt.” Alleen via de testgevallen zien we of de overige onderdelen nog samenwerken. Het contract zelf wordt afgedwongen in de implementatie, door de policy gate en de schemavalidatie.
Uit Rust kennen we een vergelijkbare verdeling. Volgens de Cargo-guide beschrijft Cargo.toml de dependencies “in a broad sense”, terwijl Cargo.lock “exact information about your dependencies” bevat. Vertaald naar de refund-agent zou “pak maar een Haiku, wees behulpzaam” het manifest zijn, en in de lockfile horen de vier gepinde onderdelen.
De Cargo-FAQ omschrijft het doel van een lockfile als “the state of the world at the time of a successful build”. Een lockfile bewijst dus dat er gebouwd is. Of het gebouwde zich correct gedraagt, staat er niet in. Daarvoor heeft Cargo tests, en die staan los van de lockfile. Bij het Agent Contract zit de eval-set mee in het pakket, en bij de versie hoort de pass rate die de eval-run opleverde.
Ook bij het pinnen gaat de vergelijking mank. Cargo pint exacte versies inclusief checksum, een model-ID pint de gewichten en verder niets. Anthropic schrijft daar zelf over: “Model weights are fixed for a given ID, but the serving infrastructure around the model can change over time.” Gelijkheid kan het contract daarom niet garanderen. Afwijkingen laat de volgende run van de eval-set zien.
Het pakket krijgt de versie
Als de onderdelen bij elkaar horen, hebben wijzigingen eraan een regel nodig. En die is bewust asymmetrisch:
- Schema, prompt, model of tooling verandert: nieuwe contractversie. De eval-set draait volledig, en pas daarna gaat de versie live.
- De eval-set verandert: ook een nieuwe versie, omdat daarmee de maatstaf verschuift. De draaiende configuratie wordt gemeten tegen de nieuwe set, dat levert de nieuwe baseline op. Vergelijken kun je alleen versies die tegen dezelfde eval-set hebben gedraaid.
Omdat dezelfde versie nooit twee keer identiek antwoordt, draaien de gevallen meerdere keren, en bij de baseline hoort een tolerantie. Securitycategorieën zoals auth_bola blokkeren toch keihard: eerst groen, nu rood, geen release.
Een verzonnen scenario voor de refund-agent: van v1 naar v2 blijven schema, tools en prompt gelijk, alleen het model is nieuw. De eval-set draait, en de auth_bola-gevallen falen, oftewel de verzoeken waarin een klant bij bestellingen van iemand anders wil. De auth gate blokkeert nog steeds, maar het nieuwe model meldt de klant een terugbetaling die nooit heeft plaatsgevonden. Versie 2 gaat niet live. Zonder contract was dat een modelupdate geweest die alleen in de config stond.
Soms gaat het zelfs met veel lawaai stuk. Claude Haiku 4.5 accepteert temperature, top_p en top_k. Bij Haiku 5.5 levert elke niet-standaardwaarde een 400-fout op, en bij Opus vanaf 4.7 en Sonnet vanaf 5 is het hetzelfde. Wie met temperature: 0.2 dus “alleen de model-ID ophoogt”, heeft daarna een feature die bij elke afzonderlijke request met een fout terugkomt. Een upgrade zou ik dat niet noemen.
Hoe de eval-set als gate in de CI komt, heb ik laten zien in de evals-CI-post.

Michael vat het probleem samen in één zin: “Een promptwijziging is een onzichtbare deployment.” Bij hem draait de eval-set bovendien elke nacht tegen de bevroren versie, omdat de provider of een externe MCP-server ook in beweging is als wij zelf niets aanraken. Wijkt de pass rate dan af van de baseline, dan komt er een alarm, maar geen nieuwe versie.
Vijf is de kern
Over de vijf onderdelen zijn Michael en ik het eens. Ik ga nog een stap verder: het contract is niet definitief afgebakend. Wat erbij komt, bepaal ik liever aan de hand van een helder criterium dan aan de hand van een lange lijst.
Het meest voor de hand liggend is de retrieval-index. Als er bij de refund-agent voor faq_search een kennisbank via RAG bijkwam, zouden indexversie en embeddingmodel in het pakket horen. De FAQ-gevallen in de eval-set moeten dan bij de indexversie passen, anders test een testgeval op een retourregel die in de index allang anders staat. In het releasemanifest van de canary-post stond de RAG-index trouwens al.

Interessanter is het fallback-model. Onder belasting, bijvoorbeeld als de provider met 429 antwoordt, springt er een ander model in, vaak van een andere provider. Voor de klant die net om zijn terugbetaling vraagt, blijft het dezelfde refund-agent. De eval-set moet daarom ook tegen de fallback draaien, en voor diens parameters geldt de temperature-valkuil van hierboven net zo goed. Anders antwoordt uitgerekend tijdens de piekbelasting een setup die nooit is gemeten.
Dan zijn er dingen die aan het contract hangen zonder een eval-run te triggeren: owner, goedkeuring, risicoclassificatie. Dat is metadata. Die stuurt processen, dus wie een nieuwe versie goedkeurt of welke documentatie nodig is, maar aan de output van de agent verandert ze niets. Bij datagrenzen hangt het ervan af: zolang ze alleen documenteren, zijn ze metadata. Filteren ze wat er in de prompt terechtkomt, dan horen ze in het pakket. In de logging-post hangen handtekening en approved_by als zulke metadata aan het contract. Of metadata in hetzelfde bestand staat of in een document ernaast, kan me eerlijk gezegd vrij weinig schelen. Als een ownerwissel maar geen nieuwe contractversie en geen eval-run oplevert.
Bestaat dit al?
In stukjes, ja. Voor bijna elk onderdeel is er een tool die het versioneert, en sommige bundelen er zelfs meerdere.
Google Dotprompt stopt vier van de vijf onderdelen in één bestand: prompt, output.schema, de toegestane tools en het model, via config.version zelfs tot op het checkpoint gepind. Een veld voor evals is er niet. Registries zoals Langfuse versioneren prompt en modelconfig samen, de evals draaien ergens anders. Bij MLflow daarentegen blijft de modelconfig achteraf aanpasbaar: “Model configuration is mutable and can be updated after a prompt version is created.”
Het dichtst in de buurt komt Docker Agent. Daar staan de agentdefinitie (een agent.yaml), de evals en een baselinevergelijking bij elkaar. De regel is streng: “An evaluation that passed and now fails always gates, regardless of the tolerance.” De baseline is wel de JSON van een eerdere run en staat naast het agent-artefact. En dat een wijziging aan het model of aan refund_order de eval-run triggert, bedraden we zelf in de CI. De eval-set inclusief baseline in hetzelfde pakket, plus de regel wanneer die moet draaien: geen van de tools levert dat compleet mee.
Wie bundelt wat?
De tabel toont de stand van oktober 2026.
| Tool | Schema | Prompt | Model | Tools | Eval-set | Opmerking |
|---|---|---|---|---|---|---|
| Google Dotprompt | ja | ja | ja | ja | nee | pint via config.version het checkpoint, geen eval-veld |
| Microsoft Prompty | ja | ja | ja | ja | nee | promptformaat, evals erbuiten |
| Langfuse Prompt Config | deels | ja | ja | ja | nee | config geversioneerd met de prompt, evals apart |
| MLflow Prompt Registry | ja | ja | deels | nee | nee | promptversies onveranderlijk, modelconfig veranderlijk |
| Braintrust Prompts | ja | ja | ja | ja | nee | prompt met model en tools geversioneerd, evals apart |
| Docker Agent | ja | ja | deels | ja | ja | baseline los van het artefact, trigger zelf bedraden |
Is dit niet gewoon MLOps?
In de kern wel. Sculley et al. beschreven dat in 2015 als het CACE-principe: “Changing Anything Changes Everything”. Nieuw bij LLM-features is dat het model gehuurd is: de provider verandert de infrastructuur erachter, verschuift aliassen en zet oude ID’s uit volgens zijn eigen planning, zonder dat wij iets committen. En een deel van het artefact is natuurlijke taal, waarvan niemand het effect via een diff kan beoordelen.
Klein beginnen
OpenAI zet v1/prompts, dus de server-side geversioneerde prompt-objecten, op 30 november 2026 uit en raadt aan: “Move versioning to your repo using git commits, PR review, and tests or evals.” Een formaat daarvoor schrijft OpenAI niet voor. Bij de migratie komt dus sowieso de vraag op wat er allemaal in je eigen repo hoort: alleen de prompt of het hele pakket.
Om te beginnen volstaat één bestand naast de code. De prompt staat meestal al in de repo, en ernaast horen het output-schema, de gepinde model-ID en de definities van de tools die de refund-agent mag aanroepen. Daar komen een stuk of twaalf echte gevallen met het verwachte resultaat bij, plus de pass rate die de laatste run opleverde. Dat is al genoeg als contract, omdat je elke wijziging ertegen kunt meten. Uitbreiden kan later.
Te veel proces voor een prompt? Voor een intern hobbyproject misschien. Ik vind de moeite gerechtvaardigd zodra echte gebruikers met de feature werken, meer dan één persoon aan de prompts sleutelt of een verkeerd antwoord iets kost. Bij de refund-agent kost het vrij letterlijk geld.
Hoe ik in productie aantoon dat het contract is nageleefd, heb ik beschreven in de logging-post.

Het antwoord op “Wat draaide daar eigenlijk?” is een versienummer. Daarachter staan vijf dingen die samen zijn getest.
