Batch tool use

Quand plusieurs opérations sont indépendantes, Claude peut les demander toutes dans une même réponse : plusieurs blocs toolUse à la fois, au lieu d’un aller-retour par outil. Cette leçon montre comment en profiter, et présente l’« outil batch » du cours officiel, qui pousse le modèle à regrouper ses appels.

Des appels en parallèle

Demandez « Quelle date tombe 50 jours après le 12 mars 2027 ? Et 100 jours après ? » : les deux calculs ne dépendent pas l’un de l’autre. Claude peut donc renvoyer deux blocs toolUse dans la même réponse. La documentation d’Anthropic indique que les modèles Claude 4 et suivants font d’eux-mêmes ces appels parallèles quand la demande s’y prête. Le cours officiel observe toutefois que le modèle ne regroupe pas toujours autant qu’on le voudrait, et enchaîne parfois les appels un par un.

Deux règles pour que le parallélisme fonctionne :

• votre run_tools traite déjà une liste de demandes : il exécute tous les blocs toolUse d’une réponse ;
• tous les résultats repartent dans un seul message user. D’après la documentation d’Anthropic, envoyer un message par résultat apprend à Claude à éviter les appels parallèles dans la suite de la conversation.

L’outil batch

L’astuce du cours officiel : un outil supplémentaire dont l’argument est une liste d’appels à d’autres outils. Claude peut alors grouper ses calculs dans un seul appel.

batch_tool_schema = {
    "toolSpec": {
        "name": "batch_tool",
        "description": (
            "Exécute plusieurs autres outils en un seul appel. "
            "Utilise-le quand plusieurs opérations indépendantes peuvent être faites en même temps. "
            "Renvoie la liste des résultats, dans l'ordre des appels."
        ),
        "inputSchema": {
            "json": {
                "type": "object",
                "properties": {
                    "invocations": {
                        "type": "array",
                        "description": "Les appels d'outils à exécuter.",
                        "items": {
                            "type": "object",
                            "properties": {
                                "name": {"type": "string", "description": "Nom de l'outil à appeler."},
                                "arguments": {
                                    "type": "string",
                                    "description": "Arguments de l'outil, encodés en chaîne JSON.",
                                },
                            },
                            "required": ["name", "arguments"],
                            "additionalProperties": False,
                        },
                    }
                },
                "required": ["invocations"],
                "additionalProperties": False,
            }
        },
    }
}

Chaque appel contient le nom d’un outil et ses arguments, encodés en chaîne JSON. La fonction qui l’exécute réutilise run_tool :

import json


def run_batch(invocations):
    results = []
    for invocation in invocations:
        name = invocation["name"]
        try:
            if name == "batch_tool":
                raise ValueError("un batch ne peut pas contenir de batch")
            output = run_tool(name, json.loads(invocation["arguments"]))
        except Exception as e:
            output = f"Erreur : {e}"
        results.append({"tool_name": name, "output": output})
    return results


TOOLS["batch_tool"] = run_batch

Le cours officiel ajoute une branche spéciale dans run_tool, car l’outil reçoit un dictionnaire {"invocations": [...]}. Avec notre aiguillage, nommer le paramètre invocations suffit : **tool_input le passe directement. Chaque appel du lot a sa propre gestion d’erreur : un calcul raté n’annule pas les autres.

tools = [get_current_datetime_schema, add_duration_to_datetime_schema, set_reminder_schema, batch_tool_schema]

messages = []
add_user_message(messages, "Quelle date tombe 50 jours après le 12 mars 2027 ? Et 100 jours après ?")
run_conversation(messages, tools)

Dans l’historique, vous verrez alors un seul appel à batch_tool qui contient les deux calculs, au lieu de deux appels successifs.

Ce que le parallélisme ne fait pas

Des appels dépendants restent séquentiels. Pour un rappel « dans 100 jours », Claude doit connaître la date du jour avant de demander le calcul : ni l’outil batch ni les appels parallèles ne peuvent regrouper ces deux étapes. Le parallélisme sert aux opérations indépendantes.

À vous de jouer

Mesurer le gain. Posez une demande qui contient trois calculs de dates indépendants, d’abord sans batch_tool, puis avec. Comptez les appels à Claude et les blocs toolUse de chaque réponse : l’outil batch change-t-il quelque chose avec Haiku 5.5 ?

Sources officielles : Batch tool use (Claude Academy) · Parallel tool use (documentation Claude)

Points clés à retenir

• Des opérations indépendantes peuvent être demandées dans une même réponse, en plusieurs blocs toolUse.
• Tous les résultats repartent dans un seul message user, sinon le parallélisme recule.
• L’outil batch regroupe plusieurs appels dans un seul, quand le modèle ne le fait pas de lui-même.
• Chaque appel du lot a sa propre gestion d’erreur.
• Des appels dépendants restent séquentiels : c’est l’affaire de la boucle.