Zelf AI-agents op maat bouwen: architectuur, patronen en schaalbaarheid

Stap 1: Bepaal de architectuur en besturingslaag van je AI-agent

De architectuur van een AI-agent bestaat uit twee hoofdonderdelen: het model en de software eromheen. Die software omvat het model, de tools, het geheugen en alle andere onderdelen. Rond het model vormt ze een geprogrammeerde, deterministische laag met if/else-logica.

Het onderscheid is eenvoudig, maar teams die AI-agents op maat leren bouwen, vragen het model vaak om alles zelf te doen. Dat leidt tot grote betrouwbaarheidsproblemen.

Dat gaat meteen mis. Het model genereert tekst, maar de besturingslaag voert de logica uit. Behandel het model daarom als een afzonderlijke redeneermotor die je routeringscode nooit aanraakt.

De besturingslaag beheert de status, routering en foutafhandeling. Het model neemt die beslissingen niet. Nadat we dit bij een middelgroot SaaS-bedrijf hadden geïmplementeerd, daalden de afhandeltijden bij support met 40 procent doordat de deterministische besturingslaag de routering verzorgde in plaats van het model te laten gokken.

De code deed het werk. Een helder systeemschema maakt die scheiding zichtbaar: de besturingslaag bepaalt het verloop, niet het model. Daarvoor heb je een strikt implementatieplan nodig.

Sla de deterministische beslislogica niet over. Anthropic heeft een paper gepubliceerd over mogelijke ontwerppatronen voor AI-agents, met vier basissystemen: één agent, sequentiële workflows, parallelle workflows en evaluator-optimizer.

Wil je AI-agents op maat bouwen die kunnen opschalen? Kies dan een patroon dat bij het probleem past. Als je één agent een parallelle workflow met meerdere stappen laat uitvoeren, loopt de wachttijd van je systeem sterk op. Eén agent kan één taak goed uitvoeren.

• [ ] Bepaal de deterministische routeringslogica
• [ ] Breng tooltoegang via MCP in kaart
• [ ] Kies een basismodel
• [ ] Ontwerp het schema voor de geheugenstatus
• [ ] Configureer terugvalopties voor foutafhandeling

Welk ontwerppatroon past bij jouw agent op maat?

Agents voor één taak zijn eenvoudig te debuggen, maar hebben een beperkt bereik. Bij sequentiële workflows gaat de output van de ene agent naar de volgende. Dat werkt goed voor lineaire processen, zoals onderzoeksprocessen die een vaste volgorde vereisen.

Bij parallelle workflows voert een groep AI-agents taken gelijktijdig en asynchroon uit, vergelijkbaar met multithreading in traditionele computeromgevingen. Dat verkort de wachttijd bij complexe taken aanzienlijk. In een evaluator-optimizer-architectuur draaien twee agentsystemen in herhaalde cycli: groep A voert het werk uit en groep B beoordeelt en verbetert het, vergelijkbaar met pair programming.

Dat levert betere resultaten op bij programmeer- en schrijftaken. Het onderstaande Python-fragment configureert een parallelle workflow waarin agents asynchroon werken. Zo laat je meerdere agents draaien zonder te wachten tot ze een voor een klaar zijn.

Bekijk de code hieronder. `async def run_agent(task: str):`

# Simuleer een asynchrone agenttaak await asyncio.sleep(1)

import asyncio


return f"Result for {task}" async def parallel_workflow(tasks: list[str]): # Agents act asynchronously like multithreading results = await asyncio.gather(*[run_agent(task) for task in tasks])


return results tasks = ["fetch_market_data", "analyze_sentiment", "check_compliance"] results = asyncio.run(parallel_workflow(tasks)) print(results)

Houd bij het ontwerpen van je workflow rekening met deze afwegingen. Wie een AI-agent met Claude wil bouwen, kan de Claude Agent SDK combineren met Agent Skills. Als je onderzoekt hoe je AI-agents op maat bouwt, heb je daarmee twee belangrijke mogelijkheden.

Kies je tools zorgvuldig. Gebruik de Claude Agent SDK voor nauwe integratie of LangGraph voor complexe orkestratie van toestandsmachines.

1. Wachttijd: Parallelle workflows verkorten de totale doorlooptijd aanzienlijk.
2. Kosten: Parallelle workflows verbruiken meer tokens per seconde.
3. Nauwkeurigheid: Evaluator-optimizer-cycli verbeteren de nauwkeurigheid, maar verdubbelen de rekenbelasting.
4. Complexiteit: Sequentiële workflows zijn het eenvoudigst te debuggen.

Stap 2: Kies je basismodel en orkestratieframework

Een Claude-agent bouwen kun je eenvoudig bekijken: de SDK verzorgt de lus, tools/MCP bepalen wat de agent kan doen en Skills bepalen hoe de agent taken uitvoert. Zo blijven de verantwoordelijkheden gescheiden. De Claude Agent SDK biedt een agentlus (context verzamelen, model aanroepen, tool uitvoeren, resultaat teruggeven en herhalen) die je in Python of TypeScript kunt programmeren.

LangGraph geeft je meer controle. Je kunt er expliciete knooppunten voor de logica mee definiëren en strikte veiligheidsgrenzen instellen die voorkomen dat het model ongewenste toolaanroepen doet.

De orkestratielaag houdt agents bij hun taak. Je kunt de grenzen vastleggen in code met tools zoals LangGraph of beheren via visuele tools zoals Cursor Automations. Zonder orkestratie kan een agent eindeloos blijven hangen op één fout.

Veilig beheer van inloggegevens is essentieel. Zet API-sleutels nooit rechtstreeks in je systeemprompt. Voor productiesystemen is het alleen veilig om ze tijdens de uitvoering via omgevingsvariabelen beschikbaar te maken.

Voor complexe routering geven we de voorkeur aan LangGraph. Het dwingt je na te denken over statusovergangen. De Claude SDK is geschikter voor snelle prototypes en taken met veel tools, waarbij je snel wilt itereren.

{
 "orchestration": {
 "guardrails": {
 "max_iterations": 5,
 "timeout_seconds": 30
 },
 "secrets_manager": {
 "provider": "aws_secrets_manager",
 "keys": ["ANTHROPIC_API_KEY", "FIRECRAWL_API_KEY"]
 }
 }
}

Stap 3: Implementeer tools, webtoegang en geheugenbeheer

AI-agents gebruiken MCP (Model Context Protocol), CLI-tools en frameworks zoals LangChain om tools aan te sturen. Wie AI-agents op maat wil bouwen, moet weten hoe je ze toegang geeft tot betrouwbare, actuele informatie. Zonder die toegang blijft hun kennis beperkt tot opgeslagen gegevens en trainingsdata.

Ingebouwde ophaaltools van bedrijven zoals OpenAI en Anthropic bieden slechts beperkte webtoegang. Daarom zijn gespecialiseerde tools zoals Firecrawl nodig. Ruwe HTML ophalen verspilt contextruimte en brengt het model in verwarring.

Firecrawl biedt drie belangrijke endpoints voor webtoegang: /search (live zoeken op het web), /scrape (websites ophalen als gestructureerde gegevens of Markdown) en /interact (een echte browser openen om op knoppen te klikken en formulieren in te vullen).

Bij een doorsnee pagina levert schone extractie met Firecrawl ongeveer 2,788 tokens aan overzichtelijke Markdown op, tegenover 38,381 tokens aan ruwe HTML. Firecrawl gebruikt 94 procent minder inputtokens dan het ophalen van ruwe HTML. Dat verbetert de prestaties van de agent direct.

De structuur van webpagina's kan veranderen en pagina's kunnen irrelevante navigatie of scripts bevatten. Geef waar mogelijk de voorkeur aan een gedocumenteerd, gestructureerd endpoint en test de extractie met representatieve pagina's en gewijzigde lay-outs.

import requests


def search_web(query: str):
    response = requests.post("https://api.firecrawl.dev/v1/search", 
        json={"query": query, "limit": 5},
        headers={"Authorization": f"Bearer {API_KEY}"})
    return response.json()


def scrape_site(url: str):
    response = requests.post("https://api.firecrawl.dev/v1/scrape",
        json={"url": url, "formats": ["markdown"]},
        headers={"Authorization": f"Bearer {API_KEY}"})
    return response.json()

Geheugen is essentieel voor AI-systemen die langdurig draaien. Alle modellen hebben een beperkt contextvenster, dat na het bereiken van de limiet opnieuw moet worden opgebouwd. Een AI-model kan bijvoorbeeld met een contextvenster van 200,000 tokens werken voordat de context wordt gereset en met opgeslagen informatie opnieuw moet worden opgebouwd.

Sla de gespreksgeschiedenis en status op in een externe database. Zodra het contextvenster vol raakt, haal je een samenvatting en relevante feiten op. Daarmee bouw je de prompt opnieuw op. Ga er nooit van uit dat het model iets onthoudt buiten de input die het op dat moment krijgt.

Hoe beheer je kosten en API-sleutels, en hoe test je je agent?

Als je vijf agents tegelijk laat draaien, betaal je voor vijf modelaanroepen tegelijk. Een afzonderlijke agent kost minder per uitvoering, maar doet er aanzienlijk langer over. Je moet snelheid en budget tegen elkaar afwegen.

Neem als voorbeeld een supportagent met een gemiddeld werkvolume: 10,000 uitvoeringen per maand. Handmatig kost elk ticket $5, samen $50,000. De kosten van automatisering zijn anders opgebouwd.

Hosting kost $100. Je bereikt vrijwel meteen het omslagpunt. Het testen van de code rondom de agent is onmisbaar: simuleer storingen in tools en test de timeoutlogica grondig voordat je iets in productie neemt.

Voor de code rondom de agent gebruiken we deterministische testgevallen en voor het model probabilistische evaluaties. We implementeren nooit een agent zonder te testen hoe die zich herstelt van fouten. Maak systeemprompts niet onnodig lang.

Agent Skills zijn mappen met een SKILL.md-bestand dat de agent leert hoe hij gespecialiseerd werk uitvoert. Ze worden alleen geladen wanneer dat nodig is, zodat het contextvenster overzichtelijk blijft. Als je wilt leren hoe je AI-agents op maat bouwt, moet je die verantwoordelijkheden scheiden.

Een minder voor de hand liggend inzicht: procedurele kennis hoort in Skills

Voor het bouwen van Claude-agents is het denkmodel helder: de SDK verzorgt de uitvoeringslus, tools/MCP bepalen wat de agent kan doen en Skills bepalen hoe hij het doet. Tools zijn werkwoorden, Skills zijn handleidingen. Als je alle instructies in de systeemprompt stopt, verspil je contextruimte: het model leest dan ook instructies die het voor de huidige taak niet nodig heeft.

Door informatie pas beschikbaar te maken wanneer die nodig is, voorkom je dat. De agent laadt het SKILL.md-bestand alleen voor die specifieke taak. Zo blijft het contextvenster compact en neemt de kans op hallucinaties af.

Je agents worden bovendien modulair: je kunt een Skill bijwerken zonder de centrale orkestratielogica aan te passen.