agents.json erklärt: So wird deine Website maschinenlesbar

Matthias Meyer

Jede Epoche des Webs hat ihre Discovery-Dateien bekommen. Dateien, die im Hintergrund liegen und Maschinen sagen: "Hier bin ich, das kann ich." Die meisten Website-Betreiber kennen mindestens zwei davon. Aber die wenigsten wissen, dass gerade eine dritte entsteht -- und dass sie die wichtigste werden koennte.

Die Evolution der Discovery-Dateien

1994: robots.txt -- Sage den Crawlern, was sie duerfen

User-agent: *
Disallow: /admin/
Allow: /

Simpel. Effektiv. robots.txt sagt Suchmaschinen-Crawlern, welche Bereiche einer Website sie indexieren duerfen und welche nicht. Kein Webmaster dachte 1994, dass dieses Textfile jemals kritisch werden wuerde. Heute hat jede ernstzunehmende Website eins.

2005: sitemap.xml -- Zeige den Crawlern, was es gibt

<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://example.com/</loc>
    <lastmod>2026-02-15</lastmod>
    <priority>1.0</priority>
  </url>
</urlset>

robots.txt sagt, was Crawler nicht anfassen sollen. sitemap.xml sagt, was sie finden sollen. Zusammen bilden sie die Grundlage fuer SEO. Google, Bing und Co. lesen diese Dateien, bevor sie eine Website indexieren.

2026: agents.json -- Sage den KI-Agenten, was du kannst

{
  "schema_version": "1.0",
  "name": "MeinUnternehmen",
  "description": "Was wir tun",
  "url": "https://example.com",
  "tools": [
    {
      "name": "get_services",
      "description": "Alle verfuegbaren Dienstleistungen abrufen",
      "endpoint": "/api/v1/services",
      "method": "GET",
      "parameters": {}
    }
  ]
}

agents.json geht einen Schritt weiter als robots.txt und sitemap.xml. Sie sagt nicht nur "hier bin ich" oder "das darf indexiert werden". Sie sagt: "Das sind meine Faehigkeiten. So kannst du mit mir interagieren. Hier sind die Endpunkte. Hier die Parameter."

Das ist der Sprung von passiver Auffindbarkeit zu aktiver Interaktion.

Was genau steht in einer agents.json?

Eine agents.json-Datei liegt unter /.well-known/agents.json und besteht aus vier Hauptbereichen:

1. Meta-Informationen

{
  "schema_version": "1.0",
  "name": "StudioMeyer",
  "description": "Premium Web Design & Development Agency...",
  "url": "https://studiomeyer.io",
  "logo": "https://studiomeyer.io/icon.png",
  "contact": {
    "email": "hello@studiomeyer.io",
    "url": "https://studiomeyer.io/de/contact"
  }
}

Name, Beschreibung, URL, Kontakt. Nichts Ueberraschendes. Aber wichtig: Diese Informationen sind maschinenlesbar. Ein KI-Agent muss nicht raten, wer hinter der Website steckt.

2. Tools -- Das Herzstueck

Hier wird es spannend. Jedes Tool beschreibt eine konkrete Faehigkeit:

{
  "name": "browse_portfolio",
  "description": "Browse the portfolio by industry, style, or technology.",
  "endpoint": "/api/v1/portfolio",
  "method": "GET",
  "parameters": {
    "industry": {
      "type": "string",
      "description": "Industry of the project",
      "enum": ["immobilien", "gastronomie", "handwerk", "technologie"]
    },
    "style": {
      "type": "string",
      "description": "Desired design style",
      "enum": ["premium", "minimalistisch", "modern", "klassisch"]
    }
  }
}

Was der Agent hieraus liest:

Name: browse_portfolio -- eine maschinenlesbare Kennung
Description: Was das Tool tut (in natuerlicher Sprache, damit der Agent entscheiden kann, ob er es braucht)
Endpoint: Wohin die Anfrage geht (/api/v1/portfolio)
Method: HTTP-Methode (GET, POST, etc.)
Parameters: Was der Agent mitschicken kann, inklusive Typ, Beschreibung und moegliche Werte

Das ist im Grunde eine API-Dokumentation -- aber so geschrieben, dass ein KI-Agent sie ohne menschliche Hilfe verstehen und nutzen kann.

3. Capabilities

{
  "capabilities": {
    "webmcp": true,
    "a2a": true,
    "a2aEndpoint": "/api/a2a",
    "languages": ["de", "en", "es"]
  }
}

Hier steht, was die Website technisch unterstuetzt. WebMCP? A2A-Protokoll? Welche Sprachen? Ein Agent kann so vorab pruefen, ob die Website fuer seine Anfrage geeignet ist.

4. Zusammenspiel mit agent-card.json

Neben agents.json gibt es agent-card.json -- das Pendant fuer das A2A-Protokoll (Agent-to-Agent). Waehrend agents.json die Tools beschreibt, beschreibt agent-card.json die Skills:

{
  "name": "StudioMeyer",
  "protocolVersion": "0.3.0",
  "skills": [
    {
      "id": "validate-webmcp",
      "name": "Validate Agent Discovery",
      "description": "Validate agents.json against WebMCP spec...",
      "tags": ["validation", "webmcp", "agents"],
      "examples": [
        "Validate agents.json for example.com",
        "Is my agents.json spec-compliant?"
      ]
    }
  ]
}

Der Unterschied: Tools sind technisch (Endpoint + Parameter). Skills sind semantisch (Was kann ich fuer dich tun?). Beides zusammen gibt einem Agent das volle Bild.

Wie ein KI-Agent agents.json nutzt -- Schritt fuer Schritt

Nehmen wir ein konkretes Szenario. Ein Nutzer fragt seinen KI-Assistenten:

"Finde mir eine Webdesign-Agentur, die Erfahrung mit Immobilien-Websites hat, und lass dir ein Angebot fuer eine 10-seitige Website machen."

Ohne agents.json (heute der Standard)

Agent googelt "Webdesign Agentur Immobilien"
Findet Websites, liest HTML
Versucht aus Marketingtexten zu erkennen, ob Immobilien-Erfahrung vorhanden ist
Findet vielleicht ein Kontaktformular
Kann kein automatisches Angebot anfordern
Sagt dem Nutzer: "Ich habe ein paar Agenturen gefunden, hier sind die Links"

Ergebnis: Der Nutzer muss selbst weitermachen. Der Agent war im Grunde eine bessere Suchmaschine.

Mit agents.json

Agent findet Website mit agents.json
Liest die Tool-Liste: browse_portfolio mit industry-Filter
Ruft /api/v1/portfolio?industry=immobilien auf
Bekommt strukturierte Daten zurueck: Projekte mit Screenshots, Tech-Stack, Ergebnissen
Liest Tool request_quote und ruft /api/v1/quote auf mit {projectType: "website", pages: "10"}
Bekommt eine Preisschaetzung zurueck
Praesentiert dem Nutzer: "StudioMeyer hat 3 Immobilien-Projekte im Portfolio. Eine 10-seitige Website liegt bei ca. X Euro. Soll ich einen Beratungstermin buchen?"

Ergebnis: Der Agent hat die Aufgabe erledigt, nicht nur recherchiert.

Konkretes Beispiel: StudioMeyers agents.json

StudioMeyer hat neun Tools in seiner agents.json implementiert. Hier ein Ueberblick, was ein KI-Agent damit tun kann:

Tool	Was es tut	Methode
`browse_portfolio`	Portfolio nach Branche und Stil filtern	GET
`request_quote`	Preisschaetzung fuer ein Webprojekt	POST
`get_services`	Alle Services und Preise abrufen	GET
`schedule_consultation`	Beratungstermin buchen	POST
`get_case_study`	Case Studies nach Branche abrufen	GET
`validate_webmcp`	agents.json-Implementierung validieren	GET
`generate_agents_json`	agents.json fuer andere Unternehmen generieren	POST
`get_api_docs`	API-Dokumentation abrufen	GET

Das ist kein theoretisches Konzept. Diese Endpunkte existieren, sind live und liefern echte Daten. Ob ein Agent sie heute schon automatisch entdeckt? In den meisten Faellen noch nicht. Aber wenn ein Agent studiomeyer.io/.well-known/agents.json aufruft, bekommt er alles, was er braucht.

Die technische Implementierung

Fuer Entwickler: So sieht die Implementierung aus.

Die Datei bereitstellen

agents.json wird als API-Route oder statische Datei unter /.well-known/agents.json bereitgestellt. In Next.js sieht das so aus:

// app/api/well-known/agents-json/route.ts
export function GET() {
  const agentsJson = {
    schema_version: "1.0",
    name: "MeinUnternehmen",
    tools: [/* ... */],
    capabilities: { webmcp: true }
  };

  return NextResponse.json(agentsJson, {
    headers: {
      "Cache-Control": "public, max-age=86400",
      "Access-Control-Allow-Origin": "*"
    }
  });
}

Wichtig: CORS muss offen sein. KI-Agenten kommen von verschiedenen Origins. Wenn die agents.json nicht oeffentlich abrufbar ist, nuetzt sie nichts.

Die Endpunkte bauen

Jedes Tool in der agents.json verweist auf einen echten API-Endpunkt. Diese Endpunkte muessen:

Strukturiertes JSON zurueckgeben (kein HTML!)
Dokumentierte Parameter akzeptieren
Sinnvolle Fehlermeldungen liefern
Ohne Authentifizierung funktionieren (zumindest fuer lesende Zugriffe)

Das ist der eigentliche Aufwand: nicht die agents.json-Datei selbst, sondern die APIs dahinter. Wer schon eine API hat, braucht nur die Discovery-Datei. Wer keine hat, muss zuerst die Endpunkte bauen.

Was agents.json NICHT ist

Um Missverstaendnisse zu vermeiden:

Kein Ersatz fuer SEO. agents.json ersetzt nicht robots.txt, sitemap.xml oder Schema.org-Markup. Es ergaenzt sie. SEO bleibt fuer Suchmaschinen relevant. agents.json ist fuer KI-Agenten.

Kein Sicherheitsrisiko. agents.json exponiert nur das, was Sie exponieren wollen. Keine internen Daten, keine Admin-Funktionen. Nur oeffentliche Endpunkte.

Kein Universal-Standard. Stand heute gibt es keinen einheitlichen Standard, den alle Agenten unterstuetzen. agents.json ist ein Community-Vorschlag, A2A ein Google-initiiertes Protokoll, WebMCP eine W3C-Community-Group-Initiative. Die Konvergenz kommt, aber sie ist noch nicht da.

Keine Garantie fuer Traffic. Nur weil Sie agents.json haben, heisst das nicht, dass morgen KI-Agenten Ihre Website stuermen. Es ist eine Investition in die Zukunft, kein Sofort-Traffic-Booster.

Wer sollte agents.json implementieren?

Nicht jede Website braucht agents.json. Ehrlich gesagt: Ein privater Blog oder eine einfache Visitenkarten-Website hat davon wenig.

Sinnvoll ist es fuer:

Dienstleister mit buchbaren Services (Berater, Agenturen, Aerzte)
E-Commerce mit Produktkatalogen und APIs
SaaS-Unternehmen mit dokumentierten APIs
Gastronomie mit Reservierungssystemen
Immobilien mit durchsuchbaren Objektdatenbanken
Jedes Unternehmen das online Anfragen generieren will

Weniger relevant fuer:

Reine Content-Websites ohne interaktive Funktionen
Websites, die ausschliesslich ueber Formulare kommunizieren
Unternehmen ohne digitale Prozesse

Die drei Schritte zur eigenen agents.json

Schritt 1: Inventur machen

Welche Informationen und Aktionen bietet Ihre Website? Listen Sie alles auf:

Welche Daten koennte ein Agent abrufen? (Preise, Portfolio, FAQ)
Welche Aktionen koennte ein Agent ausfuehren? (Termin buchen, Angebot anfordern)
Welche bestehenden APIs gibt es schon?

Schritt 2: APIs bauen oder erweitern

Fuer jede identifizierte Faehigkeit brauchen Sie einen API-Endpunkt, der JSON zurueckgibt. Starten Sie mit den einfachsten:

/api/services -- Dienstleistungen auflisten
/api/contact -- Kontaktanfrage entgegennehmen
/api/faq -- Haeufige Fragen beantworten

Schritt 3: agents.json erstellen und deployen

Erstellen Sie die Datei unter /.well-known/agents.json, listen Sie Ihre Tools auf, und stellen Sie sicher, dass die Endpunkte funktionieren.

Oder -- und das ist der pragmatische Weg -- lassen Sie sie generieren. StudioMeyer bietet genau dafuer ein Tool an: /api/v1/generate-agents-json nimmt Branche und Unternehmensname entgegen und liefert eine fertige agents.json zurueck.

Fazit: Die naechste Discovery-Datei ist da

robots.txt hat Websites fuer Crawler sichtbar gemacht. sitemap.xml hat die Inhalte strukturiert. agents.json macht Websites fuer KI-Agenten interaktiv.

Der Standard ist jung. Die Adoption beginnt. Aber die Evolution ist klar: Websites, die mit Maschinen sprechen koennen, werden gegenueber solchen, die nur von Menschen gelesen werden, einen Vorteil haben.

Die gute Nachricht: Der Einstieg ist ueberraschend einfach. Eine JSON-Datei, ein paar API-Endpunkte, und Ihre Website spricht eine neue Sprache. Nicht die Sprache der Suchmaschinen. Sondern die Sprache der KI-Agenten.

Und die werden in den naechsten Jahren eine Menge zu sagen haben.