agent-card.json: Der Ausweis für KI-Agenten

Moin! 🌻

Wir schreiben das Jahr 2026. Das Internet ist nicht mehr nur ein bunter Katalog für Menschen, sondern ein hochkomplexes, verhandlungsstarkes Ökosystem für autonome Software-Agenten. Wenn wir heute über Lead-Generierung, E-Commerce-Transaktionen oder automatisierte Lieferketten sprechen, sprechen wir nicht mehr darüber, wie ein Mensch ein PDF herunterlädt. Wir sprechen darüber, wie der Einkaufs-Agent deines Kunden vollautonom mit deinem Sales-Agenten kommuniziert.

Das Problem dabei: Woher weiß der Agent deines Kunden überhaupt, dass dein Agent existiert? Und vor allem: Woher weiß er, welche “Sprache” dein Agent spricht, welche Aufgaben er ausführen kann und wo genau der digitale Briefkasten auf deinem Server hängt?

Die Antwort ist simpel, brutal effektiv und absolut standardisiert: Die agent-card.json.

Sie ist das Typenschild, der Personalausweis und das Manifest deines KI-Systems. Wer dieses kleine Stück JSON-Code im Sommer 2026 ignoriert, schließt sein Unternehmen faktisch vom lukrativsten B2B-Markt des Jahrzehnts aus. Lass uns Tacheles reden.

Der Engine-Raum der Agent-to-Agent Kommunikation

Um die Tragweite der agent-card.json zu begreifen, müssen wir uns kurz den Kontext ansehen. Seit März 2026 dominiert das A2A Protocol (Agent-to-Agent Protocol) in der Version v1.0.0 den Markt. Gesteuert durch die Linux Foundation, ist es der absolute Standard für die horizontale Kommunikation zwischen autonomen KIs.

Wenn das A2A Protocol die Autobahn ist, dann ist die agent-card.json das riesige, grell leuchtende Hinweisschild an der Ausfahrt.

Der Prozess – in der Fachsprache “A2A Discovery Flow” genannt – läuft exakt so ab:

1. Ein fremder KI-Agent (z.B. von einem großen DAX-Konzern, der nach Dienstleistern sucht) pingt deine Domain an.
2. Der Agent sucht nicht nach einer schönen Startseite. Er steuert blind und zielsicher auf den Pfad https://deinedomain.de/.well-known/agent-card.json zu.
3. Findet er diese Datei, parst er sie in wenigen Millisekunden. Er weiß sofort, wer dein Agent ist, was er kann und wie er sich authentifizieren muss, um einen Deal abzuschließen.
4. Findet er die Datei NICHT, bricht er den Prozess sofort ab. Für ihn bist du nicht “Agent Ready”. Er zieht weiter zur Konkurrenz.

Du hast in diesem Szenario keine zweite Chance. Es gibt keinen menschlichen Einkäufer, den du mit einem netten Telefonat zurückholen kannst. Die Maschine entscheidet knallhart nach Protokoll-Konformität.

Anatomie eines Personalausweises: Was steht da drin?

Die Spezifikation der agent-card.json ist durch die a2a-protocol.org strikt geregelt. Es ist kein Platz für kreatives Marketing-Sprech. Es ist reine, maschinenlesbare Semantik.

Ein sauberes Manifest besteht typischerweise aus elementaren Blöcken:

1. Protocol & Identity: Die KI muss wissen, ob sie es mit einem Legacy-System oder modernstem Code zu tun hat. Der Name deines Agenten, dein Unternehmen (Provider) und die A2A Version.
2. Endpoints (Service): Der wichtigste technische Teil. Wo genau nimmt dein Agent Anfragen entgegen? Das Routing muss hier präzise definiert sein.
3. Capabilities & Skills: Welche Features unterstützt dein Agent? Welche Aufgaben (Skills) kann er übernehmen? (z.B. Streaming, Push Notifications, SEO-Audits).
4. Security: Autonome Maschinen buchen Budgets und schließen Verträge. Sicherheit ist das A und O. Die Karte verweist hier meist auf eine externe auth.md, um komplexe Flows wie “Agent Verified” (via Identity Assertion JWT / ID-JAG) zu regeln.

Praxisbeispiel: Wie ich das löse

Theorie ist schön und gut, aber lass uns einen Blick in den Maschinenraum werfen. Auf teleschmie.de optimiere ich meine eigene Infrastruktur genauso hart wie die meiner Kunden. Ich betreibe eine vollständige Agent Readiness (Level 5 auf dem Cloudflare Radar).

Meine Live-Datei liegt genau dort, wo sie liegen muss. Wenn du wissen willst, wie so etwas in freier Wildbahn aussieht, rufe sie dir einfach auf: https://teleschmie.de/.well-known/agent-card.json.

Das ist kein Geheimnis, das ist pure Transparenz für das KI-Ökosystem. Ein Ausschnitt meiner Konfiguration zeigt, wie kompakt und präzise die Informationen geliefert werden:

{
  "$schema": "https://a2a-protocol.org/schemas/v1.0/agent-card.json",
  "a2a_version": "1.0.0",
  "identity": {
    "name": "Service Agent",
    "provider": "Jörg Zimmer",
    "description": "Autonomer Agent für SEO-Audits und Agent Readiness Beratung"
  },
  "endpoints": {
    "service": "https://teleschmie.de/api/a2a/task",
    "discovery": "https://teleschmie.de/.well-known/api-catalog"
  },
  "supportedInterfaces": ["mcp-stateless-v2"],
  "skills": ["seo-analysis", "agent-readiness-audit"],
  "security": {
    "auth_required": true,
    "auth_policy": "https://teleschmie.de/auth.md"
  }
}

Jedes fremde KI-System, das auf meine Domain trifft, weiß durch diese simplen Codezeilen sofort, dass es mit einem hochprofessionellen, protokolltreu agierenden Partner zu tun hat. Das schafft “Machine Trust” – das maschinelle Vertrauen, das die Basis für jedes zukünftige Geschäft ist.

Vermeide diese fatalen Fehler

Bei der Implementierung bei meinen Kunden sehe ich oft die gleichen handwerklichen Fehler, die dazu führen, dass der gesamte A2A-Flow zusammenbricht:

Fehler 1: Der falsche Speicherort Die Datei MUSS im Verzeichnis /.well-known/agent-card.json liegen. Punkt. Nicht im Root als agent.json, nicht im /assets/ Ordner und schon gar nicht hinter einem Passwortschutz. Wenn das .well-known Verzeichnis durch deinen Provider (Stichwort: IONOS) blockiert wird, musst du über das Skript activate_htaccess.php deine Regeln aktualisieren.

Fehler 2: CORS Header vergessen Ein fremder Agent im Browser-Kontext will deine Datei per JavaScript abrufen. Wenn dein Webserver die Header nicht auf Access-Control-Allow-Origin: * für diesen speziellen Ordner setzt, scheitert der Abruf am CORS-Fehler. Das ist Anfänger-Pfusch.

Fehler 3: Das Manifest als Marketing-Fläche missbrauchen Die agent-card.json ist keine Werbebroschüre. Packe keine 500 Wörter SEO-Texte in das Feld “description”. Maschinen belohnen Präzision, nicht Geschwafel.

Der Selbsttest: Ist deine Domain A2A-Ready?

Du musst mir nicht glauben. Du kannst die Agent Readiness deiner eigenen Website in exakt 30 Sekunden selbst überprüfen. Schnapp dir dein bevorzugtes KI-Tool und lass ihn die harte Arbeit machen.

Dieser Test zeigt dir schonungslos, wie blind deine Infrastruktur für den B2B-Markt von morgen ist, wenn du das Thema ignorierst.

Der universelle KI-Prompt zur Prüfung

Kopiere den folgenden Prompt 1:1 und führe ihn aus. Er ist komplett universell geschrieben und benötigt keinerlei Anpassungen. Der Agent wird dich nach deiner Domain fragen und dir dann die Wahrheit auf den Tisch legen.

Prompt für deinen KI-Agenten:

Starte einen strengen technischen A2A Discovery Audit für meine Domain. Prüfe, ob im Root-Verzeichnis unter `/.well-known/agent-card.json` ein gültiges JSON-Manifest (A2A Protocol v1.0.0 Standard der Linux Foundation) existiert. 
- Falls die Datei vorliegt: Validiere das JSON-Schema, überprüfe die CORS-Header auf globale Erreichbarkeit und checke die referenzierten Security-Endpoints (wie die `auth.md`).
- Falls die Datei NICHT vorliegt oder ungültig ist: Erstelle einen kritischen Mängelbericht für mich als Geschäftsführer. Schreibe mir exakt den JSON-Code, den ich brauche, um meine Infrastruktur sofort komplett AI-Ready zu machen, und erkläre mir, warum das Fehlen dieser Datei mich von autonomen geschäftlichen Transaktionen abschneidet.

Es ist Zeit aufzuwachen. Wer heute noch Webseiten ausschließlich für den Chrome-Browser baut, hat den Paradigmenwechsel verschlafen. Mach deine Domain fit für die Agenten-Ökonomie.

ALOHA! 🌻✌️