Le tool use

L’utilisation d’outils (tool use) est ce qui transforme un générateur de texte en un composant qu’on appelle comme une fonction. Cette leçon montre comment déclarer un outil, comment Claude s’en sert, puis comment le SDK fait tourner la boucle à votre place avec le Tool Runner.

Quand utiliser un outil

La documentation donne quatre cas :

• les actions qui ont un effet : envoyer un e-mail, écrire un fichier, mettre à jour un enregistrement ;
• les données fraîches ou externes : un prix du jour, la météo, le contenu de votre base ;
• les sorties de forme garantie : un objet JSON avec des champs précis plutôt que de la prose ;
• l’appel à des systèmes existants : bases de données, API internes, systèmes de fichiers.

Déclarer un outil

Un outil se décrit par un nom, une description et un schéma d’entrée au format JSON Schema. Claude ne voit jamais votre implémentation : il ne connaît que ce schéma et ce que vous lui renvoyez. La description est donc décisive : elle dit à Claude à quoi sert l’outil et quand s’en servir.

const tools: Anthropic.Tool[] = [
  {
    name: "get_weather",
    description: "Get current weather for a location",
    input_schema: {
      type: "object",
      properties: {
        location: { type: "string", description: "City and country, e.g. Paris, France" },
        unit: { type: "string", enum: ["celsius", "fahrenheit"] },
      },
      required: ["location"],
    },
  },
];

Quand Claude veut l’utiliser, la réponse contient un bloc tool_use avec le nom de l’outil, un identifiant et un objet input d’arguments. Analysez cet objet comme du JSON, sans jamais faire de comparaison de chaînes sur sa forme sérialisée, puis renvoyez le résultat dans un bloc tool_result portant le même identifiant.

Garantir les arguments, orienter le choix

• strict: true sur la définition d’un outil garantit que les arguments respectent exactement le schéma, qui doit alors comporter additionalProperties: false et la liste required.
• tool_choice vaut auto par défaut : Claude décide s’il appelle un outil. Attention : sur Claude Opus 5.5, Sonnet 5.5 et Fable 5.1, forcer l’appel ({ type: "any" } ou { type: "tool", name: ... }) renvoie une erreur 400. Orientez Claude par le prompt (« utilise l’outil get_weather ») et vérifiez qu’un bloc tool_use est bien revenu. Si vous vouliez forcer un outil seulement pour obtenir du JSON, utilisez plutôt les sorties structurées (output_config.format).

Le Tool Runner : la boucle sans l’écrire

Une fois la boucle comprise, le SDK peut la faire tourner pour vous. Le Tool Runner (en bêta dans le SDK TypeScript) prend des outils définis avec leur fonction d’exécution, appelle l’API, exécute les outils, renvoie les résultats et recommence jusqu’à ce que Claude n’ait plus d’appel à faire :

import Anthropic from "@anthropic-ai/sdk";
import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod";
import { z } from "zod";

const client = new Anthropic();

const getWeather = betaZodTool({
  name: "get_weather",
  description: "Get current weather for a location",
  inputSchema: z.object({
    location: z.string().describe("City and country, e.g. Paris, France"),
    unit: z.enum(["celsius", "fahrenheit"]).optional(),
  }),
  run: async (input) => {
    return `22 °C et ensoleillé à ${input.location}`; // votre implémentation
  },
});

const finalMessage = await client.beta.messages.toolRunner({
  model: "claude-opus-5-5",
  max_tokens: 16000,
  tools: [getWeather],
  messages: [{ role: "user", content: "Quel temps fait-il à Paris ?" }],
});

console.log(finalMessage.content);

Le schéma est généré à partir de la définition Zod, et les entrées sont typées. Zod est facultatif : betaTool() accepte un schéma JSON brut.

Le Tool Runner n’est pas un mécanisme opaque : il garde des points d’accroche à chaque tour pour une validation humaine, la journalisation ou l’interception d’erreurs. Une précaution signalée par la documentation : s’il mélange vos outils et des outils serveur, il ne relance pas de lui-même un tour terminé par pause_turn. Vérifiez donc stop_reason à chaque itération.

Tool Runner ou Claude Agent SDK ?

Les deux noms se ressemblent mais désignent deux produits. Le Tool Runner fait partie du SDK de l’API : il fait tourner la boucle sur les outils que vous définissez, sans outil intégré ni système de fichiers. Le Claude Agent SDK est Claude Code empaqueté en bibliothèque, avec ses outils intégrés (lecture et écriture de fichiers, bash, recherche…), ses sous-agents et ses permissions. Dans les deux cas, c’est vous qui hébergez et déployez.

À vous de jouer

Un outil, deux façons. Définissez un outil get_weather avec un schéma JSON et strict: true, et écrivez la boucle à la main comme à la leçon 4. Refaites-le ensuite avec le Tool Runner et betaZodTool. Comparez le nombre de lignes, puis ajoutez une erreur volontaire dans l’outil pour voir comment chaque version la renvoie à Claude.

Sources officielles : What is tool use? (Claude Academy) · Tool use overview · How tool use works

Points clés à retenir

• Un outil = un nom, une description (décisive) et un schéma JSON ; Claude ne voit jamais votre code
• tool_use en sortie, tool_result en retour, avec le même identifiant ; analysez toujours les arguments comme du JSON
• strict: true garantit les arguments ; forcer un outil renvoie une 400 sur Opus 5.5, Sonnet 5.5 et Fable 5.1
• Le Tool Runner fait tourner la boucle pour vos outils ; le Claude Agent SDK est un autre produit, avec les outils de Claude Code