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

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](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-runner) 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](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 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](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.

<Accordion title="Exemple de réponse API avec un bloc de contenu `tool_use`">
  ```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" }
      }
    ]
  }
  ```
</Accordion>

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](https://platform.claude.com/docs/fr/build-with-claude/handling-stop-reasons#quick-reference).

Pour ces étapes sous forme de programmes complets, consultez [Tutoriel : Construire un agent utilisant des outils](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/build-a-tool-using-agent).

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`](https://platform.claude.com/docs/fr/build-with-claude/search-results).
* `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 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`](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).

<Note>
  **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 venir 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](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).

  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.
</Note>

<Warning>
  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 pourrait y intégrer des instructions visant à détourner Claude (injection de prompt indirecte). Conservez le contenu non fiable à l’intérieur 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.
</Warning>

<AccordionGroup>
  <Accordion title="Exemple de résultat d’outil avec des images">
    ```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..."
              }
            }
          ]
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Exemple de résultat d’outil vide">
    ```json JSON
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_01A09q90qw90lq917835lq9"
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Exemple de résultat d’outil avec des documents">
    ```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"
              }
            }
          ]
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Exemple de texte avant et après un résultat d’outil">
    Par exemple, ceci provoque 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
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

## 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.

<Note>
  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 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](https://platform.claude.com/docs/fr/build-with-claude/handling-stop-reasons#tool-use).
</Note>

<Tip>
  **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 `tool_result`, tandis que les messages `assistant` contiennent du contenu généré par l’IA et `tool_use`.
</Tip>

## 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.

<AccordionGroup>
  <Accordion title="Erreur d’exécution de l’outil">
    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 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. »

    <Tip>
      Rédigez des messages d’erreur instructifs. Au lieu d’erreurs génériques telles que `"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 se rétablir ou s’adapter sans avoir à deviner.
    </Tip>
  </Accordion>

  <Accordion title="Appel d’outil invalide">
    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 :

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

    <Tip>
      Pour éliminer complètement 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 correspondent toujours exactement à votre schéma, évitant ainsi les paramètres manquants et les incompatibilités de types.
    </Tip>
  </Accordion>

  <Accordion title="Erreurs des outils serveur">
    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](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/web-search-tool#errors).
  </Accordion>
</AccordionGroup>

## Étapes suivantes

<CardGroup cols={3}>
  <Card title="Utilisation d’outils en parallèle" icon="grid" href="https://platform.claude.com/docs/fr/agents-and-tools/tool-use/parallel-tool-use">
    Gérez les réponses dans lesquelles Claude appelle plusieurs outils en un seul tour.
  </Card>

  <Card title="Exécuteur d’outils (SDK)" icon="wrench" href="https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-runner">
    Laissez le SDK gérer pour vous la boucle `tool_use`, le formatage des résultats et les nouvelles tentatives.
  </Card>

  <Card title="Définir des outils" icon="hammer" href="https://platform.claude.com/docs/fr/agents-and-tools/tool-use/define-tools">
    Rédigez des schémas et des descriptions qui orientent Claude vers le bon outil.
  </Card>
</CardGroup>
