Atelier

Lección 1 — Comprendre le function calling

Le cycle du function calling et les déclarations

5 min de lectura

Este contenido aún no está traducido. Se muestra la versión original.

Le cycle du function calling et les déclarations

Le modèle n'exécute rien

Premier point, le plus important : le modèle n'appelle jamais votre API. Il renvoie une intention structurée (« j'aimerais appeler consulter_solde avec {"employe_id": "E001"} »). C'est votre code qui décide de l'exécuter, l'exécute, puis renvoie le résultat au modèle.

sequenceDiagram
  participant U as Utilisateur
  participant A as Votre code
  participant G as Gemini
  participant API as API RH
  U->>A: "Combien de congés me reste-t-il ?"
  A->>G: question + déclarations des outils
  G-->>A: function_call consulter_solde(employe_id="E001")
  A->>API: GET /employes/E001/soldes
  API-->>A: {"conges_payes": 18, "rtt": 4}
  A->>G: function_response (le résultat)
  G-->>A: "Il vous reste 18 jours de congés payés et 4 RTT."
  A-->>U: réponse finale

Deux allers-retours avec le modèle pour une seule question : c'est normal, et c'est ce qui coûte (en latence et en jetons). Un jeton (token) est un morceau de mot, l'unité de facturation des LLM.

Ce que voit le modèle : la déclaration

Le modèle ne lit pas votre code Python. Il lit une déclaration de fonction (FunctionDeclaration) : un nom, une description et un schéma JSON des paramètres. JSON Schema est un format standard pour décrire la forme d'un objet JSON (types, champs obligatoires, valeurs permises).

files/outils_rh.py (extrait)
from google.genai import types

types.FunctionDeclaration(
    name="consulter_solde",
    description="Donne le solde de congés payés et de RTT (en jours) d'un employé.",
    parameters_json_schema={
        "type": "object",
        "properties": {"employe_id": {"type": "string", "description": "Ex. E001"}},
        "required": ["employe_id"]}),

types.FunctionDeclaration(
    name="chercher_employe",
    description="Cherche un employé dans l'annuaire par son nom ou une partie du nom. "
                "Renvoie son identifiant (ex. E002). À appeler AVANT tout autre outil "
                "quand l'utilisateur donne un nom au lieu d'un identifiant.",
    parameters_json_schema={
        "type": "object",
        "properties": {"nom": {"type": "string", "description": "Ex. « Benali »"}},
        "required": ["nom"]}),

Les cinq déclarations complètes sont dans outils_rh.py.

ChampRôle pour le modèleBonne pratique
nameidentifiant renvoyé dans function_callverbe + objet en snake_case : consulter_solde
descriptionle prompt de l'outil : quand et pourquoi l'appelerdire l'ordre d'appel, donner un exemple de valeur
propertiesles paramètres et leur typeenum pour une liste fermée (["conges_payes", "rtt"])
requiredles paramètres sans lesquels l'appel n'a pas de senstout ce que la fonction exige

Deux façons d'écrire une déclaration

Le SDK google-genai peut aussi déduire la déclaration d'une fonction Python typée et documentée :

files/auto.py (extrait)
def consulter_solde(employe_id: str) -> dict:
    """Donne le solde de congés payés et de RTT (en jours) d'un employé, ex. E001."""
    return outils_rh.consulter_solde(UTILISATEUR, employe_id)

types.FunctionDeclaration.from_callable(client=client, callable=consulter_solde) produit alors la même chose que le schéma écrit à la main (sortie réelle plus bas). La signature donne les types, la docstring donne la description.

Schéma écrit à la mainDéduit d'une fonction Python
Contrôle fin (enum, descriptions par paramètre)ouilimité
Une seule source de vériténon : schéma et code à garder alignésoui
Lisible dans une revue de codetrèsoui
Utilisé dans ce lab pourla boucle manuellele mode automatique

Lors d'un function calling, qui envoie la requête HTTP à l'API RH ?

Quel champ de la déclaration influence le plus le moment où le modèle choisit un outil ?

Exercice : déclarer lister_demandes

Écrivez la déclaration de l'outil lister_demandes, qui liste les demandes de congés d'un employé avec leur statut. Ajoutez une indication qui évite au modèle de l'appeler avec un nom de personne.

Voir la solution 
types.FunctionDeclaration(
    name="lister_demandes",
    description="Liste les demandes de congés d'un employé, avec leur statut "
                "(en_attente, annulee). Si l'utilisateur donne un nom, "
                "appelle d'abord chercher_employe pour obtenir l'identifiant.",
    parameters_json_schema={
        "type": "object",
        "properties": {"employe_id": {"type": "string",
                                      "description": "Identifiant, ex. E001"}},
        "required": ["employe_id"]})

La description renvoie vers chercher_employe et l'exemple E001 fixe le format attendu. La version du lab est plus courte car l'instruction système répète déjà la règle « nom → chercher_employe ».

Résultat obtenu

Déclaration déduite par le SDK à partir de auto.consulter_solde (exécuté le 2026-10-15, sans appel réseau) :

{
 "description": "Donne le solde de congés payés et de RTT (en jours) d'un employé, ex. E001.",
 "name": "consulter_solde",
 "parameters": {
  "properties": {"employe_id": {"type": "STRING"}},
  "required": ["employe_id"],
  "type": "OBJECT"
 }
}

Et le cycle complet avec le vrai modèle (python e2e.py, scénario 1, gemini-3.5-flash) :

[E001] Combien de jours de congés me reste-t-il ?   (mode AUTO)
  [tour 1] 1 appel(s) : consulter_solde({"employe_id": "E001"})
  → Il vous reste **18 jours** de congés payés et **4 jours** de RTT.

Le modèle a deviné seul que « me » désignait E001, parce que l'instruction système lui donne l'identifiant de la session.

Je sais faire

  • Expliquer pourquoi le modèle n'exécute jamais lui-même une fonction
  • Écrire une FunctionDeclaration avec parameters_json_schema
  • Rédiger une description qui dit quand appeler l'outil
  • Choisir entre schéma écrit à la main et schéma déduit d'une fonction Python
Siguiente