De oorzaak van elke multi-agent fout
Je hebt iets indrukwekkends gebouwd: een multi-agent pipeline die onderzoekt, analyseert, schrijft en publiceert. Het werkt in tests. Je demonstreert het aan het team. Iedereen is onder de indruk. Dan push je het naar productie, en binnen 48 uur doet het iets wat niemand gevraagd heeft.
Je analyseagent schrijft rapporten. Je schrijfagent haalt data op. Je orchestrator praat rechtstreeks met gebruikers. Alles is technisch functioneel, en toch is alles fout.
De oorzaak is bijna altijd dezelfde: niemand heeft de agents verteld wie ze zijn, wat ze kunnen doen, waar ze passen of hoe ze zich moeten gedragen. De oplossing blijkt vier eenvoudige markdown-bestanden te zijn, elk met één specifieke vraag.
Eén groot systeem-prompt probeert vier fundamenteel verschillende vragen tegelijk te beantwoorden: wat kan deze agent doen, wie is hij in het systeem, waar past hij tussen de andere agents, en hoe moet hij zich stap voor stap gedragen? De oplossing is elk van deze vragen een eigen bestand te geven.
SKILL.md: Het trainingshandboek
Een SKILL.md-bestand beantwoordt: "Hoe doe ik dit specifieke ding precies?"
Beschouw het als een certificeringsdocument. Als je een data-engineer inhuurt, verwacht je dat hij SQL kent. De SKILL.md is het bewijs en de referentie voor precies die kennis. Hier is een echt voorbeeld voor een web scraping-agent:
---
name: web-scraper
description: Extraheert gestructureerde data van websites met
BeautifulSoup en Playwright.
---
## Wanneer deze skill gebruiken
- Gebruiker geeft een URL en wil gestructureerde data terug
- Pagina kan JS-gerenderd zijn (gebruik Playwright) of statisch
## Stap-voor-stap proces
1. Controleer of de pagina JS-gerenderd is. Zo ja, gebruik Playwright headless.
2. Gebruik semantische selectors: article, main, role=-attributen.
Vermijd broze CSS-paden zoals .div > span:nth-child(3).
3. Retourneer een pandas DataFrame. Sla op naar /outputs/data.csv.
## Foutafhandeling
- 403 of 429: Voeg User-Agent header toe, wacht 2 seconden, probeer opnieuw.
- Lege resultaten: Log de gebruikte selector. Stel een alternatief voor.Let op wat hier staat: echte codepatronen, expliciete stappen en foutmodi. De beste SKILL.md-bestanden beschrijven niet alleen de perfecte scenario's, maar vertellen de agent ook precies wat te doen als het misgaat.
Beste praktijk: één SKILL.md per capability. Bundel "scraping" en "database-queries" niet in één bestand. Houd skills atomisch en herbruikbaar.
Agent.md: Het medewerkerspasje
Agent.md beantwoordt: "Wie ben ik, en waar pas ik in het systeem?"
Dit is een per-agent bestand. Elke agent heeft er precies één. Het is kort, zelden meer dan 30 regels, want het probeert de agent niets te leren. Het verankert de agent in zijn identiteit:
## analyst-agent ### Wie ik ben Ik ben de data-analyseagent. Ik ontvang datasets en vragen, en ik retourneer gestructureerde AnalysisResult-dicts. ### Mijn plaats in het systeem - Gestart door: orchestrator-agent - Ik geef door aan: viz-agent en writer-agent - Ik communiceer nooit rechtstreeks met de gebruiker ### Wat ik NIET doe - Rapporten of tekst schrijven (-> writer-agent) - Grafieken of visualisaties maken (-> viz-agent) - Zakelijke aanbevelingen doen (-> menselijke review)
Die laatste sectie, "Wat ik NIET doe", is het belangrijkste deel van elke Agent.md. Agentmisgedrag komt bijna altijd doordat een agent een gat invult dat nooit expliciet gesloten werd.
Beste praktijk: houd Agent.md stabiel. Het mag bijna nooit veranderen nadat het is geschreven. Als je het regelmatig aanpast, is de rol van de agent nog niet goed gedefinieerd.
AGENTS.md: Het organogram
Als Agent.md het pasje van één medewerker is, is AGENTS.md de bedrijfsgids. Het beantwoordt: "Wie zijn alle agents, en hoe is het hele systeem verbonden?"
Dit is één bestand dat in de root van je project staat, niet in de map van een specifieke agent. Het geeft elke agent een mentaal model van het hele systeem, niet alleen van hun eigen hoekje.
# Systeemagents ## orchestrator-agent Rol: Ontvangt gebruikersverzoeken, routeert taken, aggregeert outputs Start: analyst-agent, writer-agent, viz-agent ## analyst-agent Rol: Ontvangt datasets, retourneert AnalysisResult-dicts Rapporteert aan: orchestrator-agent Geeft door aan: viz-agent, writer-agent ## writer-agent Rol: Zet analyse om in gestructureerde prosa-rapporten Rapporteert aan: orchestrator-agent Nooit: toegang tot ruwe data, externe API-aanroepen
Beste praktijk: behandel AGENTS.md als een architectuurdiagram. Houd het in de projectroot, commit het naar versiebeheer en werk het bij wanneer je een agent toevoegt of verwijdert.
INSTRUCTIONS.md: Het personeelshandboek
INSTRUCTIONS.md beantwoordt: "Hoe moet ik me gedragen, stap voor stap, bij het uitvoeren van mijn werk?"
Dit is het meest operationele van de vier bestanden. Terwijl SKILL.md zegt "zo scrape je een pagina," zegt INSTRUCTIONS.md "dit is de exacte volgorde die je elke keer volgt als een taak binnenkomt":
## Instructies: Data-analyseagent ### Kerngedragsregels 1. Valideer altijd de dataset voordat je analyseert. - Meer dan 20% nulls in een kolom? Waarschuw de gebruiker. - Type-mismatches? Gooi een fout, gok niet. 2. Verzin nooit statistieken. Als een berekening NaN of een fout retourneert, zeg dat expliciet. 3. Wees beknopt in samenvattingen. Maximaal drie zinnen. ### Exacte workflow 1. Laad de dataset. Log de vorm en kolomtypen. 2. Voer datakwaliteitscontroles uit. 3. Beantwoord de analytische vraag met code alleen. 4. Vul de AnalysisResult-dict in. 5. Geef onmiddellijk door aan de downstream-agent. Vraag de gebruiker NIET om bevestiging. ### Harde beperkingen - Lees nooit bestanden buiten /mnt/user-data/ - Maak nooit externe HTTP-aanroepen
Die expliciete genummerde workflow is wat goede INSTRUCTIONS.md-bestanden onderscheidt van slechte. Prozainstructies worden losjes geïnterpreteerd. Genummerde stappen worden precies gevolgd.
Hoe de 4 bestanden samenwerken
Hier is de mapstructuur die op elk multi-agentproject wordt gebruikt:
repo/
├── AGENTS.md <- Systeemkaart. Wie bestaat. Hoe ze verbonden zijn.
└── agents/
└── analyst/
├── Agent.md <- Ik ben analyst-agent. Ik rapporteer aan orchestrator.
├── INSTRUCTIONS.md <- Stap 1: valideer. Stap 2: bereken. Verzin nooit.
└── skills/
└── SKILL.md <- Zo voer je pandas-analyse uit.Het mentale model: AGENTS.md is de stadskaart. Agent.md is je appartementadres. INSTRUCTIONS.md is je dagelijkse routine. SKILL.md is je werkcertificaat.
- AGENTS.md (stadskaart): Zonder dit hebben agents geen idee hoe hun werk verbindt met de rest van het systeem.
- Agent.md (adres): Zonder dit verschuiven agents naar rollen die natuurlijk aanvoelen maar nooit bedoeld waren.
- INSTRUCTIONS.md (routine): Zonder dit interpreteren agents "doe de klus" op inconsistente, onvoorspelbare manieren.
- SKILL.md (certificaat): Zonder dit proberen agents capabilities zonder begeleiding over hoe uit te voeren of te herstellen van fouten.
De bestanden die teams overslaan
De meeste teams schrijven SKILL.md en INSTRUCTIONS.md vrij natuurlijk: ze komen voort uit prompt engineering-werk dat teams al doen. Wat teams consequent overslaan zijn Agent.md en AGENTS.md, omdat ze administratief aanvoelen.
"We weten wie de agents zijn," zeggen teams. "We hoeven dat niet te documenteren."
Maar agents weten niet wat jij weet. Elke keer dat een nieuw gesprek begint, begint elke agent opnieuw. Zonder Agent.md weet je analyseagent niet dat hij de analyst is. Hij weet dat hij pandas-tools heeft en wat instructies. Gegeven voldoende vrijheid, bepaalt hij zijn eigen rol.
- Roldrift: Agents breiden geleidelijk uit naar aangrenzende taken, waardoor verantwoordelijkheden vervagen.
- Outputformaat-mismatches: Agent A produceert iets dat Agent B niet kan parsen, omdat geen van beiden wist wat de ander verwachtte.
- Cascadefout: Één agent die het verkeerde doet veroorzaakt een keten van downstream-fouten die bijna onmogelijk te traceren zijn.
- Onboardingkosten: Elke nieuwe engineer moet het hele systeem reverse-engineeren uit prompts en logs.
De vier-bestandsstructuur kost ongeveer twee uur op te zetten voor een nieuwe agent. De bugs die het voorkomt kosten dagen.
Conclusie
Multi-agentsystemen falen niet omdat de modellen slecht zijn, maar omdat niemand de agents een duidelijke organisatorische structuur heeft gegeven. Vier markdown-bestanden lossen dit volledig op: één voor de systeemkaart, één voor identiteit, één voor stapsgewijs gedrag en één voor herbruikbare skills.
Als je een systeem bouwt met meer dan twee agents, voeg deze bestanden toe voordat je één regel agentcode schrijft. De structuur die je vooraf definieert is de structuur waarbinnen je agents zullen werken.
Een gestructureerd AI-agentsysteem voor je bedrijf nodig?
TecAdRise bouwt multi-agent pipelines met correcte structuur, duidelijke roldefinities en productie-klare architectuur.
Neem contact op
