ai-plugin.json Generator
Veröffentlichen Sie Ihre API für KI-Agenten mit einem gültigen Manifest.
Kurzantwort
ai-plugin.json ist das Manifest, das Ihre API als aufrufbares Tool für KI-Assistenten bereitstellt und unter /.well-known/ai-plugin.json gehostet wird. Dieser Generator erstellt ein gültiges Manifest mit Ihrem Namen, der description-for-model, dem Authentifizierungstyp und der OpenAPI-URL, damit Agenten Ihre Endpunkte entdecken und aufrufen können.
Der interaktive Generator selbst läuft auf Englisch – alles, was Sie zum Verständnis und zur Nutzung benötigen, wird auf dieser Seite erklärt.
Ihre API für KI-Agenten bereitstellen
Das `ai-plugin.json`-Manifest dient als grundlegende Schnittstelle zwischen Ihrer API und dem schnell wachsenden Ökosystem der KI-Assistenten. Gehostet unter dem festen Pfad `/.well-known/ai-plugin.json`, ist diese JSON-Datei nicht nur Metadaten; sie ist ein entscheidendes Tor. Unser Generator stellt sicher, dass Ihr Manifest strikt der OpenAPI Specification (OAS)-Referenzierung folgt, was Modellen wie GPT-4 und Googles Gemini ermöglicht, Ihre Funktionen präzise zu verstehen und aufzurufen. Eine korrekte Generierung ist für eine nahtlose Integration unerlässlich, um `invalid_manifest`-Fehler zu verhindern und zuverlässige Tool-Aufrufe zu gewährleisten.
Entscheidende `description_for_model`-Erstellung
Das Feld `description_for_model` innerhalb von `ai-plugin.json` ist wohl das wirkungsvollste für die KI-gesteuerte Tool-Nutzung. Dieser prägnante String (typischerweise unter 200 Zeichen) liefert den prompt-entwickelten Kontext für das LLM, um zu entscheiden, wann und wie Ihre API aufgerufen werden soll. Unser Generator unterstützt Sie bei der Erstellung präziser, handlungsorientierter Beschreibungen, wie z.B. „Verwenden Sie dieses Plugin, um Echtzeit-Aktienkurse für ein bestimmtes Wertpapiersymbol abzurufen“, anstatt vager Allgemeinheiten. Diese Spezifität beeinflusst direkt die Neigung des LLMs, Ihr Tool aufzurufen.
Authentifizierung & OpenAPI URL Konfiguration
Die sichere Bereitstellung Ihrer API für KI-Agenten erfordert eine sorgfältige Authentifizierungskonfiguration. Die `ai-plugin.json` unterstützt verschiedene `auth`-Typen, darunter `none`, `oauth` (OAuth 2.0 Client Credentials Grant) und `service_http` (Bearer-Token oder Basic Auth). Unser Generator erleichtert die Auswahl und Konfiguration dieser, um sicherzustellen, dass Ihre Endpunkte geschützt, aber für autorisierte Agenten zugänglich sind. Gleichzeitig validiert er den `api.url`-Eintrag und bestätigt, dass dieser auf eine live verfügbare, auffindbare OpenAPI/Swagger-Spezifikation (z.B. `https://api.example.com/openapi.yaml`) verweist, was für das Verständnis des Modells unerlässlich ist.
Warum der `/.well-known/`-Pfad entscheidend ist
Die Platzierung von `ai-plugin.json` im Pfad `/.well-known/` ist nicht willkürlich; es ist ein Standard, der durch RFC 8615 für die Host-Meta-Erkennung definiert ist. Dieser vorhersehbare Speicherort ermöglicht es KI-Agenten-Crawlern (wie `ChatGPT-User` oder `Google-Extended`), Ihr Manifest effizient ohne explizite Konfiguration zu finden und abzurufen. Dieser standardisierte Erkennungsmechanismus minimiert Latenz und Overhead für Agenten, wodurch Ihre API jedem KI-System, das Tools an diesem spezifischen und weit verbreiteten URI sucht, sofort zur Verfügung steht.
Häufige Fallstricke bei der ai-plugin.json-Generierung
| Problem | Auswirkung | Minderungsstrategie | Crawler-Antwort |
|---|---|---|---|
| Fehlerhaftes JSON | Fehler beim Parsen des Manifests, API nicht auffindbar | Verwenden Sie einen Linter oder Generator zur strikten JSON-Validierung | `HTTP 400 Bad Request` oder `Invalid JSON`-Fehler in Agenten-Logs. |
| Falsche OpenAPI-URL | API-Funktionen dem LLM unbekannt | Überprüfen Sie, ob `api.url` auf eine aktive, gültige OpenAPI-Spezifikation verweist | `API spec not found` oder `Unparseable OpenAPI`-Warnungen. |
| Vage `description_for_model` | Geringe Nutzung durch LLMs | Erstellen Sie prägnante, handlungsorientierte Beschreibungen (50-150 Zeichen) | LLM wählt Tool nicht aus oder missinterpretiert die Absicht. |
| Fehlende Pflichtfelder | Ablehnung des Manifests | Stellen Sie sicher, dass `name_for_model`, `name_for_human`, `description_for_model`, `api` und `auth` vorhanden sind | `Missing required field` oder `Manifest schema validation failed`. |
| Kein `/.well-known`-Pfad | Manifest nicht durch Standard-Crawler auffindbar | Stellen Sie `ai-plugin.json` strikt unter `/.well-known/ai-plugin.json` bereit | Crawler überspringt Host, API bleibt Agenten unbekannt. |
Wichtige Überlegungen für Ihr ai-plugin.json
- Stellen Sie sicher, dass `name_for_model` ein prägnanter, eindeutiger Bezeichner ist (z.B. `stock_price_api`).
- Vergewissern Sie sich, dass `description_for_model` für die LLM-Interpretation klar, prägnant und handlungsorientiert ist.
- Bestätigen Sie, dass Ihre `api.url` auf eine öffentlich zugängliche, gültige OpenAPI 3.0- oder 3.1-Spezifikation verweist.
- Implementieren Sie die passende `auth`-Konfiguration (z.B. `service_http` für Bearer-Token).
- Stellen Sie die `ai-plugin.json`-Datei ausschließlich unter dem Pfad `/.well-known/ai-plugin.json` bereit.
- Überprüfen Sie `legal_info_url` und `contact_email` auf Konformität und Support.
- Validieren Sie Ihr generiertes Manifest regelmäßig mit Tools zur Schema-Konformität.
- Testen Sie API-Aufrufe mit einem echten KI-Agenten (z.B. ChatGPT Plugins) vor der vollständigen Bereitstellung.
Schritte zur Bereitstellung Ihres AI Plugin Manifests
- 1Definieren Sie die Kernfunktionalität der API
Artikulieren Sie klar die spezifischen Aktionen, die Ihre API ermöglicht. Identifizieren Sie wichtige Endpunkte, Parameter und erwartete Antworten. Diese Klarheit wird direkt die `description_for_model` und die OpenAPI-Spezifikation beeinflussen. Konzentrieren Sie sich darauf, was KI-Agenten mit Ihrer API *tun* können, nicht nur darauf, was sie *ist*.
- 2OpenAPI-Spezifikation generieren
Erstellen Sie eine umfassende OpenAPI-Definition (OAS 3.0/3.1) für Ihre API. Diese Spezifikation beschreibt alle Endpunkte, Methoden, Parameter und Datenmodelle. Stellen Sie sicher, dass sie präzise und aktuell ist, da KI-Agenten dieses Dokument parsen werden, um die Fähigkeiten Ihrer API zu verstehen und Anfragen zu konstruieren.
- 3Manifest-Details konfigurieren
Verwenden Sie den Generator, um Ihre `name_for_model`, `description_for_model`, `auth`-Typ (z.B. `service_http` für API-Schlüssel), `logo_url`, `legal_info_url` und `contact_email` einzugeben. Achten Sie besonders auf die Erstellung der `description_for_model` für ein optimales Verständnis und den Aufruf Ihres Plugins durch das LLM.
- 4Generiertes JSON validieren
Vor der Bereitstellung validieren Sie die ausgegebene `ai-plugin.json` sorgfältig anhand des offiziellen Schemas. Prüfen Sie auf Syntaxfehler, fehlende Felder und korrekte URL-Formate. Stellen Sie sicher, dass die `api.url` präzise auf Ihre gehostete OpenAPI-Spezifikation verweist, um Erkennungsprobleme durch KI-Agenten wie `ChatGPT-User` zu vermeiden.
- 5Manifest unter `/.well-known/` bereitstellen
Hosten Sie die generierte `ai-plugin.json`-Datei unter der exakten URI `YOUR_DOMAIN/.well-known/ai-plugin.json`. Dieser Standardpfad ist entscheidend, damit KI-Agenten-Crawler Ihr Plugin automatisch ohne vorherige Kenntnis entdecken können. Eine falsche Platzierung macht Ihr Plugin für die meisten KI-Systeme unentdeckbar.
- 6Überwachen und Iterieren
Überwachen Sie nach der Bereitstellung die API-Nutzung und die Interaktionsprotokolle der Agenten. Achten Sie darauf, wie oft Ihr Plugin aufgerufen wird und ob Parsing-Fehler auftreten. Nutzen Sie dieses Feedback, um Ihre `description_for_model` und die OpenAPI-Spezifikation zu verfeinern und so eine optimale Leistung und zuverlässige Integration von KI-Agenten im Laufe der Zeit zu gewährleisten.
Häufig gestellte Fragen
- Was ist `ai-plugin.json` und warum ist es wichtig für meine API?
- `ai-plugin.json` ist eine standardisierte Manifestdatei, die als Bauplan für KI-Agenten (wie die, die ChatGPT oder Gemini antreiben) dient, um Ihre API zu entdecken und zu verstehen. Sie ist entscheidend, da sie es Ihren Diensten ermöglicht, als aufrufbare Tools innerhalb von KI-Ökosystemen zu fungieren, wodurch die Reichweite und Nützlichkeit Ihrer API erheblich erweitert wird, indem LLMs programmgesteuert im Auftrag von Benutzern mit ihr interagieren können.
- Wo genau muss die `ai-plugin.json`-Datei gehostet werden?
- Die `ai-plugin.json`-Datei muss genau unter dem Pfad `/.well-known/ai-plugin.json` relativ zu Ihrer Domain gehostet werden. Wenn Ihre Domain beispielsweise `example.com` ist, sollte die Datei unter `https://example.com/.well-known/ai-plugin.json` zugänglich sein. Dieser standardisierte Speicherort ist entscheidend, damit KI-Crawler Ihr Plugin-Manifest zuverlässig finden und indizieren können.
- Was ist der Zweck von `description_for_model` im Vergleich zu `description_for_human`?
- `description_for_model` bietet eine prägnante, handlungsorientierte Zusammenfassung speziell für das LLM, um zu verstehen, wann und wie Ihre API aufgerufen werden soll (z.B. „Wetterdaten für einen Standort abrufen“). `description_for_human` ist eine benutzerfreundliche, längere Beschreibung, die menschlichen Benutzern in Plugin-Marktplätzen oder Verzeichnissen angezeigt wird. Ersteres steuert den KI-Aufruf, letzteres informiert die Benutzerwahl.
- Welche Authentifizierungstypen werden in `ai-plugin.json` unterstützt?
- Der `ai-plugin.json`-Standard unterstützt mehrere Authentifizierungstypen: `none` für nicht authentifizierte APIs, `oauth` für den OAuth 2.0 Client Credentials Flow und `service_http` für API-Schlüssel-basierte Authentifizierung (entweder über einen Bearer-Token im `Authorization`-Header oder HTTP Basic Authentication). Die Wahl des richtigen Typs ist für die sichere Offenlegung der API gegenüber KI-Agenten unerlässlich.
- Kann ich eine benutzerdefinierte OpenAPI-Spezifikations-URL für meine API verwenden?
- Ja, das Feld `api.url` in `ai-plugin.json` sollte auf die direkte URL Ihres API-OpenAPI-Spezifikationsdokuments verweisen (z.B. `https://api.example.com/openapi.yaml` oder `https://api.example.com/openapi.json`). Diese URL muss öffentlich zugänglich sein und eine gültige OpenAPI 3.0- oder 3.1-Spezifikation bereitstellen, damit KI-Agenten die Endpunkte und Schemata Ihrer API parsen und verstehen können.
- Wie oft sollte ich meine `ai-plugin.json` aktualisieren?
- Sie sollten Ihre `ai-plugin.json` aktualisieren, wenn es signifikante Änderungen an der Funktionalität, den Authentifizierungsmethoden oder den öffentlich sichtbaren Beschreibungen Ihrer API gibt. Selbst geringfügige Änderungen an Ihrer `description_for_model` können das Verhalten des LLM beeinflussen. Ziel ist es, sie mit dem aktuellen Status Ihrer API synchron zu halten, um sicherzustellen, dass KI-Agenten stets genaue Informationen erhalten.
- Was passiert, wenn meine `ai-plugin.json` fehlerhaft oder ungültig ist?
- Wenn Ihre `ai-plugin.json` fehlerhaft ist, Syntaxfehler enthält oder erforderliche Felder fehlen, werden KI-Agenten sie wahrscheinlich nicht parsen können. Dies führt dazu, dass Ihre API als Tool nicht auffindbar ist oder Agenten `invalid_manifest`-Fehler melden. Die Verwendung eines Validators oder eines robusten Generators wie unserem hilft, diese kritischen Parsing-Fehler zu vermeiden und eine erfolgreiche Integration zu gewährleisten.
- Gibt es spezifische User-Agents, die `ai-plugin.json`-Dateien crawlen?
- Ja, verschiedene KI-Agenten-Plattformen verwenden spezifische User-Agents, um `ai-plugin.json`-Dateien zu entdecken und zu parsen. Bemerkenswerte Beispiele sind `ChatGPT-User` (für OpenAIs Plattform) und `Google-Extended` (für Googles KI-Dienste). Um eine erfolgreiche Plugin-Erkennung und -Indizierung zu gewährleisten, ist es entscheidend, dass Ihre `robots.txt` diesen User-Agents den Zugriff auf `/.well-known/` erlaubt.
Verwandte kostenlose Tools
- llms.txt GeneratorErstellen Sie eine spec-konforme llms.txt für KI-Crawler.
- llms.txt ValidatorÜberprüfen Sie Ihre llms.txt auf Struktur- und Linkfehler.
- KI-fähiger robots.txt GeneratorKontrollieren Sie den Zugriff von GPTBot, ClaudeBot und PerplexityBot.
- FAQ Schema GeneratorGenerieren Sie FAQPage JSON-LD, das von KI-Antworten zitiert wird.
Scannen Sie Ihre Website auf KI-Sichtbarkeit
Führen Sie einen kostenlosen GEO- und AEO-Scan durch und erhalten Sie für Ihre Domain generierte llms.txt, robots.txt, Schema- und Content-Optimierungen.
Kostenlosen Scan starten