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)

L'effacement automatique des appels de l'outil est une fonctionnalité du modèle Anthropic Claude (en version bêta). Grâce à cette fonctionnalité, Claude peut automatiquement effacer les anciens résultats d'utilisation des outils 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 des options de configuration suivantes clear_tool_uses_20250919 et choisir parmi celles-ci.

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 :

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.

Outil de recherche d'outils (version bêta)

L'outil de recherche d'outils Claude permet de travailler avec des centaines, voire des milliers d'outils sans charger toutes leurs définitions dans la fenêtre contextuelle initiale. Au lieu de déclarer tous les outils immédiatement, vous pouvez les marquer avecdefer_loading: true, rechercher et Claude charger uniquement les outils dont ils ont besoin par le biais du mécanisme de recherche d'outils.

Pour accéder à cette fonctionnalité, vous devez utiliser l'en-tête bêtatool-search-tool-2025-10-19. Notez que cette fonctionnalité n'est actuellement disponible que via le InvokeModelet InvokeModelWithResponseStream APIs.

Définition d’outil :

{
    "type": "tool_search_tool_regex",
    "name": "tool_search_tool_regex"
}

Exemple de requête :

{
    "anthropic_version": "bedrock-2023-05-31",
    "anthropic_beta": [
        "tool-search-tool-2025-10-19"
    ],
    "max_tokens": 4096,
    "tools": [{
            "type": "tool_search_tool_regex",
            "name": "tool_search_tool_regex"
        },
        {
            "name": "get_weather",
            "description": "Get current weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"]
                    }
                },
                "required": ["location"]
            },
            "defer_loading": true
        },
        {
            "name": "search_files",
            "description": "Search through files in the workspace",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string"
                    },
                    "file_types": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    }
                },
                "required": ["query"]
            },
            "defer_loading": true
        }
    ],
    "messages": [{
        "role": "user",
        "content": "What's the weather in Seattle?"
    }]
}

Exemple de réponse

{
    "role": "assistant",
    "content": [{
            "type": "text",
            "text": "I'll search for the appropriate tools to help with this task."
        },
        {
            "type": "server_tool_use",
            "id": "srvtoolu_01ABC123",
            "name": "tool_search_tool_regex",
            "input": {
                "pattern": "weather"
            }
        },
        {
            "type": "tool_search_tool_result",
            "tool_use_id": "srvtoolu_01ABC123",
            "content": {
                "type": "tool_search_tool_search_result",
                "tool_references": [{
                    "type": "tool_reference",
                    "tool_name": "get_weather"
                }]
            }
        },
        {
            "type": "text",
            "text": "Now I can check the weather."
        },
        {
            "type": "tool_use",
            "id": "toolu_01XYZ789",
            "name": "get_weather",
            "input": {
                "location": "Seattle",
                "unit": "fahrenheit"
            }
        }
    ],
    "stop_reason": "tool_use"
}

Exemple de streaming

# Event 1: content_block_start(with complete server_tool_use block) {
    "type": "content_block_start",
    "index": 0,
    "content_block": {
        "type": "server_tool_use",
        "id": "srvtoolu_01ABC123",
        "name": "tool_search_tool_regex"
    }
}

# Event 2: content_block_delta(input JSON streamed) {
    "type": "content_block_delta",
    "index": 0,
    "delta": {
        "type": "input_json_delta",
        "partial_json": "{\"regex\": \".*weather.*\"}"
    }
}

# Event 3: content_block_stop(tool_use complete) {
    "type": "content_block_stop",
    "index": 0
}

# Event 4: content_block_start(COMPLETE result in single chunk) {
    "type": "content_block_start",
    "index": 1,
    "content_block": {
        "type": "tool_search_tool_result",
        "tool_use_id": "srvtoolu_01ABC123",
        "content": {
            "type": "tool_search_tool_search_result",
            "tool_references": [{
                "type": "tool_reference",
                "tool_name": "get_weather"
            }]
        }
    }
}

# Event 5: content_block_stop(result complete) {
    "type": "content_block_stop",
    "index": 1
}

Outils de recherche d'outils personnalisés

Vous pouvez implémenter des outils de recherche d'outils personnalisés (par exemple, en utilisant des intégrations) en définissant un outil qui renvoie des blocs. tool_reference L'outil personnalisé doit l'être defer_loading: false alors que les autres outils devraient l'avoirdefer_loading: true. Lorsque vous définissez votre propre outil de recherche d'outils, celui-ci doit renvoyer un résultat contenant des blocs de tool_reference contenu pointant vers les outils que vous Claude souhaitez utiliser.

Format de réponse aux résultats attendu de l'outil de recherche d'outils défini par le client :

{
    "type": "tool_result",
    "tool_use_id": "toolu_01ABC123",
    "content": [{
            "type": "tool_reference",
            "tool_name": "get_weather"
        },
        {
            "type": "tool_reference",
            "tool_name": "weather_forecast"
        }
    ]
}

Le tool_name doit correspondre à un outil défini dans la demande avecdefer_loading: true. Claude aura alors accès aux schémas complets de ces outils.

Outils de recherche personnalisés - Exemple détaillé

Vous pouvez implémenter des outils de recherche d'outils personnalisés (par exemple, en utilisant des intégrations ou une recherche sémantique) en définissant un outil qui renvoie des blocs. tool_reference Cela permet des mécanismes sophistiqués de découverte d'outils allant au-delà de la correspondance des regex.

Exemple de demande avec TST personnalisé :

{
    "model": "claude-sonnet-4-5-20250929",
    "anthropic_version": "bedrock-2023-05-31",
    "anthropic_beta": ["tool-search-tool-2025-10-19"],
    "max_tokens": 4096,
    "tools": [{
            "name": "semantic_tool_search",
            "description": "Search for available tools using semantic similarity. Returns the most relevant tools for the given query.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Natural language description of what kind of tool is needed"
                    },
                    "top_k": {
                        "type": "integer",
                        "description": "Number of tools to return (default: 5)"
                    }
                },
                "required": ["query"]
            },
            "defer_loading": false
        },
        {
            "name": "get_weather",
            "description": "Get current weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"]
                    }
                },
                "required": ["location"]
            },
            "defer_loading": true
        },
        {
            "name": "search_flights",
            "description": "Search for available flights between locations",
            "input_schema": {
                "type": "object",
                "properties": {
                    "origin": {
                        "type": "string"
                    },
                    "destination": {
                        "type": "string"
                    },
                    "date": {
                        "type": "string"
                    }
                },
                "required": ["origin", "destination", "date"]
            },
            "defer_loading": true
        }
    ],
    "messages": [{
        "role": "user",
        "content": "What's the weather forecast in Seattle for the next 3 days?"
    }]
}

Claudede la réponse (appel au TST personnalisé) :

{
    "role": "assistant",
    "content": [{
            "type": "text",
            "text": "I'll search for the appropriate tools to help with weather information."
        },
        {
            "type": "tool_use",
            "id": "toolu_01ABC123",
            "name": "semantic_tool_search",
            "input": {
                "query": "weather forecast multiple days",
                "top_k": 3
            }
        }
    ],
    "stop_reason": "tool_use"
}

Résultat de l'outil fourni par le client

Après avoir effectué une recherche sémantique dans la bibliothèque d'outils, le client renvoie les références d'outils correspondantes :

{
    "role": "user",
    "content": [{
        "type": "tool_search_tool_result",
        "tool_use_id": "toolu_01ABC123",
        "content": {
            "type": "tool_search_tool_search_result",
            "tool_references": [{
                "type": "tool_reference",
                "tool_name": "get_weather"
            }]
        }
    }]
}

Claudesuivi (à l'aide de l'outil découvert)

{
    "role": "assistant",
    "content": [{
            "type": "text",
            "text": "I found the forecast tool. Let me get the weather forecast for Seattle."
        },
        {
            "type": "tool_use",
            "id": "toolu_01DEF456",
            "name": "get_weather",
            "input": {
                "location": "Seattle, WA"
            }
        }
    ],
    "stop_reason": "tool_use"
}

Exemples d'utilisation d'outils (version bêta)

Claude Opus4.5 prend en charge les exemples fournis par les utilisateurs dans les définitions d'outils afin d'améliorer les performances Claude d'utilisation des outils. Vous pouvez fournir des exemples sous forme d'appels de fonction complets, formatés exactement comme le seraient les sorties LLM réelles, sans qu'il soit nécessaire de les traduire dans un autre format. Pour utiliser cette fonctionnalité, vous devez transmettre l'en-tête bêtatool-examples-2025-10-29.

Exemple de définition d'outil :

{
    "name": "get_weather",
    "description": "Get the current weather in a given location",
    "input_schema": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA"
            },
            "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"],
                "description": "Temperature unit"
            }
        },
        "required": ["location"]
    },
    "input_examples": [{
            "location": "San Francisco, CA",
            "unit": "fahrenheit"
        },
        {
            "location": "Tokyo, Japan",
            "unit": "celsius"
        },
        {
            "location": "New York, NY"
        }
    ]
}

Exemples d'erreurs :

// Invalid: Example doesn't match schema (missing required field)
{
    "type": "invalid_request_error",
    "message": "Tool 'get_weather' input_examples[0] is invalid: Missing required property 'location'"
}

// Invalid: Example has wrong type for field
{
    "type": "invalid_request_error",
    "message": "Tool 'search_products' input_examples[1] is invalid: Property 'filters.price_range.min' must be a number, got string"
}

// Invalid: input_examples on server-side tool
{
    "type": "invalid_request_error",
    "message": "input_examples is not supported for server-side tool"
}