Comment implémenter l'utilisation d'outils

Choisir un modèle

En général, utilisez Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 (déprécié) ou Claude Opus 3 (déprécié) pour les outils complexes et les requêtes ambiguës ; ils gèrent mieux plusieurs outils et cherchent des clarifications lorsque nécessaire.

Utilisez Claude Haiku 3.5 ou Claude Haiku 3 pour les outils simples, mais notez qu’ils peuvent inférer des paramètres manquants.

Si vous utilisez Claude Sonnet 3.7 avec l’utilisation d’outils et la réflexion étendue, consultez notre guide ici pour plus d’informations.

Spécifier les outils clients

Les outils clients (définis par Anthropic et définis par l’utilisateur) sont spécifiés dans le paramètre de niveau supérieur tools de la requête API. Chaque définition d’outil inclut :

Paramètre	Description
name	Le nom de l’outil. Doit correspondre à la regex ^[a-zA-Z0-9_-]{1,64}$.
description	Une description détaillée en texte brut de ce que fait l’outil, quand il doit être utilisé et comment il se comporte.
input_schema	Un objet JSON Schema définissant les paramètres attendus pour l’outil.

Exemple de définition d'outil simple

JSON

{
  "name": "get_weather",
  "description": "Obtenir la météo actuelle dans un lieu donné",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "La ville et l'état, par exemple San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "L'unité de température, soit 'celsius' soit 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

Cet outil, nommé get_weather, attend un objet d’entrée avec une chaîne location requise et une chaîne unit optionnelle qui doit être soit “celsius” soit “fahrenheit”.

Prompt système d’utilisation d’outils

Lorsque vous appelez l’API Anthropic avec le paramètre tools, nous construisons un prompt système spécial à partir des définitions d’outils, de la configuration d’outils et de tout prompt système spécifié par l’utilisateur. Le prompt construit est conçu pour instruire le modèle à utiliser le ou les outils spécifiés et fournir le contexte nécessaire pour que l’outil fonctionne correctement :

Dans cet environnement, vous avez accès à un ensemble d'outils que vous pouvez utiliser pour répondre à la question de l'utilisateur.
{{ INSTRUCTIONS DE FORMATAGE }}
Les paramètres de chaîne et scalaires doivent être spécifiés tels quels, tandis que les listes et objets doivent utiliser le format JSON. Notez que les espaces pour les valeurs de chaîne ne sont pas supprimés. La sortie n'est pas censée être du XML valide et est analysée avec des expressions régulières.
Voici les fonctions disponibles au format JSONSchema :
{{ DÉFINITIONS D'OUTILS EN JSON SCHEMA }}
{{ PROMPT SYSTÈME UTILISATEUR }}
{{ CONFIGURATION D'OUTILS }}

Meilleures pratiques pour les définitions d’outils

Pour obtenir les meilleures performances de Claude lors de l’utilisation d’outils, suivez ces directives :

• Fournissez des descriptions extrêmement détaillées. C’est de loin le facteur le plus important dans les performances des outils. Vos descriptions doivent expliquer chaque détail sur l’outil, y compris :
  • Ce que fait l’outil
  • Quand il doit être utilisé (et quand il ne doit pas l’être)
  • Ce que signifie chaque paramètre et comment il affecte le comportement de l’outil
  • Toute mise en garde ou limitation importante, comme les informations que l’outil ne retourne pas si le nom de l’outil n’est pas clair. Plus vous pouvez donner de contexte à Claude sur vos outils, mieux il sera à décider quand et comment les utiliser. Visez au moins 3-4 phrases par description d’outil, plus si l’outil est complexe.
• Priorisez les descriptions par rapport aux exemples. Bien que vous puissiez inclure des exemples d’utilisation d’un outil dans sa description ou dans le prompt d’accompagnement, c’est moins important que d’avoir une explication claire et complète du but et des paramètres de l’outil. N’ajoutez des exemples qu’après avoir entièrement développé la description.

Exemple d'une bonne description d'outil

JSON

{
  "name": "get_stock_price",
  "description": "Récupère le prix actuel de l'action pour un symbole de ticker donné. Le symbole de ticker doit être un symbole valide pour une entreprise cotée en bourse sur une bourse américaine majeure comme NYSE ou NASDAQ. L'outil retournera le dernier prix de transaction en USD. Il doit être utilisé lorsque l'utilisateur demande le prix actuel ou le plus récent d'une action spécifique. Il ne fournira aucune autre information sur l'action ou l'entreprise.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "Le symbole de ticker de l'action, par exemple AAPL pour Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

Exemple de mauvaise description d'outil

JSON

{
  "name": "get_stock_price",
  "description": "Obtient le prix de l'action pour un ticker.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}

La bonne description explique clairement ce que fait l’outil, quand l’utiliser, quelles données il retourne et ce que signifie le paramètre ticker. La mauvaise description est trop brève et laisse Claude avec de nombreuses questions ouvertes sur le comportement et l’utilisation de l’outil.

Contrôler la sortie de Claude

Forcer l’utilisation d’outils

Dans certains cas, vous pourriez vouloir que Claude utilise un outil spécifique pour répondre à la question de l’utilisateur, même si Claude pense qu’il peut fournir une réponse sans utiliser d’outil. Vous pouvez le faire en spécifiant l’outil dans le champ tool_choice comme ceci :

tool_choice = {"type": "tool", "name": "get_weather"}

Lorsque vous travaillez avec le paramètre tool_choice, nous avons quatre options possibles :

• auto permet à Claude de décider s’il faut appeler les outils fournis ou non. C’est la valeur par défaut lorsque des tools sont fournis.
• any dit à Claude qu’il doit utiliser l’un des outils fournis, mais ne force pas un outil particulier.
• tool nous permet de forcer Claude à toujours utiliser un outil particulier.
• none empêche Claude d’utiliser des outils. C’est la valeur par défaut lorsqu’aucun tools n’est fourni.

Lors de l’utilisation de la mise en cache de prompts, les changements au paramètre tool_choice invalideront les blocs de messages mis en cache. Les définitions d’outils et les prompts système restent mis en cache, mais le contenu des messages doit être retraité.

Ce diagramme illustre comment fonctionne chaque option :

Notez que lorsque vous avez tool_choice comme any ou tool, nous pré-remplirons le message assistant pour forcer l’utilisation d’un outil. Cela signifie que les modèles n’émettront pas de bloc de contenu text de chaîne de pensée avant les blocs de contenu tool_use, même si explicitement demandé.

Lors de l’utilisation de la réflexion étendue avec l’utilisation d’outils, tool_choice: {"type": "any"} et tool_choice: {"type": "tool", "name": "..."} ne sont pas supportés et résulteront en une erreur. Seuls tool_choice: {"type": "auto"} (par défaut) et tool_choice: {"type": "none"} sont compatibles avec la réflexion étendue.

Nos tests ont montré que cela ne devrait pas réduire les performances. Si vous souhaitez conserver la chaîne de pensée (particulièrement avec Opus) tout en demandant que le modèle utilise un outil spécifique, vous pouvez utiliser {"type": "auto"} pour tool_choice (par défaut) et ajouter des instructions explicites dans un message user. Par exemple : Quel temps fait-il à Londres ? Utilisez l'outil get_weather dans votre réponse.

Sortie JSON

Les outils ne doivent pas nécessairement être des fonctions clients — vous pouvez utiliser des outils chaque fois que vous voulez que le modèle retourne une sortie JSON qui suit un schéma fourni. Par exemple, vous pourriez utiliser un outil record_summary avec un schéma particulier. Voir Utilisation d’outils avec Claude pour un exemple complet fonctionnel.

Chaîne de pensée

Lors de l’utilisation d’outils, Claude montrera souvent sa “chaîne de pensée”, c’est-à-dire le raisonnement étape par étape qu’il utilise pour décomposer le problème et décider quels outils utiliser. Le modèle Claude Opus 3 (déprécié) le fera si tool_choice est défini sur auto (c’est la valeur par défaut, voir Forcer l’utilisation d’outils), et Sonnet et Haiku peuvent être incités à le faire.

Par exemple, étant donné le prompt “Quel temps fait-il à San Francisco en ce moment, et quelle heure est-il là-bas ?”, Claude pourrait répondre avec :

JSON

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Pour répondre à cette question, je vais : 1. Utiliser l'outil get_weather pour obtenir la météo actuelle à San Francisco. 2. Utiliser l'outil get_time pour obtenir l'heure actuelle dans le fuseau horaire America/Los_Angeles, qui couvre San Francisco, CA."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

Cette chaîne de pensée donne un aperçu du processus de raisonnement de Claude et peut vous aider à déboguer un comportement inattendu.

Il est important de noter que Claude peut utiliser divers formats pour dénoter sa chaîne de pensée. Votre code doit traiter la chaîne de pensée comme tout autre texte généré par l’assistant, et ne pas s’appuyer sur des conventions de formatage spécifiques.

Utilisation d’outils en parallèle

Par défaut, Claude peut utiliser plusieurs outils pour répondre à une requête utilisateur. Vous pouvez désactiver ce comportement en :

• Définissant disable_parallel_tool_use=true lorsque le type tool_choice est auto, ce qui garantit que Claude utilise au plus un outil
• Définissant disable_parallel_tool_use=true lorsque le type tool_choice est any ou tool, ce qui garantit que Claude utilise exactement un outil

Exemple complet d'utilisation d'outils en parallèle

Voici un exemple complet montrant comment formater correctement les appels d’outils en parallèle dans l’historique des messages :

Python

import anthropic

client = anthropic.Anthropic()

# Définir les outils
tools = [
    {
        "name": "get_weather",
        "description": "Obtenir la météo actuelle dans un lieu donné",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "La ville et l'état, par exemple San Francisco, CA"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "Obtenir l'heure actuelle dans un fuseau horaire donné",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "Le fuseau horaire, par exemple America/New_York"
                }
            },
            "required": ["timezone"]
        }
    }
]

# Requête initiale
response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    tools=tools,
    messages=[
        {
            "role": "user",
            "content": "Quel temps fait-il à SF et NYC, et quelle heure est-il là-bas ?"
        }
    ]
)

# Réponse de Claude avec des appels d'outils en parallèle
print("Claude veut utiliser des outils:", response.stop_reason == "tool_use")
print("Nombre d'appels d'outils:", len([c for c in response.content if c.type == "tool_use"]))

# Construire la conversation avec les résultats d'outils
messages = [
    {
        "role": "user",
        "content": "Quel temps fait-il à SF et NYC, et quelle heure est-il là-bas ?"
    },
    {
        "role": "assistant",
        "content": response.content  # Contient plusieurs blocs tool_use
    },
    {
        "role": "user",
        "content": [
            {
                "type": "tool_result",
                "tool_use_id": "toolu_01",  # Doit correspondre à l'ID de tool_use
                "content": "San Francisco : 68°F, partiellement nuageux"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_02",
                "content": "New York : 45°F, ciel dégagé"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_03",
                "content": "Heure de San Francisco : 14h30 PST"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_04",
                "content": "Heure de New York : 17h30 EST"
            }
        ]
    }
]

# Obtenir la réponse finale
final_response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    tools=tools,
    messages=messages
)

print(final_response.content[0].text)

Le message assistant avec des appels d’outils en parallèle ressemblerait à ceci :

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Je vais vérifier la météo et l'heure pour San Francisco et New York City."
    },
    {
      "type": "tool_use",
      "id": "toolu_01",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    },
    {
      "type": "tool_use",
      "id": "toolu_02",
      "name": "get_weather",
      "input": {"location": "New York, NY"}
    },
    {
      "type": "tool_use",
      "id": "toolu_03",
      "name": "get_time",
      "input": {"timezone": "America/Los_Angeles"}
    },
    {
      "type": "tool_use",
      "id": "toolu_04",
      "name": "get_time",
      "input": {"timezone": "America/New_York"}
    }
  ]
}

Script de test complet pour les outils en parallèle

Voici un script complet et exécutable pour tester et vérifier que les appels d’outils en parallèle fonctionnent correctement :

Python

#!/usr/bin/env python3
"""Script de test pour vérifier les appels d'outils en parallèle avec l'API Anthropic"""

import os
from anthropic import Anthropic

# Initialiser le client
client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

# Définir les outils
tools = [
    {
        "name": "get_weather",
        "description": "Obtenir la météo actuelle dans un lieu donné",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "La ville et l'état, par exemple San Francisco, CA"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "Obtenir l'heure actuelle dans un fuseau horaire donné",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "Le fuseau horaire, par exemple America/New_York"
                }
            },
            "required": ["timezone"]
        }
    }
]

# Conversation de test avec des appels d'outils en parallèle
messages = [
    {
        "role": "user",
        "content": "Quel temps fait-il à SF et NYC, et quelle heure est-il là-bas ?"
    }
]

# Faire la requête initiale
print("Demande d'appels d'outils en parallèle...")
response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    messages=messages,
    tools=tools
)

# Vérifier les appels d'outils en parallèle
tool_uses = [block for block in response.content if block.type == "tool_use"]
print(f"\n✓ Claude a fait {len(tool_uses)} appels d'outils")

if len(tool_uses) > 1:
    print("✓ Appels d'outils en parallèle détectés !")
    for tool in tool_uses:
        print(f"  - {tool.name}: {tool.input}")
else:
    print("✗ Aucun appel d'outil en parallèle détecté")

# Simuler l'exécution d'outils et formater les résultats correctement
tool_results = []
for tool_use in tool_uses:
    if tool_use.name == "get_weather":
        if "San Francisco" in str(tool_use.input):
            result = "San Francisco : 68°F, partiellement nuageux"
        else:
            result = "New York : 45°F, ciel dégagé"
    else:  # get_time
        if "Los_Angeles" in str(tool_use.input):
            result = "14h30 PST"
        else:
            result = "17h30 EST"
    
    tool_results.append({
        "type": "tool_result",
        "tool_use_id": tool_use.id,
        "content": result
    })

# Continuer la conversation avec les résultats d'outils
messages.extend([
    {"role": "assistant", "content": response.content},
    {"role": "user", "content": tool_results}  # Tous les résultats dans un seul message !
])

# Obtenir la réponse finale
print("\nObtention de la réponse finale...")
final_response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    messages=messages,
    tools=tools
)

print(f"\nRéponse de Claude :\n{final_response.content[0].text}")

# Vérifier le formatage
print("\n--- Vérification ---")
print(f"✓ Résultats d'outils envoyés dans un seul message utilisateur : {len(tool_results)} résultats")
print("✓ Aucun texte avant les résultats d'outils dans le tableau de contenu")
print("✓ Conversation formatée correctement pour une future utilisation d'outils en parallèle")

Ce script démontre :

• Comment formater correctement les appels d’outils en parallèle et les résultats
• Comment vérifier que les appels en parallèle sont effectués
• La structure de message correcte qui encourage une future utilisation d’outils en parallèle
• Les erreurs courantes à éviter (comme du texte avant les résultats d’outils)

Exécutez ce script pour tester votre implémentation et vous assurer que Claude fait des appels d’outils en parallèle efficacement.

Maximiser l’utilisation d’outils en parallèle

Bien que les modèles Claude 4 aient d’excellentes capacités d’utilisation d’outils en parallèle par défaut, vous pouvez augmenter la probabilité d’exécution d’outils en parallèle sur tous les modèles avec un prompting ciblé :

Prompts système pour l'utilisation d'outils en parallèle

Pour les modèles Claude 4 (Opus 4.1, Opus 4 et Sonnet 4), ajoutez ceci à votre prompt système :

Pour une efficacité maximale, chaque fois que vous devez effectuer plusieurs opérations indépendantes, invoquez tous les outils pertinents simultanément plutôt que séquentiellement.

Pour une utilisation d’outils en parallèle encore plus forte (recommandée si la valeur par défaut n’est pas suffisante), utilisez :

<use_parallel_tool_calls>
Pour une efficacité maximale, chaque fois que vous effectuez plusieurs opérations indépendantes, invoquez tous les outils pertinents simultanément plutôt que séquentiellement. Priorisez l'appel d'outils en parallèle chaque fois que possible. Par exemple, lors de la lecture de 3 fichiers, exécutez 3 appels d'outils en parallèle pour lire les 3 fichiers en contexte en même temps. Lors de l'exécution de plusieurs commandes en lecture seule comme `ls` ou `list_dir`, exécutez toujours toutes les commandes en parallèle. Penchez vers la maximisation des appels d'outils en parallèle plutôt que d'exécuter trop d'outils séquentiellement.
</use_parallel_tool_calls>

Prompting de message utilisateur

Vous pouvez également encourager l’utilisation d’outils en parallèle dans des messages utilisateur spécifiques :

# Au lieu de :
"Quel temps fait-il à Paris ? Vérifiez aussi Londres."

# Utilisez :
"Vérifiez la météo à Paris et Londres simultanément."

# Ou soyez explicite :
"Veuillez utiliser des appels d'outils en parallèle pour obtenir la météo de Paris, Londres et Tokyo en même temps."

Utilisation d’outils en parallèle avec Claude Sonnet 3.7

Claude Sonnet 3.7 peut être moins susceptible de faire des appels d’outils en parallèle dans une réponse, même lorsque vous n’avez pas défini disable_parallel_tool_use. Pour contourner cela, nous recommandons d’activer l’utilisation d’outils efficace en tokens, qui aide à encourager Claude à utiliser des outils en parallèle. Cette fonctionnalité bêta réduit également la latence et économise en moyenne 14% en tokens de sortie.

Si vous préférez ne pas opter pour la bêta d’utilisation d’outils efficace en tokens, vous pouvez également introduire un “outil batch” qui peut agir comme un méta-outil pour envelopper les invocations à d’autres outils simultanément. Nous trouvons que si cet outil est présent, le modèle l’utilisera pour appeler simultanément plusieurs outils en parallèle pour vous.

Voir cet exemple dans notre cookbook pour savoir comment utiliser cette solution de contournement.

Gérer les blocs de contenu d’utilisation d’outils et de résultats d’outils

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 d’outils plus tard.
• name : Le nom de l’outil utilisé.
• input : Un objet contenant l’entrée passée à l’outil, conforme au input_schema de l’outil.

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

JSON

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-4-1-20250805",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "J'ai besoin d'utiliser get_weather, et l'utilisateur veut SF, qui est probablement San Francisco, CA."
    },
    {
      "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 devriez :

1. Extraire le name, id et input du bloc tool_use.
2. Exécuter l’outil réel dans votre base de code correspondant à ce nom d’outil, en passant 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 requête d’utilisation d’outil pour laquelle c’est un résultat.
   • content : Le résultat de l’outil, sous forme de chaîne (par exemple "content": "15 degrés"), une liste de blocs de contenu imbriqués (par exemple "content": [{"type": "text", "text": "15 degrés"}]), ou une liste de blocs de document (par exemple "content": ["type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrés"}]). Ces blocs de contenu peuvent utiliser les types text, image ou document.
   • is_error (optionnel) : Définir à true si l’exécution de l’outil a résulté en une erreur.

Exigences de formatage importantes :

• Les blocs de résultats d’outils doivent immédiatement suivre leurs blocs d’utilisation d’outils correspondants dans l’historique des messages. Vous ne pouvez pas inclure de messages 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.

Par exemple, ceci causera une erreur 400 :

{"role": "user", "content": [
  {"type": "text", "text": "Voici les résultats :"},  // ❌ Texte avant tool_result
  {"type": "tool_result", "tool_use_id": "toolu_01", ...}
]}

Ceci est correct :

{"role": "user", "content": [
  {"type": "tool_result", "tool_use_id": "toolu_01", ...},
  {"type": "text", "text": "Que dois-je faire ensuite ?"}  // ✅ Texte après tool_result
]}

Si vous recevez une erreur comme “tool_use ids were found without tool_result blocks immediately after”, vérifiez que vos résultats d’outils sont formatés correctement.

Exemple de résultat d'outil réussi

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrés"
    }
  ]
}

Exemple de résultat d'outil avec images

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "15 degrés"},
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRg...",
          }
        }
      ]
    }
  ]
}

Exemple de résultat d'outil vide

JSON

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

Exemple de résultat d'outil avec documents

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "La météo est"},
        {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "15 degrés"
          }
        }
      ]
    }
  ]
}

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

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

Différences par rapport aux autres APIs

Contrairement aux APIs qui séparent l’utilisation d’outils ou utilisent des rôles spéciaux comme tool ou function, l’API d’Anthropic intègre les outils directement dans la structure de 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 le contenu généré par l’IA et tool_use.

Gérer la raison d’arrêt max_tokens

Si la réponse de Claude est coupée en raison d’avoir atteint la limite max_tokens, et que la réponse tronquée contient un bloc d’utilisation d’outil incomplet, vous devrez réessayer la requête avec une valeur max_tokens plus élevée pour obtenir l’utilisation d’outil complète.

Python

# Vérifier si la réponse a été tronquée pendant l'utilisation d'outil
if response.stop_reason == "max_tokens":
    # Vérifier si le dernier bloc de contenu est un tool_use incomplet
    last_block = response.content[-1]
    if last_block.type == "tool_use":
        # Envoyer la requête avec max_tokens plus élevé
        response = client.messages.create(
            model="claude-opus-4-1-20250805",
            max_tokens=4096,  # Limite augmentée
            messages=messages,
            tools=tools
        )

Gérer la raison d’arrêt pause_turn

Lors de l’utilisation d’outils serveur comme la recherche web, l’API peut retourner une raison d’arrêt pause_turn, indiquant que l’API a mis en pause un tour de longue durée.

Voici comment gérer la raison d’arrêt pause_turn :

Python

import anthropic

client = anthropic.Anthropic()

# Requête initiale avec recherche web
response = client.messages.create(
    model="claude-3-7-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Recherchez des informations complètes sur les percées en informatique quantique en 2025"
        }
    ],
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 10
    }]
)

# Vérifier si la réponse a une raison d'arrêt pause_turn
if response.stop_reason == "pause_turn":
    # Continuer la conversation avec le contenu en pause
    messages = [
        {"role": "user", "content": "Recherchez des informations complètes sur les percées en informatique quantique en 2025"},
        {"role": "assistant", "content": response.content}
    ]
    
    # Envoyer la requête de continuation
    continuation = client.messages.create(
        model="claude-3-7-sonnet-latest",
        max_tokens=1024,
        messages=messages,
        tools=[{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 10
        }]
    )
    
    print(continuation)
else:
    print(response)

Lors de la gestion de pause_turn :

• Continuer la conversation : Passez la réponse en pause telle quelle dans une requête subséquente pour laisser Claude continuer son tour
• Modifier si nécessaire : Vous pouvez optionnellement modifier le contenu avant de continuer si vous voulez interrompre ou rediriger la conversation
• Préserver l’état des outils : Incluez les mêmes outils dans la requête de continuation pour maintenir la fonctionnalité

Dépannage des erreurs

Il existe quelques types d’erreurs différents qui peuvent survenir lors de l’utilisation d’outils avec Claude :

Erreur d'exécution d'outil

Si l’outil lui-même lève une erreur pendant l’exécution (par exemple une erreur réseau lors de la récupération de données météo), vous pouvez retourner le message d’erreur dans le content avec "is_error": true :

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: l'API du service météo n'est pas disponible (HTTP 500)",
      "is_error": true
    }
  ]
}

Claude incorporera 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éo n’est pas disponible. Veuillez réessayer plus tard.”

Nom d'outil invalide

Si la tentative d’utilisation d’un outil par Claude est invalide (par exemple paramètres requis manquants), cela signifie généralement qu’il n’y avait pas assez d’informations pour que Claude utilise l’outil correctement. Votre meilleur pari pendant le développement est d’essayer la requête à nouveau avec des valeurs description plus détaillées dans vos définitions d’outils.

Cependant, vous pouvez aussi continuer la conversation avec un tool_result qui indique l’erreur, et Claude essaiera d’utiliser l’outil à nouveau avec les informations manquantes remplies :

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Erreur : Paramètre 'location' requis manquant",
      "is_error": true
    }
  ]
}

Si une requête d’outil est invalide ou manque de paramètres, Claude réessaiera 2-3 fois avec des corrections avant de s’excuser auprès de l’utilisateur.

Balises <search_quality_reflection>

Pour empêcher Claude de réfléchir sur la qualité de la recherche avec des balises <search_quality_reflection>, ajoutez “Ne réfléchissez pas sur la qualité des résultats de recherche retournés dans votre réponse” à votre prompt.

Erreurs d'outils serveur

Lorsque les outils serveur rencontrent des erreurs (par exemple, problèmes réseau avec la Recherche Web), Claude gérera de manière transparente ces erreurs et tentera 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 spécifiquement, les codes d’erreur possibles incluent :

• too_many_requests : Limite de taux dépassée
• invalid_input : Paramètre de requête de recherche invalide
• max_uses_exceeded : Utilisations maximales de l’outil de recherche web dépassées
• query_too_long : La requête dépasse la longueur maximale
• unavailable : Une erreur interne s’est produite

Les appels d'outils en parallèle ne fonctionnent pas

Si Claude ne fait pas d’appels d’outils en parallèle quand attendu, vérifiez ces problèmes courants :

1. Formatage incorrect des résultats d’outils

Le problème le plus courant est de formater incorrectement les résultats d’outils dans l’historique de conversation. Cela “apprend” à Claude à éviter les appels en parallèle.

Spécifiquement pour l’utilisation d’outils en parallèle :

• ❌ Incorrect : Envoyer des messages utilisateur séparés pour chaque résultat d’outil
• ✅ Correct : Tous les résultats d’outils doivent être dans un seul message utilisateur

// ❌ Ceci réduit l'utilisation d'outils en parallèle
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1]},
  {"role": "user", "content": [tool_result_2]}  // Message séparé
]

// ✅ Ceci maintient l'utilisation d'outils en parallèle
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1, tool_result_2]}  // Message unique
]

Voir les exigences de formatage générales ci-dessus pour d’autres règles de formatage.

2. Prompting faible

Le prompting par défaut peut ne pas être suffisant. Utilisez un langage plus fort :

<use_parallel_tool_calls>
Pour une efficacité maximale, chaque fois que vous effectuez plusieurs opérations indépendantes, 
invoquez tous les outils pertinents simultanément plutôt que séquentiellement. 
Priorisez l'appel d'outils en parallèle chaque fois que possible.
</use_parallel_tool_calls>

3. Mesurer l’utilisation d’outils en parallèle

Pour vérifier que les appels d’outils en parallèle fonctionnent :

# Calculer la moyenne d'outils par message d'appel d'outil
tool_call_messages = [msg for msg in messages if any(
    block.type == "tool_use" for block in msg.content
)]
total_tool_calls = sum(
    len([b for b in msg.content if b.type == "tool_use"]) 
    for msg in tool_call_messages
)
avg_tools_per_message = total_tool_calls / len(tool_call_messages)
print(f"Moyenne d'outils par message : {avg_tools_per_message}")
# Devrait être > 1.0 si les appels en parallèle fonctionnent

4. Comportement spécifique au modèle

• Claude Opus 4.1, Opus 4 et Sonnet 4 : Excellent en utilisation d’outils en parallèle avec un prompting minimal
• Claude Sonnet 3.7 : Peut nécessiter un prompting plus fort ou l’utilisation d’outils efficace en tokens
• Claude Haiku : Moins susceptible d’utiliser des outils en parallèle sans prompting explicite