--- title: Gérer les appels d'outils url: https://platform.claude.com/docs/fr/agents-and-tools/tool-use/handle-tool-calls description: 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 : la lecture des blocs `tool_use` dans la réponse de Claude, le formatage des blocs `tool_result` dans votre réponse et le signalement des erreurs. Pour l'abstraction du SDK qui gère cela automatiquement, consultez [Tool Runner](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-runner). **Plus simple avec Tool Runner :** la gestion manuelle des outils décrite sur cette page est prise en charge automatiquement par [Tool Runner](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/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 un outil serveur](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/overview#how-tool-use-works). ## 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. Il sera utilisé pour faire correspondre les résultats d'outils 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](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/computer-use-tool) (utilisation de l'ordinateur) ou [browser use](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool) (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. ```json JSON { "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, 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 lui transmettant l'`input` de l'outil. 3. Poursuivre la conversation en envoyant un nouveau message avec le `role` `user` et un bloc `content` contenant le type `tool_result` et 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 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`, `document` ou [`search_result`](https://platform.claude.com/docs/fr/build-with-claude/search-results). * `is_error` (facultatif) : défini sur `true` si l'exécution de l'outil a entraîné une erreur. Un `tool_result` qui répond à un bloc membre de computer use ou de browser use 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 de browser use peut ajouter un bloc [`browser_state`](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#track-tabs-and-page-state) (les [membres de gestion des onglets](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#tab-management-results) ne renvoient que ce bloc). **Exigences de formatage importantes :** * Les blocs de résultats d'outils doivent suivre immédiatement leurs blocs d'utilisation d'outils 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 figurer EN PREMIER dans le tableau content. Tout texte doit venir APRÈS tous les résultats d'outils. * Si le tour de l'assistant a également appelé un [outil serveur](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/server-tools) qui n'a pas encore de bloc de résultat, le message utilisateur ne doit contenir que 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](https://platform.claude.com/docs/fr/build-with-claude/handling-stop-reasons#tool-use). Par exemple, ceci provoquera une erreur 400 : ```json { "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 : ```json { "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, fichiers téléversés par les utilisateurs, API tierces. Traitez ce contenu comme non fiable : un attaquant capable de l'influencer peut y intégrer des instructions qui tentent de détourner Claude (« indirect prompt injection », ou injection de prompt indirecte). Conservez le contenu non fiable dans des blocs `tool_result` plutôt que dans des prompts `system` ou des blocs `text` utilisateur simples, et consultez [Atténuer les jailbreaks et les injections de prompt](https://platform.claude.com/docs/fr/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks#indirect-prompt-injection) pour un renforcement supplémentaire. ```json JSON { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9", "content": "15 degrees" } ] } ``` ```json JSON { "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..." } } ] } ] } ``` ```json JSON { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9" } ] } ``` ```json JSON { "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" } } ] } ] } ``` Après avoir reçu le résultat de l'outil, Claude utilisera cette information pour continuer à générer une réponse au prompt initial de l'utilisateur. ## 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. 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 ne contient que les blocs `tool_result` pour les outils clients 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](https://platform.claude.com/docs/fr/build-with-claude/handling-stop-reasons#tool-use). **Différences avec d'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`. ## Gérer les erreurs avec is\_error Plusieurs types d'erreurs peuvent survenir lors de l'utilisation d'outils avec Claude : 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` : ```json JSON { "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 intégrera alors cette erreur dans sa réponse à l'utilisateur. Par exemple : « 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. » Rédigez des messages d'erreur instructifs. Au lieu d'erreurs génériques comme `"failed"`, indiquez ce qui s'est mal passé et ce que Claude devrait essayer ensuite (par exemple, `"Rate limit exceeded. Retry after 60 seconds."`). Cela donne à Claude le contexte dont il a besoin pour récupérer ou s'adapter sans avoir à deviner. 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, et Claude tentera d'utiliser à nouveau l'outil en complétant les informations manquantes : ```json JSON { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9", "content": "Error: Missing required 'location' parameter", "is_error": true } ] } ``` Si une requête d'outil est invalide ou qu'il lui manque des paramètres, Claude réessaiera 2 à 3 fois avec des corrections avant de présenter ses excuses à l'utilisateur. Pour éliminer entièrement les appels d'outils invalides, utilisez l'[utilisation d'outils stricte](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/strict-tool-use) avec `strict: true` dans vos définitions d'outils. Cela garantit que les entrées des outils correspondront toujours exactement à votre schéma, évitant ainsi les paramètres manquants et les incompatibilités de types. Lorsque les outils serveur rencontrent des erreurs (par exemple, des problèmes réseau avec la recherche web), Claude gère ces erreurs de manière transparente et tente de fournir une réponse alternative ou une explication à l'utilisateur. Contrairement aux outils clients, vous n'avez pas besoin de gérer les résultats `is_error` pour les outils serveur. Pour la recherche web en particulier, les codes d'erreur possibles incluent : * `too_many_requests` : limite de débit dépassée * `invalid_input` : paramètre de requête de recherche invalide * `max_uses_exceeded` : nombre maximal d'utilisations de l'outil de recherche web dépassé * `query_too_long` : la requête dépasse la longueur maximale * `unavailable` : une erreur interne s'est produite ## É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.