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 B2B-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 Foundation strikt geregelt. Es ist kein Platz für kreatives Marketing-Sprech. Es ist reine, maschinenlesbare Semantik.

Ein sauberes Manifest besteht aus vier elementaren Blöcken:

1. Protocol & Versioning: Die KI muss wissen, ob sie es mit einem Legacy-System oder modernstem Code zu tun hat. Die Deklaration von "a2a_version": "1.0.0" ist das Eintrittsticket.
2. Identity: Hier steht der Name deines Agenten, dein Unternehmen (Provider) und eine ultrakurze Beschreibung der Kernkompetenz.
3. Endpoints: Der wichtigste technische Teil. Wo genau nimmt dein Agent Anfragen entgegen? Wo liegt der API-Katalog? Das Routing muss hier präzise definiert sein.
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 die Teleschmiede das löst

Theorie ist schön und gut, aber lass uns einen Blick in den Maschinenraum werfen. Bei der Teleschmiede optimieren wir unsere eigene Infrastruktur genauso hart wie die unserer Kunden. Wir betreiben Agent Readiness auf Level 5 (dem höchsten Level im Cloudflare-Raster).

Unsere 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 unserer Konfiguration zeigt, wie kompakt und präzise die Informationen geliefert werden:

{
  "a2a_version": "1.0.0",
  "identity": {
    "name": "Teleschmiede Service Agent",
    "provider": "Teleschmiede 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"
  },
  "security": {
    "auth_required": true,
    "auth_policy": "https://teleschmie.de/.well-known/auth.md"
  }
}

Jedes fremde KI-System, das auf unsere Domain trifft, weiß durch diese simplen 15 Zeilen Code 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 B2B-Geschäft ist.

Vermeide diese fatalen Fehler

Bei der Implementierung bei unseren 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/ liegen. Punkt. Nicht im Root, nicht im /assets/ Ordner und schon gar nicht hinter einem Passwortschutz. Wenn das .well-known Verzeichnis durch deine .htaccess oder deinen Provider blockiert wird (Stichwort: IONOS oder Strato), hast du ein massives Infrastruktur-Problem.

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 (ChatGPT, Claude, oder einen spezialisierten Terminal-Agenten) 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 Agent-Ready (Level 5) zu machen, und erkläre mir, warum das Fehlen dieser Datei mich von autonomen B2B-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! 🌻✌️