Appels d'outils en parallèle

Quand plusieurs opérations sont indépendantes, Claude peut les demander toutes dans une même réponse : plusieurs blocs tool_use à la fois, au lieu d’un aller-retour par outil. Cette leçon montre comment exécuter ces appels, comment renvoyer leurs résultats pour que le parallélisme continue de fonctionner, et comment le désactiver quand il le faut.

Une leçon qui a changé

Les premières versions du cours officiel consacraient cette leçon à un « outil batch » : un outil supplémentaire dont l’argument était une liste d’appels à d’autres outils, pour pousser le modèle à regrouper ce qu’il faisait un par un. Cette astuce n’a plus de raison d’être. D’après la documentation, les modèles Claude 4 et suivants font d’eux-mêmes des appels parallèles quand la demande s’y prête, et le cours de l’Academy a retiré la leçon. Nous gardons sa place pour le mécanisme qui l’a remplacée.

Exécuter plusieurs appels

Demandez « Programme deux rappels pour le 27 juin 2050 : le dentiste à 9 h et le garage à 14 h » : Claude peut répondre par deux blocs tool_use pour set_reminder, dans le même message. L’API n’impose aucun ordre d’exécution. Vous pouvez lancer les appels en même temps ou les uns après les autres, dans l’ordre où ils arrivent. Le choix dépend des outils :

• des opérations indépendantes et en lecture seule, comme lire trois fichiers ou interroger deux services, gagnent à tourner en parallèle ;
• des opérations avec effets, état partagé ou ordre à respecter, comme écrire un fichier puis le relire, se font plutôt en séquence.

La fonction run_tools de la leçon 38 exécute déjà tous les appels, en séquence. Pour des outils qui attendent le réseau, on peut les lancer en même temps avec un pool de fils d’exécution :

import json
from concurrent.futures import ThreadPoolExecutor

def run_tools_parallel(message):
    tool_uses = [block for block in message.content if block.type == "tool_use"]

    def run_one(block):
        try:
            output = run_tool(block.name, block.input)
            content = output if isinstance(output, str) else json.dumps(output, ensure_ascii=False)
            return {"type": "tool_result", "tool_use_id": block.id, "content": content}
        except Exception as e:
            return {"type": "tool_result", "tool_use_id": block.id, "content": f"Erreur : {e}", "is_error": True}

    with ThreadPoolExecutor() as pool:
        return list(pool.map(run_one, tool_uses))

pool.map rend les résultats dans l’ordre des appels. Chaque résultat porte de toute façon son tool_use_id, qui le rattache à sa demande.

Tous les résultats dans un seul message

C’est la règle qui fait ou défait le parallélisme. Les résultats de tous les appels d’une réponse repartent ensemble, dans un seul message user, chacun avec son tool_use_id.

# Un seul message pour tous les résultats de la réponse
add_user_message(messages, run_tools_parallel(response))

Envoyer un message par résultat est l’erreur la plus courante. D’après la documentation, cette mise en forme « apprend » à Claude à éviter les appels parallèles dans la suite de la conversation.

Si vous décidez de ne pas exécuter un appel, par exemple parce que l’appel précédent de la série a échoué, renvoyez quand même son tool_result, avec is_error: True et une explication brève : « Non exécuté : l’écriture précédente a échoué. »

Encourager ou désactiver le parallélisme

Pour obtenir davantage d’appels parallèles, la documentation propose d’ajouter cette consigne au prompt système :

For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.

Claude Fable 5.1 fait moins d’appels parallèles que les modèles précédents dans les longues boucles d’agent ; la documentation lui consacre une consigne spécifique dans son guide de prompting.

À l’inverse, pour qu’il n’y ait jamais plus d’un appel par réponse, on désactive le parallélisme dans tool_choice. Ce n’est pas un paramètre de premier niveau de la requête :

response = client.messages.create(
    model=model,
    max_tokens=4096,
    messages=messages,
    tools=tool_schemas,
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
)

Avec auto, Claude appelle alors au plus un outil par réponse, et peut toujours répondre en texte sans outil. Le réglage se pose sur la requête qui produit les appels : le poser plus tard n’a aucun effet sur des appels déjà faits.

Ce que le parallélisme ne fait pas

Des appels dépendants restent séquentiels. Pour un rappel « dans 103 jours », Claude doit connaître la date du jour avant de demander le calcul : aucun réglage ne peut regrouper ces deux appels. Le parallélisme sert aux opérations indépendantes ; les chaînes de dépendances restent l’affaire de la boucle multi-tours.

À vous de jouer

Mesurer le parallélisme. Posez à l’assistant de rappels une demande qui contient trois rappels indépendants. Comptez les blocs tool_use de la première réponse. Relancez avec disable_parallel_tool_use, puis comparez le nombre de tours et la durée totale.

Sources officielles : Parallel tool use (documentation Claude) · Troubleshooting tool use (appels parallèles qui ne se déclenchent pas)

Points clés à retenir

• Les modèles Claude 4 et suivants demandent plusieurs outils à la fois quand les opérations sont indépendantes : l’ancien « outil batch » est inutile.
• L’ordre d’exécution vous appartient : en parallèle pour les lectures indépendantes, en séquence pour les effets et l’état partagé.
• Tous les résultats repartent dans un seul message user ; un message par résultat fait reculer le parallélisme.
• Un appel non exécuté reçoit quand même son tool_result, avec is_error.
• disable_parallel_tool_use se règle à l’intérieur de tool_choice.