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.

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

Plus simple avec Tool Runner : la gestion manuelle des outils décrite sur cette page est automatiquement prise en charge par Tool Runner. Utilisez cette page lorsque vous avez besoin d'un contrôle personnalisé sur l'exécution des outils.

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

Gestion des résultats des outils client

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. Il sera 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.

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

Extraire le name, l'id et l'input du bloc tool_use.
Exécuter l'outil réel dans votre base de code correspondant à ce nom d'outil, en transmettant l'input de l'outil.
Poursuivre la conversation en envoyant un nouveau message avec le role de user et un bloc content contenant le type tool_result ainsi que les informations suivantes :
- tool_use_id : l'id de la requête d'utilisation d'outil à laquelle ce résultat correspond.
- content (facultatif) : le résultat de l'outil, sous forme de chaîne de caractères (par exemple, "content": "15 degrees"), de liste de blocs de contenu imbriqués (par exemple, "content": [{"type": "text", "text": "15 degrees"}]) ou de liste de blocs de document (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, document ou search_result.
- is_error (facultatif) : défini sur true si l'exécution de l'outil a entraîné une erreur.

Exigences de formatage importantes :

Les blocs de résultat d'outil doivent suivre immédiatement leurs blocs d'utilisation d'outil correspondants dans l'historique des messages. Vous ne pouvez inclure aucun message entre le message d'utilisation d'outil de l'assistant et le message de résultat d'outil de l'utilisateur.
Dans le message utilisateur contenant les résultats d'outils, les blocs tool_result doivent apparaître EN PREMIER dans le tableau de contenu. Tout texte doit venir APRÈS tous les résultats d'outils.
Si le tour de l'assistant a également appelé un outil serveur qui n'a pas encore de bloc de résultat, le message utilisateur doit contenir uniquement des blocs tool_result. Du texte après les résultats met fin au tour prématurément ; pour un outil serveur que Claude a appelé directement, la requête échoue alors avec une erreur 400 qui nomme l'outil serveur non résolu. Consultez Raisons d'arrêt et solution de repli.

Par exemple, ceci provoquera 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 appelle uniquement des outils client :

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

Si vous recevez une erreur telle que « tool_use ids were found without tool_result blocks immediately after », vérifiez que vos résultats d'outils sont correctement formatés.

Les résultats d'outils contiennent souvent du contenu provenant de sources hors de votre contrôle : pages web, e-mails entrants, téléversements d'utilisateurs, API tierces. Traitez ce contenu comme non fiable : un attaquant capable de l'influencer peut y intégrer des instructions visant à rediriger Claude (injection de prompt indirecte). Conservez le contenu non fiable dans des blocs tool_result plutôt que dans des invites system ou des blocs text utilisateur simples, et consultez Atténuer les jailbreaks et les injections de prompts pour un renforcement supplémentaire.

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

Gestion des résultats des outils serveur

Claude exécute l'outil en interne et incorpore les résultats directement dans sa réponse sans nécessiter d'interaction supplémentaire de l'utilisateur.

Une réponse peut contenir à la fois un bloc tool_use client et un bloc server_tool_use qui n'a pas de bloc de résultat. Cet appel d'outil serveur n'est pas encore terminé, et son bloc de résultat arrive dans une réponse ultérieure. Répondez avec un message utilisateur qui contient uniquement les blocs tool_result pour les outils client et conservez le même tableau tools ; pour un outil serveur que Claude a appelé directement, l'API l'exécute lors de cette requête et la réponse suivante commence par son bloc de résultat. Consultez Raisons d'arrêt et solution de repli.

Différences avec les autres API

Contrairement aux API qui séparent l'utilisation d'outils ou utilisent des rôles spéciaux comme tool ou function, l'API Claude intègre les outils directement dans la structure des messages user et assistant.

Les messages contiennent des tableaux de blocs text, image, tool_use et tool_result. Les messages user incluent le contenu client et les tool_result, tandis que les messages assistant contiennent le contenu généré par l'IA et les tool_use.

Gestion des erreurs avec is_error

Plusieurs types d'erreurs peuvent survenir lors de l'utilisation d'outils avec Claude :

Étapes suivantes

Utilisation d'outils en parallèle

Gérez les réponses dans lesquelles Claude appelle plusieurs outils en un seul tour.

Tool Runner (SDK)

Laissez le SDK gérer la boucle tool_use, le formatage des résultats et les nouvelles tentatives pour vous.

Définir des outils

Rédigez des schémas et des descriptions qui orientent Claude vers le bon outil.

Was this page helpful?

Gestion des résultats des outils client

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. Il sera 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.

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

Extraire le name, l'id et l'input du bloc tool_use.

Exécuter l'outil réel dans votre base de code correspondant à ce nom d'outil, en transmettant l'input de l'outil.

Poursuivre la conversation en envoyant un nouveau message avec le role de user et un bloc content contenant le type tool_result ainsi que les informations suivantes :

tool_use_id : l'id de la requête d'utilisation d'outil à laquelle ce résultat correspond.
content (facultatif) : le résultat de l'outil, sous forme de chaîne de caractères (par exemple, "content": "15 degrees"), de liste de blocs de contenu imbriqués (par exemple, "content": [{"type": "text", "text": "15 degrees"}]) ou de liste de blocs de document (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, document ou search_result.
is_error (facultatif) : défini sur true si l'exécution de l'outil a entraîné une erreur.

Exigences de formatage importantes :

Les blocs de résultat d'outil doivent suivre immédiatement leurs blocs d'utilisation d'outil correspondants dans l'historique des messages. Vous ne pouvez inclure aucun message entre le message d'utilisation d'outil de l'assistant et le message de résultat d'outil de l'utilisateur.
Dans le message utilisateur contenant les résultats d'outils, les blocs tool_result doivent apparaître EN PREMIER dans le tableau de contenu. Tout texte doit venir APRÈS tous les résultats d'outils.
Si le tour de l'assistant a également appelé un outil serveur qui n'a pas encore de bloc de résultat, le message utilisateur doit contenir uniquement des blocs tool_result. Du texte après les résultats met fin au tour prématurément ; pour un outil serveur que Claude a appelé directement, la requête échoue alors avec une erreur 400 qui nomme l'outil serveur non résolu. Consultez Raisons d'arrêt et solution de repli.

Par exemple, ceci provoquera 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 appelle uniquement des outils client :

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

Si vous recevez une erreur telle que « tool_use ids were found without tool_result blocks immediately after », vérifiez que vos résultats d'outils sont correctement formatés.

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

Gestion des résultats des outils serveur

Claude exécute l'outil en interne et incorpore les résultats directement dans sa réponse sans nécessiter d'interaction supplémentaire de l'utilisateur.

Différences avec les autres API

Gestion des résultats des outils client

Exemple de réponse API avec un bloc de contenu `tool_use`

Exemple de résultat d'outil réussi

Exemple de résultat d'outil avec des images

Exemple de résultat d'outil vide

Exemple de résultat d'outil avec des documents

Gestion des résultats des outils serveur

Gestion des erreurs avec is_error

Erreur d'exécution de l'outil

Nom d'outil invalide

Erreurs d'outils serveur

Étapes suivantes

Gestion des résultats des outils client

Exemple de réponse API avec un bloc de contenu `tool_use`

Exemple de résultat d'outil réussi

Exemple de résultat d'outil avec des images

Exemple de résultat d'outil vide

Exemple de résultat d'outil avec des documents

Gestion des résultats des outils serveur

Gestion des erreurs avec is_error

Erreur d'exécution de l'outil

Nom d'outil invalide

Erreurs d'outils serveur

Étapes suivantes

Gestion des résultats des outils client

Gestion des résultats des outils serveur

Gestion des erreurs avec is_error

Étapes suivantes

Gestion des résultats des outils client

Gestion des résultats des outils serveur

Gestion des erreurs avec is_error

Étapes suivantes