Gids voor het begrijpen, bouwen en optimaliseren van API-aanroepende agenten Takenlijst API versie: 1.0.0 paden: /taken: post: samenvatting: Voeg een nieuwe taak toe aanvraagbody: vereist: true inhoud: application/json: schema: type: object eigenschappen: beschrijving: type: string antwoorden: ‘201’: beschrijving: Taak succesvol gemaakt get: samenvatting: Haal alle taken op antwoorden: ‘200’: beschrijving: Lijst met taken Stap 2: Standaardiseer tooltoegang Converteer de OpenAPI-specificatie naar Model Context Protocol (MCP)-configuraties. Met een tool zoals Stainless.ai kan dit resulteren in: Toolnaam Beschrijving Invoerparameters Uitvoerbeschrijving Taak toevoegen Voegt een nieuwe taak toe aan de takenlijst. `beschrijving` (string, vereist): De beschrijving van de taak. Bevestiging van taakcreatie. Taken ophalen Haalt alle taken op uit de takenlijst. Geen Lijst met taken met hun beschrijvingen. Stap 3: Implementeer de agent Gebruik Pydantic voor gegevensmodellering, maak functies die overeenkomen met de MCP-tools. Gebruik vervolgens een LLM om natuurlijke taalopdrachten te interpreteren en de juiste tool en parameters te selecteren. Stap 4: Curateer een kwaliteitsdataset Maak een dataset: Opdracht Verwachte API-aanroep Verwacht resultaat “Voeg ‘Boodschappen doen’ toe aan mijn lijst.” `Taak toevoegen` met `beschrijving` = “Boodschappen doen” Bevestiging van taakcreatie “Wat staat er op mijn lijst?” `Taken ophalen` Lijst met taken, inclusief “Boodschappen doen” Stap 5: Optimaliseer agentprompts en -logica Gebruik DSPy om prompts te verfijnen, met focus op duidelijke instructies, toolselectie en parameterextractie met de gecureerde dataset voor evaluatie en verbetering. Door deze bouwstenen te integreren – van gestructureerde API-definities en gestandaardiseerde toolprotocollen tot rigoureuze datapraktijken en systematische optimalisatie – kunnen technische teams meer capabele, betrouwbare en onderhoudsvriendelijke API-aanroepende AI-agenten bouwen.

De rol van Artificial Intelligence in technologiebedrijven evolueert snel; AI-use cases zijn geëvolueerd van passieve informatieverwerking tot proactieve agenten die taken kunnen uitvoeren. Volgens een enquête over wereldwijde AI-adoptie in maart 2025, uitgevoerd door Georgian en NewtonX, gebruiken of plannen 91% van de technische directeuren in groeifase- en ondernemingsbedrijven agentic AI.

API-aanroepende agenten zijn een primair voorbeeld van deze verschuiving naar agenten. API-aanroepende agenten gebruiken Large Language Models (LLM’s) om te communiceren met software-systemen via hun Application Programming Interfaces (API’s).

Bijvoorbeeld, door natuurlijke taalopdrachten om te zetten in precieze API-aanroepen, kunnen agenten real-time gegevens ophalen, routine-taken automatiseren of zelfs andere software-systemen controleren. Deze mogelijkheid transformeert AI-agenten in nuttige tussenpersonen tussen menselijke intentie en software-functionaliteit.

Bedrijven gebruiken momenteel API-aanroepende agenten in verschillende domeinen, waaronder:

• Consumententoepassingen: Assistenten zoals Apple’s Siri of Amazon’s Alexa zijn ontworpen om dagelijkse taken te vereenvoudigen, zoals het controleren van slimme thuisapparaten en het maken van reserveringen.
• Bedrijfsworkflows: Bedrijven hebben API-agenten geïmplementeerd om routine-taken te automatiseren, zoals het ophalen van gegevens uit CRM’s, het genereren van rapporten of het consolideren van informatie uit interne systemen.
• Gegevensopname en -analyse: Bedrijven gebruiken API-agenten om toegang te krijgen tot propriëtaire datasets, abonnementsgebaseerde bronnen en openbare API’s om inzichten te genereren.

In dit artikel zal ik een technisch-georiënteerde aanpak gebruiken om API-aanroepende agenten te begrijpen, te bouwen en te optimaliseren. Het materiaal in dit artikel is gebaseerd op praktisch onderzoek en ontwikkeling door Georgian’s AI Lab. De motiverende vraag voor veel van het onderzoek van de AI Lab op het gebied van API-aanroepende agenten was: “Als een organisatie een API heeft, wat is de meest effectieve manier om een agent te bouwen die kan communiceren met die API met behulp van natuurlijke taal?”

Ik zal uitleggen hoe API-aanroepende agenten werken en hoe ze succesvol kunnen worden geïmplementeerd voor prestaties. Ten slotte zal ik een systematische workflow bieden die technische teams kunnen gebruiken om API-aanroepende agenten te implementeren.

I. Sleuteldefinities:

• API of Application Programming Interface: Een set regels en protocollen die verschillende softwaretoepassingen in staat stellen om te communiceren en informatie uit te wisselen.
• Agent: Een AI-systeem dat is ontworpen om zijn omgeving waar te nemen, beslissingen te nemen en acties te ondernemen om specifieke doelen te bereiken.
• API-aanroepende agent: Een gespecialiseerde AI-agent die natuurlijke taalopdrachten omzet in precieze API-aanroepen.
• Code-genererende agent: Een AI-systeem dat helpt bij software-ontwikkeling door code te schrijven, te wijzigen en te debuggen. Hoewel dit gerelateerd is, ligt mijn focus hier voornamelijk op agenten die API’s aanroepen, hoewel AI ook kan helpen bij het bouwen van deze agenten.
• MCP (Model Context Protocol): Een protocol, ontwikkeld door Anthropic, dat definieert hoe LLM’s kunnen aansluiten op en gebruikmaken van externe tools en gegevensbronnen.

II. Kernopdracht: Natuurlijke taal omzetten in API-acties

De fundamentele functie van een API-aanroepende agent is om een gebruikers natuurlijke taalopdracht te interpreteren en om te zetten in een of meer precieze API-aanroepen. Dit proces omvat meestal:

1. Intentieherkenning: Het begrijpen van de gebruikersdoel, zelfs als deze vaag is uitgedrukt.
2. Toolselectie: Het identificeren van de juiste API-eindpunt(en) – of “tools” – uit een set beschikbare opties die de intentie kunnen vervullen.
3. Parameterextractie: Het identificeren en extraheren van de benodigde parameters voor de geselecteerde API-aanroep(en) uit de gebruikersquery.
4. Uitvoering en responsgeneratie: Het maken van de API-aanroep(en), het ontvangen van de respons(en) en het vervolgens synthesizeren van deze informatie in een coherent antwoord of het uitvoeren van een vervolgactie.

Bijvoorbeeld, bij een opdracht als “Hey Siri, wat is het weer vandaag?”, moet de agent de behoefte identificeren om een weeraanroep te doen, de locatie van de gebruiker bepalen (of toestaan dat de gebruiker een locatie opgeeft) en vervolgens de API-aanroep formuleren om de weergegevens op te halen.

Als voorbeeld voor de opdracht “Hey Siri, wat is het weer vandaag?” kan een API-aanroep er als volgt uitzien:

GET /v1/weer?locatie=New%20York&eenheden=metric

Aanvankelijke hoge-niveau-uitdagingen zijn inherent aan dit vertaalproces, waaronder de ambiguïteit van natuurlijke taal en de noodzaak voor de agent om context te behouden over meerdere interacties.

Bijvoorbeeld moet de agent vaak “onthouden” eerder onderdelen van een conversatie of eerder API-aanroepresultaten om de huidige acties te informeren. Contextverlies is een veelvoorkomende foutmodus als dit niet expliciet wordt beheerd.

III. Architectuur van de oplossing: Sleutelcomponenten en -protocollen

Het bouwen van effectieve API-aanroepende agenten vereist een gestructureerde architecturale aanpak.

1. Definiëren van “tools” voor de agent

Voor een LLM om een API te gebruiken, moeten de capaciteiten van die API worden beschreven op een manier die het kan begrijpen. Elk API-eindpunt of -functie wordt vaak weergegeven als een “tool”. Een robuuste tooldefinitie omvat:

• Een duidelijke, natuurlijke taalbeschrijving van de toolfunctie en -functionaliteit.
• Een precieze specificatie van de invoerparameters (naam, type, of het verplicht is of optioneel, en een beschrijving).
• Een beschrijving van de uitvoer of gegevens die de tool retourneert.

2. De rol van Model Context Protocol (MCP)

MCP is een kritieke factor voor meer gestandaardiseerd en robuust toolgebruik door LLM’s. Het biedt een gestructureerd formaat voor het definiëren van hoe modellen kunnen aansluiten op en gebruikmaken van externe tools en gegevensbronnen.

MCP-standaardisatie is nuttig omdat het een gemakkelijkere integratie van diverse tools mogelijk maakt, het hergebruik van tooldefinities over verschillende agenten of modellen bevordert. Bovendien is het een best practice voor technische teams om te beginnen met goed gedefinieerde API-specificaties, zoals een OpenAPI-specificatie. Tools zoals Stainless.ai zijn ontworpen om te helpen bij het omzetten van deze OpenAPI-specificaties in MCP-configuraties, waardoor het proces van het maken van API’s “agent-ready” wordt gestroomlijnd.

3. Agentframeworks en implementatiekeuzes

Er zijn verschillende frameworks die kunnen helpen bij het bouwen van de agent zelf. Deze omvatten:

• Pydantic: Hoewel Pydantic niet exclusief een agentframework is, is het nuttig voor het definiëren van gegevensstructuren en het waarborgen van typeveiligheid voor toolinvoer en -uitvoer, wat belangrijk is voor betrouwbaarheid. Veel aangepaste agentimplementaties gebruiken Pydantic voor deze structurele integriteit.
• LastMile’s mcp_agent: Dit framework is specifiek ontworpen om te werken met MCP’s, waardoor een meer geïnformeerde structuur wordt geboden die aansluit bij de praktijken voor het bouwen van effectieve agenten zoals beschreven in onderzoek van bedrijven als Anthropic.
• Interne framework: Het is ook steeds vaker gebruikelijk om AI-codegenererende agenten (met behulp van tools zoals Cursor of Cline) te gebruiken om te helpen bij het schrijven van de boilerplate-code voor de agent, zijn tools en de omliggende logica. De ervaring van Georgian’s AI Lab met het werken met bedrijven aan agentic-implementaties toont aan dat dit geweldig kan zijn voor het creëren van zeer minimale, aangepaste frameworks.

IV. Technisch ontwerp voor betrouwbaarheid en prestaties

Het waarborgen dat een agent API-aanroepen betrouwbaar maakt en goed presteert, vereist een gerichte technische inspanning. Twee manieren om dit te doen zijn (1) datasetcreatie en -validatie en (2) promptengineering en -optimalisatie.

1. Datasetcreatie en -validatie

Het trainen (indien van toepassing), testen en optimaliseren van een agent vereist een hoogwaardige dataset. Deze dataset moet bestaan uit representatieve natuurlijke taalopdrachten en hun overeenkomstige gewenste API-aanroepsequenties of -resultaten.

• Handmatige creatie: Handmatig een dataset cureren waarborgt hoge precisie en relevantie, maar kan arbeidsintensief zijn.
• Synthetische generatie: Gegevens programmatisch genereren of gebruiken van LLM’s kan de datasetcreatie schalen, maar deze aanpak stelt significante uitdagingen. Onderzoek van Georgian AI Lab heeft aangetoond dat het waarborgen van de correctheid en realistische complexiteit van synthetisch gegenereerde API-aanroepen en -opdrachten zeer moeilijk is. Vaak waren gegenereerde vragen te triviaal of onmogelijk complex, waardoor het moeilijk was om nuances in agentprestaties te meten. Zorgvuldige validatie van synthetische gegevens is absoluut kritiek.

Voor kritische evaluatie biedt een kleinere, hoogwaardige, handmatig geverifieerde dataset vaak meer betrouwbare inzichten dan een grote, lawaaierige synthetische.

2. Promptengineering en -optimalisatie

De prestaties van een LLM-gebaseerde agent worden sterk beïnvloed door de prompts die worden gebruikt om zijn redenering en toolselectie te leiden.

• Effectief prompten omvat het duidelijk definiëren van de agenttaak, het bieden van beschrijvingen van beschikbare tools en het structureren van de prompt om accurate parameterextractie te stimuleren.
• Systeemoptimalisatie met frameworks zoals DSPy kan de prestaties aanzienlijk verbeteren. DSPy laat u toe om de componenten van uw agent te definiëren (bijv. modules voor gedachtengeneratie, toolselectie, parameterformattering) en vervolgens met een compiler-achtige aanpak met enkele voorbeelden uit uw dataset de geoptimaliseerde prompts of configuraties voor deze componenten te vinden.

V. Een aanbevolen pad naar effectieve API-agenten

Het ontwikkelen van robuuste API-aanroepende AI-agenten is een iteratieve technische discipline. Op basis van de bevindingen van het onderzoek van Georgian AI Lab, kunnen resultaten aanzienlijk worden verbeterd met een systematische workflow zoals de volgende:

1. Begin met duidelijke API-definities: Begin met goed gestructureerde OpenAPI-specificaties voor de API’s waarmee uw agent zal communiceren.
2. Standaardiseer tooltoegang: Converteer uw OpenAPI-specificaties naar MCP. Tools zoals Stainless.ai kunnen dit proces vergemakkelijken, waardoor een gestandaardiseerde manier ontstaat voor uw agent om API’s te begrijpen en te gebruiken.
3. Implementeer de agent: Kies een geschikt framework of benadering. Dit kan het gebruik van Pydantic voor gegevensmodellering binnen een aangepaste agentstructuur omvatten of het gebruik van een framework zoals LastMile’s mcp_agent dat is gebouwd rond MCP.
   • Voordat u dit doet, overweeg om de MCP te verbinden met een tool zoals Claude Desktop of Cline en gebruik deze interface handmatig om een gevoel te krijgen voor hoe goed een generieke agent deze MCP kan gebruiken, hoeveel iteraties het meestal kost om de MCP correct te gebruiken en andere details die u tijd kunnen besparen tijdens de implementatie.
4. Curateer een kwaliteitsdataset voor evaluatie: Maak handmatig een dataset of valideer deze zorgvuldig. Dit is kritiek voor betrouwbare testen en optimalisatie.
5. Optimaliseer agentprompts en -logica: Gebruik frameworks zoals DSPy om uw agentprompts en interne logica te verfijnen, met uw dataset als leidraad voor verbeteringen in nauwkeurigheid en betrouwbaarheid.

VI. Een illustratief voorbeeld van de workflow

Hier is een vereenvoudigd voorbeeld dat de aanbevolen workflow illustreert voor het bouwen van een API-aanroepende agent:

Stap 1: Begin met duidelijke API-definities

Stel dat u een API heeft voor het beheren van een eenvoudige takenlijst, gedefinieerd in OpenAPI:

openapi: 3.0.0

info: