La plupart des API sont conçues pour les développeurs humains qui lisent la documentation, parcourent des exemples et débuggent avec des stack traces. Mais en 2026, les consommateurs d'API dont la croissance est la plus rapide sont les agents IA, et ils interagissent avec les API de manière très différente.
Voici l'histoire de la façon dont nous avons repensé l'API IA unifiée de LemonData autour d'un principe simple : ne soyez pas intelligent, soyez informatif. Le résultat est ce que nous appelons le design d'API agent-first, et cela a réduit les tokens gaspillés par nos utilisateurs de plus de 60 %.
Qu'est-ce que le design d'API Agent-First ?
Le design d'API agent-first consiste à structurer vos réponses d'API, en particulier les réponses d'erreur, afin qu'un agent IA puisse comprendre ce qui n'a pas fonctionné et le corriger sans aide extérieure.
Erreur d'API traditionnelle :
{"error": {"message": "Model not found"}}
Erreur d'API agent-first :
{
"error": {
"code": "model_not_found",
"message": "Model 'gpt5' not found",
"did_you_mean": "gpt-4o",
"suggestions": [{"id": "gpt-4o"}, {"id": "gpt-4o-mini"}],
"hint": "Use GET /v1/models to list all available models."
}
}
La différence ? Avec une API traditionnelle, l'agent doit effectuer des recherches sur le web, trouver la documentation, analyser le HTML et deviner. Avec une API agent-first, il s'auto-corrige en une seule étape.
Pourquoi les API traditionnelles échouent face aux agents IA
Regardez ce qui se passe lorsqu'un agent IA sollicite un agrégateur d'API typique pour la première fois :
Agent: POST /v1/chat/completions {"model": "gpt5"}
API: 400 {"error": {"message": "Model not found"}}
Agent: (recherche sur le web "lemondata models list")
Agent: (récupère une page de doc, peut-être la mauvaise)
Agent: (analyse le HTML, trouve un nom de modèle)
Agent: POST /v1/chat/completions {"model": "gpt-4o"}
API: 200 ✓
Six étapes. Plusieurs requêtes réseau. Des centaines de tokens gaspillés. Et c'est le scénario idéal, où l'agent a deviné la bonne URL de documentation.
Avec le design agent-first :
Agent: POST /v1/chat/completions {"model": "gpt5"}
API: 400 {"did_you_mean": "gpt-4o", "hint": "Use GET /v1/models..."}
Agent: POST /v1/chat/completions {"model": "gpt-4o"}
API: 200 ✓
Deux étapes. Zéro recherche web. L'agent s'est auto-corrigé uniquement à partir de la réponse d'erreur.
Le principe fondamental : l'intelligence reste du côté du modèle
La tentation est de construire des API « intelligentes » : corriger automatiquement le nom du modèle, router silencieusement vers un modèle similaire, ajouter un moteur de recommandation. Nous avons rejeté tout cela.
Lorsqu'un agent envoie model: "gpt5", vous ne connaissez pas son intention. Peut-être teste-t-il si GPT-5 existe. Peut-être a-t-il une contrainte budgétaire. Peut-être a-t-il besoin d'une capacité spécifique. Router automatiquement vers gpt-4o modifierait silencieusement le coût, la qualité de sortie et les capacités, tout cela à l'insu de l'agent.
La bonne approche est d'échouer rapidement et de manière informative. Donnez toutes les données à l'agent. Laissez-le décider.
Quatre patterns de design d'API Agent-First
Pattern 1 : Modèle non trouvé → Suggestions floues (Fuzzy Suggestions)
{
"error": {
"code": "model_not_found",
"did_you_mean": "gpt-4-turbo",
"suggestions": [
{"id": "gpt-4o"},
{"id": "gpt-4o-mini"},
{"id": "claude-sonnet-4-5"}
],
"hint": "Did you mean 'gpt-4-turbo'? Use GET /v1/models to list all available models."
}
}
Le champ did_you_mean utilise une résolution à trois niveaux : un mapping d'alias statique à partir des données de production, une correspondance de chaînes normalisée et une distance d'édition limitée. Tous les candidats sont validés par rapport à la liste des modèles en direct, de sorte que nous ne suggérons jamais un modèle qui est actuellement hors ligne.
Pattern 2 : Solde insuffisant → Alternatives tenant compte du budget
{
"error": {
"code": "insufficient_balance",
"balance_usd": 0.12,
"estimated_cost_usd": 0.35,
"suggestions": [
{"id": "gpt-4o-mini", "estimated_cost_usd": 0.02},
{"id": "deepseek-chat", "estimated_cost_usd": 0.01}
],
"hint": "Insufficient balance. Try a cheaper model or top up."
}
}
Au lieu de dire simplement « pas assez d'argent », nous indiquons à l'agent exactement combien il possède, combien il lui faut et quels modèles il peut s'offrir. L'agent peut rétrograder de manière autonome vers un modèle IA moins cher, sans aucune intervention humaine.
Pattern 3 : Tous les canaux ont échoué → Alternatives en direct
{
"error": {
"code": "all_channels_failed",
"retryable": true,
"retry_after": 30,
"alternatives": [
{"id": "claude-sonnet-4-5", "status": "available"},
{"id": "gpt-4o", "status": "available"}
],
"hint": "All channels for 'claude-opus-4-6' temporarily unavailable. Retry in 30s or try an alternative."
}
}
La liste alternatives n'est pas statique. Il s'agit d'une requête en direct sur nos données de santé des canaux, de sorte que l'agent reçoit des informations en temps réel sur ce qui fonctionne réellement en ce moment.
Pattern 4 : Limite de débit atteinte (Rate Limited) → Délai de réessai exact
{
"error": {
"code": "rate_limit_exceeded",
"retryable": true,
"retry_after": 8,
"limit": "1000/min",
"remaining": 0,
"hint": "Rate limited. Retry after 8s."
}
}
Pas de devinettes. Pas de backoff exponentiel commençant par des valeurs arbitraires. L'agent connaît le temps d'attente exact. Pour en savoir plus sur la gestion efficace des limites de débit, consultez notre guide sur le rate limiting des API IA.
Les réponses de succès transportent aussi des indices
Lorsqu'un agent appelle /v1/chat/completions avec un modèle Claude, la réponse inclut :
X-LemonData-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance.
X-LemonData-Native-Endpoint: /v1/messages
Nous disons à l'agent : « cela a fonctionné, mais il existe une meilleure façon de faire. » L'agent peut passer à l'endpoint natif lors du prochain appel, accédant ainsi à des fonctionnalités telles que l'extended thinking et le prompt caching qui ne sont pas disponibles via le format compatible OpenAI.
Nous plaçons cela dans les headers, pas dans le corps de la réponse, car le corps suit la spécification OpenAI/Anthropic. Les headers sont le point d'extension sûr.
La réponse /v1/models comme aide-mémoire pour l'agent
Nous avons ajouté trois champs à chaque modèle dans la réponse /v1/models :
category: modèle de chat, générateur d'images, modèle vidéo ou audio. Plus besoin de deviner à partir du nom.pricing_unit: par token, par image, par seconde ou par requête. Essentiel pour l'estimation des coûts.cache_pricing: prix du cache de prompt en amont plus remise sur le cache sémantique de la plateforme.
Combiné aux champs existants (tarification, capacités, alias, tokens max), un agent peut prendre des décisions de sélection de modèle parfaitement informées à partir d'un seul appel API.
llms.txt : La première lecture de l'agent
Nous servons un fichier llms.txt dynamique sur api.lemondata.cc/llms.txt, une vue d'ensemble lisible par machine de l'intégralité de l'API. Il comprend :
- Un template de premier appel avec du code fonctionnel
- Les noms de modèles courants (générés automatiquement à partir des données d'utilisation, pas codés en dur)
- Les 12 endpoints avec leurs paramètres
- Des paramètres de filtrage pour la découverte de modèles
Un agent qui lit ce fichier avant son premier appel API aura de fortes chances de réussir du premier coup.
Piloté par les données, pas par la connaissance
Chaque suggestion dans notre système provient des données de production. La carte d'alias did_you_mean a été initialisée à partir de 30 jours d'erreurs model_not_found réelles dans nos logs de requêtes. Les suggestions de modèles sont triées par modèles d'utilisation réels. Les « noms de modèles courants » dans llms.txt sont générés à partir de notre base de données.
Nous suivons chaque échec de modèle dans un ensemble trié Redis. Lorsqu'une faute d'orthographe accumule suffisamment de hits, elle est promue dans la carte d'alias. Lorsqu'un modèle passe hors ligne, il disparaît automatiquement de toutes les suggestions. Le système s'améliore de lui-même.
La contrainte de design qui a permis d'aboutir
Nous avons fixé une règle : pas de nouveaux endpoints, pas de nouveaux SDK, pas de changements de rupture (breaking changes). Tout devait fonctionner dans le format d'erreur compatible OpenAI existant. Les nouveaux champs sont optionnels, de sorte que tout client qui les ignore bénéficie de la même expérience qu'auparavant.
Cette contrainte nous a forcés à être précis sur les informations qui aident réellement un agent à s'auto-corriger, plutôt que de construire de nouvelles API élaborées que personne n'adopterait.
Comment appliquer le design Agent-First à votre propre API
Si vous construisez des API que les agents IA consommeront :
- Chaque erreur doit être exploitable. Incluez ce qui n'a pas fonctionné, pourquoi, et ce qu'il faut faire ensuite.
- Suggérez des alternatives, ne corrigez pas automatiquement. Laissez l'agent prendre des décisions éclairées.
- Utilisez des champs structurés, pas de la prose.
did_you_meanest analysable ; « Vouliez-vous dire... » dans une chaîne de caractères ne l'est pas. - Fondez les suggestions sur des données réelles. Les modèles d'utilisation en production l'emportent sur les listes codées en dur.
- Proposez une découverte lisible par machine via
llms.txt, des spécifications OpenAPI ou des listes de modèles structurées. - Maintenez la compatibilité ascendante. Les nouveaux champs d'indices doivent être additifs, jamais disruptifs.
Par où commencer sans tout réécrire
La plupart des équipes n'ont pas besoin de reconcevoir toute leur API en une semaine.
Le point de départ pratique est plus modeste :
- ajoutez un ou deux champs d'indices lisibles par machine à vos erreurs les plus fréquentes
- rendez
/v1/modelsou l'endpoint de découverte de modèles équivalent plus riche et plus explicite - publiez une vue d'ensemble lisible par machine telle que
llms.txt - testez toute la boucle avec un client agent, pas seulement avec curl
Si vous opérez déjà via une couche de passerelle, le guide de la passerelle IA unifiée montre pourquoi ce plan de contrôle est important. Si vous utilisez encore une intégration directe compatible OpenAI, le guide de migration est l'endroit le plus simple pour commencer avant d'ajouter des comportements plus adaptés aux agents.
FAQ
Qu'est-ce que le design d'API agent-first ?
Le design d'API agent-first est une approche où les réponses d'erreur incluent des indices structurés et lisibles par machine qui permettent aux agents IA de s'auto-corriger sans intervention humaine ni consultation de documentation externe.
En quoi l'agent-first est-il différent du design d'API developer-first ?
Les API developer-first optimisent la lisibilité humaine : messages d'erreur clairs, bonne documentation, exemples utiles. Les API agent-first ajoutent des champs structurés (did_you_mean, suggestions, hint) que les machines peuvent analyser et traiter par programmation.
Le design agent-first casse-t-il les clients existants ?
Non. Les champs agent-first sont additifs, ce qui signifie que les clients existants peuvent les ignorer et continuer à fonctionner sans changement.
Comment LemonData implémente-t-il le design agent-first ?
La passerelle API IA unifiée de LemonData ajoute des indices d'erreur structurés à l'ensemble des plus de 300 modèles. Chaque réponse d'erreur inclut des suggestions exploitables, et l'endpoint llms.txt permet une découverte de l'API lisible par machine.
LemonData offre un accès unifié à plus de 300 modèles d'IA via une seule API. Essayez-le gratuitement pour tester l'API agent-first avec 1 $ de crédits de départ.
