Gemini · Function calling et sorties structurées
Donner à Gemini une fonction qu'il peut appeler le fait passer du statut de générateur de texte à celui d'outil capable de lire votre agenda, d'interroger votre APIAPIApplication Programming Interface : une interface standardisée qui permet aux applications de communiquer et d'échanger des données sans connaître leur fonctionnement interne respectif.Voir la définition complète → de tarification ou votre base de données. Récupérer un JSON propre permet à votre code d'exploiter le résultat sans bricolage à coups de regex. Ces deux capacités sont la colonne vertébrale de toute intégration sérieuse de Gemini, et leur fonctionnement interne est très différent.
Le function calling est une négociation, pas une exécution
Le changement de perspective le plus important : Gemini n'exécute jamais votre fonction. Il décide seulement *qu'une* fonction doit être appelée et *avec quels arguments*. C'est vous qui exécutez le code. Vous renvoyez le résultat. Gemini continue.
Cet aller-retour constitue la boucle d'appel d'outils :
- Vous envoyez un prompt accompagné d'une liste de *déclarations* de fonctions (nom, description, paramètres).
- Gemini répond soit par du texte classique, soit par une partie
functionCallcontenant la fonction choisie et ses arguments. - Votre code exécute réellement cette fonction.
- Vous renvoyez le résultat sous forme de
functionResponse. - Gemini utilise le résultat pour produire sa réponse finale (ou appeler une autre fonction).
Le modèle fait de la reconnaissance d'intention structurée. Votre rôle est de brancher l'exécution réelle et de continuer à réinjecter l'état dans la conversation.
Déclarer une fonction
Une déclaration de fonction est un schémamaUtiliser un logiciel pour automatiser les tâches et campagnes marketing répétitives, afin de personnaliser à grande échelle sur des canaux comme l'email, le web et le social.Voir la définition complète →. Gemini lit les champs description pour décider quand et comment l'appeler : traitez-les donc comme du prompt engineeringprompt engineeringLe prompt engineering consiste à concevoir et affiner des instructions textuelles pour guider les grands modèles de langage vers des réponses justes, pertinentes et fiables.Voir la définition complète →, pas comme de la documentation. Des descriptions vagues produisent des appels erronés.
from google import genai
from google.genai import types
client = genai.Client()
get_weather = types.FunctionDeclaration(
name="get_weather",
description="Get the current temperature for a city. Use only when the user asks about weather.",
parameters={
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name, e.g. 'Lisbon'"},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
},
"required": ["city"],
},
)
weather_tool = types.Tool(function_declarations=[get_weather])Cet exemple utilise le Google Gen AI SDK unifié, la bibliothèque Python actuellement recommandée. Le même SDK cible à la fois l'API Gemini (via des clés AI Studio) et Vertex AI en changeant simplement la configuration du client : vous écrivez la boucle une seule fois.
Faire tourner la boucle
Voici l'aller-retour complet avec un modèle Flash. Les identifiants de modèles changent tous les quelques mois : gardez le nom dans une seule constante et consultez la page des modèles pour connaître l'ID Flash en vigueur.
MODEL = "gemini-3-flash-preview" # remplacez par l'ID du modèle Flash actuel
def get_weather_impl(city, unit="celsius"):
return {"city": city, "temp": 19, "unit": unit} # le vrai appel API se fait ici
config = types.GenerateContentConfig(tools=[weather_tool])
contents = ["What's the weather in Lisbon right now?"]
resp = client.models.generate_content(model=MODEL, contents=contents, config=config)
if resp.function_calls:
call = resp.function_calls[0]
result = get_weather_impl(**call.args)
contents.append(resp.candidates[0].content) # l'appel du modèle, sans modification
contents.append(types.Content(role="user", parts=[
types.Part.from_function_response(name=call.name, response=result)
]))
final = client.models.generate_content(model=MODEL, contents=contents, config=config)
print(final.text) # « Il fait 19 °C à Lisbonne en ce moment. »Les lignes clés sont les deux appels contents.append. Vous réinjectez dans l'historique le tour du modèle lui-même, puis vous ajoutez le résultat. Sautez le premier append et Gemini perd la trace de ce qu'il a demandé.
Ajoutez ce tour tel quel. Les modèles Gemini 3 attachent une thought signature aux parties d'appel de fonction, un enregistrement chiffré du raisonnement du modèle, et l'API s'attend à la recevoir à nouveau dans la requête suivante. Ajouter resp.candidates[0].content sans modification s'en charge pour vous. Si vous reconstruisez la partie d'appel à la main à partir de son nom et de ses arguments, vous perdez la signature et la requête peut échouer à la validation.
Laisser Gemini appeler plusieurs fonctions
Fournissez-lui plusieurs déclarations et Gemini choisit la bonne, ou en demande plusieurs. On parle de parallel function calling lorsqu'une seule réponse contient plusieurs parties functionCall (« compare la météo à Lisbonne et à Madrid » produit deux appels simultanés). Parcourez resp.function_calls, exécutez chaque appel et ajoutez toutes les réponses ensemble avant le tour suivant.
Vous pouvez aussi contraindre le comportement avec tool_config. Régler le mode de function calling sur ANY force Gemini à appeler une fonction plutôt qu'à répondre en texte libre, ce qui est utile quand un appel d'outil est le seul résultat acceptable :
config = types.GenerateContentConfig(
tools=[weather_tool],
tool_config=types.ToolConfig(
function_calling_config=types.FunctionCallingConfig(mode="ANY")
),
)Les modes sont AUTO (par défaut, le modèle décide), ANY (doit appeler quelque chose) et NONE (n'appelle jamais). Utilisez ANY avec une liste allowed_function_names pour cantonner le modèle à un sous-ensemble précis.
Sorties structurées : quand vous voulez des données, pas un outil
Le function calling sert à *agir*. La sortie structurée sert à *extraire*. Si vous voulez simplement que Gemini renvoie un JSON propre et parsable, ne le simulez pas avec un outil. Utilisez la fonctionnalité de response schemaschemaUn schema est le plan formel qui définit comment les données sont structurées, nommées, typées et reliées entre elles au sein d'une base de données, d'un fichier ou d'un message.Voir la définition complète →, qui contraint le décodage du modèle pour que la sortie corresponde à votre schéma.
C'est le décodage contraint : au moment de la génération, Gemini ne peut produire que des tokenstokensUn token est l'unité de base de texte que traitent les modèles de langage : le plus souvent un fragment de mot, un mot entier ou un signe de ponctuation, plutôt qu'un simple caractère.Voir la définition complète → qui maintiennent la sortie valide par rapport à votre schéma. Vous n'espérez pas du JSON. Vous l'obtenez.
from pydantic import BaseModel
class Invoice(BaseModel):
vendor: str
total: float
currency: str
line_items: list[str]
resp = client.models.generate_content(
model=MODEL,
contents="Extract the invoice details from this email: ...",
config=types.GenerateContentConfig(
response_mime_type="application/json",
response_json_schema=Invoice.model_json_schema(),
),
)
invoice = Invoice.model_validate_json(resp.text)
print(invoice.total, invoice.currency)L'API Gemini accepte le JSON Schema standard via response_json_schema : le model_json_schema() d'un modèle Pydantic s'y branche directement, et vous validez le résultat en objets typés. Pas de prompt qui supplie de « renvoyer uniquement du JSON ». Pas de balises markdown parasites à retirer. Les clés de sortie reviennent dans l'ordre défini par votre schéma. Vous croiserez encore response_schema et propertyOrdering dans du code plus ancien : ils fonctionnent, mais c'est la voie JSON Schema qu'il faut utiliser pour les nouveaux projets.
Quand le schéma est dynamique
Si la structure est déterminée à l'exécution, passez un simple dictionnaire de schéma :
schema = {
"type": "object",
"properties": {
"sentiment": {"type": "string", "enum": ["positive", "neutral", "negative"]},
"topics": {"type": "array", "items": {"type": "string"}},
},
"required": ["sentiment", "topics"],
}Pour la classification, un enum sur un champ unique comme sentiment force la réponse à être exactement l'un de vos libellés, et rien d'autre. C'est la façon la plus propre de faire de la classification à libellé unique.
Choisir entre les deux
Les deux se recoupent, alors choisissez délibérément :
- La sortie structurée quand vous maîtrisez toute l'interaction et avez seulement besoin de données parsées à partir d'un appel. Plus rapide, plus simple, structure garantie.
- Le function calling quand Gemini doit aller *au-delà* de lui-même : données en temps réel, vos API, effets de bord, raisonnement en plusieurs étapes où chaque étape dépend de résultats réels.
Un pattern courant combine les deux : les appels de fonctions récupèrent les données réelles, et la réponse finale revient via un response schema pour que votre code en aval reste typé. Les modèles Gemini 3 acceptent des outils et un response schema dans la même requête, ce qui évite désormais un appel d'extraction séparé.
Ne recodez pas ce que la plateforme vous fournit
Certaines « fonctions » existent déjà sous forme d'outils intégrés. Le grounding avec Google Search, l'exécution de code et le contexte d'URL sont des outils natifs que vous activez dans la configuration au lieu de les implémenter vous-même. Si vous avez besoin de faits récents, activez le grounding Search plutôt que d'écrire votre propre fonction de recherche :
config = types.GenerateContentConfig(
tools=[
types.Tool(google_search=types.GoogleSearch()),
weather_tool,
]
)Sur les modèles Gemini 3, vous pouvez combiner les outils intégrés avec vos propres déclarations de fonctions, comme ci-dessus. Les modèles plus anciens et certaines configurations Vertex AI restreignent encore cette possibilité : vérifiez la documentation des outils pour le modèle que vous déployez.
Vérification des acquis
1. Quelle est la distinction conceptuelle la plus importante dans la façon dont Gemini gère le function calling ?
2. Pourquoi la leçon affirme-t-elle que les champs `description` d'une fonction doivent être traités comme du prompt engineering plutôt que comme de la documentation ?
3. Dans la boucle d'appel d'outils, que renvoie votre code à Gemini après avoir réellement exécuté la fonction choisie ?
4. Sélectionnez TOUTES les affirmations correctes sur la boucle d'appel d'outils et les déclarations de fonctions.
Sélectionnez toutes les réponses correctes.
5. Sélectionnez TOUTES les affirmations correctes sur les bénéfices et la conception du function calling et des sorties structurées décrits dans la leçon.
Sélectionnez toutes les réponses correctes.
Prototyper dans AI Studio, puis passer à l'échelle correctement
Avant d'écrire la moindre boucle, construisez la déclaration de fonction visuellement dans Google AI Studio. Vous pouvez y définir des outils, observer Gemini émettre des parties functionCall et copier du code fonctionnel dans votre langage. C'est le moyen le plus rapide d'affiner ces chaînes description.
Au passage en production, la question est de savoir *où* tourne la boucle :
- API Gemini (ai.google.dev) pour les backends applicatifs et les services rapides. Le code SDK ci-dessus suffit.
- Vertex AI quand vous avez besoin de contrôles entreprise : IAM, VPC, résidence des donnéesrésidence des donnéesL'exigence de stocker et traiter les données physiquement dans un pays ou une région précise, souvent pour des raisons légales ou contractuelles.Voir la définition complète → et déploiement managé. Même SDK, initialisation du client différente.
- Agent Development Kit (ADK) quand un modèle avec quelques outils devient un véritable agent avec planification, mémoire et de nombreux outils. ADK vous fournit la boucle, l'état et l'orchestration des outils sous forme de framework, et vous cessez d'écrire à la main la plomberie d'ajout des réponses. Voir la documentation ADK.
Pour l'automatisation interne dans Workspace, vous n'avez pas toujours besoin de tout cela. Apps Script peut appeler Gemini et agir directement sur Docs, Sheets ou Gmail, ce qui est souvent le chemin le plus court vers un outil fonctionnel dans Google Workspace.
Détails appris à la dure qui vous feront gagner des heures
Les descriptions sont des prompts. La précision de Gemini pour choisir et renseigner les fonctions suit de près la qualité de vos champs description et de la documentation des paramètres. Précisez *quand* utiliser une fonction et *quand ne pas* l'utiliser.
Validez chaque argument. Gemini remplit les arguments à partir d'un schéma, mais il peut quand même halluciner une valeur plausible mais fausse, en particulier pour des ID ou des enums dont il se souvient à moitié. Traitez les arguments de fonction comme une saisie utilisateur non fiable. Validez avant d'exécuter quoi que ce soit qui a des effets de bord.
Utilisez `required` et `enum` sans retenue. Chaque contrainte posée dans le schéma est une contrainte que le modèle doit respecter. Les enums éliminent des catégories entières de valeurs aberrantes. Les champs obligatoires empêchent les appels à moitié remplis.
Choisissez le niveau de modèle selon la tâche. Flash gère la plupart du routage d'outils et de l'extraction avec une latence et un coût faibles. Passez à Pro quand le choix de l'outil à appeler exige un vrai raisonnement sur un long contexte, ou quand l'extraction repose sur une logique subtile répartie sur plusieurs documents.
Réinjectez toujours les résultats des fonctions. Le bug le plus courant consiste à oublier d'ajouter l'appel de fonction du modèle lui-même avant la réponse. Sans lui, l'historique de conversation est incohérent, la réponse finale dérive, et sur Gemini 3 l'absence de thought signature peut faire échouer la requête.
Points clés
- Vous exécutez, Gemini décide. La boucle : déclarer les fonctions, recevoir un
functionCall, l'exécuter vous-même, ajouter à la fois le tour non modifié du modèle et votrefunctionResponse, puis générer la réponse finale. - Utilisez
response_json_schema(lemodel_json_schema()d'un modèle Pydantic fonctionne) pour obtenir un JSON conforme au schéma grâce au décodage contraint. ArrArrL'Annual Recurring Revenue (ARR) est le revenu normalisé et prévisible qu'une entreprise par abonnement attend de ses contrats actifs sur une année.Voir la définition complète →êtez de demander du JSON dans le prompt et de retirer des balises markdown. - Le function calling va chercher à l'extérieur du modèle des données en temps réel et des effets de bord ; la sortie structurée parse des données à partir d'un seul appel. Sur Gemini 3, vous pouvez utiliser les deux, plus des outils intégrés comme Search, dans une même requête.
- La précision des outils dépend surtout de la qualité du schéma : investissez dans les champs
description, les enums etrequired. - Prototypez dans AI Studio, puis passez à l'API Gemini, à Vertex AI ou à ADK selon l'échelle, les contrôles entreprise ou l'orchestration d'agents. Gardez les ID de modèles à un seul endroit et validez toujours les arguments de fonction avant d'agir.