appel d’outils

L’appel d’outils est un format avant d’être une capacité : tout ce que cette fiche affirme se lit dans la forme des objets échangés. Voici les quatre temps ci-dessus, dans le même ordre, avec les objets à la place des phrases.

1. 01

   Déclarer le catalogue

   Le catalogue part dans le contexte, comme du texte, à chaque tour. Il n’existe aucun autre canal : ce que le modèle sait de vos outils tient entièrement dans ces quelques lignes, et rien de ce que fait l’outil ne lui est accessible autrement.

   jsonCopier

   {
     "name": "chercher_dossier",
     "description": "Retrouve un dossier par son numéro exact, tel qu'il figure dans la conversation. Ne cherche ni par nom, ni par date.",
     "input_schema": {
       "type": "object",
       "properties": {
         "numero": { "type": "string", "pattern": "^[A-Z]-[0-9]{4}$" }
       },
       "required": ["numero"],
       "additionalProperties": false
     }
   }
   

   name

   L’identifiant que le modèle recopiera dans sa demande. C’est tout ce qui apparie une déclaration et un appel.

   description

   Le seul critère sur lequel le modèle choisit. C’est donc du prompt, pas de la documentation : ce qu’on y écrit change le comportement. Y nommer le hors périmètre évite plus d’appels erronés que d’y détailler le périmètre.

   input_schema

   La forme attendue des paramètres. Elle sert deux fois : elle oriente le modèle quand il remplit, et elle arme la validation du harnais quand il reçoit.

   additionalProperties

   À false, un champ inventé fait échouer la validation au lieu de traverser sans bruit.

   Le piègeDeux outils dont les descriptions se chevauchent produisent des choix erratiques, et aucune instruction ajoutée ailleurs ne les départage : le problème se règle ici, dans la rédaction du catalogue, et nulle part ailleurs.

2. 02

   Lire la demande

   Le modèle n’a rien fait. Il a produit cet objet, puis il s’est arrêté. Rien là dedans n’a touché un système d’information : c’est le bon de commande de l’analogie, et il peut encore être refusé.

   jsonCopier

   {
     "role": "assistant",
     "stop_reason": "tool_use",
     "content": [
       { "type": "text", "text": "Je vérifie ce dossier." },
       {
         "type": "tool_use",
         "id": "appel_01",
         "name": "chercher_dossier",
         "input": { "numero": "A-4417" }
       }
     ]
   }
   

   stop_reason

   Le motif d’arrêt. Il vaut ici « appel d’outils » et non « fin de tour » : c’est à cette valeur que le harnais reconnaît qu’on attend quelque chose de lui.

   id

   L’appariement. Le résultat devra citer cet identifiant, faute de quoi le modèle ignore de quelle demande il est la réponse, et plusieurs appels partis ensemble deviennent indémêlables.

   input

   Les paramètres, remplis par plausibilité comme le reste du texte. Rien ici ne garantit que le dossier A-4417 ait jamais existé.

   Le piègeUn même tour peut porter plusieurs blocs tool_use. Un harnais qui ne lit que le premier laisse les autres sans réponse : le format attend un résultat par demande, et le tour suivant part incohérent.

3. 03

   Valider, puis exécuter

   Voici le seul endroit du dispositif où quelque chose se produit, donc le seul où l’on puisse l’empêcher. Les quatre contrôles sont dans cet ordre parce que chacun suppose le précédent : on ne valide pas les paramètres d’un outil qui n’existe pas, on ne vérifie pas un droit sur des paramètres non validés.

   jsCopier

   async function executer(appel, session) {
     const outil = CATALOGUE[appel.name];
   
     // 1 · l'outil existe-t-il ? un nom s'invente aussi bien qu'un paramètre
     if (!outil) return refus('outil inconnu');
   
     // 2 · les paramètres tiennent-ils le schéma déclaré au temps 01 ?
     const verdict = valider(appel.input, outil.input_schema);
     if (!verdict.ok) return refus(verdict.raison);
   
     // 3 · le DEMANDEUR a-t-il ce droit ? la question ne porte pas sur le modèle
     if (!session.droits.has(outil.droit)) return refus('droit refusé');
   
     // 4 · irréversible : on rend la main plutôt que d'agir
     if (outil.irreversible && !session.aConfirme(appel)) return refus('confirmation requise');
   
     journal.ecrire({ session: session.id, appel });
     return { content: await outil.lancer(appel.input, session), is_error: false };
   }
   
   // un refus se RACONTE au modèle : il n'interrompt pas la boucle
   const refus = (raison) => ({ content: `Refusé : ${raison}.`, is_error: true });
   

   session.droits

   Les droits du demandeur humain, portés par sa session. C’est la ligne qui décide si le dispositif tient.

   is_error

   Un refus reste un résultat, pas une exception. Le modèle le lit, comprend pourquoi, et peut corriger son appel : une erreur remontée en exception coupe la boucle et lui laisse croire que l’action a eu lieu.

   Le piègeLe troisième contrôle interroge la session, jamais la demande. Un système qui déduit les droits de ce que le modèle a écrit fait signer l’autorisation par celui même qu’elle est censée contraindre : un document piégé qui obtient un appel obtient du même coup le droit de l’exécuter.

4. 04

   Réinjecter, et relancer

   Le résultat revient comme un message de plus, et le modèle reprend là où il s’était arrêté. C’est ce tour de boucle, et non le modèle, qui produit ce qu’on appelle un agent : le modèle, lui, ne fait que répondre à un contexte plus long à chaque passage.

   jsCopier

   let tours = 0;
   
   while (tours++ < MAX_TOURS) {
     const reponse = await modele.repondre({ messages, outils });
     messages.push({ role: 'assistant', content: reponse.content });
   
     const appels = reponse.content.filter((b) => b.type === 'tool_use');
     if (appels.length === 0) return reponse;   // le modèle rédige : le tour est fini
   
     // un résultat par demande, tous dans UN message, avant de relancer
     const resultats = await Promise.all(
       appels.map(async (appel) => ({
         type: 'tool_result',
         tool_use_id: appel.id,               // le même identifiant qu'au temps 02
         ...(await executer(appel, session)), // { content, is_error }
       })),
     );
   
     messages.push({ role: 'user', content: resultats });
   }
   

   MAX_TOURS

   La condition d’arrêt. Sans elle, deux outils qui se renvoient l’un à l’autre bouclent jusqu’à épuisement du budget : rien dans le format n’oblige le modèle à s’arrêter.

   content

   Du texte, et rien d’autre. Ce qu’un outil rapporte se lit exactement comme une consigne : c’est par là qu’un contenu extérieur peut commander l’appel suivant.

   Le piègeLa boucle ne distingue pas ce qui vient de vous de ce qui vient d’un document rapporté : tout est du texte dans le même contexte. C’est ici, à ce point précis du circuit, que se joue l’injection de prompt que la couche 2 annonce, et la fiche `injection-de-prompt` montre l’absence de champ qui la rend possible.

Ce qui varieLes noms de champs varient d’un fournisseur à l’autre : input_schema s’appelle ailleurs parameters, le bloc tool_use s’appelle ailleurs un appel de fonction, et le résultat remonte tantôt dans un message d’utilisateur, tantôt dans un rôle qui lui est propre. Le circuit, lui, ne varie pas : un catalogue décrit en JSON Schema, une demande nommée et identifiée, un résultat apparié rendu sous forme de texte, une boucle qui relance. C’est pourquoi un catalogue se transporte d’un modèle à l’autre en renommant des champs, jamais en changeant d’architecture.