OpenAPI voor AI-agents

Een OpenAPI-document beschrijft een HTTP-API in machineleesbare vorm: de endpoints, de parameters die elk endpoint accepteert, de structuur van elke response en de manier van authenticeren. Een agent kan zo’n document lezen om te leren hoe een API aan te roepen die hij nog nooit heeft gezien.

Vermelde diensten met een OpenAPI-beschrijving: 23
Sites met een echt ai-plugin.json-bestand: 75 van 1.504

Van API-beschrijving naar tools

Agentframeworks en verschillende assistentplatforms kunnen de operaties in een OpenAPI-document omzetten in tools: de identifier van de operatie wordt de naam van de tool, de samenvatting en beschrijving vertellen het model wanneer de tool te gebruiken, en het parameterschema wordt de invoer van de tool. Het model vult vervolgens de parameters in, en het platform voert het HTTP-request uit.

Het pluginmanifest

Het manifest /.well-known/ai-plugin.json werd in 2023 geïntroduceerd met het pluginsysteem van ChatGPT: het noemde de dienst, beschreef die voor het model en verwees naar een OpenAPI-document. Dat pluginsysteem is inmiddels vervangen, maar sommige sites leveren het bestand nog steeds, en het geeft nog altijd aan waar hun API-beschrijving staat.

OpenAPI en MCP

OpenAPI beschrijft elke HTTP-API, ongeacht wie die aanroept. MCP is een protocol dat voor assistenten is gemaakt: de server somt zijn tools op wanneer de client verbinding maakt, en de client roept ze aan. Veel MCP-servers zijn een dunne laag boven een API die ook een OpenAPI-beschrijving heeft, en er bestaan tools die het ene uit het andere genereren.

Wat een beschrijving agentvriendelijk maakt

Duidelijke identifiers en beschrijvingen van operaties, geschreven voor iemand die de API nog nooit heeft gezien; voorbeelden; enumeraties voor toegestane waarden; gedocumenteerde fouten; een gedeclareerd authenticatieschema, niet alleen in lopende tekst uitgelegd; en kleine operaties die elk één ding doen. Een gepubliceerde, stabiele URL voor het document zorgt dat agents en directory’s het kunnen vinden.

Diensten met een OpenAPI-beschrijving · Diensten met een openbare API · Naar de directory →

Meer: Wat is een MCP-server? · Wat is llms.txt? · Zo vinden en boeken AI-assistenten reizen · Zo worden vermeldingen gecontroleerd · MCP-transports: stdio, Streamable HTTP en SSE · Extern of lokaal: welk type MCP-server gebruiken · Zo voeg je een MCP-server toe aan een AI-assistent · Wat is de officiële MCP Registry? · Wat er in een llms.txt-bestand staat · Zo vinden AI-assistenten beschikbaarheid voor reizen · Voordat je een MCP-server koppelt: een checklist