Gérer les appels d'outils

Cette page couvre le cycle de vie des appels d'outils : lire les blocs tool_use de la réponse de Claude, formater les blocs tool_result dans votre réponse et signaler les erreurs. Pour l'abstraction SDK qui gère cela automatiquement, voir Tool Runner.

La réponse de Claude diffère selon qu'il utilise un outil client ou serveur.

Gérer les résultats des outils clients

La réponse aura 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. Ceci sera utilisé pour faire correspondre les résultats de l'outil plus tard.
• name : Le nom de l'outil utilisé.
• input : Un objet contenant l'entrée transmise à l'outil, conforme au input_schema de l'outil.

Lorsque vous recevez une réponse d'utilisation d'outil pour un outil client, vous devez :

1. Extraire le name, l'id et l'input du bloc tool_use.
2. Exécuter l'outil réel dans votre base de code correspondant à ce nom d'outil, en transmettant l'input de l'outil.
3. Continuer la conversation en envoyant un nouveau message avec le role de user et un bloc content contenant le type tool_result et les informations suivantes :
   • tool_use_id : L'id de la demande d'utilisation d'outil pour laquelle ceci est un résultat.
   • content : Le résultat de l'outil, sous forme de chaîne (par exemple, "content": "15 degrees"), une liste de blocs de contenu imbriqués (par exemple, "content": [{"type": "text", "text": "15 degrees"}]), ou une liste de blocs de documents (par exemple, "content": [{"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}}]). Ces blocs de contenu peuvent utiliser les types text, image ou document.
   • is_error (optionnel) : Défini sur true si l'exécution de l'outil a entraîné une erreur.

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Here are the results:" }, // ❌ Text before tool_result
    { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ }
  ]
}

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ },
    { "type": "text", "text": "What should I do next?" } // ✅ Text after tool_result
  ]
}

Après avoir reçu le résultat de l'outil, Claude utilisera ces informations pour continuer à générer une réponse à la demande utilisateur d'origine.

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 utilisateur supplémentaire.

Gérer les erreurs avec is_error

Il existe plusieurs types d'erreurs qui peuvent survenir lors de l'utilisation d'outils avec Claude :

Étapes suivantes

• Pour exécuter plusieurs outils en un seul tour, voir Parallel tool use.
• Pour l'abstraction SDK qui automatise cette boucle, voir Tool Runner.
• Pour le flux de travail complet d'utilisation d'outils, voir Define tools.