Gestion des blocs de messages

Quand on travaille avec la fonctionnalité d’outils de Claude, on rencontre un nouveau type de structure de réponse, différent des simples réponses textuelles vues précédemment. Au lieu de recevoir un seul bloc de texte, Claude peut maintenant renvoyer des messages multi-blocs contenant à la fois du texte et des informations d’utilisation d’outils.

Effectuer un appel API avec des outils

Pour permettre à Claude d’utiliser des outils, il faut inclure un paramètre tools dans l’appel API :

messages = []
messages.append({
    "role": "user",
    "content": "What is the exact time, formatted as HH:MM:SS?"
})

response = client.messages.create(
    model=model,
    max_tokens=1000,
    messages=messages,
    tools=[get_current_datetime_schema],  # Liste des schemas d'outils disponibles
)

Le paramètre tools prend une liste de schémas JSON décrivant les fonctions disponibles que Claude peut appeler.

Comprendre les messages multi-blocs

Quand Claude décide d’utiliser un outil, il renvoie un message assistant avec plusieurs blocs dans la liste content. C’est un changement significatif par rapport aux réponses texte seules.

Un message multi-blocs contient typiquement :

1. Bloc texte (TextBlock)

Du texte lisible expliquant ce que Claude est en train de faire, par exemple :

“Je peux vous aider à trouver l’heure actuelle. Laissez-moi chercher cette information.”

2. Bloc ToolUse

Des instructions pour votre code indiquant quel outil appeler et avec quels paramètres. Ce bloc inclut :

Gérer l’historique de conversation

Rappel important : Claude ne stocke pas l’historique de conversation — c’est à vous de le gérer manuellement. Quand on travaille avec des réponses d’outils, il faut préserver toute la structure du contenu, y compris tous les blocs.

Voici comment ajouter correctement un message assistant multi-blocs à votre historique :

# Ajouter la réponse COMPLETE (texte + tool_use) a l'historique
messages.append({
    "role": "assistant",
    "content": response.content  # Contient TOUS les blocs
})

Cela préserve à la fois le bloc texte et le bloc tool_use, ce qui est essentiel pour maintenir le contexte de la conversation lors des appels API suivants.

Flux complet d’utilisation d’outil

Le processus suit ce schéma :

1. Envoi du message utilisateur avec le schéma d’outil à Claude
2. Réception du message assistant avec bloc texte + bloc tool_use
3. Extraction des informations d’outil et exécution de la fonction réelle
4. Renvoi du résultat d’outil à Claude avec l’historique complet
5. Réception de la réponse finale de Claude

Chaque étape nécessite une gestion soigneuse de la structure des messages pour que Claude ait tout le contexte nécessaire.

Mise à jour des fonctions utilitaires

Si vous utilisez des fonctions utilitaires comme add_user_message() et add_assistant_message(), vous devrez les mettre à jour pour gérer le contenu multi-blocs. Les versions actuelles ne supportent probablement que des blocs de texte simples, mais elles doivent maintenant prendre en charge des structures de contenu plus complexes incluant des blocs tool_use.

Quiz : Testez votre compréhension

Question 1 : Quand Claude décide d’utiliser un outil, combien de blocs minimum contient typiquement sa réponse ?

Réponse : Deux blocs — un bloc texte et un bloc tool_use. Le bloc texte explique ce que Claude fait, et le bloc tool_use contient les instructions pour appeler la fonction.

Question 2 : Pourquoi faut-il passer response.content (et pas juste le texte) dans l’historique ?

Réponse : Parce que response.content contient tous les blocs (texte + tool_use). Si on ne garde que le texte, Claude perd le contexte de l’appel d’outil et ne peut pas traiter correctement le résultat qu’on lui renverra ensuite.

Question 3 : Le paramètre tools est-il obligatoire uniquement au premier appel ?

Réponse : Non, il faut le passer à chaque appel API, même quand on renvoie les résultats d’outil. Claude en a besoin pour comprendre les références aux outils dans l’historique de conversation.