Voici quelques exemples de code démontrant divers modèles et techniques d’utilisation d’outils. Par souci de concision, les outils sont des outils simples et les descriptions d’outils sont plus courtes que ce qui serait idéal pour garantir les meilleures performances. Voir spécification des outils pour plus d’informations.

​
Outil unique

Cet exemple montre une situation de base avec un seul outil, en utilisant un outil get_weather.

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-opus-20240229",
    "max_tokens": 1024,
    "tools": [{
        "name": "get_weather",
        "description": "Obtenir la météo actuelle pour un lieu donné",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "La ville et l'état, par ex. San Francisco, CA"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "L'unité de température, soit \"celsius\" soit \"fahrenheit\""
                }
            },
            "required": ["location"]
        }
    }],
    "messages": [{"role": "user", "content": "Quel temps fait-il à San Francisco ?"}]
}'

Claude renverra une réponse similaire à :

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-opus-20240229",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Je dois appeler la fonction get_weather, et l'utilisateur veut SF, qui est probablement San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9", 
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

Vous devrez ensuite exécuter la fonction get_weather avec l’entrée fournie, et renvoyer le résultat dans un nouveau message user :

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-opus-20240229",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Obtenir la météo actuelle pour un lieu donné",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "La ville et l'état, par ex. San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "L'unité de température, soit \"celsius\" soit \"fahrenheit\""
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Quel temps fait-il à San Francisco ?"
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "<thinking>Je dois utiliser get_weather, et l'utilisateur veut SF, qui est probablement San Francisco, CA.</thinking>"
                },
                {
                    "type": "tool_use",
                    "id": "toolu_01A09q90qw90lq917835lq9",
                    "name": "get_weather",
                    "input": {
                        "location": "San Francisco, CA",
                        "unit": "celsius"
                    }
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
                    "content": "15 degrés"
                }
            ]
        }
    ]
}'

Cela imprimera la réponse finale de Claude, incorporant les données météorologiques :

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-opus-20240229",
  "stop_reason": "stop_sequence",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "La météo actuelle à San Francisco est de 15 degrés Celsius (59 degrés Fahrenheit). C'est une journée fraîche dans la ville au bord de la baie !"
    }
  ]
}

​
Informations manquantes

Si l’invite de l’utilisateur ne contient pas suffisamment d’informations pour remplir tous les paramètres requis pour un outil, Claude 3 Opus est beaucoup plus susceptible de reconnaître qu’un paramètre est manquant et de le demander. Claude 3 Sonnet peut le demander, surtout lorsqu’on lui demande de réfléchir avant de produire une requête d’outil. Mais il peut aussi faire de son mieux pour déduire une valeur raisonnable.

Par exemple, en utilisant l’outil get_weather ci-dessus, si vous demandez à Claude “Quel temps fait-il ?” sans préciser de lieu, Claude, en particulier Claude 3 Sonnet, peut faire une supposition sur les entrées des outils :

JSON
{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "get_weather", 
  "input": {"location": "New York, NY", "unit": "fahrenheit"}
}

Ce comportement n’est pas garanti, surtout pour des invites plus ambiguës et pour des modèles moins intelligents que Claude 3 Opus. Si Claude 3 Opus n’a pas suffisamment de contexte pour remplir les paramètres requis, il est beaucoup plus susceptible de répondre par une question de clarification au lieu de faire un appel d’outil.

​
Outils multiples

Vous pouvez fournir à Claude plusieurs outils parmi lesquels choisir dans une seule requête. Voici un exemple avec à la fois un outil get_weather et un outil get_time, ainsi qu’une requête utilisateur qui demande les deux.

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-opus-20240229",
    "max_tokens": 1024,
    "tools": [{
        "name": "get_weather",
        "description": "Obtenir la météo actuelle pour un lieu donné",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "La ville et l'état, par ex. San Francisco, CA"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "L'unité de température, soit 'celsius' soit 'fahrenheit'"
                }
            },
            "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 nom du fuseau horaire IANA, par ex. America/Los_Angeles"
                }
            },
            "required": ["timezone"]
        }
    }],
    "messages": [{
        "role": "user",
        "content": "Quel temps fait-il en ce moment à New York ? Et quelle heure est-il là-bas ?"
    }]
}'

Dans ce cas, Claude essaiera très probablement d’utiliser deux outils distincts, un à la fois - get_weather puis get_time - afin de répondre complètement à la question de l’utilisateur. Cependant, il produira aussi parfois deux blocs tool_use à la fois, en particulier s’ils ne dépendent pas l’un de l’autre. Vous devrez exécuter chaque outil et renvoyer leurs résultats dans des blocs tool_result séparés au sein d’un seul message user.

​
Outils séquentiels

Certaines tâches peuvent nécessiter d’appeler plusieurs outils en séquence, en utilisant la sortie d’un outil comme entrée d’un autre. Dans un tel cas, Claude appellera un outil à la fois. S’il est invité à appeler tous les outils à la fois, Claude est susceptible de deviner les paramètres des outils plus en aval s’ils dépendent des résultats des outils plus en amont.

Voici un exemple d’utilisation d’un outil get_location pour obtenir la localisation de l’utilisateur, puis de passer cette localisation à l’outil get_weather :

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-opus-20240229",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_location",
            "description": "Obtenir la localisation actuelle de l'utilisateur en fonction de son adresse IP. Cet outil n'a pas de paramètres ou d'arguments.",
            "input_schema": {
                "type": "object",
                "properties": {}
            }
        },
        {
            "name": "get_weather",
            "description": "Obtenir la météo actuelle pour un lieu donné",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "La ville et l'état, par ex. San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "L'unité de température, soit 'celsius' soit 'fahrenheit'"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [{
        "role": "user",
        "content": "Quel temps fait-il là où je suis ?"
    }]
}'

Dans ce cas, Claude appellerait d’abord l’outil get_location pour obtenir la localisation de l’utilisateur. Après que vous ayez renvoyé la localisation dans un tool_result, Claude appellerait ensuite get_weather avec cette localisation pour obtenir la réponse finale.

La conversation complète pourrait ressembler à :

RôleContenu
UtilisateurQuel temps fait-il là où je suis ?
Assistant<thinking>Pour répondre à cela, je dois d’abord déterminer la localisation de l’utilisateur en utilisant l’outil get_location. Ensuite, je peux passer cette localisation à l’outil get_weather pour trouver la météo actuelle à cet endroit.</thinking>[Utilisation de l’outil pour get_location]
Utilisateur[Résultat de l’outil pour get_location avec l’id correspondant et le résultat San Francisco, CA]
Assistant[Utilisation de l’outil pour get_weather avec l’entrée suivante]{ “location”: “San Francisco, CA”, “unit”: “fahrenheit” }
Utilisateur[Résultat de l’outil pour get_weather avec l’id correspondant et le résultat “59°F (15°C), plutôt nuageux”]
AssistantD’après votre localisation actuelle à San Francisco, CA, la météo en ce moment est de 59°F (15°C) et plutôt nuageuse. C’est une journée assez fraîche et couverte dans la ville. Vous voudrez peut-être prendre une veste légère si vous sortez.

Cet exemple montre comment Claude peut enchaîner plusieurs appels d’outils pour répondre à une question qui nécessite de rassembler des données provenant de différentes sources. Les étapes clés sont :

  1. Claude réalise d’abord qu’il a besoin de la localisation de l’utilisateur pour répondre à la question sur la météo, il appelle donc l’outil get_location.
  2. L’utilisateur (c’est-à-dire le code client) exécute la fonction get_location réelle et renvoie le résultat “San Francisco, CA” dans un bloc tool_result.
  3. La localisation étant maintenant connue, Claude procède à l’appel de l’outil get_weather, en passant “San Francisco, CA” comme paramètre location (ainsi qu’un paramètre unit deviné, car unit n’est pas un paramètre requis).
  4. L’utilisateur exécute à nouveau la fonction get_weather réelle avec les arguments fournis et renvoie les données météorologiques dans un autre bloc tool_result.
  5. Enfin, Claude intègre les données météorologiques dans une réponse en langage naturel à la question initiale.

​
Utilisation d’outils avec une chaîne de pensée

Par défaut, Claude 3 Opus est invité à réfléchir avant de répondre à une requête d’utilisation d’outil pour mieux déterminer si un outil est nécessaire, quel outil utiliser et les paramètres appropriés. Claude 3 Sonnet et Claude 3 Haiku sont invités à essayer d’utiliser des outils autant que possible et sont plus susceptibles d’appeler un outil inutile ou de déduire des paramètres manquants. Pour inciter Sonnet ou Haiku à mieux évaluer la requête de l’utilisateur avant de faire des appels d’outils, l’invite suivante peut être utilisée :

Invite de chaîne de pensée

Répondez à la demande de l'utilisateur en utilisant les outils pertinents (s'ils sont disponibles). Avant d'appeler un outil, faites une analyse dans des balises \<thinking>\</thinking>. Tout d'abord, réfléchissez à l'outil fourni qui est pertinent pour répondre à la demande de l'utilisateur. Ensuite, passez en revue chacun des paramètres requis de l'outil pertinent et déterminez si l'utilisateur a directement fourni ou donné suffisamment d'informations pour en déduire une valeur. Lorsque vous décidez si le paramètre peut être déduit, considérez attentivement tout le contexte pour voir s'il supporte une valeur spécifique. Si toutes les valeurs des paramètres requis sont présentes ou peuvent être raisonnablement déduites, fermez la balise de réflexion et procédez à l'appel de l'outil. MAIS, si l'une des valeurs d'un paramètre requis est manquante, N'invoquez PAS la fonction (pas même avec des valeurs de remplissage pour les paramètres manquants) et demandez plutôt à l'utilisateur de fournir les paramètres manquants. NE demandez PAS plus d'informations sur les paramètres optionnels s'ils ne sont pas fournis.

​
Mode JSON

Vous pouvez utiliser des outils pour que Claude produise une sortie JSON qui suit un schéma, même si vous n’avez pas l’intention d’exécuter cette sortie via un outil ou une fonction.

Lorsque vous utilisez des outils de cette manière :

  • Vous voulez généralement fournir un seul outil
  • Vous devez définir tool_choice (voir Forcer l’utilisation d’un outil) pour indiquer au modèle d’utiliser explicitement cet outil
  • N’oubliez pas que le modèle passera l’input à l’outil, donc le nom de l’outil et sa description doivent être du point de vue du modèle.

L’exemple suivant utilise un outil record_summary pour décrire une image suivant un format particulier.

#!/bin/bash
IMAGE_URL="https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
IMAGE_MEDIA_TYPE="image/jpeg"
IMAGE_BASE64=$(curl "$IMAGE_URL" | base64)

curl https://api.anthropic.com/v1/messages \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --data \
'{
    "model": "claude-3-sonnet-20240229",
    "max_tokens": 1024,
    "tools": [{
        "name": "record_summary",
        "description": "Enregistrer un résumé d'une image en utilisant du JSON bien structuré.",
        "input_schema": {
            "type": "object",
            "properties": {
                "key_colors": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
"r": { "type": "number", "description": "valeur rouge [0.0, 1.0]" },
"g": { "type": "number", "description": "valeur verte [0.0, 1.0]" },
"b": { "type": "number", "description": "valeur bleue [0.0, 1.0]" },
"name": { "type": "string", "description": "Nom de couleur lisible par l'homme en snake_case, par ex. \"olive_green\" ou \"turquoise\"" }
                        },
                        "required": [ "r", "g", "b", "name" ]
                    },
                    "description": "Couleurs clés dans l'image. Limitez à moins de quatre."
                },
                "description": {
                    "type": "string",
                    "description": "Description de l'image. Une à deux phrases maximum."
                },
                "estimated_year": {
                    "type": "integer",
                    "description": "Année estimée de prise de l'image, s'il s'agit d'une photo. Ne définissez ceci que si l'image semble être non fictive. Des estimations approximatives sont acceptables !"
                }
            },
            "required": [ "key_colors", "description" ]
        }
    }],
    "tool_choice": {"type": "tool", "name": "record_summary"},
    "messages": [
        {"role": "user", "content": [
            {"type": "image", "source": {
                "type": "base64",
                "media_type": "'$IMAGE_MEDIA_TYPE'",
                "data": "'$IMAGE_BASE64'"
            }},
            {"type": "text", "text": "Décrivez cette image."}
        ]}
    ]
}'
AperçuTarification et jetons pour l'utilisation des outils