Utilisation d’outil

Avec les modèles Anthropic Claude, vous pouvez spécifier un outil que le modèle peut utiliser pour répondre à un message. Par exemple, vous pouvez spécifier un outil qui capte la chanson la plus populaire d’une station de radio. Si l’utilisateur passe le message Quelle est la chanson la plus populaire sur WZPZ ?, le modèle détermine que l’outil que vous avez spécifié peut aider à répondre à la question. Dans sa réponse, le modèle vous demande d’exécuter l’outil en son nom. Vous exécutez ensuite l’outil et transmettez le résultat de l’outil au modèle, qui génère alors une réponse pour le message d’origine. Pour plus d’informations, consultez la section Utilisation de l’outil (appel de fonction) dans la documentation Anthropic Claude.

Vous spécifiez les outils que vous souhaitez mettre à la disposition d’un modèle dans le champ tools. L’exemple suivant concerne un outil qui obtient les chansons les plus populaires d’une station de radio.

[
    {
        "name": "top_song",
        "description": "Get the most popular song played on a radio station.",
        "input_schema": {
            "type": "object",
            "properties": {
                "sign": {
                    "type": "string",
                    "description": "The call sign for the radio station for which you want the most popular song. Example calls signs are WZPZ and WKRP."
                }
            },
            "required": [
                "sign"
            ]
        }
    }
]

Lorsque le modèle a besoin d’un outil pour générer une réponse à un message, il renvoie des informations sur l’outil demandé, ainsi que l’entrée de l’outil, dans le champ content du message. Il définit également le motif d’arrêt de la réponse à tool_use.

{
    "id": "msg_bdrk_01USsY5m3XRUF4FCppHP8KBx",
    "type": "message",
    "role": "assistant",
    "model": "claude-3-sonnet-20240229",
    "stop_sequence": null,
    "usage": {
        "input_tokens": 375,
        "output_tokens": 36
    },
    "content": [
        {
            "type": "tool_use",
            "id": "toolu_bdrk_01SnXQc6YVWD8Dom5jz7KhHy",
            "name": "top_song",
            "input": {
                "sign": "WZPZ"
            }
        }
    ],
    "stop_reason": "tool_use"
}

Dans votre code, vous appelez l’outil en son nom. Vous transmettez ensuite le résultat de l’outil (tool_result) dans un message utilisateur au modèle.

{
    "role": "user",
    "content": [
        {
            "type": "tool_result",
            "tool_use_id": "toolu_bdrk_01SnXQc6YVWD8Dom5jz7KhHy",
            "content": "Elemental Hotel"
        }
    ]
}

Dans sa réponse, le modèle utilise le résultat de l’outil pour générer une réponse pour le message d’origine.

{
    "id": "msg_bdrk_012AaqvTiKuUSc6WadhUkDLP",
    "type": "message",
    "role": "assistant",
    "model": "claude-3-sonnet-20240229",
    "content": [
        {
            "type": "text",
            "text": "According to the tool, the most popular song played on radio station WZPZ is \"Elemental Hotel\"."
        }
    ],
    "stop_reason": "end_turn"
}

Streaming d’outil affiné

Le streaming d’outil affiné est une capacité du modèle Anthropic Claude disponible avec Claude Sonnet 4.5, Claude Haiku 4.5, Claude Sonnet 4 et Claude Opus 4. Grâce au streaming d’outil affiné, les développeurs Claude peuvent diffuser les paramètres d’utilisation d’outil sans mise en mémoire tampon ni validation JSON, réduisant ainsi le temps de latence nécessaire pour commencer à recevoir des paramètres de grande taille.

Pour utiliser cette fonctionnalité, il suffit d’ajouter l’en-tête fine-grained-tool-streaming-2025-05-14 à une demande d’utilisation d’outil.

Voici un exemple de la manière de spécifier l’en-tête de streaming d’outil affiné :

{
  "anthropic_version": "bedrock-2023-05-31",
  "max_tokens": 1024,
  "anthropic_beta": ["fine-grained-tool-streaming-2025-05-14"],
  "messages": [
    {
      "role": "user",
      "content": "Can you write a long poem and make a file called poem.txt?"
    }
  ],
  "tools": [
    {
      "name": "make_file",
      "description": "Write text to a file",
      "input_schema": {
        "type": "object",
        "properties": {
          "filename": {
            "type": "string",
            "description": "The filename to write text to"
          },
          "lines_of_text": {
            "type": "array",
            "description": "An array of lines of text to write to the file"
          }
        },
        "required": [
          "filename",
          "lines_of_text"
        ]
      }
    }
  ]
}

Dans cet exemple, le streaming d’outil affiné permet à Claude de diffuser les lignes d’un long poème dans l’appel d’outil make_file sans mise en mémoire tampon pour valider si le paramètre lines_of_text est un JSON valide. Cela signifie que vous pouvez voir le flux de paramètres tel qu’il arrive, sans avoir à attendre que l’intégralité du paramètre soit mise en mémoire tampon et validée.

Grâce au streaming d’outil affiné, les segments d’utilisation d’outil commencent à être diffusés plus rapidement, sont souvent plus longs et contiennent moins de sauts de mots. Cela est dû à des différences de comportement de segmentation.

Par exemple, sans streaming affiné (délai de 15 s) :

Chunk 1: '{"'
Chunk 2: 'query": "Ty'
Chunk 3: 'peScri'
Chunk 4: 'pt 5.0 5.1 '
Chunk 5: '5.2 5'
Chunk 6: '.3'
Chunk 8: ' new f'
Chunk 9: 'eatur'
...

Avec streaming affiné (délai de 3 s) :

Chunk 1: '{"query": "TypeScript 5.0 5.1 5.2 5.3'
Chunk 2: ' new features comparison'

Utilisation d’ordinateur (version bêta)

L’utilisation d’ordinateur est une capacité du modèle Anthropic Claude (en version bêta) disponible avec Claude 3.5 Sonnet v2, Claude Sonnet 4.5, Claude Haiku 4.5, Claude 3.7 Sonnet, Claude Sonnet 4 et Claude Opus 4. Grâce à l’utilisation d’ordinateur, Claude peut vous aider à automatiser les tâches à travers des actions de base de l’interface graphique.

L’API d’utilisation d’ordinateur propose plusieurs outils d’utilisation d’ordinateur prédéfinis que vous pouvez utiliser. Vous pouvez ensuite créer une invite avec votre demande, telle que « envoyer un e-mail à Ben avec les notes de ma dernière réunion » et une capture d’écran (si nécessaire). La réponse contient une liste d’actions tool_use au format JSON (par exemple, scroll_down, left_button_press, screenshot). Votre code exécute les actions de l’ordinateur et fournit une capture d’écran à Claude présentant les sorties (sur demande).

Depuis la sortie de Claude 3.5 v2, le paramètre tools a été mis à jour pour accepter les types d’outils polymorphes ; une propriété tool.type a été ajoutée pour les distinguer. Le type est facultatif ; s’il est omis, l’outil est supposé être un outil personnalisé (auparavant le seul type d’outil pris en charge). Pour accéder à l’utilisation d’ordinateur, vous devez utiliser le paramètre anthropic_beta, avec une énumération correspondante, dont la valeur dépend de la version du modèle utilisée. Pour plus d’informations, consultez le tableau suivant.

Seules les requêtes effectuées avec ce paramètre et enum peuvent utiliser les outils d’utilisation d’ordinateur. Cela peut être spécifié comme suit : "anthropic_beta": ["computer-use-2025-01-24"].

Pour plus d’informations, consultez Utilisation d’ordinateur (version bêta) dans la documentation Anthropic.

Voici un exemple de réponse qui suppose que la demande contenait une capture d’écran de votre bureau avec une icône Firefox.

{
    "id": "msg_123",
    "type": "message",
    "role": "assistant",
    "model": "anthropic.claude-3-5-sonnet-20241022-v2:0",
    "content": [
        {
            "type": "text",
            "text": "I see the Firefox icon. Let me click on it and then navigate to a weather website."
        },
        {
            "type": "tool_use",
            "id": "toolu_123",
            "name": "computer",
            "input": {
                "action": "mouse_move",
                "coordinate": [
                    708,
                    736
                ]
            }
        },
        {
            "type": "tool_use",
            "id": "toolu_234",
            "name": "computer",
            "input": {
                "action": "left_click"
            }
        }
    ],
    "stop_reason": "tool_use",
    "stop_sequence": null,
    "usage": {
        "input_tokens": 3391,
        "output_tokens": 132
    }
}

Outils définis par Anthropic

Anthropic fournit un ensemble d’outils permettant à certains modèles Claude d’utiliser efficacement les ordinateurs. Lorsque vous spécifiez un outil défini par Anthropic, les champs description et tool_schema ne sont ni nécessaires ni autorisés. Les outils définis par Anthropic sont définis par Anthropic, mais vous devez évaluer explicitement les résultats de l’outil et renvoyer les tool_results à Claude. Comme pour tout outil, le modèle n’exécute pas automatiquement l’outil. Chaque outil défini par Anthropic possède des versions optimisées pour des modèles spécifiques Claude 3.5 Sonnet (nouveaux) et Claude 3.7 Sonnet :

{ 
    "type": "text_editor_20250124", 
    "name": "str_replace_based_edit_tool" 
}

{ 
    "type": "computer_20250124", 
    "name": "computer" 
}

{ 
    "type": "text_editor_20250124", 
    "name": "str_replace_editor"
}

{ 
    "type": "bash_20250124", 
    "name": "bash" 
}

{ 
    "type": "text_editor_20241022", 
    "name": "str_replace_editor"
}

{ 
    "type": "bash_20241022", 
    "name": "bash"
}

{ 
    "type": "computer_20241022", 
    "name": "computer"
}

Le champ type identifie l’outil et ses paramètres à des fins de validation, le champ name est le nom de l’outil exposé au modèle.

Si vous souhaitez inviter le modèle à utiliser l’un de ces outils, vous pouvez référencer explicitement l’outil par le champ name. Le champ name doit être unique dans la liste d’outils ; vous ne pouvez pas définir un outil avec le même name qu’un outil défini par Anthropic dans le même appel d’API.

Effacement automatique des appels d’outil (version bêta)

Claude Sonnet 4.5 prend en charge une nouvelle fonctionnalité bêta qui efface automatiquement les anciens résultats d’utilisation d’outil lorsque vous approchez des limites de jetons, ce qui permet une gestion du contexte plus efficace dans les scénarios d’utilisation d’outils à plusieurs tours. Pour utiliser l’effacement de l’utilisation d’outil, vous devez ajouter context-management-2025-06-27 à la liste des en-têtes bêta sur le paramètre de demande anthropic_beta. Vous devrez également spécifier l’utilisation de clear_tool_uses_20250919 et choisir parmi les options de configuration suivantes.

Voici les contrôles disponibles pour la stratégie de gestion du contexte clear_tool_uses_20250919. Elles sont toutes facultatives ou comportent des valeurs par défaut :

Lorsque vous utilisez Claude Sonnet 4.5 avec l’effacement automatique d’appel d’outil, la réponse inclut des informations supplémentaires de gestion du contexte :

{
    "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
    "type": "message",
    "role": "assistant",
    "content": [...],
    ...
    "usage": {...},
    "context_management": {
        "applied_edits": [
            {
                "type": "clear_tool_uses_20250919",
                "cleared_tool_uses": 8,  # Number of tool use/result pairs that were cleared
                "cleared_input_tokens": 50000  # Total number of input tokens removed from the prompt
            }
        ]
    }
}

Outil de mémoire (version bêta)

Claude Sonnet 4.5 inclut un nouvel outil de mémoire qui permet aux clients de gérer la mémoire d’une conversation à l’autre. Grâce à cette fonctionnalité, les clients peuvent autoriser Claude à récupérer des informations en dehors de la fenêtre contextuelle en donnant accès à un répertoire local. Cela sera disponible en tant que fonctionnalité bêta. Pour utiliser cette fonctionnalité, vous devez utiliser l’en-tête bêta context-management-2025-06-27.

Définition d’outil :

{
  "type": "memory_20250818",
  "name": "memory"
}

Exemple de demande :

{
    "max_tokens": 2048,
    "anthropic_version": "bedrock-2023-05-31",
    "anthropic_beta": ["context-management-2025-06-27"],
    "tools": [{
        "type": "memory_20250818",
        "name": "memory"
    }],
    "messages": [
        {
            "role": "user",
            "content": [{"type": "text", "text": "Remember that my favorite color is blue and I work at Amazon?"}]
        }
    ]
}

Exemple de réponse :

{
    "id": "msg_vrtx_014mQ5ficCRB6PEa5k5sKqHd",
    "type": "message",
    "role": "assistant",
    "model": "claude-sonnet-4-20250514",
    "content": [
        {
            "type": "text",
            "text": "I'll start by checking your memory directory and then record this important information about you."
        },
        {
            "type": "tool_use",
            "id": "toolu_vrtx_01EU1UrCDigyPMRntr3VYvUB",
            "name": "memory",
            "input": {
                "command": "view",
                "path": "/memories"
            }
        }
    ],
    "stop_reason": "tool_use",
    "stop_sequence": null,
    "usage": {
        "input_tokens": 1403,
        "cache_creation_input_tokens": 0,
        "cache_read_input_tokens": 0,
        "output_tokens": 87
    },
    "context_management": {
        "applied_edits": []
    }
}

Considérations relatives aux coûts liés à l’utilisation d’outil

Les demandes d’utilisation d’outil sont facturées en fonction des facteurs suivants :

Le prix des outils est le même que celui de toutes les autres requêtes API Claude, mais ils incluent des jetons supplémentaires par demande. Les jetons supplémentaires liés à l’utilisation de l’outil proviennent des éléments suivants :

Lorsque vous utilisez des outils, les modèles Anthropic incluent automatiquement une invite système spéciale qui permet de les utiliser. Le nombre de jetons d’utilisation d’outils requis pour chaque modèle est indiqué dans le tableau suivant. Ce tableau exclut les jetons supplémentaires décrits précédemment. Notez que ce tableau suppose qu’au moins un outil est fourni. Si aucun outil n’est fourni, le choix d’aucun outil n’utilise aucun jeton d’invite système supplémentaire.