Les fonctions d'outils

Une fonction d’outil est une fonction ordinaire de votre code, que votre application exécute quand Claude en fait la demande. Cette leçon écrit la première du projet, get_current_datetime, et pose les règles qui valent pour toutes les suivantes.

Trois règles pour une fonction d’outil

1. Des noms parlants. Le nom de la fonction et ceux de ses paramètres disent ce qu’ils font : get_current_datetime(date_format) plutôt que gcd(f).
2. Des entrées validées. Vérifiez qu’un paramètre requis n’est ni vide ni invalide, et levez une erreur sinon.
3. Des messages d’erreur instructifs. Claude lit le message d’erreur que vous lui renvoyez. « date_format ne peut pas être vide » lui permet de corriger son appel ; « échec » ne lui apprend rien.

La documentation ajoute deux conseils sur ce que la fonction renvoie : peu d’informations, mais utiles, et des identifiants stables et lisibles plutôt que des références internes opaques. Tout ce que la fonction renvoie entre dans le contexte de Claude.

La première fonction du projet

from datetime import datetime

def get_current_datetime(date_format="%Y-%m-%d %H:%M:%S"):
    if not date_format:
        raise ValueError("date_format ne peut pas être vide")
    return datetime.now().strftime(date_format)

La fonction lit l’heure de la machine et la met en forme avec les codes de strftime. Le format par défaut donne l’année, le mois et le jour, puis l’heure, les minutes et les secondes.

get_current_datetime()          # par exemple "2026-11-05 14:30:25"
get_current_datetime("%H:%M")   # par exemple "14:30"

La vérification du format servira rarement ici. Elle illustre le réflexe à prendre : valider chaque entrée et lever une erreur explicite. La boucle de la leçon 28 transmettra ce message à Claude, qui pourra corriger son appel.

Une précision sur l’heure

datetime.now() renvoie l’heure locale du serveur, sans fuseau horaire. Si vos utilisateurs vivent dans d’autres fuseaux que votre serveur, renvoyez une heure qui porte son fuseau, par exemple datetime.now(ZoneInfo("Europe/Paris")) avec le module zoneinfo de la bibliothèque standard, et précisez-le dans la description de l’outil.

La suite

Une fonction seule ne suffit pas : Claude ne voit jamais votre code. Il ne connaît l’outil que par son schéma, que la leçon suivante écrit.

À vous de jouer

Une fonction d’âge. Écrivez une fonction d’outil qui calcule l’âge d’une personne à partir de sa date de naissance, puis relisez-la avec les trois règles.

from datetime import date, datetime

def calculate_age(birth_date, date_format="%Y-%m-%d"):
    if not birth_date:
        raise ValueError("birth_date ne peut pas être vide, format attendu : AAAA-MM-JJ")
    born = datetime.strptime(birth_date, date_format).date()
    today = date.today()
    if born > today:
        raise ValueError(f"birth_date est dans le futur : {birth_date}")
    return today.year - born.year - ((today.month, today.day) < (born.month, born.day))

Sources officielles : Tool functions (Claude Academy) · Define tools (documentation Claude : bonnes pratiques) · Handle tool calls (messages d’erreur instructifs)

Points clés à retenir

• Une fonction d’outil est une fonction ordinaire, exécutée par votre application à la demande de Claude.
• Noms parlants, entrées validées, messages d’erreur qui disent quoi corriger.
• Renvoyez peu d’informations, mais utiles : tout ce qui est renvoyé occupe le contexte de Claude.
• Claude ne voit jamais votre code : il ne connaît l’outil que par son schéma.