Gérer les appels d’outils
Analysez les blocs tool_use, formatez les réponses tool_result et gérez les erreurs avec is_error.
Lorsque la réponse de Claude contient des blocs tool_use, votre code exécute chaque outil et renvoie des blocs tool_result, y compris les éventuelles erreurs. Écrivez ce code vous-même lorsque vous avez besoin d’un contrôle personnalisé sur l’exécution des outils. Sinon, utilisez l’exécuteur d’outils du SDK, qui exécute les outils et envoie les résultats à votre place.
La réponse de Claude diffère selon qu’il utilise un outil client ou un outil serveur.
Gérer les résultats des outils clients
La réponse a un stop_reason de tool_use et un ou plusieurs blocs de contenu tool_use qui incluent :
id: Un identifiant unique pour ce bloc d’utilisation d’outil particulier. Il est utilisé pour faire correspondre les résultats de l’outil ultérieurement.name: le nom de l’outil utilisé.input: un objet contenant l’entrée transmise à l’outil, conforme auinput_schemade l’outil.
Un bloc tool_use pour un membre de l’ensemble d’outils computer use (utilisation de l’ordinateur) ou browser use (utilisation du navigateur) comporte également un champ toolset_name ("computer" ou "browser"). Son name est l’outil membre que Claude appelle, tel que screenshot ou navigate ; répartissez donc ces blocs en fonction des deux champs.
{
"id": "msg_01Aq9w938a90dw8q",
"model": "claude-opus-5-5",
"stop_reason": "tool_use",
"role": "assistant",
"content": [
{
"type": "text",
"text": "I'll check the current weather in San Francisco for you."
},
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_weather",
"input": { "location": "San Francisco, CA", "unit": "celsius" }
}
]
}Lorsque vous recevez une réponse d’utilisation d’outil pour un outil client, suivez ces étapes :
- Pour chaque bloc
tool_use, exécutez l’outil que le bloc nomme, en lui transmettant soninput. - Dans une nouvelle requête, conservez les messages précédents et ajoutez le
contentde la réponse sans modification en tant que messageassistant. - Ajoutez un message
usercontenant un bloctool_resultpour chaque bloctool_usede ce contenu, même si l’outil a échoué. - Envoyez la requête avec les mêmes
toolsque la première requête. Claude utilise les résultats des outils pour poursuivre sa réponse. - Si le
stop_reasonde la réponse suivante est égalementtool_use, répétez ces étapes. Pour les autres valeurs, consultez la référence rapide des raisons d’arrêt.
Pour ces étapes sous forme de programmes complets, consultez Tutoriel : Construire un agent utilisant des outils.
Chaque bloc tool_result a son type défini sur tool_result, ainsi que les champs suivants :
tool_use_id: l’iddu bloctool_useauquel ce résultat répond.content(facultatif) : le résultat de l’outil, sous forme de chaîne de caractères ou de liste de blocs de contenu. Ces blocs de contenu peuvent utiliser les typestext,image,documentousearch_result.is_error(facultatif) : défini surtruesi l’outil a échoué ou si l’appel était invalide.
Par exemple, un résultat d’outil réussi se présente ainsi :
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "15 degrees"
}
]
}Un tool_result qui répond à un bloc membre d’utilisation de l’ordinateur ou d’utilisation du navigateur doit également reprendre la même valeur toolset_name que le bloc tool_use ; un résultat de membre qui l’omet est rejeté. Son content est également plus restreint : un résultat de membre ne peut contenir que des blocs text et image, et un résultat d’utilisation du navigateur peut ajouter un bloc browser_state (les membres de gestion des onglets ne renvoient que ce bloc).
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": [
{ "type": "text", "text": "15 degrees" },
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "/9j/4AAQSkZJRg..."
}
}
]
}
]
}{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9"
}
]
}{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": [
{ "type": "text", "text": "The weather is" },
{
"type": "document",
"source": {
"type": "text",
"media_type": "text/plain",
"data": "15 degrees"
}
}
]
}
]
}Par exemple, ceci provoque une erreur 400 :
{
"role": "user",
"content": [
{ "type": "text", "text": "Here are the results:" }, // ❌ Text before tool_result
{ "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ }
]
}Ceci est correct lorsque le tour de l’assistant n’appelle que des outils clients :
{
"role": "user",
"content": [
{ "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ },
{ "type": "text", "text": "What should I do next?" } // ✅ Text after tool_result
]
}Gérer les résultats des outils serveur
Claude exécute l’outil en interne et intègre les résultats directement dans sa réponse sans nécessiter d’interaction supplémentaire de l’utilisateur.
Gérer les erreurs avec is_error
Lorsqu’un outil client échoue ou qu’un appel est invalide, envoyez un bloc tool_result avec is_error défini sur true. Claude peut alors appeler à nouveau l’outil avec un nouveau bloc tool_use ; limitez donc le nombre de nouvelles tentatives autorisées par votre boucle.
Si l’outil lui-même génère une erreur pendant son exécution (par exemple, une erreur réseau lors de la récupération de données météorologiques), vous pouvez renvoyer le message d’erreur dans le content accompagné de "is_error": true :
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "ConnectionError: the weather service API is not available (HTTP 500)",
"is_error": true
}
]
}Claude peut alors appeler à nouveau l’outil ou indiquer à l’utilisateur ce qui s’est passé. Par exemple, Claude pourrait dire : « Je suis désolé, je n’ai pas pu récupérer la météo actuelle car l’API du service météorologique n’est pas disponible. Veuillez réessayer plus tard. »
Si la tentative d’utilisation d’un outil par Claude est invalide (par exemple, des paramètres obligatoires manquants), cela signifie généralement que Claude ne disposait pas de suffisamment d’informations pour utiliser l’outil correctement. La meilleure approche pendant le développement consiste à réessayer la requête avec des valeurs description plus détaillées dans vos définitions d’outils.
Cependant, vous pouvez également poursuivre la conversation avec un tool_result qui indique l’erreur :
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: Missing required 'location' parameter",
"is_error": true
}
]
}Claude peut alors appeler à nouveau l’outil en complétant les informations manquantes.
Contrairement aux outils client, vous n’envoyez pas de résultats is_error pour les outils serveur. Lorsqu’un outil serveur rencontre une erreur, comme un problème réseau pendant une recherche web, l’API renvoie l’erreur dans le bloc de résultat de l’outil. Dans la plupart des cas, Claude poursuit alors avec une autre approche ou une explication pour l’utilisateur.
Pour les codes d’erreur de la recherche web, consultez Erreurs de l’outil de recherche web.
Étapes suivantes
Gérez les réponses dans lesquelles Claude appelle plusieurs outils en un seul tour.
Laissez le SDK gérer pour vous la boucle tool_use, le formatage des résultats et les nouvelles tentatives.
Rédigez des schémas et des descriptions qui orientent Claude vers le bon outil.
Cette page vous a-t-elle été utile ?