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

robots.txt vertelt crawlers al dertig jaar waar ze niet mogen komen. Dat werkte goed voor crawlers, maar AI-agents browsen, redeneren en voeren zelfstandig acties uit. Ze hebben een bestand nodig dat vertelt wat ze wel kunnen doen. agents.json is een poging daartoe.

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. Het beschrijft welke endpoints je site biedt, welke workflows agents kunnen uitvoeren, hoe ze zich authenticeren en welke tools beschikbaar zijn.

Geen enkele standaardorganisatie bezit het concept. Meerdere onafhankelijke initiatieven kwamen op hetzelfde idee uit: 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 is gebouwd voor mensen die op links klikken en API's voor ontwikkelaars die code schrijven. Een AI-agent is autonome software die moet ontdekken wat een website kan doen, moet begrijpen hoe het ermee interacteert en 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 en API-endpoints raden. Dat is fragiel en foutgevoelig. Met een agents.json bestand hoeven agents niet te raden, want je declareert wat ze kunnen doen.

Het is vergelijkbaar met iemand een menukaart geven in plaats van hem de keuken in te laten lopen. 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 kernidee van de Wildcard-spec is 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 drie auth-schema's, en een vierde staat op de roadmap:

• 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:

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 bedoeld voor agents die met andere agents praten, agents.json 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 waarmee de agent verbinding maakt. agents.json is een statisch bestand en heeft 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. Het voegt drie dingen toe: flows (meerstaps-workflows), agent-instructies (gewone-taal begeleiding voor LLM's) en geoptimaliseerde schema's (gestructureerd voor machines, niet voor documentatie). Je houdt je OpenAPI-spec en 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.

Het voorstel maakt onderscheid 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"). Agents kunnen het vinden 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, inclusief mogelijkheden, tools, runtimes en governance-beleid. agents.json beschrijft wat je API aan agents biedt, terwijl PAM agent- definities overdraagbaar maakt 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 voorstel is 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. Het zit nog in het voorstelstadium. Wordt het aangenomen, dan komt er een enkel ingangspunt in plaats van meerdere losse bestanden.

Hoe Implementeer Je agents.json

Implementeren gaat in vijf stappen, 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, zoals producten zoeken, bestellingen plaatsen, accountstatus controleren en afspraken boeken. Richt je 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 stel CORS-headers in 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. Die bestanden 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

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.

Het volwassenheidsniveau blijkt uit vijf punten:

• 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.

Meerdere afzonderlijke initiatieven (agent-permissions.json, JSON Agents, AI Card) werken aan verwante ideeën. Welke naam de uiteindelijke standaard ook krijgt, de Wildcard-spec is tot nu toe de meest concrete poging tot een "robots.txt voor mogelijkheden".

Het Nieuwe Complement van robots.txt

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

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

Een mogelijk model combineert vier bestanden:

• 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: toegangscontrole (robots.txt), contentsamenvatting (llms.txt), gestructureerde interactie (agents.json) en agent-naar-agent communicatie (agent.json).

Verwachte Evolutie

Op basis van de huidige ontwikkelingen 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?

Omdat de spec nog vroeg 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.

Praktische Implementatie-Checklist

Dit is een checklist voor de implementatie:

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 voorstel voor een web waarin je AI-agents vertelt wat je site kan doen, zodat ze niet hoeven te raden. De spec is jong, het ecosysteem is klein en geen enkel groot platform ondersteunt het officieel.

Of je er vandaag mee begint, hangt af van je situatie. Beheer je een API die agents zouden moeten gebruiken, experimenteer er dan nu mee. Beheer je een contentsite, besteed je tijd dan eerst aan gestructureerde data, semantische HTML en llms.txt. In beide gevallen helpt het om AI agent readiness te begrijpen, en het idee om naast beperkingen ook mogelijkheden te declareren.

robots.txt vertelde bots wat ze niet mogen doen. agents.json vertelt agents wat ze wel kunnen.

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 - 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