Qu’est-ce que le Function Calling ? Comment OpenAI, Gemini et Claude appellent-ils des API et des outils externes via JSON ?

Vous voyez bien une demande de l’agent, mais aucune facture ne part, aucun fichier ne s’ouvre et aucune API n’est appelée.

La solution la plus rapide consiste à traiter le Function Calling comme un cycle contrôlé : le modèle produit une requête JSON conforme à un outil déclaré, votre application vérifie puis exécute l’action, et le résultat est renvoyé au modèle pour générer la réponse finale.

Cette méthode s’applique à OpenAI, Google Gemini et Claude API, mais leurs structures de messages, identifiants d’appel, règles de schéma et mécanismes d’état ne sont pas interchangeables.

Cette page s’adresse d’abord aux développeurs backend qui construisent leur premier assistant connecté à des outils, aux ingénieurs qui doivent faire fonctionner plusieurs modèles derrière une même application et aux responsables sécurité chargés de limiter les actions sensibles. Si votre agent doit interagir avec une base de données, un service audio, une chaîne vidéo, une boutique ou un environnement de développement, vous trouverez ici la séparation des responsabilités à mettre en place avant la mise en production.

Le Function Calling JSON API décrit une intention, pas une exécution

Le Function Calling relie un modèle de langage à une fonction que votre application sait déjà exécuter. Vous fournissez au modèle le nom de l’outil, sa description, ses paramètres et leur schéma. Le modèle analyse la demande et peut produire une structure indiquant, par exemple, qu’il souhaite appeler get_project_status avec un identifiant précis.

Il ne possède pas automatiquement le droit de se connecter à votre base de données. Il ne détient pas vos clés privées. Il ne décide pas seul si une commande peut être exécutée sur un serveur. Dans le modèle classique, il génère une intention structurée ; votre code reste responsable de l’exécution.

Le cycle général est donc le suivant :

Votre application déclare un ou plusieurs outils.
Le modèle reçoit la demande utilisateur et les définitions disponibles.
Le modèle renvoie un ou plusieurs appels structurés.
Votre exécuteur valide les arguments et lance l’opération.
Votre application renvoie le résultat au modèle.
Le modèle produit une réponse finale ou demande un autre outil.

La documentation officielle du Function Calling d’OpenAI formalise ce cycle en cinq grandes étapes, tandis que la documentation de Google sur le Function Calling distingue explicitement la déclaration, l’appel, l’exécution côté application et le retour du résultat.

Le modèle exécute-t-il directement une API ?

Non. Même lorsque la réponse contient un nom de fonction et des arguments JSON valides, c’est votre application qui doit trouver l’implémentation correspondante, effectuer l’authentification, gérer le réseau, appliquer les règles métier et renvoyer un résultat contrôlé. Une plateforme peut proposer des outils hébergés, mais cela ne transforme pas automatiquement une fonction personnalisée en appel libre à votre infrastructure.

Cette distinction est essentielle pour les outils créatifs. Un agent qui prépare un montage vidéo peut demander la durée d’un média ou proposer un rendu. Il ne devrait pas pouvoir supprimer une bibliothèque, publier une vidéo ou exposer un fichier simplement parce qu’un texte généré contient une commande plausible.

Première responsabilité : déclarer un outil compréhensible et vérifiable

L’équipe qui intègre le modèle doit commencer par un contrat d’outil limité. Une déclaration utile comporte généralement quatre éléments :

un nom stable ;
une description indiquant ce que fait l’outil et dans quel cas l’utiliser ;
un objet de paramètres ;
un schéma décrivant les types, propriétés et champs obligatoires.

Un outil comme search_orders doit préciser si la recherche accepte un identifiant client, une période, un statut ou une combinaison de filtres. Une description vague augmente le risque que le modèle choisisse cet outil au mauvais moment. Un schéma incomplet laisse passer des arguments que votre exécuteur ne sait pas interpréter.

Le schéma JSON ne sert donc pas uniquement à faciliter le décodage. Il constitue une première frontière entre langage naturel et données opérationnelles. Le site officiel JSON Schema rappelle qu’un schéma permet de décrire la structure et les contraintes d’un document JSON. Il faut toutefois retenir sa limite : un schéma peut vérifier qu’un champ est une chaîne ou qu’une valeur appartient à une liste, mais il ne sait pas si l’utilisateur possède réellement la ressource ciblée.

OpenAI propose un mode strict pour rapprocher les arguments générés du schéma fourni ; son guide officiel sur le Function Calling précise que strict: true vise une correspondance exacte avec le JSON Schema pris en charge. Google Gemini utilise des déclarations de fonction comportant notamment name, description et parameters. Claude API emploie une définition avec name, description et input_schema, comme l’illustre la documentation officielle Anthropic sur l’utilisation des outils.

Pourquoi le Function Calling a-t-il besoin de JSON Schema ?

Parce qu’un texte comme « recherchez les commandes récentes du client 284 » ne fournit pas une interface fiable à un programme. Le schéma transforme cette intention en objet contrôlable, par exemple avec un champ customer_id de type chaîne et un champ status limité à des valeurs connues.

Il ne faut cependant pas confondre conformité syntaxique et autorisation. Un argument peut être parfaitement conforme tout en ciblant le mauvais compte, une mauvaise organisation ou une ressource appartenant à un autre utilisateur.

OpenAI, Google Gemini et Claude : même boucle, contrats différents

Les trois plateformes partagent le même principe architectural, mais la représentation de l’appel varie. Il est donc dangereux de copier un exemple OpenAI dans une intégration Google Gemini ou Claude API en remplaçant seulement le nom du modèle.

Élément à comparer	OpenAI	Google Gemini	Claude API
Déclaration	Outils de type fonction avec paramètres JSON Schema	Function declarations avec nom, description et paramètres	Outils avec `name`, `description` et `input_schema`
Retour du modèle	Élément ou bloc d’appel contenant le nom et les arguments	Étape ou partie `function_call` contenant le nom et les arguments	Bloc `tool_use`, généralement associé à un identifiant
Exécution	Réalisée par votre application pour les fonctions personnalisées	Réalisée par votre application	Réalisée par votre application pour les outils clients
Retour du résultat	Élément de sortie d’outil associé à l’appel	`function_result` associé à l’identifiant d’appel	Bloc `tool_result` associé à `tool_use_id`
État de la conversation	Dépend de l’API choisie et de votre gestion d’historique	Peut utiliser un identifiant d’interaction ou un historique géré côté client	Repose sur la séquence correcte des messages et des blocs
Appels multiples	Possibles selon l’API et la configuration	Appels parallèles et appels composés documentés	Plusieurs blocs d’utilisation peuvent apparaître dans une réponse

Ce tableau sert à orienter l’architecture, pas à fabriquer un format commun. Votre adaptateur interne peut transformer ces sorties en événements tels que :

json

{
  "type": "tool_request",
  "provider": "google",
  "tool_name": "get_project_status",
  "call_id": "conserver-la-valeur-originale",
  "arguments": {
    "project_id": "p-284"
  },
  "raw_response": {}
}

Cet objet est un contrat interne, pas une requête à envoyer directement à l’un des fournisseurs. Vous devez conserver la réponse originale dans un champ séparé. Sinon, vous risquez de perdre un bloc de réflexion, une signature de pensée, un motif d’arrêt, une information de parallélisme ou une métadonnée nécessaire à la suite de la conversation.

Les formats JSON des trois modèles sont-ils identiques ?

Non. Le contenu conceptuel est proche, mais les noms de champs, la position des blocs, les identifiants et le retour du résultat diffèrent. Anthropic indique notamment que son API Messages intègre les blocs tool_use et tool_result directement dans les messages assistant et user. Google documente de son côté les étapes function_call et function_result, avec la possibilité de conserver un identifiant d’interaction ou de gérer tout l’historique côté client.

Une couche d’adaptation doit donc normaliser les événements utiles à votre application, sans prétendre effacer les particularités du fournisseur.

Attention : ne faites pas reposer votre contrat interne sur un seul champ tel que function.name. Certaines réponses peuvent contenir plusieurs appels, des blocs de texte, des résultats multimédias ou des états intermédiaires. Parcourez la réponse selon le type d’élément documenté par le fournisseur.

Deuxième responsabilité : exécuter l’outil hors du modèle

L’exécuteur est le composant qui transforme une intention JSON en opération réelle. Il doit être beaucoup plus strict qu’un simple dictionnaire nom_de_fonction → fonction.

Avant l’appel, il doit :

vérifier que le nom de l’outil figure dans une liste autorisée ;
parser les arguments JSON ;
valider le schéma avec une bibliothèque adaptée ;
appliquer les contrôles métier ;
vérifier l’identité, l’organisation et la propriété de la ressource ;
choisir un délai d’expiration ;
appliquer une limite de taille et de volume ;
attribuer un identifiant de traçage.

Pour un outil en lecture seule, comme récupérer les métadonnées d’un fichier audio, le risque est généralement limité. Pour un outil qui modifie un projet vidéo, déclenche un rendu payant ou publie un livrable, l’exécution doit être séparée de la simple décision du modèle.

L’authentification doit rester dans l’environnement d’exécution. Ne placez jamais une clé longue durée dans le prompt, dans un fichier que le modèle peut lire ou dans la description de l’outil. Le modèle n’a besoin de connaître que le résultat fonctionnel attendu : il n’a pas besoin de recevoir le secret qui permet d’obtenir ce résultat.

La gestion des erreurs doit également être structurée. Une réponse d’API en erreur ne doit pas être convertie en texte vague comme « cela n’a pas fonctionné ». Renvoyez au modèle un résultat qui distingue, par exemple, une validation impossible, une ressource absente, un délai dépassé et une erreur temporaire. Vous pourrez alors choisir entre demander une précision, retenter, changer d’outil ou arrêter la boucle.

Que faire si le modèle produit un argument incorrect ?

Refusez l’exécution et renvoyez une erreur contrôlée. Ne corrigez pas silencieusement un identifiant ou une quantité sensible. Pour une faute bénigne, votre application peut demander au modèle de reformuler l’appel avec les contraintes retournées par le validateur. Pour une opération d’écriture, une confirmation utilisateur ou une correction explicite est préférable.

Une stratégie robuste comporte trois niveaux :

erreur de syntaxe : le JSON ne se parse pas ;
erreur de contrat : le JSON est valide mais ne respecte pas le schéma ;
erreur métier : le schéma est correct, mais l’action est interdite ou impossible.

Ces niveaux doivent être visibles dans les journaux. Sinon, les équipes confondront un problème de modèle avec un problème d’API ou de permissions.

Troisième responsabilité : sécuriser les actions et les données

La sécurité doit traiter l’outil comme une capacité opérationnelle, et non comme une simple extension de prompt. Classez vos outils avant de les exposer :

lecture seule : consulter un état, une liste ou une métrique ;
écriture réversible : créer un brouillon, ajouter une étiquette, préparer un rendu ;
écriture sensible : modifier une facture, envoyer un courriel, publier un contenu ;
destruction ou réseau ouvert : supprimer une ressource, lancer une commande, appeler une destination non prévue.

Le choix automatique du modèle peut être acceptable pour la lecture. Il doit être encadré par une approbation, une politique ou un mode d’exécution limité pour les autres catégories.

Le schéma ne remplace ni l’autorisation de l’utilisateur, ni les règles métier, ni la vérification de propriété. Un champ project_id correctement typé ne prouve pas que la personne connectée peut modifier ce projet. Une URL conforme au format attendu ne prouve pas qu’elle est sûre. Une quantité positive ne prouve pas qu’elle respecte un plafond.

Vous devez également considérer les données retournées par les outils comme non fiables. Une base de connaissances, un commentaire client ou un fichier importé peut contenir du texte qui tente d’influencer la suite des instructions. La publication technique d’OpenAI sur le Function Calling signalait déjà le risque qu’une sortie d’outil contienne des instructions inattendues. Dans votre architecture, séparez donc les données métier des instructions de contrôle et appliquez un filtrage avant de les remettre au modèle.

Pour approfondir cette logique dans les systèmes d’agents, vous pouvez consulter notre guide consacré au cadre de travail des compétences Claude Code, notamment si vos outils pilotent des opérations de développement ou d’automatisation.

Quatrième responsabilité : tester la boucle complète, pas seulement le JSON

Une intégration qui réussit un exemple nominal n’est pas encore fiable. Les tests doivent couvrir le trajet complet entre le message utilisateur, l’appel du modèle, l’exécution et la réponse finale.

Commencez avec un seul cas métier identique pour OpenAI, Google Gemini et Claude API. Par exemple : consulter l’état d’un projet créatif à partir d’un identifiant. Ne comparez pas trois prompts différents. Vous ne sauriez plus si l’écart vient du modèle, du schéma ou de votre code.

Votre liste de contrôle devrait contenir les cas suivants :

[ ] aucun outil pertinent : le modèle répond sans appel ;
[ ] champ obligatoire absent : l’exécuteur refuse la requête ;
[ ] valeur hors énumération : la validation bloque l’opération ;
[ ] plusieurs appels indépendants : l’ordonnanceur décide s’ils peuvent être parallèles ;
[ ] appels dépendants : le second outil attend le résultat du premier ;
[ ] erreur réseau : le système applique un délai et une stratégie de reprise ;
[ ] résultat vide : le modèle reçoit une réponse explicite ;
[ ] historique incomplet : la boucle détecte les blocs manquants ;
[ ] identifiant d’appel inconnu : le résultat est rejeté ;
[ ] réponse finale incorrecte : la sortie utilisateur est contrôlée avant affichage.

Google documente les appels parallèles et les appels composés, tandis qu’Anthropic impose une correspondance précise entre un bloc tool_use et son bloc tool_result. Ces différences doivent apparaître dans vos tests d’adaptateur, pas être découvertes en production.

Conservez pour chaque scénario le fournisseur, le modèle, la version du SDK, l’interface utilisée, le schéma envoyé, la réponse originale, l’action exécutée et le résultat retourné. Les interfaces évoluent. Une comparaison valable doit pouvoir être rejouée avec les mêmes paramètres.

Pour les équipes qui construisent des chaînes de développement, le guide Hashvps sur les règles et compétences des flux de programmation assistée peut compléter cette approche par une séparation plus nette entre intention, outil et validation.

Choisir une intégration directe ou une couche d’adaptation

La décision dépend moins du nombre de modèles annoncé dans votre feuille de route que du nombre de fois où les mêmes outils seront réutilisés.

Choisissez l’intégration directe avec le SDK officiel si :

votre application utilise un seul fournisseur ;
les outils sont peu nombreux ;
vous acceptez de suivre directement son format d’événements ;
vous n’avez pas besoin de partager ces outils avec une autre équipe ;
la priorité est de valider rapidement un prototype.

Ajoutez une couche de contrat interne si :

plusieurs fournisseurs doivent servir le même produit ;
un même outil est partagé entre plusieurs agents ;
vous devez centraliser les autorisations, les journaux et les reprises ;
les réponses peuvent contenir des appels parallèles ou des étapes intermédiaires ;
vous voulez changer de modèle sans réécrire l’exécuteur.

Dans ce second cas, ne normalisez que ce qui est stable : type d’événement, nom logique de l’outil, arguments validés, identifiant de corrélation, état d’exécution et résultat. Gardez la charge originale afin de pouvoir diagnostiquer une différence de comportement.

Le protocole MCP peut ensuite devenir pertinent lorsque vous souhaitez standardiser la découverte et la connexion entre applications, modèles et serveurs d’outils. Il ne remplace pas votre politique d’autorisation. Il ajoute une couche de protocole. La documentation officielle du MCP publiée par Anthropic le présente comme un protocole destiné à standardiser la manière dont les applications fournissent du contexte aux modèles.

Si votre projet est encore un prototype mono-modèle, utilisez d’abord le SDK officiel. Sinon, si les mêmes outils doivent survivre à un changement de fournisseur, construisez dès maintenant un adaptateur minimal et conservez les réponses originales.

Cette approche évite deux excès : créer une abstraction complexe avant d’avoir compris le cycle réel, ou laisser des formats propriétaires se répandre dans toute votre logique métier.

Quand un nœud Mac distant devient une décision d’architecture

La plupart des outils HTTP, bases de données et services de traitement peuvent être exécutés dans votre environnement backend habituel. La situation change lorsque l’agent doit piloter macOS, Xcode, la signature d’applications, des tests iOS, une automatisation Apple ou un logiciel audio et vidéo disponible uniquement sur Mac.

Dans ce cas, le Function Calling ne doit pas donner au modèle un accès direct au système. Créez un outil métier limité, tel que start_ios_build, inspect_testflight_artifact ou render_video_preview. L’exécuteur distant vérifie le projet, l’utilisateur, la branche, le délai et les permissions avant de lancer l’action. Le résultat revient sous forme d’état, de journal filtré et d’artefact identifié.

Pour un besoin ponctuel de test ou de validation, louer un environnement Mac auprès de Hashvps peut être plus cohérent que maintenir une machine dédiée inutilisée entre deux campagnes. Cette option reste moins adaptée si vous avez besoin d’une charge lourde permanente, d’interfaces physiques spécifiques ou d’un contrôle matériel continu. Dans ces cas, un Mac acheté et administré en interne peut conserver un avantage opérationnel.

L’intérêt du nœud distant apparaît surtout lorsque la durée de la tâche varie, que plusieurs équipes partagent l’environnement ou que vous devez isoler les exécutions. Votre agent garde alors une interface d’outil stable, tandis que l’infrastructure d’exécution peut évoluer séparément.

Si vous comparez déjà un poste local et une infrastructure distante pour des flux d’IA, notre analyse sur le choix entre poste haut de gamme local et cloud fournit un cadre complémentaire : coût de possession, accès partagé, persistance et contraintes d’environnement.

Le point à retenir est simple : le modèle décide éventuellement quoi demander, l’adaptateur décide comment traduire la demande, l’exécuteur décide si l’action est techniquement possible, et l’équipe sécurité décide si elle est autorisée. Tant que ces responsabilités restent séparées, OpenAI, Google Gemini et Claude API peuvent alimenter la même application sans transformer votre backend en assemblage fragile de formats JSON propriétaires.