Claude · Tool use et structured outputs
Un modèle qui ne sait produire que du texte devient une impasse dès que vous avez besoin qu'il interroge une base de données en direct, appelle une APIAPIApplication Programming Interface : une interface standardisée qui permet aux applications de communiquer et d'échanger des données sans connaître leur fonctionnement interne respectif.Voir la définition complète → ou transmette un JSON propre au service suivant de votre pipelinepipelineL'ensemble des opportunités commerciales actives réparties selon les étapes du processus de vente, avec leur valeur potentielle cumulée et leur probabilité de conclusion.Voir la définition complète →. Le tool use et les structured outputs comblent ce manque avec Claude. Vous décrivez des capacités, Claude décide quand les invoquer, et vous récupérez des données que votre code peut exploiter.
Cette leçon couvre ces deux mécanismes sur l'API Messages d'Anthropic. Vous verrez la forme des requêtes que vous envoyez et des réponses que vous analysez, ainsi que le lien entre les deux techniques.
Ce que recouvre vraiment le « tool use »
Le tool use (parfois appelé function calling) est un protocole. Claude n'exécute jamais votre code. Vous lui fournissez une liste de définitions d'outils. Chacune comporte un nom, une description et un JSON SchemaSchemaUn schema est le plan formel qui définit comment les données sont structurées, nommées, typées et reliées entre elles au sein d'une base de données, d'un fichier ou d'un message.Voir la définition complète → pour ses entrées.
Quand Claude estime qu'un outil serait utile, il arrarrL'Annual Recurring Revenue (ARR) est le revenu normalisé et prévisible qu'une entreprise par abonnement attend de ses contrats actifs sur une année.Voir la définition complète →ête de rédiger et émet une requête structurée, par exemple : « appeler get_weather avec {"location": "Paris"} ». Votre application exécute cette fonction et renvoie le résultat. Claude reprend ensuite.
Cet aller-retour constitue la boucle de tool use. Une fois que vous l'avez comprise, le reste de la leçon en découle.
Les quatre étapes de la boucle
- Vous envoyez un message utilisateur accompagné de votre tableau
tools. - Claude répond avec
stop_reason: "tool_use"et un bloc de contenutool_use. - Vous exécutez l'outil et renvoyez la réponse sous forme de
tool_result. - Claude lit le résultat et produit sa réponse textuelle finale.
Une boucle get_weather concrète
Voici la boucle complète en Python avec le SDK officiel. Lisez-la une fois, puis nous détaillerons chaque structure.
import anthropic
client = anthropic.Anthropic()
tools = [{
"name": "get_weather",
"description": "Get current temperature for a given city.",
"input_schema": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "City name, e.g. 'Paris'"}
},
"required": ["location"],
},
}]
def get_weather(location):
# En conditions réelles, appelez ici une API météo.
return {"location": location, "temp_c": 14, "conditions": "cloudy"}
messages = [{"role": "user", "content": "What's the weather in Paris right now?"}]
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
tools=tools,
messages=messages,
)
# Étape 2 : Claude a demandé un outil.
if response.stop_reason == "tool_use":
tool_call = next(b for b in response.content if b.type == "tool_use")
result = get_weather(**tool_call.input)
# Étape 3 : ajoutez la requête de Claude ET votre résultat.
messages.append({"role": "assistant", "content": response.content})
messages.append({
"role": "user",
"content": [{
"type": "tool_result",
"tool_use_id": tool_call.id,
"content": str(result),
}],
})
# Étape 4 : Claude lit le résultat et rédige la réponse.
final = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
tools=tools,
messages=messages,
)
print(final.content[0].text)Les exemples utilisent claude-sonnet-4-5. Tout identifiant de modèle Claude actuel figurant dans la vue d'ensemble des modèles fonctionne de la même façon.
Lire la structure de la réponse
Quand Claude veut un outil, response.content est une liste de blocs. Celui qui vous intéresse ressemble à ceci :
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_weather",
"input": {"location": "Paris"}
}Trois champs comptent :
namevous indique quelle fonction exécuter.inputest déjà un objet analysé conforme à votre schémamaUtiliser un logiciel pour automatiser les tâches et campagnes marketing répétitives, afin de personnaliser à grande échelle sur des canaux comme l'email, le web et le social.Voir la définition complète →, vous n'avez donc aucune chaîne à parser.- `id` est l'identifiant que vous devez renvoyer.
Renvoyer le résultat
Le détail qui échappe souvent : vous devez ajouter deux messages, dans cet ordre.
- Le tour assistant de Claude lui-même : l'intégralité de
response.content, bloctool_usecompris. - Un tour utilisateur contenant le
tool_result.
Le tool_use_id de votre résultat doit correspondre exactement à l'id envoyé par Claude, sinon la boucle casse.
Si votre outil échoue, indiquez "is_error": true dans le bloc de résultat. Claude verra l'erreur. Il pourra alors s'excuser, réessayer avec d'autres entrées ou choisir un autre outil.
Plusieurs outils et appels parallèles
Vous livrez rarement un seul outil. Passez-en plusieurs dans le tableau tools et Claude oriente vers le bon en fonction des descriptions.
Rédigez ces descriptions comme de la documentation, car c'est la seule chose sur laquelle Claude s'appuie pour décider. « Get current temperaturetemperatureUn reglage qui controle le caractere aleatoire ou previsible des reponses d'un modele d'IA : bas pour la coherence, haut pour la creativite.Voir la définition complète → for a given city » l'emporte toujours sur « weather tool ».
Claude peut aussi demander plusieurs outils dans un même tour (parallel tool use). Dans ce cas, response.content contient plusieurs blocs tool_use. Exécutez-les tous. Renvoyez ensuite tous les blocs tool_result ensemble dans un seul message utilisateur avant de rappeler l'API.
Claude peut enchaîner plusieurs outils avant d'avoir terminé. Pour gérer ce cas, placez l'appel dans une boucle while response.stop_reason == "tool_use" plutôt que dans un simple if.
Structured outputs : récupérer un JSON propre
Le tool use répond à « fais quelque chose ». Les structured outputs répondent à « donne-moi des données dans une forme exacte ». Imaginons que vous extrayiez des champs d'un e-mail de support. Il vous faut {"category": ..., "urgency": ..., "summary": ...} à chaque fois, sans prose ni balises markdown.
Depuis novembre 2025, l'API Messages propose des structured outputs natifs. Ils existent sous deux formes :
- JSON outputs. Vous passez un JSON Schema comme format de réponse, et la réponse textuelle de Claude est garantie analysable et conforme.
- Strict tool use. Vous ajoutez
"strict": trueà une définition d'outil, et chaque entréetool_useest garantie conforme à l'input_schemade cet outil.
Les deux reposent sur le décodage contraint. Le modèle ne peut pas émettre de tokenstokensUn token est l'unité de base de texte que traitent les modèles de langage : le plus souvent un fragment de mot, un mot entier ou un signe de ponctuation, plutôt qu'un simple caractère.Voir la définition complète → qui casseraient votre schéma, vous n'avez donc plus besoin de logique de relance en cas de JSON invalide.
import json
import anthropic
client = anthropic.Anthropic()
ticket_schema = {
"type": "object",
"properties": {
"category": {"type": "string", "enum": ["billing", "bug", "feature", "other"]},
"urgency": {"type": "string", "enum": ["low", "medium", "high"]},
"summary": {"type": "string", "description": "One sentence."},
},
"required": ["category", "urgency", "summary"],
"additionalProperties": False,
}
email = "I was charged twice this month and need this fixed before Friday!"
response = client.beta.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
betas=["structured-outputs-2025-11-13"],
output_format={"type": "json_schema", "schema": ticket_schema},
messages=[{"role": "user", "content": email}],
)
ticket = json.loads(response.content[0].text)
print(ticket)
# {'category': 'billing', 'urgency': 'high', 'summary': 'Customer charged twice and wants a fix by Friday.'}La fonctionnalité a été lancée en bêta avec l'en-tête indiqué ci-dessus. Consultez la documentation pour connaître les noms de paramètres actuels et les modèles compatibles, car les API bêta peuvent changer de forme lors de leur passage en disponibilité générale.
Les SDK Python et TypeScript acceptent aussi un modèle Pydantic ou Zod et le convertissent en schéma pour vous.
Les contraintes enum font ici un vrai travail. Avec le décodage contraint, Claude ne peut pas inventer un quatrième niveau d'urgence. Plus votre schéma est strict, plus vos sorties le sont.
Certaines fonctionnalités de schéma ne sont pas prises en charge, comme certaines bornes numériques et les définitions récursives complexes. La première requête avec un nouveau schéma entraîne aussi une latence supplémentaire pendant la compilation de la grammaire, qui est ensuite mise en cache.
Le pattern de l'outil forcé
Avant l'arrivée des structured outputs natifs, l'astuce classique consistait à définir un outil représentant votre sortie et à forcer Claude à l'appeler. Vous le retrouverez dans beaucoup de code existant. Il fonctionne toujours, et l'ajout de "strict": true le rend garanti.
extract_tool = {
"name": "record_ticket",
"description": "Record the structured fields of a support ticket.",
"strict": True,
"input_schema": ticket_schema,
}
response = client.beta.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
betas=["structured-outputs-2025-11-13"],
tools=[extract_tool],
tool_choice={"type": "tool", "name": "record_ticket"},
messages=[{"role": "user", "content": email}],
)
ticket = next(b.input for b in response.content if b.type == "tool_use")Le paramètre tool_choice est le levier. Le régler sur {"type": "tool", "name": "record_ticket"} force cet appel précis. Vous n'exécutez aucune fonction ici. Vous lisez simplement b.input.
Autres valeurs de tool_choice :
{"type": "auto"}(par défaut) : Claude décide s'il utilise un outil.{"type": "any"}: Claude doit utiliser *un* outil, mais choisit lequel.{"type": "tool", "name": "..."}: force un outil précis, comme ci-dessus.{"type": "none"}: aucun appel d'outil pendant ce tour.
En règle générale, utilisez les JSON outputs quand vous voulez que la réponse de Claude elle-même ait une forme fixe. Utilisez les strict tools quand Claude appelle de vraies fonctions dans un agent et qu'un argument mal formé casserait quelque chose.
Le guide du tool use fait référence pour les cas limites de schéma et le streaming.
Vérification des acquis
1. Dans le protocole de tool use décrit, que se passe-t-il réellement quand Claude « utilise » un outil ?
2. Pourquoi le tool use et les structured outputs sont-ils utiles pour intégrer Claude dans un pipeline logiciel ?
3. Après que vous avez renvoyé un tool_result à Claude, que se passe-t-il à la dernière étape de la boucle de tool use ?
4. Sélectionnez TOUS les éléments qu'une définition d'outil doit contenir quand vous envoyez votre tableau tools à Claude.
Sélectionnez toutes les réponses correctes.
5. Sélectionnez TOUTES les affirmations qui décrivent correctement le fonctionnement de la boucle de tool use.
Sélectionnez toutes les réponses correctes.
Le lien avec MCPMCPUn standard ouvert qui permet aux assistants IA de se connecter aux outils et données de l'entreprise de façon cohérente et gouvernée, sans intégration sur mesure à chaque fois.Voir la définition complète → et l'Agent SDK
Tout ce qui précède correspond à l'API brute. Vous définissez les outils en ligne et les exécutez vous-même. C'est parfait pour quelques outils sur mesure au sein d'un seul service.
Vous voudrez vite des outils réutilisables que n'importe quelle interface Claude peut appeler, comme l'application desktop, Claude Code ou votre propre agent. MCP (Model Context Protocol) standardise cela.
Un serveur MCP expose des outils (ainsi que des ressources et des prompts) via un protocole défini. Vous écrivez un outil une fois et le branchez sur de nombreux clients. Les applications Claude les présentent sous forme de Connectors, et un annuaire de connecteurs existe pour les plus courants comme Google Drive ou GitHub.
Les outils MCP et les outils API sont la même idée à des échelles différentes. La liste d'outils d'un serveur MCP finit par devenir des entrées dans un tableau tools, et l'échange appel/résultat reproduit la boucle que vous venez d'apprendre. Découvrez le protocole sur modelcontextprotocol.io.
Le Claude Agent SDK se situe un niveau au-dessus. Il exécute la boucle de tool use pour vous, gère le contexte et prend en charge le comportement multi-étapes de l'agent. Vous décrivez des outils et des objectifs au lieu de coder à la main la mécanique while stop_reason == "tool_use".
Quand vous construisez un vrai agent, prenez le SDK. Quand vous avez besoin d'un contrôle précis sur un échange unique, descendez à l'API Messages comme montré plus haut. Les deux utilisent le même protocole de tool use, c'est pourquoi maîtriser la boucle brute est rentable.
Pièges pratiques
Quelques points qui vous rattraperont en production :
- Budget de tokens. Les définitions d'outils occupent la fenêtre de contexte, donc vingt outils verbeux coûtent de vrais tokens à chaque appel. Gardez des schémas légers et des descriptions précises.
- Validez quand même les valeurs. Le mode strict garantit la forme, pas le sens. Un
{"user_id": "1 OR 1=1"}conforme au schéma reste dangereux. Traitezinputcomme une saisie utilisateur non fiable : vérifiez les plages, nettoyez et contrôlez les autorisations avant d'interroger une base de données. - Les outils forcés sautent le raisonnement. Quand vous forcez
tool_choicesur un outil précis, Claude passe directement à l'appel, et le choix d'outil forcé n'est pas compatible avec l'extended thinking. Si vous avez besoin d'un raisonnement préalable, laissez-le surauto, utilisez les JSON outputs ou répartissez le travail sur deux appels. - Les erreurs sont un signal, pas un échec. Renvoyer
is_error: trueavec un message utile permet souvent à Claude de se corriger au tour suivant. C'est préférable à un plantage de votre boucle.
Points clés
- Le tool use est une boucle en quatre étapes. Envoyez les outils, recevez un bloc
tool_use, exécutez la fonction et renvoyez untool_resultavec letool_use_idcorrespondant. Renvoyez le tour assistant de Claude avant le résultat, sinon la boucle casse. - Pour un JSON garanti, utilisez les structured outputs natifs. Utilisez un format de sortie
json_schemapour la réponse elle-même, ou"strict": truesur les outils. Grâce au décodage contraint, le schéma est toujours respecté. L'ancien pattern de l'outil forcé fonctionne toujours. - Rédigez les descriptions d'outils comme de la documentation. Claude s'en sert pour orienter ses choix, alors soyez précis.
- Validez les entrées des outils dans votre code. Une forme valide ne signifie pas une valeur sûre. Claude propose, votre application exécute.
- Montez en échelle de façon réfléchie. Utilisez l'API Messages brute pour un échange sur mesure, MCP pour des outils réutilisables entre applications, et l'Agent SDK quand vous voulez que la boucle soit gérée pour vous. Les trois utilisent le même protocole.
À faire, tiré de cette leçon
Ces actions sont compilées dans le plan d'action du rôle.
- Forcez un schéma de tool quand vous avez besoin d'un JSON parsé garanti