Qu'est-ce que l'utilisation d'outils ?
Vos flux de travail actuels reposent sur de nombreuses technologies différentes — logiciels de gestion de projet, bases de données, fichiers. Claude ne peut pas vérifier ces éléments par lui-même. Il s'appuie plutôt sur des outils, qui donnent à Claude accès à des données et des actions externes.
Qu'est-ce qu'un outil
En termes simples, un outil est une fonction que vous définissez et exposez à Claude. Vous décrivez ce qu'elle fait et quelles entrées elle prend, et Claude décide quand l'appeler.
Voici l'essentiel à bien comprendre : Claude n'exécute pas l'outil — c'est votre code qui le fait. Le déroulement ressemble à ceci :
- Claude demande un appel d'outil.
- Votre code exécute la fonction.
- Le résultat est renvoyé à Claude, qui poursuit son raisonnement.
Comment les outils sont définis
Les outils sont des schémas JSON comportant trois parties : un nom, une description et un schéma d'entrée. Vous les transmettez à Claude dans le corps de la requête sous la forme d'un tableau tools.
La description est ce que Claude lit pour décider s'il doit appeler l'outil. Si vous rédigez une description vague, vous obtenez une mauvaise utilisation d'outils. C'est la principale raison pour laquelle les agents se trompent ou ne saisissent pas les outils dont ils disposent. Soyez précis.
Voici à quoi ressemble une définition d'outil :
{
"name": "lookup_building_code",
"description": "Look up a specific building code section by its identifier. Returns the full text of that code section.",
"input_schema": {
"type": "object",
"properties": {
"section": {
"type": "string",
"description": "The building code section to look up"
}
},
"required": ["section"]
}
}Alors que se passe-t-il lorsqu'on utilise cela ? Disons que nous envoyons un rapport de conformité à un agent. Au premier tour, Claude répond avec stop_reason: "tool_use" — c'est notre signal. Voici à quoi ressemble cette réponse :

Notre boucle appelle lookup_building_code avec le paramètre demandé par Claude, puis renvoie le résultat sous forme de résultat d'outil — un message utilisateur contenant un bloc tool_result lié à l'identifiant de l'appel d'outil :

Et Claude poursuit. À ce stade, nous pouvons continuer à appeler des outils et à renvoyer des résultats à Claude jusqu'à ce qu'il dispose de ce dont il a besoin.
Plusieurs outils : laisser Claude choisir
Un seul outil est utile, mais la partie intéressante consiste à donner à Claude plusieurs outils et à observer lequel il choisit d'utiliser, et dans quel ordre.
Imaginez ce scénario : vous préparez vos bagages pour un voyage de trois jours à Denver, et vous souhaitez connaître à la fois la météo du jour et les prévisions pour les prochains jours. Nous déclarons donc deux outils au lieu d'un seul :
const tools = [
{
name: "get_weather",
description: "Get today's current weather for a city.",
input_schema: {
type: "object",
properties: {
city: { type: "string", description: "The city to check" }
},
required: ["city"]
}
},
{
name: "get_forecast",
description: "Get the weather forecast for the next few days for a city.",
input_schema: {
type: "object",
properties: {
city: { type: "string", description: "The city to check" }
},
required: ["city"]
}
}
];La boucle est identique aux boucles d'agent que nous avons déjà vues. Le seul nouvel élément est une fonction runTool qui se répartit selon le nom de l'outil à l'aide d'une instruction switch — ce bloc de code est simplement l'endroit où votre code s'exécute réellement. Elle ajoute également deux recherches codées en dur et le message initial afin que vous puissiez l'exécuter, et elle utilise le client de « Votre premier appel à l'API » :
// Deux recherches codées en dur. Dans une vraie application, elles appelleraient un service météo.
const getWeather = (city) => `${city} today: 34F, snow flurries`;
const getForecast = (city) => `${city}, next three days: 38F, 45F, and 52F, sunny`;
const messages = [
{
role: "user",
content:
"I'm packing for a three-day trip to Denver. What's the weather today and over the next few days?",
},
];
function runTool(name, input) {
switch (name) {
case "get_weather":
return getWeather(input.city);
case "get_forecast":
return getForecast(input.city);
}
}
while (true) {
const response = await client.messages.create({
model: "claude-sonnet-5",
max_tokens: 1024,
messages,
tools,
});
if (response.stop_reason !== "tool_use") {
// Claude a terminé — c'est la réponse finale
for (const block of response.content) {
if (block.type === "text") console.log(block.text);
}
break;
}
messages.push({ role: "assistant", content: response.content });
const toolResults = response.content
.filter((block) => block.type === "tool_use")
.map((block) => ({
type: "tool_result",
tool_use_id: block.id,
content: runTool(block.name, block.input),
}));
messages.push({ role: "user", content: toolResults });
}Et c'est tout le principe. Vous voulez un troisième outil ? Ajoutez-le au tableau, ajoutez un cas au switch, et c'est terminé.
Exécutez ceci, et vous verrez Claude appeler get_weather puis get_forecast — parfois dans le même tour, parfois l'un après l'autre. Il répond ensuite : prévoyez plusieurs couches, attendez-vous à des averses de neige aujourd'hui, avec un réchauffement au fil de la semaine.
Remarquez maintenant comment Claude a choisi. Il a lu les descriptions, a associé votre requête à « la météo du jour » et « les prochains jours », et a sélectionné le bon outil pour chacun. C'est pourquoi les descriptions de vos outils comptent vraiment.
Le tool runner : éviter le code répétitif
Vous avez probablement déjà repéré deux signaux d'alerte dans ce que nous venons d'écrire :
- C'est beaucoup de code pour deux simples recherches.
- Dans une base de code réelle, vous ne voulez pas écrire à la main des schémas JSON pour chaque fonction que vous avez. C'est comme écrire votre code deux fois.
C'est là qu'intervient le tool runner. Il est disponible en version bêta dans les SDK Claude : TypeScript, Python, Ruby, C#, Go, Java et PHP. Vous définissez chaque outil une seule fois, et le runner gère en interne l'ensemble de la boucle d'utilisation d'outils / de résultats d'outils.
En TypeScript, l'assistant recommandé du runner, betaZodTool(), décrit chaque outil à l'aide d'un court schéma écrit en Zod, une bibliothèque TypeScript permettant de déclarer et de valider la forme des données. Cet assistant nécessite Zod 3.25.0 ou une version ultérieure, ce qu'une installation récente vous fournit :
npm install zodVotre code se réduit à ceci : décrire l'outil, envoyer la requête, attendre le résultat. Voici la même démonstration météo à deux outils, connectée via le tool runner :
import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod";
import { z } from "zod";
// Encapsule les deux mêmes recherches effectuées manuellement, chacune avec un court schéma Zod
const weatherTool = betaZodTool({
name: "get_weather",
description: "Get today's current weather for a city.",
inputSchema: z.object({
city: z.string().describe("The city to check"),
}),
run: async ({ city }) => getWeather(city),
});
const forecastTool = betaZodTool({
name: "get_forecast",
description: "Get the weather forecast for the next few days for a city.",
inputSchema: z.object({
city: z.string().describe("The city to check"),
}),
run: async ({ city }) => getForecast(city),
});
const runner = client.beta.messages.toolRunner({
model: "claude-sonnet-5",
max_tokens: 1024,
messages: [
{
role: "user",
content:
"I'm packing for a three-day trip to Denver. What's the weather today and over the next few days?",
},
],
tools: [weatherTool, forecastTool],
});
// Attend le runner pour obtenir le message final une fois tous les allers-retours d'outils terminés
const finalMessage = await runner;
for (const block of finalMessage.content) {
if (block.type === "text") console.log(block.text);
}Même scénario, une fraction du code :
- Pas de boucle while, pas de switch sur le motif d'arrêt, pas de renvoi manuel des résultats d'outils dans les messages — le runner s'occupe de tout cela.
- Aucun schéma JSON écrit à la main, juste un court schéma Zod par outil, qui valide également l'entrée envoyée par Claude.
- Chaque fonction
runencapsule la même recherche que nous avons exécutée manuellement il y a un instant. - Attendre le runner renvoie le message final de l'assistant une fois que tout s'est stabilisé.
Exécutez-le, et vous obtenez la même réponse.
Les outils réels encapsulent votre code existant
Dans la vraie vie, vos outils ne seraient pas des données météo codées en dur. Ils encapsuleraient des fonctions réelles que vous avez déjà dans votre application.
Prenons un agent de revue de conformité : ses outils sont de fines enveloppes autour des fonctions lookup_building_code et search_building_code qui existent déjà dans la base de code. Avec le tool runner, vous encapsulez chacune de ces fonctions dans une courte définition d'outil avec son propre schéma Zod, et l'agent cite des sections de code spécifiques dans chaque constat qu'il rédige :

Récapitulatif
- Les outils donnent à Claude accès à vos systèmes. Un outil est une fonction que vous définissez et exposez ; Claude décide quand l'appeler, et votre code l'exécute.
- Les outils sont des schémas JSON comportant un nom, une description et un schéma d'entrée, transmis dans la requête sous la forme d'un tableau
tools. - Rédigez des descriptions précises. Les descriptions vagues sont la principale raison pour laquelle les agents se trompent.
stop_reason: "tool_use"est votre signal pour exécuter l'outil et renvoyer le résultat sous forme de résultat d'outil.- Pour plusieurs outils, répartissez selon le nom de l'outil. Ajouter un outil signifie l'ajouter au tableau et ajouter un cas.
- Le tool runner du SDK (disponible en version bêta dans tous les SDK Claude) gère l'ensemble de la boucle, et en TypeScript, chaque outil est une courte définition accompagnée d'un schéma Zod. Vous pouvez aussi exécuter la boucle vous-même.
- Vous exécutez, ou vous déléguez la boucle. À l'extrémité de ce spectre, les agents gérés délèguent l'ensemble de l'agent à Anthropic.