Tool calling et sorties structurées : le contrat qui tient

Avant la mécanique, la phrase qui évite le plus de confusion : un appel d’outil est une demande, pas une action.

Le modèle émet un message structuré qui dit je voudrais que search_flights soit appelé avec ces arguments. Puis il s’arrête. Votre code reçoit ce message, décide s’il l’honore, appelle ce qu’il doit appeler, puis renvoie le résultat sous forme d’un autre message. Le modèle n’a jamais touché votre base de données, n’a jamais fait de requête HTTP, n’a jamais eu d’identifiants.

Tout ce qui concerne la sécurité des agent dans le chapitre 30 découle de cette séparation, tout comme tout ce qui concerne la conception des agent dans le chapitre 23 : le modèle propose et votre code dispose, et c’est dans le code que vivent toutes les garanties.

Donc un outil, dépouillé du vocabulaire, est deux choses :

Rien de tout cela n’est émergent. Comme l’a établi le chapitre 11, le tool calling est un comportement entraîné :¹ pendant le post-entraînement, le modèle a vu des milliers de conversations structurées exactement ainsi. C’est pourquoi le format dépend du modèle, pourquoi la fiabilité varie autant entre des modèles de taille similaire, et pourquoi un modèle peut appeler un outil qu’il n’a jamais vu — la forme a été apprise, l’outil précis vient de votre prompt.

Voici l’outil tel que la plupart des gens l’écrivent au début. Notez que rien n’est faux ; il est simplement trop mince :

{
  name: "search_flights",
  description: "Search for flights.",
  parameters: {
    type: "object",
    properties: {
      from: { type: "string", description: "Airport." },   
      to:   { type: "string", description: "Airport." },   
      date: { type: "string", description: "The date." },  
    },
    required: ["from", "to", "date"],
  },
}

Vingt-quatre requêtes, six paires de villes croisées avec quatre façons d’exprimer une date (« le 3 du mois prochain », « vendredi prochain », « 15 décembre », « demain »), décodage greedy pour que les résultats soient reproductibles :

Lisez les deux premières colonnes avant les trois dernières. Le modèle appelle le bon outil à chaque fois et produit un JSON bien formé à chaque fois. L’échec est entièrement dans les valeurs, et les valeurs sont inutilisables : "Madrid" au lieu de MAD, "3rd October 2026" au lieu de 2026-10-03.

Il vaut la peine d’insister, parce que cela détermine où regarder quand quelque chose casse. Le réflexe est d’ajouter un parseur JSON avec une nouvelle tentative, ou de demander plus fermement au modèle un JSON valide. Ni l’un ni l’autre ne traite quoi que ce soit de ce qui s’est passé ici.

Même endpoint. Même code derrière. Même modèle, mêmes prompts, même décodage. La seule chose qui change est le texte dans le schéma :

{
  name: "search_flights",
  description: "Search scheduled flights between two airports on a given day.",
  parameters: {
    type: "object",
    properties: {
      from: {
        type: "string",
        description: "Departure airport as a three-letter IATA code, e.g. MAD for Madrid. Never a city name.",   
        pattern: "^[A-Z]{3}$",
      },
      to: { /* same */ },
      date: {
        type: "string",
        description: "Departure date as an ISO 8601 calendar date, YYYY-MM-DD. Resolve relative dates against today before calling.",   
        format: "date",
        pattern: "^\\d{4}-\\d{2}-\\d{2}$",
      },
    },
    required: ["from", "to", "date"],
  },
}

Le format de date passe de 2 sur 24 à 24 sur 24. Parfait, grâce à un changement de texte, sans toucher au code et sans logique de nouvelle tentative. Si vous devez retenir une habitude opérationnelle de ce chapitre, c’est celle-ci : quand un outil est appelé de travers, la correction est presque toujours dans la description, et c’est la correction la moins chère du système.

Lisez maintenant la deuxième colonne, qui est la moitié la plus importante.

La date est au format ISO 24 fois sur 24. C’est le bon jour 12 fois sur 24.

La moitié des appels contient donc maintenant une date parfaitement formatée qui est la mauvaise date. La description a dit au modèle quelle forme produire, et le modèle l’a produite sans faute — mais transformer « vendredi prochain » en 2026-09-11 exige de connaître la date du jour et de faire de l’arithmétique de calendrier, et aucune description ne fournit cela. Même histoire pour les aéroports : le format est passé de 4 à 16, mais la valeur seulement de 4 à 8, parce qu’écrire MAD exige de savoir que l’aéroport de Madrid est MAD.

Cette distinction est l’idée porteuse du chapitre :

Un schéma est un contrat sur la forme. Il peut rendre la sortie du modèle analysable, typée et cohérente. Il ne peut pas la rendre vraie, et tout mode d’échec qui survit à un bon schéma est un échec de connaissance, pas un échec de format.

Les deux demandent des corrections différentes, et les confondre fait perdre des semaines. Les échecs de format se corrigent dans la description ou avec du décodage contraint, ci-dessous. Les échecs de connaissance se corrigent en mettant la connaissance dans le prompt — la date actuelle dans le message système, une recherche d’aéroport comme second outil que le modèle appelle d’abord, un enum dans le schéma quand l’ensemble est assez petit pour être énuméré. Notez ce que les trois ont en commun : ils déplacent le problème hors de la mémoire du modèle et dans son entrée, ce qui est tout le sujet du chapitre 24.

Tout ce qui précède repose encore sur le fait que le modèle choisit de produire la bonne forme. Il existe une garantie plus forte, et c’est le meilleur retour du chapitre 17.

Rappelez-vous comment fonctionne la génération : à chaque étape, le modèle produit un logit pour chaque token du vocabulaire, et l’échantillonneur en choisit un. Le décodage contraint insère une étape entre les deux. À partir d’une grammaire — dérivée de votre JSON Schema — il calcule quels tokens pourraient légalement venir ensuite, fixe les logits de tous les autres à l’infini négatif, puis laisse l’échantillonneur choisir parmi ce qui reste.

Si le schéma dit que la prochaine chose doit être un {, alors chaque token qui n’est pas { a une probabilité zéro. Pas « improbable » : zéro. Le modèle ne peut pas émettre de JSON invalide parce que les tokens invalides ont été retirés de la distribution avant l’échantillonnage.

C’est ce que sont, sous le capot, les « sorties structurées », le « JSON mode » et la « génération guidée », et cela explique leurs deux propriétés. La garantie est totale pour tout ce que la grammaire peut exprimer — types, champs requis, enums, imbrication — parce qu’elle est appliquée mécaniquement plutôt que demandée poliment. Et elle ne dit rien sur le contenu : une grammaire peut forcer "date" à être une chaîne correspondant à un motif de date, et ne peut pas le forcer à être le bon jour. C’est le même mur que dans la section précédente, atteint par l’autre côté.

Deux notes pratiques. Ce n’est pas gratuit : le masque doit être calculé à chaque étape, et les grammaires complexes coûtent une latence mesurable. Et cela change ce que fait le modèle — un modèle détourné de son token préféré peut produire un contenu moins bon tout en produisant une structure parfaite, ce qui explique pourquoi « demander gentiment et valider » reste un défaut raisonnable pour des formes simples, tandis que le décodage contraint mérite son coût quand la forme est complexe ou que le consommateur est strict.

Le chapitre 14 a mesuré un timeout suivi d’une nouvelle tentative facturant deux générations pour une seule réponse. Avec les outils, le même échec empire, parce qu’un outil peut faire quelque chose.

Si votre code appelle charge_card, expire, puis réessaie, vous avez deux débits. Le modèle n’a aucune idée que cela s’est produit ; il voit un seul résultat d’outil. La correction est la même que dans n’importe quel système distribué, et ce n’est pas le problème du modèle : rendre l’opération idempotente en donnant une clé à l’appel, afin que la deuxième exécution reconnaisse la première et renvoie son résultat au lieu de refaire le travail.

La règle de conception qui en découle mérite d’être énoncée clairement. Séparez les lectures des écritures dans votre catalogue d’outils. Une lecture peut être relancée librement, exécutée en parallèle et mise en cache. Une écriture ne le peut pas, et doit porter une clé, une vérification d’autorisation et — pour tout ce dont un utilisateur voudrait être informé avant que cela n’arrive — une étape d’approbation qui place un humain entre la demande et l’action. Cette étape d’approbation n’est pas une politesse : c’est l’une des rares choses qui se dressent entre une injection de prompt et une conséquence réelle — et, le chapitre 30 le mesure, la plus faible d’entre elles.

Le folklore dit que charger beaucoup d’outils fait mal choisir le modèle. Cela vaut la peine de mesurer plutôt que de répéter, donc : les mêmes vingt-quatre requêtes, avec l’outil de vols plus un ensemble croissant d’autres outils — dont trois volontairement confusables (horaires de train, traversées en ferry, lignes de bus).

La sélection ne s’est pas dégradée. Avec vingt outils, dont trois plausiblement confusables, un modèle d’un demi-milliard de paramètres a choisi le bon vingt-quatre fois sur vingt-quatre. Le creux à dix correspond à trois appels qui ont nommé un autre outil, et il ne survit pas au passage à vingt.

C’est un résultat négatif et il faut le présenter comme tel : sur cette tâche, avec ces outils, « trop d’outils » n’était pas le problème. Ce qui a bien augmenté, monotoniquement et d’un facteur six, c’est le prompt : de 353 tokens à 2,119, payés à chaque requête de la conversation, pour toujours, qu’un outil soit utilisé ou non.

La version honnête du folklore porte donc sur le coût et le context, pas sur l’exactitude. Vingt outils sont une taxe permanente sur chaque message, et le chapitre 16 a déjà montré ce qu’un préfixe permanent fait à une facture sur quarante tours. Quand des gens rapportent que beaucoup d’outils nuisent à la qualité, le mécanisme est généralement que les définitions ont évincé le context qui comptait — un problème de chapitre 24 déguisé en chapitre 18. Les outils réellement quasi doublons sont aussi un vrai problème, et la correction n’est pas de réduire le nombre d’outils mais d’avoir de meilleures descriptions et namespaces : préfixez-les par système (crm.search_customer, billing.search_customer) pour que deux catalogues fusionnés de deux équipes n’entrent pas en collision, et pour que le modèle ait quelque chose sur quoi discriminer.

Il est utile de classer les outils selon ce qu’ils font au monde, parce que l’ingénierie diffère pour chacun.

Les outils de données lisent : chercher, récupérer, interroger. Ils peuvent être relancés, parallélisés, mis en cache. Ils échouent en ne renvoyant rien d’utile, et leur principal risque est de faire entrer du texte non fiable dans le context — ce qui constitue toute la surface d’attaque du chapitre 30.

Les outils d’action écrivent : envoyer, créer, facturer, supprimer. Ils ne sont pas relançables sans clé, ne sont pas parallélisables en sécurité, et sont la raison d’être des flux d’approbation.

Les outils d’orchestration appellent d’autres modèles. Un outil dont l’implémentation est un autre agent, avec son propre prompt, ses propres outils et sa propre boucle — et pour le modèle appelant, il ressemble exactement aux deux autres, parce qu’un schéma et un endpoint sont tout ce qu’il voit jamais.

Ce troisième type n’est pas une curiosité. C’est le mécanisme derrière la moitié agent-as-a-tool du chapitre 25 — l’autre topologie, le handoff, abandonne la conversation et ne la récupère jamais — et il fonctionne précisément parce que l’interface de ce chapitre est assez étroite pour qu’un agent entier tienne derrière.

Vous avez maintenant un modèle qui peut demander des choses, et un contrat qui rend la demande analysable. Ce que vous n’avez pas, c’est quoi que ce soit à lui faire demander à propos de au-delà de ce qui tient dans son prompt.

L’outil le plus courant en production, et de loin, est une recherche sur un corpus de texte que le modèle n’a jamais vu pendant l’entraînement : votre documentation, vos tickets, vos contrats. Cela ressemble à un problème résolu — faites-en un embedding, trouvez les plus proches voisins, collez-les — et les parties qui ne sont pas résolues sont celles qui décident si la réponse est digne de confiance : comment le texte est découpé avant d’être embedded, quel seuil de similarité est assez bas pour signifier je ne sais pas, et comment une citation est attachée à une affirmation pour qu’un lecteur puisse la vérifier.

Le chapitre 19 porte sur la retrieval, et c’est le chapitre où une mauvaise réponse cesse d’être une curiosité pour devenir une responsabilité.

Les mesures de ce chapitre viennent de Qwen/Qwen2.5-0.5B-Instruct avec décodage greedy, sur 24 requêtes générées croisant six paires de villes et quatre formulations de date, en utilisant le template de chat propre au modèle pour les définitions d’outils. Elles se reproduisent exactement, et il s’agit d’un petit modèle : lisez la séparation format/valeur comme une démonstration du mécanisme plutôt que comme un benchmark de ce que font les modèles actuels. Un modèle frontier résout « vendredi prochain » correctement bien plus souvent — et ne peut toujours pas y être contraint par un schéma, ce qui est la partie qui se généralise.

Le vocabulaire JSON Schema utilisé ci-dessus (type, properties, required, pattern, format, enum) est spécifié dans le draft JSON Schema nommé par la documentation de votre fournisseur ; le sous-ensemble utile est petit et le même d’un fournisseur à l’autre, et les différences qui existent — quels mots-clés sont imposés par le décodage contraint plutôt que simplement transmis au modèle — méritent d’être lues dans le guide de sorties structurées du fournisseur plutôt que supposées.

Pour le décodage contraint comme technique, les bibliothèques de style guidance et le projet outlines documentent la construction grammaire-vers-masque-de-logits d’une façon qui correspond directement à l’échantillonneur du chapitre 17. Et pour l’aller-retour lui-même, la spécification la plus claire n’est pas un tutoriel mais un protocole : le chapitre 26 le lit ligne par ligne.