Utilisation d’outils
Appels de fonctions sur le point d’accès natif Anthropic. La passerelle normalise tool_choice pour que les anciens SDK qui envoient {type:any} ou {type:tool} continuent de fonctionner.
Format de la requête
Déclarez les outils dans un tableau. Chaque outil a un name, une description et un schéma JSON input_schema. Le modèle émet un bloc de contenu tool_use chaque fois qu’il décide d’en appeler un.
{
"model": "claude-sonnet-5-5",
"max_tokens": 1024,
"tools": [
{
"name": "get_weather",
"description": "Return current weather for a city.",
"input_schema": {
"type": "object",
"properties": {
"city": { "type": "string" },
"units": { "type": "string", "enum": ["c", "f"] }
},
"required": ["city"]
}
}
],
"messages": [
{ "role": "user", "content": "What's the weather in Berlin in celsius?" }
]
}Réponse avec un appel d’outil
{
"id": "msg_01...",
"stop_reason": "tool_use",
"content": [
{ "type": "text", "text": "Let me check that for you." },
{
"type": "tool_use",
"id": "toolu_bdrk_01...",
"name": "get_weather",
"input": { "city": "Berlin", "units": "c" }
}
]
}Poursuivre la boucle
Une fois l’outil exécuté par votre code, renvoyez le résultat dans un message user contenant un bloc tool_result. Le modèle émet alors un nouvel appel d’outil ou une réponse texte finale.
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_bdrk_01...",
"content": "{\"city\":\"Berlin\",\"temp_c\":18,\"sky\":\"clear\"}"
}
]
}tool_choice — notre normalisation
Anthropic accepte quatre formes de tool_choice. La passerelle API-AI accepte les quatre depuis votre client, mais en réécrit deux avant de les transmettre :
| Le client envoie | La passerelle transmet | Pourquoi |
|---|---|---|
{"type":"auto"} (ou absent) | inchangé | Le modèle décide — cas nominal. |
{"type":"none"} | inchangé | Force une réponse texte uniquement. |
{"type":"any"} | {"type":"auto"} + consigne système | L’amont renvoie une 502 sur any ; nous indiquons plutôt au modèle « tu DOIS appeler un outil ». |
{"type":"tool","name":"X"} | {"type":"auto"} + consigne système | Même problème en amont ; la consigne précise le nom de l’outil. |
tool_choice:any et tool_choice:tool. Ce comportement a été vérifié sur une batterie de 72 requêtes de test. La couche de compatibilité récupère environ 95 % de ces requêtes en les réécrivant en auto + une consigne système forte. Si un appel d’outil attendu est remplacé par du texte, la consigne n’a pas suffi : précisez votre prompt utilisateur ou passez à un modèle plus capable.Appels d’outils parallèles
Une même réponse peut contenir plusieurs blocs tool_use — le modèle décide s’il parallélise. Exécutez-les tous, puis renvoyez un seul message user avec plusieurs blocs tool_result (un par tool_use_id). L’ordre n’a pas d’importance.
Nommage des outils
- Les noms sont sensibles à la casse et transmis tels quels — le modèle reprend exactement ce que vous avez déclaré.
snake_caseetPascalCasefonctionnent tous les deux. La CLI Claude Code utilise le PascalCase (Read,Bash,Edit) ; les SDK génériques utilisent plutôt le snake_case.- Gardez des noms de moins de 64 caractères, en ASCII
[a-zA-Z0-9_].
Appels d’outils au format OpenAI
Sur le point d’accès /v1/chat/completions, utilisez le format OpenAI standard tools / tool_calls — nous le traduisons en blocs Anthropic tool_use en interne.