Gérer les appels d'outils

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.

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

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-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.
   • 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 (les membres de gestion des onglets ne renvoient que ce bloc).

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrees"
    }
  ]
}

{
  "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..."
          }
        }
      ]
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9"
    }
  ]
}

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

Gérer les erreurs avec is_error

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

{
  "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
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Missing required 'location' parameter",
      "is_error": true
    }
  ]
}

Étapes suivantes