Gérer les blocs de messages

Dès que des outils entrent en jeu, la réponse de Claude change de forme. Ce n’est plus un simple bloc de texte, mais une liste de blocs de types différents, dont une demande d’appel d’outil. Cette leçon envoie la première requête avec un outil et apprend à lire ce qui revient.

Une requête avec des outils

On ajoute le paramètre tools, qui reçoit la liste des définitions écrites à la leçon précédente :

messages = [
    {"role": "user", "content": "Quelle heure est-il exactement ? Donne-la au format HH:MM:SS."}
]

response = client.messages.create(
    model=model,
    max_tokens=4096,
    messages=messages,
    tools=[get_current_datetime_schema],
)

print(response.stop_reason)       # "tool_use"
for block in response.content:
    print(block.type)              # par exemple : thinking, text, tool_use

stop_reason vaut "tool_use" : Claude s’est arrêté pour demander un outil, et attend son résultat.

Les blocs d’une réponse avec outil

• thinking : sur les modèles Claude 5, comme Sonnet 5.5 utilisé dans ce cours, la réflexion est active par défaut. La réponse peut donc commencer par un bloc de réflexion, dont le texte est masqué par défaut.
• text : souvent, une phrase pour l’utilisateur, du type « Je regarde l’heure pour vous ». Ce bloc est facultatif : Claude peut appeler l’outil sans rien dire.
• tool_use : la demande d’appel, avec quatre champs.

Une même réponse peut contenir plusieurs blocs tool_use, quand Claude a besoin de plusieurs outils à la fois (leçon 30).

Ne jamais compter sur la position d’un bloc

Le nombre et l’ordre des blocs varient d’une réponse à l’autre : un bloc de réflexion ou non, un texte d’introduction ou non, un ou plusieurs appels. Écrire response.content[1].input en supposant que le deuxième bloc est l’appel d’outil fonctionne un jour et casse le lendemain. On cherche toujours les blocs par leur type :

tool_uses = [block for block in response.content if block.type == "tool_use"]

Garder tous les blocs dans l’historique

L’API ne conserve rien entre deux requêtes : c’est votre code qui tient l’historique de la conversation. Avec les outils, on y ajoute la réponse de Claude entière, avec tous ses blocs :

messages.append({"role": "assistant", "content": response.content})

Ne garder que le texte serait une erreur à deux titres. Claude perdrait la trace de l’appel auquel répond le résultat que vous allez lui envoyer. Et l’API exige que les blocs de réflexion lui reviennent complets et inchangés quand vous renvoyez un résultat d’outil : un message reconstruit ou filtré provoque une erreur 400.

Le parcours complet

1. Envoyer le message de l’utilisateur avec les définitions d’outils.
2. Recevoir une réponse qui contient un ou plusieurs blocs tool_use.
3. Exécuter la fonction demandée avec les arguments reçus.
4. Renvoyer le résultat avec tout l’historique.
5. Recevoir la réponse finale de Claude.

Cette leçon a couvert les deux premières étapes ; la suivante couvre les trois autres.

À vous de jouer

Inspecter une réponse. Envoyez la requête ci-dessus, puis affichez chaque bloc avec print(block). Relancez-la trois fois et notez si la composition des blocs change. Posez ensuite une question qui ne demande pas l’heure, comme « Combien font 7 fois 8 ? », et observez le stop_reason et les blocs.

Sources officielles : Handling message blocks (Claude Academy) · Handle tool calls (documentation Claude) · Thinking in tool and multi-turn workflows (blocs de réflexion à renvoyer intacts)

Points clés à retenir

• Avec des outils, la réponse est une liste de blocs : thinking éventuel, text facultatif, un ou plusieurs tool_use.
• stop_reason vaut "tool_use" quand Claude attend le résultat d’un outil.
• Un bloc tool_use porte un id, un name et un input.
• Cherchez les blocs par leur type, jamais par leur position.
• Ajoutez la réponse entière à l’historique : les blocs de réflexion doivent revenir intacts.