Wat is agents.json? AI Agent-mogelijkheden op je website adverteren

robots.txt bestaat al dertig jaar. Een simpel tekstbestand dat crawlers vertelt waar ze niet mogen komen. Prima, werkte goed. Maar AI-agents zijn geen crawlers meer. Het zijn autonome actoren die browsen, redeneren en acties uitvoeren. En dan heb je een ander soort bestand nodig, eentje dat agents vertelt wat ze wel kunnen doen. Dat is waar agents.json om de hoek komt kijken.

Wat Is agents.json?

agents.json is een machineleesbaar JSON-bestand dat beschrijft wat AI-agents kunnen doen op of met je website. Waar robots.txt een lijst van beperkingen is, is agents.json een lijst van mogelijkheden. Welke endpoints je site biedt, welke workflows agents kunnen uitvoeren, hoe ze zich authenticeren, welke tools beschikbaar zijn.

Het concept komt niet van een enkele standaardorganisatie. Meerdere onafhankelijke initiatieven zijn onafhankelijk op hetzelfde idee uitgekomen: een vindbaar JSON-bestand op /.well-known/agents.json, een soort machineleesbaar visitekaartje voor AI-agents die je domein bezoeken. De meest prominente variant is de agents.json-specificatie van Wildcard AI , een open-source project (v0.1.0) dat OpenAPI uitbreidt met agent-specifieke metadata.

Waarom agents.json Ertoe Doet

Het web was gebouwd voor mensen die op links klikken. API's voor ontwikkelaars die code schrijven. AI-agents zijn geen van beide. Het is autonome software die moet ontdekken wat een website kan doen, moet begrijpen hoe het ermee interacteert, en vervolgens meerstaps-workflows moet uitvoeren. Zonder dat er een mens aan te pas komt.

Op dit moment moet een AI-agent die je website bezoekt je mogelijkheden reverse-engineeren. HTML lezen, API-endpoints raden, hopen dat het werkt. Fragiel, foutgevoelig, inefficient. Met een agents.json bestand draai je dat om: in plaats van dat agents moeten raden, declareer je wat ze kunnen doen.

Vergelijk het met iemand een menukaart geven versus ze de keuken in laten dwalen. De menukaart wint altijd. agents.json is die menukaart voor AI-agents.

De Wildcard agents.json-Specificatie

De meest uitgewerkte agents.json specificatie komt van Wildcard AI , een Y Combinator-startup die API's bruikbaar wil maken voor AI-agents. Hun spec (v0.1.0, Apache 2.0) bouwt voort op OpenAPI met drie toevoegingen:

Flows en Links

Het interessantste idee in de Wildcard-spec is het concept van flows (ook wel "chains") en links. Een flow beschrijft een complete workflow: een reeks API-aanroepen die samen een resultaat opleveren. Links leggen vast hoe die stappen met elkaar verbonden zijn. Output van stap 1 wordt input voor stap 2.

{
  "apiVersion": "0.1.0",
  "baseUrl": "https://api.example.com",
  "info": {
    "title": "Example API for Agents",
    "description": "Manage orders and customers"
  },
  "chains": {
    "create_order": {
      "description": "Create a new order for an existing customer",
      "agent_instructions": "Look up the customer first, then create the order",
      "steps": [
        {
          "endpoint": "/customers/search",
          "method": "GET",
          "parameters": {
            "query": "$user_input.customer_name"
          }
        },
        {
          "endpoint": "/orders",
          "method": "POST",
          "parameters": {
            "customer_id": "$prev.results[0].id",
            "items": "$user_input.items"
          }
        }
      ]
    }
  }
}

De create_order chain hierboven beschrijft een tweestaps-workflow: zoek een klant, maak dan een bestelling aan met dat klant-ID. Het agent_instructions veld geeft het LLM context in gewone taal om de intentie te snappen. De stappen definieren de exacte API-aanroepen.

Authenticatie

De spec ondersteunt meerdere auth-schema's, de gebruikelijke verdachten:

• API Key: Sleutel meegegeven in een header, queryparameter of cookie
• Bearer Token: Standaard OAuth 2.0 bearer tokens
• Basic Auth: Gebruikersnaam/wachtwoord-combinatie
• OAuth: Volledige OAuth-flows (op de roadmap voor v0.2)

Ontwerpprincipes

De Wildcard-spec hanteert vier principes die het onderscheiden van de rest:

1. Bouw voort op OpenAPI: Vind het wiel niet opnieuw uit. Breid bestaande API-documentatie uit.
2. Optimaliseer voor LLM's: Structureer het schema voor machineconsumptie, niet voor menselijke leesbaarheid.
3. Stateless by design: Agents beheren hun eigen orchestratie. De specificatie definieert wat te doen, niet hoe sessies te beheren.
4. Minimale API-wijzigingen: Het toevoegen van agents.json zou geen wijzigingen aan je bestaande API moeten vereisen.

Hoe agents.json Zich Verhoudt tot Andere Ontdekkingsformaten

Er zijn inmiddels meerdere agent-gerelateerde JSON-bestanden op het web, en ze lijken op het eerste gezicht op elkaar. Maar elk lost een ander probleem op:

agents.json vs A2A's agent.json

Google's Agent-to-Agent (A2A) protocol gebruikt een "Agent Card" op /.well-known/agent.json voor agent-naar-agent communicatie. Het verschil zit 'm in de richting: A2A's agent.json beschrijft wat een agent is (identiteit, vaardigheden, ondersteunde modi). agents.json beschrijft wat een API kan doen voor agents (endpoints, workflows, auth). A2A is voor agents die met andere agents praten. agents.json is voor agents die met jouw API praten.

agents.json vs MCP

Anthropic's Model Context Protocol (MCP) biedt een stateful verbinding tussen een AI-model en externe tools. Er moet een MCP-server draaien, de agent verbindt zich daarmee. agents.json is een statisch bestand. Geen server nodig. Zoals Nordic APIs opmerkt , mist MCP "een vindbaarheidslaag" en werkt het waarschijnlijk het best in combinatie met iets als agents.json dat het ontdekkingsprobleem oplost.

agents.json vs OpenAPI

OpenAPI documenteert API's voor menselijke ontwikkelaars. agents.json voegt daar een laag bovenop voor AI-agents. De toevoegingen: flows (meerstaps-workflows), agent-instructies (gewone-taal begeleiding voor LLM's) en geoptimaliseerde schema's (gestructureerd voor machines, niet voor documentatie). Je vervangt je OpenAPI-spec niet. Je bouwt agents.json erop.

Gerelateerde Initiatieven om in de Gaten te Houden

Het idee van machineleesbare agent-mogelijkheden wordt vanuit meerdere hoeken verkend. Naast Wildcard zijn er nog een paar projecten die aangrenzende problemen aanpakken:

agent-permissions.json

De Lightweight Agent Standards Working Group (LAS-WG) ontwikkelt agent-permissions.json, een voorstel gepubliceerd op arXiv voor een "robots.txt-achtig toestemmingsmanifest voor webagents." agents.json declareert mogelijkheden. agent-permissions.json declareert toestemmingen: wat agents mogen doen op specifieke pagina's, tot op individuele HTML-elementen.

Er zit een mooi onderscheid in tussen resource-niveau regels (machinaal afdwingbaar, zoals "klik niet op deze knop") en actie-niveau richtlijnen (gedragsinstructies, zoals "gebruik _bot aan het einde van gebruikersnamen bij registratie"). Vindbaar via een <link rel="agent-permissions"> tag of op /.well-known/agent-permissions.json.

JSON Agents (Portable Agent Manifest)

Het JSON Agents-project definieert een Portable Agent Manifest (PAM): een framework-onafhankelijk formaat voor het beschrijven van AI-agents zelf. Mogelijkheden, tools, runtimes, governance-beleid. agents.json richt zich op wat je API biedt aan agents. PAM richt zich op het overdraagbaar maken van agent- definities tussen frameworks als LangChain, AutoGen en MCP.

AI Card (Uniforme AI-Servicemetadata)

Het AI Card-initiatief wil de wildgroei aan agent-ontdekkingsbestanden bundelen in een enkele standaard. Het idee: een enkel /.well-known/ai-card.json dat metadata bevat voor alle protocollen die een server ondersteunt (MCP, A2A, custom API's) op een plek. Nog in het voorstelstadium, maar de richting is duidelijk: een uniform ingangspunt in plaats van vijf losse bestanden.

Hoe Implementeer Je agents.json

Implementeren is niet ingewikkeld. Hier is een stapsgewijze aanpak op basis van de Wildcard-spec:

Stap 1: Inventariseer Je API-Mogelijkheden

Maak een lijst van elk endpoint dat je wilt openstellen voor AI-agents. Producten zoeken, bestellingen plaatsen, accountstatus controleren, afspraken boeken. Focus op taken die een agent namens een gebruiker zou uitvoeren.

Stap 2: Definieer Agent Flows

Definieer voor elke gebruikerstaak de volgorde van API-aanroepen. Groepeer gerelateerde endpoints in benoemde chains met duidelijke beschrijvingen en instructies die een LLM kan snappen:

{
  "apiVersion": "0.1.0",
  "baseUrl": "https://api.mystore.com/v1",
  "info": {
    "title": "MyStore API",
    "description": "E-commerce API for product search, cart management, and checkout"
  },
  "auth": {
    "type": "bearer",
    "description": "OAuth 2.0 access token required for cart and checkout operations"
  },
  "chains": {
    "search_products": {
      "description": "Search the product catalog by keyword, category, or price range",
      "agent_instructions": "Use this to help users find products. Supports filtering by category and price.",
      "steps": [
        {
          "endpoint": "/products/search",
          "method": "GET",
          "parameters": {
            "q": "$user_input.query",
            "category": "$user_input.category",
            "min_price": "$user_input.min_price",
            "max_price": "$user_input.max_price"
          }
        }
      ]
    },
    "add_to_cart_and_checkout": {
      "description": "Add a product to the cart and proceed to checkout",
      "agent_instructions": "First add the item to the cart, then initiate checkout. Requires auth.",
      "steps": [
        {
          "endpoint": "/cart/items",
          "method": "POST",
          "parameters": {
            "product_id": "$user_input.product_id",
            "quantity": "$user_input.quantity"
          }
        },
        {
          "endpoint": "/checkout",
          "method": "POST",
          "parameters": {
            "cart_id": "$prev.cart_id"
          }
        }
      ]
    }
  }
}

Stap 3: Host het Bestand

Plaats je agents.json bestand op het well-known pad van je domein:

https://yourdomain.com/.well-known/agents.json

Serveer het met Content-Type: application/json en vergeet de CORS-headers niet als agents het vanaf andere origins benaderen.

Stap 4: Verwijs Naar Je OpenAPI-Specificatie

Heb je al een OpenAPI-spec? Verwijs ernaar vanuit je agents.json zodat agents toegang krijgen tot de gedetailleerde typedefinities. De agents.json-flows zijn de "wat te doen"-laag, OpenAPI is de "hoe het werkt"-laag:

{
  "apiVersion": "0.1.0",
  "baseUrl": "https://api.example.com",
  "info": {
    "title": "Example API",
    "openapi_spec": "https://api.example.com/openapi.json"
  },
  "chains": {
    "get_user_profile": {
      "description": "Retrieve a user profile by ID",
      "agent_instructions": "Use this when the user wants to view profile information",
      "steps": [
        {
          "endpoint": "/users/{user_id}",
          "method": "GET"
        }
      ]
    }
  }
}

Stap 5: Test en Itereer

Gebruik de Wildcard Bridge SDK (Python 3.10+) om je agents.json te valideren en agent-interacties te testen:

pip install wildcard-bridge

from wildcard_bridge import AgentsJSON

# Load and validate your spec
spec = AgentsJSON.from_url("https://yourdomain.com/.well-known/agents.json")

# List available chains
for chain_name, chain in spec.chains.items():
    print(f"{chain_name}: {chain.description}")

Wie Gebruikt agents.json?

Volgens de Nordic APIs-vergelijking heeft Wildcard agents.json-bestanden gepubliceerd voor grote API-aanbieders, waaronder Resend, Alpaca, Slack, HubSpot en Stripe. Belangrijk detail: die worden niet onderhouden door de API-aanbieders zelf. Wildcard heeft ze gemaakt om het formaat te demonstreren.

OpenBB, een financieel dataplatform, heeft het formaat ook geadopteerd met hun eigen agents.json-referentie voor het beschrijven van AI-agents die verbinding maken met hun workspace.

Huidige Status en Volwassenheid

Even eerlijk zijn: agents.json is het minst gestandaardiseerd van de agent-ontdekkingsformaten. A2A heeft Google erachter met een formele protocolspec. MCP heeft Anthropic met een groeiend ecosysteem. agents.json is een community-voorstel, gedreven door een startup.

Wat we weten over het volwassenheidsniveau:

• Geen formele RFC: Er is geen IETF-draft of W3C-voorstel voor agents.json. Het is een open-source project op GitHub.
• Enkele primaire auteur: Wildcard AI drijft de specificatie. Community-bijdragen bestaan maar zijn beperkt.
• Geen browser- of platformondersteuning: Geen enkel groot AI-platform (OpenAI, Google, Anthropic) consumeert officieel agents.json-bestanden.
• Onvolledige tooling: De Wildcard Bridge SDK is de primaire tool. Alternatieven zijn schaars.
• Actieve ontwikkeling: De roadmap omvat geheugenbeheer, veldtransformaties, rate limiting en conditionele logica.

Dat gezegd hebbende: het concept achter agents.json wint aan momentum vanuit meerdere richtingen. Of de uiteindelijke standaard agents.json, ai-card.json of iets heel anders gaat heten maakt eigenlijk niet zoveel uit. Het web heeft een "robots.txt voor mogelijkheden" nodig, en de Wildcard-spec is de meest concrete poging tot nu toe.

Het Nieuwe Complement van robots.txt

Dertig jaar lang was het contract tussen sites en bots eenrichtingsverkeer. "Dit mag je niet doen." Met robots.txt blokkeerden site-eigenaren paden, beperkten crawlsnelheden en vertelden bots welke pagina's ze moesten negeren. Prima model, simpele tijden.

Het AI-agent tijdperk vraagt om een tweerichtingscontract. Sites moeten nog steeds grenzen stellen (robots.txt, agent-permissions.json), maar ze moeten ook mogelijkheden adverteren. Een AI-agent die een vlucht boekt, verzekeringen vergelijkt of een abonnement beheert, moet weten wat er kan. Niet alleen wat er niet mag.

Het model dat zich aftekent:

• robots.txt - Wat crawlers niet mogen benaderen (beperkingen)
• llms.txt - Waar je site over gaat (contentsamenvatting voor LLM's)
• agents.json - Wat agents kunnen doen (mogelijkheden en workflows)
• agent.json - Wat jouw agent is (identiteit voor agent-naar-agent communicatie)

Samen vormen deze bestanden een gelaagd ontdekkingssysteem. Van basale toegangscontrole, naar contentbegrip, naar gestructureerde interactie, naar samenwerking tussen agents.

Verwachte Evolutie

Het landschap beweegt snel. Op basis van de huidige trajecten verwacht ik het volgende:

Korte termijn (2026)

• Wildcard agents.json bereikt v0.2 met OAuth-ondersteuning en conditionele logica
• Meer API-aanbieders publiceren hun eigen agents.json-bestanden (in plaats van dat Wildcard het voor hen doet)
• De LAS-WG agent-permissions.json wint aan tractie als complementaire standaard
• AI-platformen beginnen te experimenteren met het consumeren van capability-bestanden tijdens het browsen

Middellange termijn (2026-2027)

• Convergentie tussen concurrerende formaten, mogelijk via het AI Card-initiatief of een vergelijkbare unificatie-inspanning
• Grote AI-platformen (OpenAI, Google, Anthropic) beginnen officieel een capability discovery-standaard te ondersteunen
• Mogelijke IETF- of W3C-werkgroep voor agent-webinteractie-standaarden

Lange termijn (2027+)

• Een uniforme agent-ontdekkingsstandaard ontstaat, mogelijk met elementen van agents.json, A2A en MCP
• Browser-niveau ondersteuning voor agent-capability-bestanden, vergelijkbaar met hoe browsers robots.txt afhandelen
• Agent-bewuste webframeworks genereren automatisch capability-bestanden vanuit API-definities

Wie Zou agents.json Moeten Implementeren?

Gezien hoe vroeg het nog is, levert het implementeren van agents.json het meeste op voor:

• API-first bedrijven die willen dat AI-agents hun diensten betrouwbaar consumeren
• SaaS-platformen die AI-agent-integraties bouwen naast hun MCP- of A2A-ondersteuning
• E-commerce sites die willen dat agents namens gebruikers zoeken, vergelijken en transacties uitvoeren
• Developer tool-aanbieders wier API's frequent worden gebruikt door coding agents en AI-assistenten
• Early adopters die klaar willen zijn wanneer AI-platformen capability-bestanden gaan consumeren

Heb je een contentgerichte website zonder API's (blog, portfolio, informatieve site)? Dan is agents.json minder relevant voor je. Focus eerst op gestructureerde data, llms.txt en semantische HTML . Die hebben bredere ondersteuning en meer directe impact.

Praktische Implementatie-Checklist

Ga je ermee aan de slag? Hier is een beknopte checklist:

1. Begin met je bestaande OpenAPI-specificatie (of maak er een als je die nog niet hebt)
2. Identificeer de top 5-10 workflows die agents zouden willen uitvoeren
3. Schrijf chains met duidelijke agent_instructions voor elke workflow
4. Definieer je authenticatieschema
5. Host het bestand op /.well-known/agents.json
6. Stel passende CORS-headers in voor cross-origin toegang
7. Test met de Wildcard Bridge SDK
8. Monitor en itereer naarmate de specificatie evolueert

De Conclusie

agents.json is een weddenschap op een web waar AI-agents niet hoeven te raden wat je site kan doen, omdat je het ze gewoon vertelt. De spec is jong, het ecosysteem is klein, geen enkel groot platform ondersteunt het officieel. Maar de behoefte is er wel, en die groeit.

Of je er vandaag mee aan de slag gaat hangt af van je situatie. Beheer je een API die agents zouden moeten gebruiken? Experimenteer er nu mee. Beheer je een contentsite? Dan is je tijd beter besteed aan gestructureerde data, semantische HTML en llms.txt. Hoe dan ook, het begrijpen van AI agent readiness en het idee van mogelijkheden declareren (niet alleen beperkingen) is de richting die het web opgaat.

robots.txt vertelde bots wat ze niet mogen doen. agents.json vertelt agents wat ze wel kunnen. Dat contract wordt herschreven.

Bronnen

• Wildcard AI - agents.json GitHub Repository - Open-source specificatie (v0.1.0) voor agent-API interactiecontracten
• Nordic APIs - Comparing 7 AI Agent-to-API Standards - Uitgebreide vergelijking inclusief agents.json, MCP, A2A en meer
• Hacker News - Show HN: Agents.json – OpenAPI Specification for LLMs - Communitydiscussie over de agents.json-specificatie
• agents.json: an open source specification for AI-API interaction - Overzicht van agents.json-ontwerp en -implementatie
• LAS-WG - agent-permissions.json - Robots.txt-achtig toestemmingsmanifest voor webagents
• Permission Manifests for Web Agents (arXiv) - Academisch paper van de Lightweight Agent Standards Working Group
• JSON Agents - Portable Agent Manifest Specification - Framework-onafhankelijk formaat voor agentbeschrijvingen
• AI Card - Unified AI Service Metadata Standard - Voorstel voor een uniform agent-ontdekkingsformaat
• OpenBB - agents.json Reference - Praktische agents.json-implementatie voor financiele data
• A2A Protocol - Agent Discovery - Google's benadering van agent-ontdekking via Agent Cards
• Google Cloud - Trends in Agent Discoverability and Interoperability - Overzicht van het agent-ontdekkingslandschap
• From robots.txt to agents.json: Web for AI-Agents - Visie op agents.json als de volgende evolutie van web-botcontracten