Générateur ai-plugin.json
Exposez votre API aux agents IA avec un manifeste valide.
Réponse rapide
ai-plugin.json est le manifeste qui expose votre API comme un outil invocable aux assistants IA, hébergé à l'adresse /.well-known/ai-plugin.json. Ce générateur rédige un manifeste valide avec votre nom, description pour le modèle, type d'authentification et URL OpenAPI afin que les agents puissent découvrir et appeler vos endpoints.
Le générateur interactif est en anglais – tout ce dont vous avez besoin pour le comprendre et l'utiliser est expliqué sur cette page.
Exposer Votre API aux Agents IA
Le manifeste `ai-plugin.json` agit comme le contrat fondamental entre votre API et l'écosystème émergent des assistants IA. Hébergé à l'emplacement prévisible `/.well-known/ai-plugin.json`, ce fichier JSON n'est pas seulement des métadonnées ; c'est une passerelle critique. Notre générateur assure que votre manifeste adhère strictement à la spécification OpenAPI (OAS) pour le référencement, permettant à des modèles comme GPT-4 et Google Gemini de comprendre et d'invoquer précisément vos fonctions. Une génération correcte est primordiale pour une intégration fluide, évitant les erreurs `invalid_manifest` et garantissant des appels d'outils fiables.
Rédaction Essentielle de `description_for_model`
Le champ `description_for_model` au sein de `ai-plugin.json` est sans doute le plus impactant pour l'utilisation d'outils pilotés par l'IA. Cette chaîne succincte (généralement moins de 200 caractères) fournit le contexte, optimisé pour le prompt, au LLM pour décider quand et comment appeler votre API. Notre générateur vous guide dans la création de descriptions précises et orientées action, telles que "Utiliser ce plugin pour récupérer les cours boursiers en temps réel pour un symbole boursier donné" plutôt que des généralités vagues. Cette spécificité influence directement la propension du LLM à invoquer votre outil.
Configuration de l'Authentification et de l'URL OpenAPI
L'exposition sécurisée de votre API aux agents IA nécessite une configuration d'authentification minutieuse. Le `ai-plugin.json` prend en charge divers types d'`auth`, y compris `none`, `oauth` (Flux d'octroi des identifiants client OAuth 2.0), et `service_http` (Jeton Bearer ou authentification basique). Notre générateur facilite la sélection et la configuration de ceux-ci, garantissant que vos endpoints sont protégés tout en étant accessibles aux agents autorisés. Parallèlement, il valide l'entrée `api.url`, confirmant qu'elle pointe vers une spécification OpenAPI/Swagger valide et accessible en ligne (par exemple, `https://api.example.com/openapi.yaml`), ce qui est essentiel pour la compréhension par le modèle.
Pourquoi le Chemin `/.well-known/` Est Crucial
Le placement de `ai-plugin.json` au chemin `/.well-known/` n'est pas arbitraire ; c'est une norme définie par la RFC 8615 pour la découverte de type host-meta. Cet emplacement prévisible permet aux crawlers d'agents IA (comme `ChatGPT-User` ou `Google-Extended`) de découvrir et de récupérer efficacement votre manifeste sans configuration explicite. Ce mécanisme de découverte standardisé minimise la latence et la surcharge pour les agents, rendant votre API immédiatement disponible à tout système d'IA conçu pour rechercher des outils à cette URI spécifiée et largement adoptée.
Pièges Courants de la Génération ai-plugin.json
| Problème | Impact | Stratégie d'Atténuation | Réponse du Crawler |
|---|---|---|---|
| JSON Mal Formé | Échec de l'analyse du manifeste, API non découvrable | Utiliser un linter ou un générateur pour une validation JSON stricte | `HTTP 400 Bad Request` ou erreur `Invalid JSON` dans les logs de l'agent. |
| URL OpenAPI Incorrecte | Fonctions API inconnues du LLM | Vérifier que `api.url` pointe vers une spécification OpenAPI valide et en ligne | Avertissements `API spec not found` ou `Unparseable OpenAPI`. |
| `description_for_model` Vague | Sous-utilisation par les LLM | Rédiger des descriptions concises et orientées action (50-150 caractères) | Le LLM ne sélectionne pas l'outil, ou interprète mal l'intention. |
| Champs Requis Manquants | Rejet du manifeste | S'assurer que `name_for_model`, `name_for_human`, `description_for_model`, `api`, et `auth` sont présents | `Missing required field` ou `Manifest schema validation failed`. |
| Pas de Chemin `/.well-known` | Manifeste non découvrable par les crawlers standards | Déployer `ai-plugin.json` strictement à `/.well-known/ai-plugin.json` | Le crawler ignore l'hôte, l'API reste inconnue des agents. |
Points Clés pour Votre ai-plugin.json
- Assurez-vous que `name_for_model` est un identifiant succinct et unique (ex: `stock_price_api`).
- Vérifiez que `description_for_model` est claire, concise et orientée action pour l'interprétation par le LLM.
- Confirmez que votre `api.url` pointe vers une spécification OpenAPI 3.0 ou 3.1 valide et publiquement accessible.
- Implémentez une configuration `auth` appropriée (ex: `service_http` pour les tokens Bearer).
- Déployez le fichier `ai-plugin.json` exclusivement au chemin `/.well-known/ai-plugin.json`.
- Passez en revue les champs `legal_info_url` et `contact_email` pour la conformité et le support.
- Validez régulièrement votre manifeste généré à l'aide d'outils pour l'adhésion au schéma.
- Testez les appels API avec un agent IA réel (ex: ChatGPT Plugins) avant le déploiement complet.
Étapes pour Déployer Votre Manifeste de Plugin IA
- 1Définir la Fonctionnalité de Base de l'API
Articulez clairement les actions spécifiques que votre API permet. Identifiez les endpoints clés, les paramètres et les réponses attendues. Cette clarté éclairera directement la `description_for_model` et la spécification OpenAPI. Concentrez-vous sur ce que les agents IA peuvent *faire* avec votre API, pas seulement sur ce qu'elle *est*.
- 2Générer la Spécification OpenAPI
Créez une définition OpenAPI (OAS 3.0/3.1) complète pour votre API. Cette spécification détaille tous les endpoints, méthodes, paramètres et modèles de données. Assurez-vous qu'elle est précise et à jour, car les agents IA analyseront ce document pour comprendre les capacités de votre API et comment construire les requêtes.
- 3Configurer les Détails du Manifeste
Utilisez le générateur pour saisir votre `name_for_model`, `description_for_model`, type d'`auth` (ex: `service_http` pour les clés API), `logo_url`, `legal_info_url`, et `contact_email`. Portez une attention particulière à la rédaction de la `description_for_model` pour une compréhension optimale par le LLM et l'invocation de votre plugin.
- 4Valider le JSON Généré
Avant le déploiement, validez méticuleusement le fichier `ai-plugin.json` de sortie par rapport au schéma officiel. Vérifiez les erreurs de syntaxe, les champs manquants et les formats d'URL corrects. Assurez-vous que l'`api.url` pointe précisément vers votre spécification OpenAPI hébergée afin d'éviter les problèmes de découverte par les agents IA comme `ChatGPT-User`.
- 5Déployer le Manifeste vers `/.well-known/`
Hébergez le fichier `ai-plugin.json` généré à l'URI exacte `VOTRE_DOMAINE/.well-known/ai-plugin.json`. Ce chemin standard est essentiel pour que les crawlers d'agents IA découvrent automatiquement votre plugin sans connaissance préalable. Un placement incorrect rendra votre plugin indétectable par la plupart des systèmes d'IA.
- 6Surveiller et Itérer
Après le déploiement, surveillez l'utilisation de votre API et les logs d'interaction des agents. Portez attention à la fréquence d'invocation de votre plugin et s'il y a des erreurs d'analyse. Utilisez ces retours pour affiner votre `description_for_model` et votre spécification OpenAPI, garantissant une performance optimale et une intégration fiable des agents IA au fil du temps.
Foire aux questions
- Qu'est-ce que `ai-plugin.json` et pourquoi est-il important pour mon API ?
- `ai-plugin.json` est un fichier manifeste standardisé qui sert de modèle aux agents IA (comme ceux alimentant ChatGPT ou Gemini) pour découvrir et comprendre votre API. Il est crucial car il permet à vos services d'être des outils appelables au sein des écosystèmes IA, élargissant considérablement la portée et l'utilité de votre API en permettant aux LLM d'interagir programmatiquement avec elle au nom des utilisateurs.
- Où exactement le fichier `ai-plugin.json` doit-il être hébergé ?
- Le fichier `ai-plugin.json` doit être hébergé précisément au chemin `/.well-known/ai-plugin.json` par rapport à votre domaine. Par exemple, si votre domaine est `example.com`, le fichier doit être accessible à `https://example.com/.well-known/ai-plugin.json`. Cet emplacement standardisé est vital pour que les crawlers IA puissent trouver et indexer de manière fiable votre manifeste de plugin.
- Quel est le but de `description_for_model` comparé à `description_for_human` ?
- `description_for_model` fournit un résumé concis et orienté action spécifiquement pour que le LLM comprenne quand et comment appeler votre API (ex: "Obtenir les données météorologiques actuelles pour un emplacement"). `description_for_human` est une description plus longue et conviviale affichée aux utilisateurs humains dans les places de marché de plugins ou les répertoires. Le premier pilote l'invocation par l'IA, le second informe le choix de l'utilisateur.
- Quels types d'authentification sont pris en charge dans `ai-plugin.json` ?
- La norme `ai-plugin.json` prend en charge plusieurs types d'authentification : `none` pour les API non authentifiées, `oauth` pour le flux d'identifiants client OAuth 2.0, et `service_http` pour l'authentification basée sur une clé API (soit via un token Bearer dans l'en-tête `Authorization`, soit une authentification HTTP Basique). Choisir le bon type est essentiel pour une exposition sécurisée de l'API aux agents IA.
- Puis-je utiliser une URL de spécification OpenAPI personnalisée pour mon API ?
- Oui, le champ `api.url` dans `ai-plugin.json` doit pointer vers l'URL directe de votre document de spécification OpenAPI de votre API (par exemple, `https://api.example.com/openapi.yaml` ou `https://api.example.com/openapi.json`). Cette URL doit être publiquement accessible et servir une spécification OpenAPI 3.0 ou 3.1 valide pour que les agents IA puissent analyser et comprendre les endpoints et les schémas de votre API.
- À quelle fréquence dois-je mettre à jour mon `ai-plugin.json` ?
- Vous devriez mettre à jour votre `ai-plugin.json` chaque fois qu'il y a des changements significatifs dans la fonctionnalité de votre API, les méthodes d'authentification ou les descriptions publiques. Même des changements mineurs à votre `description_for_model` peuvent impacter le comportement du LLM. Visez à le maintenir synchronisé avec l'état actuel de votre API pour garantir que les agents IA disposent toujours d'informations précises.
- Que se passe-t-il si mon `ai-plugin.json` est mal formé ou invalide ?
- Si votre `ai-plugin.json` est mal formé, contient des erreurs de syntaxe ou si des champs requis sont manquants, les agents IA échoueront probablement à l'analyser. Il en résulte que votre API ne sera pas découvrable en tant qu'outil, ou les agents signaleront des erreurs `invalid_manifest`. L'utilisation d'un validateur ou d'un générateur robuste comme le nôtre aide à prévenir ces défaillances critiques d'analyse et assure une intégration réussie.
- Existe-t-il des user agents spécifiques qui explorent les fichiers `ai-plugin.json` ?
- Oui, diverses plateformes d'agents IA utilisent des user agents spécifiques pour découvrir et analyser les fichiers `ai-plugin.json`. Parmi les exemples notables figurent `ChatGPT-User` (pour la plateforme d'OpenAI) et `Google-Extended` (pour les services IA de Google). S'assurer que votre `robots.txt` autorise ces user agents à accéder à `/.well-known/` est crucial pour une découverte et une indexation réussies des plugins.
Outils gratuits connexes
- Générateur de llms.txtCréez un fichier llms.txt conforme aux spécifications pour les crawlers IA.
- Validateur de llms.txtVérifiez votre llms.txt pour les erreurs de structure et de liens.
- Générateur de robots.txt adapté à l'IAContrôlez l'accès de GPTBot, ClaudeBot et PerplexityBot.
- Générateur de schéma FAQGénérez du JSON-LD FAQPage cité par les réponses IA.
Analysez la visibilité de votre site sur l'IA
Effectuez un scan GEO et AEO gratuit et obtenez des fichiers llms.txt, robots.txt, ainsi que des corrections de schéma et de contenu générées pour votre domaine.
Lancer un scan gratuit