Claude Platform Docs
MessagesOutils

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 au input_schema de 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.

Lorsque vous recevez une réponse d’utilisation d’outil pour un outil client, suivez ces étapes :

  1. Pour chaque bloc tool_use, exécutez l’outil que le bloc nomme, en lui transmettant son input.
  2. Dans une nouvelle requête, conservez les messages précédents et ajoutez le content de la réponse sans modification en tant que message assistant.
  3. Ajoutez un message user contenant un bloc tool_result pour chaque bloc tool_use de ce contenu, même si l’outil a échoué.
  4. Envoyez la requête avec les mêmes tools que la première requête. Claude utilise les résultats des outils pour poursuivre sa réponse.
  5. Si le stop_reason de la réponse suivante est également tool_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’id du bloc tool_use auquel 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 types text, image, document ou search_result.
  • is_error (facultatif) : défini sur true si l’outil a échoué ou si l’appel était invalide.

Par exemple, un résultat d’outil réussi se présente ainsi :

JSON
{
  "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).

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.

É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 ?