La plupart des API sont conçues pour des développeurs humains qui lisent la documentation, parcourent des exemples et déboguent à l'aide de traces de pile (stack traces). En 2026, une part croissante du trafic API provient d'agents IA, et ils n'interagissent pas avec les API de la même manière que les humains.
Voici comment nous avons repensé l'API IA unifiée de TokenLab autour d'un principe : ne cherchez pas à être ingénieux, soyez informatif. Nous appelons cela la conception d'API « agent-first », et cela a permis de réduire le gaspillage de tokens pour nos utilisateurs de plus de 60 %.
Points clés à retenir
- La conception d'API « agent-first » ajoute des indices structurés et lisibles par machine aux réponses d'erreur, afin que les agents IA puissent s'auto-corriger sans recherche web ni aide humaine.
- Suggérez des alternatives, ne corrigez pas automatiquement. Des champs comme
did_you_mean,suggestionsetretryablepermettent aux agents de prendre des décisions éclairées plutôt que de subir une décision imposée. - Chaque suggestion est basée sur des données de production, de sorte que les modèles hors ligne ou obsolètes n'apparaissent jamais dans la liste des candidats.
- Les champs d'indices sont additifs et rétrocompatibles, ce qui permet aux clients existants compatibles avec OpenAI de continuer à fonctionner sans modification.
Qu'est-ce que la conception d'API « Agent-First » ?
La conception d'API « agent-first » consiste à structurer vos réponses, en particulier les réponses d'erreur, afin qu'un agent IA puisse comprendre ce qui n'a pas fonctionné et le corriger sans quitter la conversation.
Erreur d'API traditionnelle :
{"error": {"message": "Model not found"}}
Erreur d'API « agent-first » :
{
"error": {
"code": "model_not_found",
"message": "Model 'gpt5.5' not found",
"did_you_mean": "gpt-5.5",
"suggestions": [{"id": "gpt-5.5"}, {"id": "gemini-3.5-flash"}],
"hint": "Use GET /v1/models to list all available models."
}
}
Avec une API traditionnelle, l'agent doit effectuer une recherche 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
Observez ce qui se passe lorsqu'un agent interroge un agrégateur d'API typique pour la première fois :
Agent: POST /v1/chat/completions {"model": "gpt5.5"}
API: 400 {"error": {"message": "Model not found"}}
Agent: (recherche sur le web "tokenlab models list")
Agent: (récupère une page de documentation, peut-être la mauvaise)
Agent: (analyse le HTML, trouve un nom de modèle)
Agent: POST /v1/chat/completions {"model": "gpt-5.5"}
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 réussi à deviner la bonne URL de documentation.
Avec une conception « agent-first » :
Agent: POST /v1/chat/completions {"model": "gpt5.5"}
API: 400 {"did_you_mean": "gpt-5.5", "hint": "Use GET /v1/models..."}
Agent: POST /v1/chat/completions {"model": "gpt-5.5"}
API: 200 ✓
Deux étapes, aucune recherche web. L'agent s'est auto-corrigé à partir de la seule réponse d'erreur.
Le principe fondamental : l'intelligence reste du côté du modèle
La tentation est de construire des API « intelligentes » qui corrigent automatiquement le nom du modèle, redirigent silencieusement vers quelque chose de similaire ou ajoutent un moteur de recommandation. Nous avons rejeté tout cela.
Lorsqu'un agent envoie model: "gpt5.5", vous ne connaissez pas réellement son intention. Peut-être vérifie-t-il si une version plus récente de GPT existe. Peut-être a-t-il une contrainte budgétaire stricte. Peut-être a-t-il besoin d'une capacité spécifique qu'un seul modèle prend en charge. Une redirection automatique vers gpt-5.5 modifierait silencieusement le coût, la qualité et les capacités, et l'agent ne le saurait jamais.
La meilleure approche est d'échouer rapidement et de manière informative. Donnez toutes les données à l'agent et laissez-le décider.
Quatre modèles de conception d'API « Agent-First »
Modèle 1 : Modèle non trouvé → Suggestions floues
{
"error": {
"code": "model_not_found",
"did_you_mean": "gpt-5.5",
"suggestions": [
{"id": "gpt-5.5"},
{"id": "gemini-3.5-flash"},
{"id": "claude-sonnet-5"}
],
"hint": "Did you mean 'gpt-5.5'? Use GET /v1/models to list all available models."
}
}
did_you_mean utilise une résolution à trois niveaux : mappage d'alias statique à partir des données de production, correspondance de chaînes normalisée et distance d'édition bornée. Chaque candidat est vérifié par rapport à la liste des modèles en direct, nous ne suggérons donc jamais un modèle actuellement hors ligne.
Modèle 2 : Solde insuffisant → Alternatives tenant compte du budget
{
"error": {
"code": "insufficient_balance",
"balance_usd": 0.12,
"estimated_cost_usd": 0.35,
"suggestions": [
{"id": "gemini-3.5-flash", "estimated_cost_usd": 0.02},
{"id": "deepseek-v4-flash", "estimated_cost_usd": 0.01}
],
"hint": "Insufficient balance. Try a cheaper model or top up."
}
}
Au lieu de simplement dire « fonds insuffisants », nous indiquons à l'agent exactement ce qu'il possède, ce dont il a besoin et quels modèles il peut se permettre en ce moment. L'agent peut choisir de manière autonome de passer à un modèle d'IA moins coûteux sans intervention humaine. Vérifiez la tarification actuelle par modèle sur le répertoire des modèles TokenLab avant de coder en dur des seuils de coût.
Modèle 3 : Échec de tous les canaux → Alternatives en direct
{
"error": {
"code": "all_channels_failed",
"retryable": true,
"retry_after": 30,
"alternatives": [
{"id": "claude-sonnet-5", "status": "available"},
{"id": "gpt-5.5", "status": "available"}
],
"hint": "All channels for 'claude-opus-4-8' 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 obtient des informations en temps réel sur ce qui fonctionne réellement, et non une liste de secours codée en dur qui pourrait être obsolète.
Modèle 4 : Limite de débit → Temps de nouvelle tentative précis
{
"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 à partir d'une valeur arbitraire. L'agent connaît le temps d'attente exact. Pour en savoir plus sur la gestion des limites de débit, consultez notre guide sur la limitation de débit des API IA.
Les réponses de succès contiennent aussi des indices
Lorsqu'un agent appelle /v1/chat/completions avec un modèle Claude, la réponse inclut :
X-TokenLab-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance.
X-TokenLab-Native-Endpoint: /v1/messages
Nous disons à l'agent : « cela a fonctionné, mais il existe une meilleure façon ». Il peut basculer vers le point de terminaison natif lors du prochain appel et bénéficier de fonctionnalités comme le « extended thinking » et le « prompt caching » qui ne sont pas exposées via le format compatible OpenAI.
Ces indices résident dans les en-têtes, et non dans le corps de la réponse, car le corps doit suivre exactement la spécification OpenAI ou Anthropic. Les en-têtes sont le point d'extension sûr qui ne cassera aucune logique d'analyse existante.
La réponse /v1/models comme aide-mémoire pour l'agent
Nous avons ajouté trois champs à chaque entrée de 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. Nécessaire pour toute estimation de coût réelle.cache_pricing: prix du cache de prompt en amont plus la remise sur le cache sémantique de la plateforme.
Combiné avec les champs existants (tarification, capacités, alias, max tokens), un agent peut faire une sélection de modèle parfaitement informée à partir d'un seul appel API. Vous pouvez voir le catalogue complet en direct dans le répertoire des modèles TokenLab (observé le 07/07/2026), qui répertorie actuellement plus de 300 modèles dans les catégories chat, image, vidéo et audio, y compris les options de pointe actuelles comme Claude Sonnet 5, GPT-5.5 et Gemini 3.5 Flash. Vérifiez la tarification et la disponibilité actuelles sur cette page plutôt que de supposer que les chiffres de cet article sont à jour.
llms.txt : La première lecture de l'agent
Nous servons un fichier llms.txt dynamique sur api.tokenlab.sh/llms.txt, un aperçu lisible par machine de toute l'API. Il comprend :
- Un modèle de premier appel avec du code fonctionnel
- Des noms de modèles courants, générés automatiquement à partir des données d'utilisation plutôt que codés en dur
- Les 12 points de terminaison 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 a beaucoup plus de chances de réussir sa requête dès le premier essai.
Axé sur les données, pas sur la connaissance
Chaque suggestion dans le système provient de données de production. La carte d'alias did_you_mean a été alimentée par 30 jours d'erreurs model_not_found réelles dans nos journaux de requêtes. Les suggestions de modèles sont triées par utilisation réelle. La liste des « noms de modèles courants » dans llms.txt est générée à partir de notre base de données, et non maintenue manuellement.
Nous suivons chaque erreur de modèle dans un ensemble trié Redis. Une fois qu'une faute de frappe accumule suffisamment de hits, elle est promue dans la carte d'alias. Lorsqu'un modèle est hors ligne, il est automatiquement retiré de chaque liste de suggestions. Le système s'ajuste lui-même au fil du temps au lieu de devenir obsolète, ce qui est important lorsque de nouvelles versions de modèles comme GPT-5.5, Claude Sonnet 5 et Gemini 3.5 Flash sortent à des moments qui se chevauchent.
La contrainte de conception qui a fait fonctionner le tout
Nous avons fixé une règle : pas de nouveaux points de terminaison, pas de nouveaux SDK, pas de changements cassants. Tout devait tenir dans le format d'erreur existant compatible avec OpenAI. Les nouveaux champs sont facultatifs, donc tout client qui les ignore bénéficie exactement de la même expérience qu'auparavant.
Cette contrainte a imposé une précision sur ce qui aide réellement un agent à s'auto-corriger, plutôt que de construire de nouvelles API élaborées que personne ne prendrait la peine d'adopter.
Comment appliquer la conception « Agent-First » à votre propre API
Si vous construisez des API que des agents IA consommeront :
- Rendez chaque erreur exploitable. Indiquez ce qui n'a pas fonctionné, pourquoi et quoi faire ensuite.
- Suggérez des alternatives au lieu de corriger automatiquement. Laissez l'agent prendre une décision éclairée.
- Utilisez des champs structurés, pas de la prose.
did_you_meanest analysable ; un « vouliez-vous dire... » enfoui dans une phrase ne l'est pas. - Basez les suggestions sur des données réelles. Les modèles d'utilisation en production valent mieux qu'une liste codée en dur qui devient obsolète.
- Proposez une découverte lisible par machine via
llms.txt, une spécification OpenAPI ou une liste de modèles structurée. - Restez rétrocompatible. Les nouveaux champs d'indices doivent être additifs, jamais cassants.
Par où commencer sans tout réécrire
La plupart des équipes n'ont pas besoin de repenser toute leur API en une semaine. Un point de départ plus modeste fonctionne très bien :
- Ajoutez un ou deux champs d'indices lisibles par machine à vos erreurs les plus fréquentes.
- Rendez
/v1/modelsou votre point de terminaison de découverte équivalent plus riche et plus explicite. - Publiez un aperçu lisible par machine, tel que
llms.txt. - Testez la boucle complète avec un client agent réel, pas seulement avec curl.
Si vous opérez déjà via une couche de passerelle, le guide de la passerelle IA unifiée explique pourquoi ce plan de contrôle est important. Si vous êtes toujours sur une intégration directe compatible OpenAI, le guide de migration est le point de départ le plus simple avant d'ajouter un comportement adapté aux agents.
FAQ
Qu'est-ce que la conception d'API « agent-first » ?
C'est une approche où les réponses d'erreur incluent des indices structurés et lisibles par machine (champs comme did_you_mean, suggestions et hint) afin que les agents IA puissent s'auto-corriger sans intervention humaine ni consultation de documentation.
En quoi la conception « agent-first » diffère-t-elle de la conception « developer-first » ?
Les API « developer-first » optimisent la lisibilité humaine : messages clairs, bonne documentation, exemples utiles. Les API « agent-first » ajoutent des champs structurés par-dessus afin que les machines puissent analyser l'erreur et agir par programmation, sans rien lire.
La conception « agent-first » casse-t-elle les clients existants ?
Non. Les champs sont additifs. Les clients existants qui ne recherchent pas did_you_mean ou suggestions les ignorent simplement et continuent de fonctionner exactement comme avant.
TokenLab fournit un accès unifié à plus de 300 modèles d'IA, y compris les modèles de pointe actuels comme GPT-5.5, Claude Sonnet 5 et Gemini 3.5 Flash, via une API unique répertoriée dans le répertoire des modèles. Commencez gratuitement pour tester l'API « agent-first » avec 1 $ de crédits de démarrage.
Sources
Prix observé le 2026-07-07
- TokenLab model directoryObservé le 2026-07-07
