GraphQL est le langage que les agents d'IA attendaient

GraphQL a été conçu en 2015 pour accélérer le développement frontend. Il s’est révélé être l’interface parfaite pour des machines qui posent des questions intelligentes.

Dans un texte précédent, l’argument était que toute application doit être API-first parce que les agents d’IA deviennent les principaux consommateurs de logiciels. L’API est le produit. L’interface est un client parmi d’autres.

Cet argument laisse une question de suivi que presque personne ne pose encore, mais que tout le monde devrait poser : quel type d’API faut-il construire ?

La réponse, dès qu’on observe vraiment comment les agents tentent d’utiliser un logiciel, pointe fortement dans une direction. GraphQL. Pas parce que c’est à la mode : il a une décennie à ce stade. Parce que les propriétés précises qui distinguent GraphQL de REST sont presque parfaitement alignées avec ce dont les agents ont besoin pour opérer sans humain dans la boucle.

C’est comme si Facebook avait accidentellement construit le langage de requête de l’ère des agents en 2015 et que le secteur avait ensuite passé dix ans à s’en servir principalement pour rendre les applications React un peu plus commodes. C’est le sous-estimer. Considérablement.

Le problème de la découverte

Voici l’indice le plus clair qu’une API a été construite pour des humains et non pour des machines : la page de documentation. Des points d’accès listés sous forme de noms. Des exemples écrits pour quelqu’un qui sait déjà ce qu’il cherche. Un historique de versions que personne n’a mis à jour depuis la dernière réorganisation. Quand un développeur arrive, il lit la documentation, se construit un modèle mental du graphe de ressources et écrit du code qui effectue des séquences d’appels précises et planifiées d’avance pour obtenir les données dont il a besoin. La documentation est un coût d’entrée payé une fois.

Les agents ne fonctionnent pas comme cela. Un agent arrive sur votre API avec un objectif (trouver les trois tickets ouverts les plus prioritaires assignés à l’équipe d’ingénierie et résumer leur activité la plus récente) et doit déterminer dynamiquement comment décomposer cet objectif en opérations. Il n’y a pas d’intégration préconstruite. Il n’y a pas d’ingénieur expérimenté pour lire la documentation. L’agent raisonne sur votre API en temps réel, lors de sa première rencontre avec elle.

Appelons cela le problème de la découverte : un agent arrive sur votre application sans savoir ce qui s’y trouve, et le coût de cette ignorance est payé dans chaque flux de travail qu’il tente d’exécuter. Avec REST, l’agent doit deviner quels points d’accès existent, faire un appel, inspecter la réponse pour comprendre la forme des données, réaliser qu’il lui faut des données liées venant d’ailleurs, faire un autre appel, corréler les résultats, gérer la pagination et répéter, tout en brûlant sa fenêtre de contexte sur des données dont il n’a pas besoin.

GraphQL fait s’effondrer le problème de la découverte. Un agent peut lancer une seule requête d’introspection et recevoir le schéma complet : chaque type, chaque champ, chaque relation, chaque argument, chaque description. Le schéma n’est pas un artefact séparé susceptible de dériver de la réalité. Il est la réalité. Il est généré depuis le même code qui résout les requêtes.

Pour un agent, c’est la différence entre traverser une ville sans carte et démarrer avec un GPS.

L’introspection est une auto-documentation

Toute API GraphQL est auto-documentée. Pas dans le sens vague et velléitaire où les API REST sont « auto-documentées » quand quelqu’un pense à maintenir à jour la spécification OpenAPI. Les API GraphQL sont littéralement auto-documentées, par conception, comme fonctionnalité centrale du protocole.

Cela compte d’une façon précise pour les agents. Avant de faire une seule requête de données, l’agent peut demander à l’API : que peux-tu faire ? Quelles données as-tu ? Comment tout cela se relie-t-il ? Et l’API répond, complètement, exactement, dans un format trivialement analysable.

Imaginez un agent chargé de trouver les réclamations récentes de clients sur la facturation. Il introspecte le schéma et découvre un type Customer avec un champ tickets, que les tickets ont une énumération category qui inclut BILLING, que les tickets ont un horodatage createdAt et un champ status, qu’il existe une connexion comments sur chaque ticket. En quelques secondes, il a la carte complète du modèle de données, non pas en lisant une documentation qui peut être ou non à jour, mais depuis le système vivant lui-même.

C’est la propriété que le Model Context Protocol, le standard d’Anthropic pour permettre aux assistants d’IA de découvrir et d’appeler des outils externes, essaie essentiellement de replaquer sur tous les types d’API. Un schéma GraphQL est déjà un manifeste de forme MCP. Le protocole rencontre le modèle de données à mi-chemin quand les deux parlent la même langue.

Demander exactement ce dont vous avez besoin

Les API REST renvoient des structures de données fixes. Vous appelez /api/users/123 et vous récupérez tout ce que le serveur a décidé d’inclure dans une réponse utilisateur : nom, e-mail, adresse, préférences, URL d’avatar, date de création du compte, horodatage de dernière connexion, niveau d’abonnement et quarante autres champs. Si vous avez aussi besoin des commandes récentes de cet utilisateur, c’est un appel séparé. S’il vous faut les articles de ces commandes, c’est un appel de plus par commande.

Cela avait du sens quand chaque consommateur d’API était un ingénieur frontend capable d’écrire du code sur mesure pour gérer la surrécupération et orchestrer les allers-retours. C’est profondément inefficace quand le consommateur est un agent qui opère sous de vraies contraintes.

Les agents ont des fenêtres de contexte. Chaque jeton de données inutiles dans une réponse est un jeton qui aurait pu servir au raisonnement, à la planification ou à retenir un autre contexte pertinent. Quand une API REST renvoie 4 Ko de données utilisateur alors que l’agent n’avait besoin que du nom et de l’e-mail, ce n’est pas seulement de la bande passante gâchée. C’est de la capacité cognitive gâchée. Multipliez cela par chaque appel d’un flux en plusieurs étapes et le contexte de l’agent se remplit de bruit.

GraphQL élimine le problème. L’agent spécifie les champs exacts dont il a besoin :

query {
  user(id: "123") {
    name
    email
    recentOrders(first: 3) {
      status
      total
      items {
        productName
        quantity
      }
    }
  }
}

Une requête. Exactement les données nécessaires. Pas de surrécupération. Pas de sous-récupération. Pas de jetons gâchés. L’agent récupère une réponse précise qui correspond directement à ses besoins d’information. Ce n’est pas une optimisation : c’est un modèle fondamentalement différent de récupération de données, où le consommateur décrit la forme et le serveur détermine comment l’assembler.

C’est le modèle que des agents intelligents devraient pouvoir utiliser pour interagir avec une source de données. C’est le modèle que GraphQL fait tourner discrètement depuis une décennie.

Une requête au lieu de douze

Le problème de la sous-récupération dans REST est encore plus douloureux que celui de la surrécupération, et c’est là que l’avantage de GraphQL devient le plus visible.

Imaginez un agent chargé de générer un rapport hebdomadaire d’état d’équipe. Il lui faut les membres de l’équipe, les tâches assignées à chaque personne, le statut et la priorité de ces tâches, les commentaires sur toute tâche mise à jour cette semaine et les projets auxquels ces tâches appartiennent. Dans une API REST typique, c’est une cascade : récupérer la liste de l’équipe, puis pour chaque membre récupérer ses tâches, puis pour chaque tâche récupérer les commentaires et le projet. Des dizaines de requêtes, chacune dépendante de la précédente. L’agent doit orchestrer tout cela, gérer la pagination sur chaque point d’accès, faire face aux limitations de débit et recoudre des données de formes de réponse différentes. Beaucoup de logique séquentielle pour ce qui est, conceptuellement, une seule question.

En GraphQL, c’est une requête. Un aller-retour. Toutes les données, correctement imbriquées, exactement dans la forme demandée par l’agent. L’agent n’a pas à comprendre le schéma d’orchestration, ni à gérer d’état intermédiaire, ni à maintenir un modèle mental de la façon dont les points d’accès s’enchaînent. Chaque aller-retour éliminé est un mode de défaillance supprimé, un coût de latence économisé et un morceau de code d’orchestration que l’agent n’a jamais à écrire.

Pour un agent, qui est fondamentalement un moteur de raisonnement cherchant à minimiser la complexité inutile, c’est un avantage énorme.

Des mutations avec validation intégrée

L’avantage de GraphQL ne se limite pas à la lecture de données. Quand les agents doivent faire des choses (créer des enregistrements, mettre à jour un état, déclencher des flux) les mutations GraphQL offrent une interface structurée, prévisible et auto-validante.

Quand un agent crée un ticket de support via une API REST, il doit construire une requête POST avec un corps JSON, mais la forme exacte de ce corps (quels champs sont requis, lesquels sont optionnels, quels types ils attendent, quelles valeurs sont valides) n’est définie que dans une documentation externe. S’il se trompe, l’agent l’apprend à l’exécution, par une réponse d’erreur qui peut être utile ou non.

Les mutations GraphQL ont des objets d’entrée typés. Le schéma déclare explicitement chaque argument, son type, son caractère obligatoire ou non, et sa description. L’agent peut introspecter la mutation avant de faire l’appel, construire une charge utile valide avec certitude et demander exactement les données de confirmation qu’il veut en retour. Pas de devinette. Pas d’essais et d’erreurs. Pas d’intégrations instables recousues à coups d’espoir.

C’est ainsi qu’une machine devrait pouvoir interagir avec une application.

Le schéma est le contrat

Un schéma GraphQL est, en pratique, un manifeste de capacités lisible par la machine. Il déclare : voici tout ce que cette application peut faire, voici les types de données impliqués, voici comment ils se relient, voici les opérations disponibles. C’est un contrat entre votre application et tout système intelligent qui veut l’utiliser.

Quand un agent rencontre une API GraphQL, il n’a pas besoin d’une intégration sur mesure. Il n’a pas besoin que quelqu’un écrive un adaptateur à la main. Il lit le schéma et se met au travail. Le schéma est la couche d’intégration.

C’est la propriété autour de laquelle Archie Core a été conçu. Toute application construite sur Archie Core (frontend, backend ou les deux) obtient gratuitement un schéma GraphQL. Pas comme arrière-pensée, pas comme composant annexe, mais comme interface principale. L’implication n’est pas subtile : toute application livrée sur Archie est prête pour les agents dès le premier jour, parce que l’agent parle déjà la langue.

Dans une économie où les agents sont de plus en plus ceux qui choisissent quels outils invoquer au nom d’un utilisateur, être facile à utiliser n’est pas un détail technique. C’est une stratégie de mise sur le marché.

Les compromis honnêtes

GraphQL a de vrais coûts et prétendre le contraire serait paresseux. Construire un serveur GraphQL est plus lourd que monter des points d’accès REST. Les implémentations naïves peuvent générer un excès de requêtes en base (le problème N+1) et exigent des motifs de type DataLoader et de la planification de requêtes pour l’atténuer. La mise en cache est plus difficile qu’avec les ressources fondées sur des URL de REST : il faut des stratégies au niveau applicatif comme les requêtes persistées au lieu de s’appuyer sur le cache d’un CDN. Et si votre application a un modèle de ressources plat avec peu de relations, REST peut être parfaitement adéquat, même pour des agents.

Ce sont des défis d’ingénierie avec des solutions connues, pas des limites fondamentales. La question est de savoir si le coût vaut la peine face aux bénéfices de l’ère des agents, et la réponse est de plus en plus oui pour toute application qui prend cet avenir au sérieux.

Construisez l’API avec laquelle les machines peuvent penser

L’argument pour l’API-first est que les applications doivent être pleinement accessibles via des interfaces programmatiques parce que les agents deviennent les principaux consommateurs. L’argument pour GraphQL est l’extension naturelle : l’API devrait être conçue d’une façon que des machines intelligentes puissent découvrir, comprendre et utiliser avec un minimum de friction.

GraphQL vous donne un schéma auto-descriptif qui sert de manifeste vivant de capacités. Une récupération de données précise qui respecte les limites de contexte d’un agent. Des mutations typées qui éliminent les devinettes. Des abonnements en temps réel qui rendent possible un comportement proactif. Tout cela via un point d’accès unique avec un langage de requête unifié.

REST a été bâti pour un monde où les développeurs écrivaient les intégrations à la main, un point d’accès à la fois. Ce monde existe encore, et REST le sert toujours bien. Mais le monde qui émerge, où des agents découvrent et composent dynamiquement des capacités applicatives à la volée, exige quelque chose de plus expressif, de plus structuré, de plus introspectable.

GraphQL n’est plus seulement un confort pour développeurs. C’est le langage d’interface avec lequel des agents intelligents peuvent raisonner. Et les applications qui le parlent seront celles vers lesquelles ils se tourneront d’abord.

Lectures liées

Le plaidoyer pour l’architecture qui se trouve en dessous est dans l’interface est un mensonge, et sa version commerciale dans l’argument économique pour l’API-first.

Questions fréquentes

Pourquoi GraphQL est-il meilleur que REST pour les agents d’IA ? GraphQL est auto-documenté par introspection, permet aux agents de demander exactement les champs dont ils ont besoin en un seul aller-retour et impose des entrées typées sur les mutations. REST oblige les agents à deviner la forme des points d’accès, à orchestrer plusieurs appels pour des données liées et à découvrir les champs requis par essais et erreurs.

Qu’est-ce que le problème de la découverte ? Le problème de la découverte est le coût que paie un agent d’IA lorsqu’il arrive sur une application sans savoir quelles données et quelles opérations sont disponibles. Les API REST obligent l’agent à deviner ; les API GraphQL répondent par une seule requête d’introspection qui renvoie le schéma complet.

Quel est le rapport entre GraphQL et le Model Context Protocol (MCP) ? MCP est le standard d’Anthropic pour permettre aux assistants d’IA de découvrir et d’appeler des outils externes. Un schéma GraphQL a déjà la forme attendue par MCP : il fournit le manifeste de capacités lisible par la machine que MCP est conçu pour exposer. Les applications GraphQL rencontrent l’écosystème des agents à mi-chemin.

GraphQL n’a-t-il pas de vrais coûts et de la complexité ? Si. Les serveurs GraphQL sont plus complexes à construire que des points d’accès REST. La mise en cache est plus difficile. Les implémentations naïves ont des problèmes de requêtes N+1. Ce sont des défis d’ingénierie avec des solutions connues (DataLoader, requêtes persistées, planification de schéma) pas des limites fondamentales.

Pourquoi Archie Core a-t-il choisi GraphQL comme API principale ? Archie Core a été conçu pour que toute application construite dessus obtienne gratuitement un schéma GraphQL, ce qui rend l’application découvrable et opérable par des agents d’IA dès le premier jour. L’aptitude aux agents est une propriété de l’architecture, pas une fonctionnalité ajoutée plus tard.