L'outil batch

L’API autorise Claude à inclure plusieurs blocs tool_use dans un même message — nous l’avons vu dans la boucle multi-tours. Mais en pratique, le modèle n’exploite pas toujours cette possibilité : face à deux opérations liées, il a tendance à demander la première, attendre le résultat, puis demander la seconde. Chaque aller-retour ajoute une requête API complète, avec sa latence et son coût en tokens (tout l’historique est renvoyé à chaque tour). L’outil batch est une astuce de conception qui reprend le contrôle sur ce comportement.

Le problème

Prenez un cas concret : l’utilisateur demande de programmer deux rappels pour la même date. Le déroulé typique sans batch : Claude appelle add_reminder pour le premier rappel, votre code l’exécute et renvoie le résultat, Claude appelle alors add_reminder pour le second, nouvel aller-retour, puis il formule enfin sa réponse. Trois requêtes API pour une tâche qui n’en méritait qu’une — et le phénomène s’aggrave avec le nombre d’opérations : dix rappels, onze allers-retours.

L’idée du batch tool est élégante : puisque Claude choisit ses outils d’après leurs descriptions, offrons-lui un outil dont la fonction est précisément « exécuter plusieurs appels d’outils simultanément ». Le regroupement devient alors une option visible que le modèle apprend à saisir.

Le schéma de l’outil batch

batch_tool_schema = {
    "name": "batch_tool",
    "description": "Exécute plusieurs appels d'outils simultanement",
    "input_schema": {
        "type": "object",
        "properties": {
            "invocations": {
                "type": "array",
                "description": "Les appels d'outils a exécuter",
                "items": {
                    "type": "object",
                    "properties": {
                        "name": {
                            "type": "string",
                            "description": "Nom de l'outil a invoquer"
                        },
                        "arguments": {
                            "type": "object",
                            "description": "Arguments a passer a l'outil"
                        }
                    }
                }
            }
        }
    }
}

Regardez la structure : ce schéma ne décrit aucune opération métier. Il décrit un conteneur — un tableau d’invocations, chacune portant le nom d’un outil et ses arguments. C’est un outil d’ordre supérieur : un outil qui appelle des outils. Claude comprend cette abstraction sans difficulté, car du point de vue du modèle, remplir ce tableau n’est qu’une génération JSON comme une autre.

Traitement des appels batch

def run_batch(invocations=[]):
    batch_output = []
    for invocation in invocations:
        name = invocation["name"]
        args = json.loads(invocation["arguments"])
        tool_output = run_tool(name, args)
        batch_output.append({
            "tool_name": name,
            "output": tool_output
        })
    return batch_output

Côté implémentation, run_batch réutilise le routage run_tool construit dans la leçon sur les tours multiples : chaque invocation du tableau est déballée puis dirigée vers la vraie fonction, et les sorties s’accumulent avec le nom de l’outil qui les a produites — ce marquage permet à Claude de savoir quel résultat correspond à quelle opération. Il ne reste qu’à enregistrer batch_tool dans votre routeur comme n’importe quel autre outil : la boucle de conversation ne change pas d’une ligne.

Notez que « simultanément » est ici du point de vue de la conversation, pas du processeur : les invocations s’exécutent en séquence dans la boucle Python. Si vos outils font des appels réseau lents, vous pouvez paralléliser réellement l’intérieur de run_batch — mais le gain principal est déjà acquis : tout tient dans un seul tour de conversation.

Le résultat se mesure immédiatement : une requête utilisateur, une réponse de Claude contenant le batch, un seul renvoi avec tous les résultats, et la réponse finale. Là où dix rappels coûtaient onze allers-retours, il n’y en a plus que deux — moins de latence pour l’utilisateur, moins de tokens facturés pour vous.

Points clés à retenir

• Sans incitation, Claude tend à appeler ses outils un par un, multipliant les allers-retours API
• Le batch tool est un outil « conteneur » : son schéma accepte un tableau d’invocations {nom, arguments}
• run_batch déballe chaque invocation vers le routage run_tool existant — la boucle de conversation ne change pas
• Chaque sortie est marquée du nom de son outil pour que Claude apparie opérations et résultats
• Bénéfice direct : un seul tour de conversation pour N opérations, donc moins de latence et moins de tokens