Exécuter les fonctions outils

Claude a demandé un outil : à votre serveur de l’exécuter et de préparer le résultat. Cette étape consiste à extraire les blocs toolUse de la réponse, à lancer les fonctions demandées et à mettre leurs sorties au bon format.

Plusieurs demandes à la fois

Une même réponse peut contenir plusieurs blocs toolUse : un texte suivi d’une, deux demandes ou davantage. Si Claude veut calculer deux échéances indépendantes, il peut les demander ensemble. Votre code doit donc toujours traiter une liste de demandes, jamais une seule.

Aiguiller vers la bonne fonction

TOOLS = {
    "get_current_datetime": get_current_datetime,
}


def run_tool(tool_name, tool_input):
    if tool_name not in TOOLS:
        raise ValueError(f"Outil inconnu : {tool_name}")
    return TOOLS[tool_name](**tool_input)

Claude fournit toujours les arguments sous forme de dictionnaire : **tool_input les déplie en arguments nommés de la fonction. Le cours officiel aiguille par une suite de if et elif ; un dictionnaire fait le même travail et grandit d’une ligne par outil.

Le bloc `toolResult`

D'après la leçon « Running tool functions » (Claude Academy, Claude with Amazon Bedrock).

Chaque résultat repart dans un bloc toolResult à trois champs :

toolUseId : l’identifiant de la demande, recopié tel quel ;
content : la sortie de l’outil, ici sérialisée en texte JSON ;
status : success ou error.

L’identifiant fait le lien entre demande et résultat. Si Claude demande deux fois la même calculatrice, ses deux demandes portent deux identifiants différents, et vos deux résultats doivent reprendre chacun le bon.

Les erreurs font partie du dialogue

Entourez l’exécution d’un try : une erreur renvoyée proprement permet à Claude de corriger son appel ou de changer d’approche.

import json


def run_tools(parts):
    tool_result_parts = []
    for part in parts:
        if "toolUse" not in part:
            continue
        tool_use = part["toolUse"]
        try:
            output = run_tool(tool_use["name"], tool_use["input"])
            result = {
                "toolUseId": tool_use["toolUseId"],
                "content": [{"text": json.dumps(output, ensure_ascii=False)}],
                "status": "success",
            }
        except Exception as e:
            result = {
                "toolUseId": tool_use["toolUseId"],
                "content": [{"text": f"Erreur : {e}"}],
                "status": "error",
            }
        tool_result_parts.append({"toolResult": result})
    return tool_result_parts

La boucle ignore les blocs de texte et de réflexion, exécute chaque demande et renvoie la liste des blocs toolResult, un par demande. Le message d’erreur est rédigé pour Claude : c’est lui qui le lira.

L’API Converse accepte aussi un bloc {"json": ...} dans content, qui transporte directement un objet. Le texte JSON du cours officiel convient à tous les cas, y compris une simple chaîne comme l’heure renvoyée par get_current_datetime.

À vous de jouer

Tester sans Claude. Fabriquez à la main une liste parts qui contient deux blocs toolUse : un appel valide à get_current_datetime et un appel à un outil qui n’existe pas. Passez-la à run_tools et vérifiez que vous obtenez un résultat success et un résultat error, chacun avec le bon identifiant.

Sources officielles : Running tool functions (Claude Academy) · Use a tool to complete an Amazon Bedrock model response et API Converse (documentation AWS)

Points clés à retenir