Hoe bouw je een AI-agent die werkt

Leer betrouwbare AI-agents te bouwen. We behandelen ontwerp, automatisering workflows en AI-integraties die consistente resultaten opleveren. Stap-voor-stap voor technische ontwikkelaars.

Door Copy&Prompt TEAM · Laatst bijgewerkt oktober 2025

Snel antwoord

1. Definieer één meetbaar resultaat voor de agent.
2. Kies een framework dat geheugen en tooloproepen blootlegt.
3. Ontwerp een systeemprompt die rol en gedrag vastlegt.
4. Koppel 2 tot 3 tools aan de LLM-loop.
5. Sla elke run op met inputs, outputs en traces.
6. Itereer met echte gegevens, niet hypothetisch.
7. Versieer de agent zodat regressies voorkomst zijn.

Een werkende agent is een lus, geen enkele prompt. Het verschil tussen een demo en een systeem dat je kunt vertrouwen, is reproduceerbaarheid. Deze gids laat zien hoe je er een bouwt die blijft werken.

Inhoudsopgave

• Vereisten
• Stap 1: Definieer een meetbaar resultaat
• Stap 2: Kies je framework
• Stap 3: Vastlegging van de systeemprompt
• Stap 4: Koppel tools aan de lus
• Stap 5: Sla en traceer elke run op
• Stap 6: Test met echte gegevens
• Stap 7: Versieer voor stabiliteit
• Hoe verifieer je dat het werkt
• Wat als het niet werkt
• FAQ

Vereisten

Dit artikel gaat ervan uit dat je Python kunt lezen en schrijven, werkzaam bent vanaf een terminal en begrijpt hoe je een API aanroept. Je hebt het volgende nodig voordat je begint:

• Een API-sleutel voor een modern model zoals GPT-5, Claude Opus of Gemini.
• Python 3.11 of nieuwer geïnstalleerd lokaal.
• Pip voor het installeren van een framework zoals LangChain of OpenAI Agents.
• Een gratis account op een tracingplatform, zoals LangSmith of Arize.
• Geschatte kosten: nul dollars voor prototyping, daarna alleen modelgebruikskosten.

Stap 1: Definieer een meetbaar resultaat

Begin met het gewenste resultaat, niet met de tools die je leuk vindt. Een onduidelijke agent zweeft. Een smalle agent die een echte taak oplost, is de basis van elk nuttig systeem.

We bouwden recent een agent die inkomende verkoopmails verwerkt. Ons resultaat was specifiek: classificeer elke mail in één van vijf intenties en retourneer een JSON-object met de intentie, een vertrouwensscore en een éénregelige samenvatting. Die ene beperking vormde elke ontwerpkeuze.

Schrijf het resultaat op. Als je het niet kunt meten, kun je het niet verbeteren.

Tips

Formuleer het resultaat in één zin op een plaknotitiebal. Plak het boven je monitor. Verwijder de agent uit het bereik zodra het stopt met het dienen van die zin.

Fout om te vermijden

Een generieke “assistent” agent bouwen die alles kan doen. Een model dat mag algemeen zijn, wordt onvoorspelbaar.

Stap 2: Kies je framework

Je kunt een agent bouwen met raw API-aanroepen, maar een framework geeft geheugen, tooloproepen en opnieuw probing gratis. De keuze is belangrijk omdat het je ontsnappelijsten later bepaalt.

OpenAI Agents SDK biedt lichte orchestration. Het is ideaal als je strakke controle over de lus wilt. LangChain heeft breerdere integraties maar een zwaardere abstractie. Voor teams die snel prototypen, is LangChain meestal voldoende. Voor productielussen die debugbaar moeten blijven, is de OpenAI SDK moeilijker te breken.

Frameworkkeuze beïnvloedt ook je trace-graadigheid. Kies degene wiens traces nuttig zien eruit in je debugger.

Tips

Begin met het framework wiens quickstartvoorbeeld in minder dan tien minuten draait op je machine.

Fout om te vermijden

Een framework kiezen omdat het de meeste extensies heeft in plaats van de duidelijkste luscontrole.

Stap 3: Vastlegging van de systeemprompt

De systeemprompt is de operatieve overeenkomst van de agent. Het definieert de rol, de toon, de randgevallen en wat “klaar” betekent.

We testten vier systeemprompts op de e-mailverwerkingsagent. De eerste drie mislukten omdat ze ruimte lieten voor het model om te improviseren. De winnende prompt las:

Rol: E-mailclassificator.
Context: Je verwerkt verkoopmails van een gedeelde inbox. Elke e-mail komt met onderwerp en tekst.
Taak: Classificeer intentie, retourneer vertrouwen, vat in één regel sammen.
Beperkingen:
- Output alleen geldige JSON.
- Gebruik één van vijf intenties: inquiry, objection, purchase, followup, spam.
- Vertrouwen tussen 0 en 100.
- Als onzeker, zet intentie op inquiry en vertrouwen onder 60.
Uitvoerformaat: Alleen JSON-object.

Deze prompt hield over 2.000 echte e-mails. Het werkte omdat het keuze nam, niet toevoegde.

Tips

Schrijf de systeemprompt als laatste, nadat je weet wat de agent overleven moet.

Fout om te vermijden

Converseregelregels stapelen in de systeemprompt. Houd het kort, laat gedrag daarna in de taakstroom.

Stap 4: Koppel tools aan de lus

Tools zijn waar de agent echtwaar werk doet. Een ketting van twee tot drie goed benoemde tools is meestal genoeg om een modelaanroep nuttig te maken.

Voor onze classificerende agent was de ketting simpel:

1. extract_email_fields parseert onderwerp en tekst.
2. classify_intent voert de bovenstaande systeemprompt uit.
3. log_result schrijft JSON naar een tracingbackend.

Elke tool heeft een duidelijke naam en één taak. Die duidelijkheid zie je terug in de traces, wat debugging goedkoop maakt.

Toolvolgorde is belangrijk. Plaats retrieval of parsing eerst, redeneren tweede, loggen als laatste. Dat omgekeerde volgorde verbergt het werkelijke falenpunt.

Tips

Benoem tools naar werkwoorden. classify_intent is beter dan intent_classifier omdat je de flow van boven naar bennen leest als een zin.

Fout om te vermijden

Het model een dozijn losweggedefinieerde tools geven. Te veel keuzes vouwen zich op willekeurige selectie, wat eruitziet als intelligentie, maar niet is.

Stap 5: Sla en traceer elke run op

Reproduceerbaarheid is het verschil tussen een demo en een systeem. Als je een faling niet kunt opnemen, kun je deze niet repareren.

Elke run moet drie dingen wegschrijven:

• De inputs die bij het model aankwamen.
• Het output dat het model retourneerde.
• De tooloproepen en hun tussenresultaten.

We sturen alle traces naar Arize. Binnen twee weken liet traceergegevens ons zien dat 12 procent van de fouten kwam van e-mails langer dan 3.000 tekens. We Trimden inputs. Nauwkeid sprong van 78 naar 89 procent.

Opslag kosten pennies. Niet-hebben van gegevens kosten weken.

Tips

Traceer vóór loggen. Vang het modeloutput op zelfs als een downstream tool mislukt.

Fout om te vermijden

Alleen eindresultaten loggen. Dan is de fout al propageerd en is het signaal verloren.

Stap 6: Test met echte gegevens

Eenheidstests controleren één pad. Echte gegevens controleren de distributie die de agent zal ondervinden.

We houden 500 e-mails per week terug als testset. Elke maandag draaien we de agent opnieuw tegen die set en vergelijken we JSON-output met menselijke annotaties. Die ritmegedraging vangt regressie sneller op dan elke code-test.

Echte gegevens onthullen ook stille fouten. Eens begon een model elke onduidelijke e-mail automatisch als “spam” te labelen na een fine-tuning. Het geïntegreerde pakket merkte het nooit op omdat het de randgevallen niet bevatte.

Tips

Houd de testset in een formaat dat de agent van nature leest, niet een getransformeerde kopie.

Fout om te vermijden

Evalueren met synthetische prompt genereren door dezelfde modelfamilie. Dat blazen scores op zonder de prestatie in de praktijk te verbeteren.

Stap 7: Versieer voor stabiliteit

Agents driften wanneer het model, de prompt of de tools zonder waarschuwing veranderen. Versiebeheer is de zijspan.

Tag elke systeemprompt met een versie-string. Vastlegging van de modelnaam in code in plaats van in een omgevingsvariabele. Als gedrag verandert, wijst de diff de oorzaak aan.

We leerden dit hardweg toen OpenAI zijn standaardmodel bijwerkte en onze agent begon met prosa in plaats van JSON te retourneren. Een vastgelegde modelnaam zou het voorkomen.

Tips

Bewaar prompts en tools in hetzelfde versiebeheer als de code die ze uitvoert.

Fout om te vermijden

De systeemprompt als muteerbare configuratie behandelen. Muteerbare prompts zijn onreproduceerbare agents.

Hoe verifieer je dat het werkt

Een agent werkt wanneer drie voorwaarden gelden:

1. Het retourneert geldige output op minimaal 95 procent van de testset.
2. Traceergegevens laten dezelfde tooloproep patronen zien als handmatige runs.
3. Latency blijft onder het service-niveau doel gedurende een week verkeer.

We controleren deze dagenelijks in Arize-dashboards. De curve boven 95 procent nauwkeid verscheen voor het eerst zes weken na ons toevoegen van expliciete JSON-beperkingen aan de systeemprompt.

Wat als het niet werkt

Als nauwkeid onder 90 procent daalt, keer dan terug naar de recentste wijziging. Voer vervolgens opnieuw de testset uit voordat je iets terugzet.

Veelgestelde vragen

Heb ik een framework nodig om een agent te bouwen?

Nee. Je kunt de API rechtstreeks aanroepen en de lus zelf beheren. Een framework bespaart tijd wanneer je geheugen, opnieuw probing of tracing nodig hebt.

Hoeveel tools moet een agent hebben?

Begin met twee of drie. Meer tools verhogen willekeurige selectie. Voeg toe wanneer een tool een meetbare fout losmaakt.

Welk model werkt het beste voor agenten?

GPT-5, Claude Opus en Gemini ondersteunen tooloproepen goed. Kies op basis van uw tracingopzet en kostenbudget.

Hoe vaak moet ik de agent op echte gegevens testen?

Wekelijks is een goede ritmegedraging. Maandelijks is te traag om regressie in snel bewegende API's op te sporen.

Waar moet ik prompts en traces opslaan?

Bewaar beide als geversioneerde artefacten. Copy&Prompt biedt een promptbibliotheek die elke agent reproduceerbaar maakt binnen runs.

Hoofdleerlingen

• Een werkende agent begint met één meetbaar resultaat, niet een vaag doel.
• Frameworks helpen, maar alleen als hun traces overeenkomen met hoe je debugt.
• Veranker gedrag in een korte, precieze systeemprompt.
• Toolkettingen moeten twee of drie benoemde werkwoorden zijn in volgorde.
• Traceer elke run zodat falen herhaalbaar is, niet geraden.
• Test wekelijks op echte gegevens, niet op synthetische prompt.
• Vastlegging van modellen en promptversies om stil drift te stoppen.

Volgende stap

Bouw de minimale agent die de testset een keer doorstaat. Alles anders is verfijning.

We vertrouwen op één principe bij elke agent die we verzenden: als je deze niet kunt herhaalnemen, kun je deze niet repareren. Dat is het verschil tussen een demo die verblindt en een systeem dat schaalbaar is.

Verbeter uw AI-resultaten vandaag nog — Maak betere prompts en krijg nauwkeidigere reacties met Copy&Prompt.