+200 XP

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 API ou transmette un JSON propre au service suivant de votre pipeline. 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 Schema pour ses entrées.

Quand Claude estime qu'un outil serait utile, il arrê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

  1. Vous envoyez un message utilisateur accompagné de votre tableau tools.
  2. Claude répond avec stop_reason: "tool_use" et un bloc de contenu tool_use.
  3. Vous exécutez l'outil et renvoyez la réponse sous forme de tool_result.
  4. 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.

python
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 :

json
{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "get_weather",
  "input": {"location": "Paris"}
}

Trois champs comptent :

  • name vous indique quelle fonction exécuter.
  • input est déjà un objet analysé conforme à votre schéma, 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.

  1. Le tour assistant de Claude lui-même : l'intégralité de response.content, bloc tool_use compris.
  2. 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 temperature 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ée tool_use est garantie conforme à l'input_schema de cet outil.

Les deux reposent sur le décodage contraint. Le modèle ne peut pas émettre de tokens qui casseraient votre schéma, vous n'avez donc plus besoin de logique de relance en cas de JSON invalide.

python
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.

python
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 ?

CHOIX MULTIPLES

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.

CHOIX MULTIPLES

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 MCP 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. Traitez input comme 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_choice sur 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 sur auto, utilisez les JSON outputs ou répartissez le travail sur deux appels.
  • Les erreurs sont un signal, pas un échec. Renvoyer is_error: true avec 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 un tool_result avec le tool_use_id correspondant. 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_schema pour la réponse elle-même, ou "strict": true sur 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
Voir le plan d'action complet →