GraphQL is de taal waarop AI-agenten wachtten

GraphQL werd in 2015 ontworpen om frontendontwikkeling sneller te maken. Het bleek de perfecte interface voor machines die slimme vragen stellen.

In een eerder stuk was het argument dat elke toepassing API-first moet zijn omdat AI-agenten de belangrijkste afnemers van software worden. De API is het product. De interface is één afnemer.

Dat argument laat een vervolgvraag liggen die bijna niemand stelt, maar die iedereen zou moeten stellen: welk soort API moet je bouwen?

Het antwoord wijst, zodra je werkelijk kijkt hoe agenten software proberen te gebruiken, hard in één richting. GraphQL. Niet omdat het in de mode is: het is inmiddels een decennium oud. Wel omdat de specifieke eigenschappen die GraphQL van REST onderscheiden bijna perfect aansluiten bij wat agenten nodig hebben om te werken zonder mens in de lus.

Het is alsof Facebook in 2015 per ongeluk de opvraagtaal van het agententijdperk heeft gebouwd en de sector daarna tien jaar heeft besteed aan die vooral gebruiken om React-apps iets prettiger te maken. Dat verkoopt haar te goedkoop. Ruimschoots.

Het ontdekkingsprobleem

Hier is het duidelijkste teken dat een API voor mensen en niet voor machines is gebouwd: de documentatiepagina. Toegangspunten opgesomd als zelfstandige naamwoorden. Voorbeelden geschreven voor wie al weet wat hij zoekt. Een versiegeschiedenis die niemand sinds de laatste reorganisatie heeft bijgewerkt. Wanneer iemand uit de ontwikkeling aankomt, leest die de documentatie, houdt een denkmodel van de bronnenkaart in het hoofd en schrijft code die bepaalde, vooraf geplande reeksen aanroepen doet om de nodige gegevens te halen. De documentatie is eenmalige instapkost.

Agenten werken niet zo. Een agent komt met een doel bij jouw API aan (vind de drie openstaande tickets met de hoogste prioriteit die aan het technische team zijn toegewezen en vat hun recentste activiteit samen) en moet ter plekke uitzoeken hoe dat doel in bewerkingen uiteenvalt. Er is geen kant-en-klare integratie. Er is niemand met ervaring die de documentatie leest. De agent denkt in real time over jouw API na, bij de eerste ontmoeting.

Noem dat het ontdekkingsprobleem: een agent komt bij jouw toepassing aan zonder te weten wat er is, en de kosten van die onwetendheid worden betaald in elke gang die hij probeert te rijden. Met REST moet de agent gokken welke toegangspunten er zijn, een aanroep doen, het antwoord bekijken om de vorm van de gegevens te begrijpen, merken dat hij samenhangende gegevens elders nodig heeft, nog een aanroep doen, de resultaten koppelen, de paginering behandelen en herhalen, terwijl hij al die tijd contextvenster verbrandt aan gegevens die hij niet nodig heeft.

GraphQL laat het ontdekkingsprobleem instorten. Een agent kan één introspectieopvraag doen en het volledige schema terugkrijgen: elk type, elk veld, elke relatie, elk argument, elke beschrijving. Het schema is geen apart artefact dat van de werkelijkheid kan afwijken. Het is de werkelijkheid. Het wordt opgeleverd uit dezelfde code die de opvragen oplost.

Voor een agent is dat het verschil tussen een stad doorkruisen zonder kaart en beginnen met een navigatiesysteem.

Introspectie is zelfdocumentatie

Elke GraphQL-API documenteert zichzelf. Niet in de losse, hoopvolle zin waarin REST-API’s «zelfdocumenterend» zijn wanneer iemand eraan denkt de OpenAPI-specificatie bij te houden. GraphQL-API’s documenteren zichzelf letterlijk, van opzet, als kerneigenschap van het protocol.

Dat telt voor agenten op een bepaalde manier. Voordat hij één gegevensverzoek doet, kan de agent de API vragen: wat kun je? Welke gegevens heb je? Hoe hangt het allemaal samen? En de API antwoordt, volledig, correct, in een vorm die triviaal te verwerken is.

Stel je een agent voor die recente klachten van klanten over facturatie moet vinden. Hij bekijkt het schema en ontdekt een type Customer met een veld tickets, dat tickets een opsomming category hebben die BILLING bevat, dat tickets een tijdstempel createdAt en een veld status hebben, dat aan elk ticket een verbinding comments hangt. Binnen seconden heeft hij de volledige kaart van het gegevensmodel, niet uit documentatie die bijgewerkt kan zijn of niet, maar uit het levende systeem zelf.

Dat is de eigenschap die het Model Context Protocol, de norm van Anthropic waarmee AI-assistenten externe hulpmiddelen kunnen ontdekken en aanroepen, in wezen achteraf aan elk soort API probeert te geven. Een GraphQL-schema is al een manifest in MCP-vorm. Protocol en gegevensmodel ontmoeten elkaar halverwege wanneer beide dezelfde taal spreken.

Precies vragen wat je nodig hebt

REST-API’s geven vaste gegevensstructuren terug. Je roept /api/users/123 aan en je krijgt alles wat de server in een gebruikersantwoord besloot te stoppen: naam, e-mail, adres, voorkeuren, adres van de afbeelding, aanmaakdatum van het account, tijdstempel van de laatste aanmelding en veertig andere velden. Als je ook de recente bestellingen van die gebruiker nodig hebt, is dat een aparte aanroep. Als je de artikelen in die bestellingen nodig hebt, is dat nog een aanroep per bestelling.

Dat was zinnig toen elke afnemer van een API iemand in de frontend was die eigen code kon schrijven om de overtollige gegevens te behandelen en de heen-en-weerreizen te orkestreren. Het is diep inefficiënt wanneer de afnemer een agent is die onder echte beperkingen werkt.

Agenten hebben contextvensters. Elk teken aan onnodige gegevens in een antwoord is een teken dat gebruikt had kunnen worden om te denken, te plannen of andere relevante context vast te houden. Wanneer een REST-API 4 KB gebruikersgegevens teruggeeft en de agent alleen naam en e-mail nodig had, is dat niet alleen verspilde bandbreedte. Het is verspilde denkcapaciteit. Vermenigvuldig dat met elke aanroep in een gang met meerdere stappen en de context van de agent vult zich met ruis.

GraphQL neemt het probleem weg. De agent geeft precies de velden aan die hij nodig heeft:

query {
  user(id: "123") {
    name
    email
    recentOrders(first: 3) {
      status
      total
      items {
        productName
        quantity
      }
    }
  }
}

Één verzoek. Precies de nodige gegevens. Niets te veel. Niets te weinig. Geen verspilde tekens. De agent krijgt een precies antwoord dat direct op zijn informatiebehoefte past. Dat is geen optimalisatie: het is een fundamenteel ander model van gegevens ophalen, waarin de afnemer de vorm beschrijft en de server uitzoekt hoe die samen te stellen.

Het is het model waarmee slimme agenten met een gegevensbron zouden moeten kunnen omgaan. Het is het model dat GraphQL al een decennium stil laat draaien.

Één verzoek in plaats van twaalf

Het probleem van te weinig gegevens bij REST is nog pijnlijker dan dat van te veel, en daar wordt het voordeel van GraphQL het zichtbaarst.

Stel je een agent voor die een weekrapport over de stand van een team moet opleveren. Hij heeft de teamleden nodig, de taken die aan elk zijn toegewezen, de status en prioriteit van die taken, de opmerkingen bij alle taken die deze week zijn bijgewerkt en de projecten waar die taken bij horen. In een gebruikelijke REST-API is dat een waterval: de teamlijst ophalen, dan per lid de taken, dan per taak de opmerkingen en het project. Tientallen verzoeken, elk afhankelijk van het vorige. De agent moet alles orkestreren, de paginering op elk toegangspunt behandelen, met snelheidsgrenzen omgaan en gegevens uit verschillende antwoordvormen aan elkaar naaien. Heel veel opeenvolgende logica voor wat begripsmatig één vraag is.

In GraphQL is het één opvraag. Één heen en weer. Alle gegevens, netjes genest, precies in de vorm die de agent heeft gevraagd. De agent hoeft het orkestratiepatroon niet te begrijpen, geen tussenliggende toestand te beheren, geen denkmodel bij te houden van hoe de toegangspunten aan elkaar hangen. Elke uitgespaarde heen-en-weerreis is een manier van falen die verdwijnt, vertraging die je uitspaart en een stuk orkestratiecode dat de agent nooit hoeft te schrijven.

Voor een agent, die in de kern een denkmachine is die onnodige complexiteit wil beperken, is dat een enorm voordeel.

Mutaties met ingebouwde validatie

Het voordeel van GraphQL blijft niet bij het lezen van gegevens. Wanneer agenten dingen moeten doen (records aanmaken, toestand veranderen, gangen starten) bieden GraphQL-mutaties een gestructureerde, voorspelbare interface die zichzelf valideert.

Wanneer een agent via een REST-API een ondersteuningsticket aanmaakt, moet hij een POST-verzoek met een JSON-body samenstellen, maar de precieze vorm van die body (welke velden verplicht zijn, welke optioneel, welke typen verwacht worden, welke waarden geldig zijn) is alleen in externe documentatie vastgelegd. Doet hij het verkeerd, dan komt de agent daar tijdens de uitvoering achter, via een foutantwoord dat nuttig kan zijn of niet.

GraphQL-mutaties hebben getypeerde invoerobjecten. Het schema verklaart uitdrukkelijk elk argument, het type, of het verplicht is en de beschrijving. De agent kan de mutatie bekijken vóór de aanroep, met zekerheid een geldige lading samenstellen en precies de bevestigingsgegevens terugvragen die hij nodig heeft. Geen gokwerk. Geen proberen en missen. Geen wankele integraties die met hoop aan elkaar zijn genaaid.

Zo zou een machine met een toepassing moeten kunnen omgaan.

Het schema is het contract

Een GraphQL-schema is in de praktijk een door machines leesbaar manifest van de mogelijkheden. Het verklaart: hier is alles wat deze toepassing kan, hier zijn de betrokken gegevenstypen, hier is hoe ze samenhangen, hier zijn de beschikbare bewerkingen. Het is een contract tussen jouw toepassing en elk slim systeem dat haar wil gebruiken.

Wanneer een agent op een GraphQL-API stuit, heeft hij geen integratie op maat nodig. Hij heeft niemand nodig die met de hand een adapter schrijft. Hij leest het schema en begint te werken. Het schema is de integratielaag.

Dat is de eigenschap waar Archie Core rond is ontworpen. Elke toepassing die op Archie Core wordt gebouwd (frontend, backend of beide) krijgt gratis een GraphQL-schema. Niet als nagedachte, niet als bijwagen, maar als voornaamste interface. Het gevolg is niet subtiel: elke toepassing die op Archie wordt uitgebracht, is vanaf dag één klaar voor agenten, omdat de agent de taal al spreekt.

In een economie waarin steeds vaker agenten kiezen welke hulpmiddelen namens een gebruiker worden aangeroepen, is gemakkelijk zijn om mee te werken geen technisch detail. Het is een strategie om de markt te bereiken.

De eerlijke afwegingen

GraphQL kost werkelijk iets en doen alsof dat niet zo is, zou gemakzuchtig zijn. Een GraphQL-server bouwen is meer werk dan REST-toegangspunten neerzetten. Naïeve uitvoeringen kunnen buitensporig veel databaseopvragen opleveren (het N+1-probleem) en vragen patronen als DataLoader en het plannen van opvragen om dat te dempen. Tussenopslag is moeilijker dan bij de op URL’s gebaseerde bronnen van REST; je hebt strategieën op toepassingsniveau nodig zoals blijvende opvragen in plaats van te leunen op de tussenopslag in de CDN-laag. En als jouw toepassing een plat bronnenmodel met minimale relaties heeft, kan REST volstrekt toereikend zijn, ook voor agenten.

Dat zijn technische uitdagingen met bekende oplossingen, geen fundamentele grenzen. De vraag is of de kosten de voordelen van het agententijdperk waard zijn, en het antwoord is steeds vaker ja voor elke toepassing die die toekomst serieus neemt.

Bouw de API waarmee machines kunnen denken

Het argument voor API-first is dat toepassingen volledig toegankelijk moeten zijn via programmatische interfaces omdat agenten de belangrijkste afnemers worden. Het argument voor GraphQL is de natuurlijke uitbreiding: de API zou zo ontworpen moeten zijn dat slimme machines haar met minimale wrijving kunnen ontdekken, begrijpen en gebruiken.

GraphQL geeft je een schema dat zichzelf beschrijft en als levend manifest van de mogelijkheden dient. Precies gegevens ophalen dat de contextgrenzen van een agent respecteert. Getypeerde mutaties die het gokken wegnemen. Abonnementen in real time die vooruitziend gedrag mogelijk maken. Alles via één toegangspunt met één eenvormige opvraagtaal.

REST is gebouwd voor een wereld waarin mensen integraties met de hand schreven, één toegangspunt tegelijk. Die wereld bestaat nog, en REST bedient haar nog goed. Maar de wereld die opkomt, waarin agenten de mogelijkheden van toepassingen ter plekke ontdekken en samenstellen, vraagt iets expressievers, iets meer gestructureerd, iets beter te bekijken.

GraphQL is niet langer alleen een gemak voor de ontwikkeling. Het is de interfacetaal waarmee slimme agenten kunnen denken. En de toepassingen die haar spreken, zijn die waar ze zich eerst tot wenden.

Verwante lectuur

De onderbouwing van de architectuur eronder staat in de interface is een leugen, en de commerciële versie ervan in de zakelijke onderbouwing voor API-first.

Veelgestelde vragen

Waarom is GraphQL beter dan REST voor AI-agenten? GraphQL documenteert zichzelf via introspectie, laat agenten precies de velden vragen die ze nodig hebben in één heen-en-weerreis en dwingt getypeerde invoer bij mutaties. REST dwingt agenten de vorm van toegangspunten te gokken, meerdere aanroepen voor samenhangende gegevens te orkestreren en verplichte velden door proberen en missen te ontdekken.

Wat is het ontdekkingsprobleem? Het ontdekkingsprobleem zijn de kosten die een AI-agent betaalt wanneer hij bij een toepassing aankomt zonder te weten welke gegevens en bewerkingen beschikbaar zijn. REST-API’s dwingen de agent te gokken; GraphQL-API’s antwoorden met één introspectieopvraag die het volledige schema teruggeeft.

Hoe verhoudt GraphQL zich tot het Model Context Protocol (MCP)? MCP is de norm van Anthropic waarmee AI-assistenten externe hulpmiddelen kunnen ontdekken en aanroepen. Een GraphQL-schema heeft al de vorm van MCP: het levert het door machines leesbare manifest van de mogelijkheden dat MCP moet aanbieden. GraphQL-toepassingen ontmoeten het ecosysteem van agenten halverwege.

Kost GraphQL niet werkelijk iets in complexiteit? Ja. GraphQL-servers zijn complexer te bouwen dan REST-toegangspunten. Tussenopslag is moeilijker. Naïeve uitvoeringen hebben N+1-opvraagproblemen. Dat zijn technische uitdagingen met bekende oplossingen (DataLoader, blijvende opvragen, schemaplanning) en geen fundamentele grenzen.

Waarom koos Archie Core GraphQL als voornaamste API? Archie Core is zo ontworpen dat elke toepassing die erop wordt gebouwd gratis een GraphQL-schema krijgt, waardoor de toepassing vanaf dag één vindbaar en bruikbaar is voor AI-agenten. Gereedheid voor agenten is een eigenschap van de architectuur en geen later toegevoegde functie.