Gemini API Tool Retrieval : tool_search, defer_loading et facturation

Activez Tool Retrieval en aperçu sur l'API Gemini Interactions (v1beta) grâce à tool_search et defer_loading. Comparez les modes serveur et client, vérifiez les quatre modèles documentés face au blog Google, gérez les serveurs MCP distants et le mode sans état, corrigez les erreurs 400 et évaluez la facturation en jetons ainsi que le cache de préfixe implicite.

Sommaire
Gemini API Tool Retrieval : tool_search, defer_loading et facturation

Tool Retrieval est désormais disponible en aperçu dans l’API Gemini Interactions (v1beta) et permet aux agents de charger les schémas de paramètres d’outils à la demande via tool_search et defer_loading. Cette nouveauté concerne les développeurs qui connectent des dizaines de fonctions personnalisées ou de serveurs MCP distants à Gemini, et elle fonctionne uniquement sur l’API Interactions (pas sur generateContent). Au 2026-11-20, pour la tester, appelez v1beta/interactions avec l’un des quatre modèles documentés (gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash ou gemini-3.6-flash), ajoutez {"type": "tool_search"} et définissez defer_loading: true sur les outils hors de votre socle principal.

Choisir d’abord le bon point d’accès API

Google a annoncé Tool Retrieval le 19 novembre 2026 sur le blog Google et a publié la procédure d’intégration dans la documentation Tool retrieval d’AI Studio. Comme la fonctionnalité dépend de l’aperçu de l’API Interactions (v1beta), votre point de terminaison actuel détermine si vous pouvez l’adopter immédiatement.

OptionCompte et régionUnité de facturationPrise en charge de Tool RetrievalQuand la choisir
API officielle Gemini Interactions (v1beta)Clé API Google AI Studio dans une région prise en charge ; niveau payant (Paid Tier) requis pour gemini-4-argonPar 1M de jetons d’entrée, en cache et de sortie (niveau gratuit Standard Free Tier disponible pour gemini-4-hydrogen, gemini-3.8-flash et gemini-3.6-flash)Prise en charge en aperçu (tool_search, defer_loading, mcp_server distant)Vous gérez un vaste catalogue d’outils et pouvez appeler v1beta/interactions directement
API officielle Gemini generateContentMême compte Google AI Studio et région prise en chargePar 1M de jetons d’entrée, en cache et de sortieNon prise en chargeVous avez moins de ~20 outils stables, avez besoin du cache explicite sur les modèles Gemini 3 ou 2.5 compatibles, ou ne pouvez pas encore migrer
Passerelle API à l’usage (comme BetterToken)Compte BetterToken et clé API créée dans la consoleSolde prépayé à l’usage facturé selon l’unité courante de chaque modèleL’API Interactions n’est pas documentée ; la prise en charge de Tool Retrieval n’est pas vérifiéeVous conservez les points de terminaison documentés Gemini generateContent natif ou Chat Completions compatible OpenAI sur plusieurs modèles (vérifiez la prise en charge des outils par modèle dans la documentation BetterToken)

Si vous restez sur l’API standard Gemini generateContent ou sur Chat Completions compatible OpenAI au lieu de migrer vers l’API Interactions, vous pouvez consulter la référence API Gemini de BetterToken pour vérifier les points de terminaison documentés, les identifiants de modèles et la prise en charge des outils par modèle.

Modèles pris en charge et erreur 400 sur Gemini 4

L’article de blog Google du 19 novembre 2026 indique que Tool Retrieval fonctionne avec Gemini 3.6 et les versions ultérieures, y compris tous les modèles Gemini 4, avec un lien vers la page Latest Gemini models. Cette page répertorie quatre modèles Gemini 4 : gemini-4-carbon, gemini-4-neon, gemini-4-hydrogen et gemini-4-argon.

Pourtant, au 2026-11-20, la liste officielle des modèles compatibles avec Tool retrieval ne mentionne que quatre identifiants de modèles :

  • gemini-4-hydrogen
  • gemini-4-argon
  • gemini-3.8-flash
  • gemini-3.6-flash

gemini-4-carbon et gemini-4-neon ne figurent pas sur la page de documentation Tool Retrieval au 2026-11-20. L’envoi de defer_loading vers un modèle non pris en charge renvoie une erreur HTTP 400 avec le message deferred loading is not supported for this model.

Démarrez votre intégration avec gemini-4-hydrogen, que Google utilise dans l’ensemble des exemples Tool Retrieval ; consultez notre guide de tarification et migration Gemini 4 Hydrogen si vous quittez les modèles Flash. Si votre flux de travail repose sur gemini-4-carbon, vérifiez le comportement réel sur v1beta avant d’activer defer_loading, ou consultez la tarification et migration de l’API Gemini 4 Carbon tout en conservant le chargement statique des outils.

Recherche côté serveur ou côté client

L’API Interactions propose deux modes de recherche mutuellement exclusifs : la recherche côté serveur (mode par défaut) et la recherche côté client (execution: "client"). Les deux gardent les schémas hors du prompt initial, mais ils diffèrent en latence, en mise en œuvre et en déclaration des outils.

CritèreChargement statiqueRecherche côté serveurRecherche côté client
Transmission des schémas au modèleTous envoyés dès le départGemini charge les schémas différés à la demandeVotre application renvoie les schémas dans function_result
Code de recherche à écrireAucunAucunRecherche, classement et filtrage personnalisés
Outils déclarés à l’avanceOuiOuiNon
Prise en charge MCP distantOuiOui (defer_loading: true sur mcp_server)Non applicable
Allers-retours réseau supplémentairesAucunAucun (exécuté au sein d’un seul appel API)Un aller-retour par recherche
Meilleur cas d’usageMoins de ~20 outils stablesGrandes bibliothèques fixes d’outils ou plusieurs serveurs MCPRegistres propriétaires, permissions par utilisateur, outils dynamiques en cours de session

Vous ne pouvez déclarer qu’une seule entrée tool_search par requête. Combiner des entrées tool_search côté serveur et côté client dans la même requête renvoie l’erreur Cannot specify both client-side and server-side tool_search tools..

Configurer la recherche côté serveur et un serveur MCP distant

La recherche côté serveur exige la version d’API v1beta. Bien que l’extrait du blog Google omette api_version, le guide officiel Tool retrieval précise que l’aperçu de Tool Retrieval requiert v1beta : en Python, initialisez genai.Client(http_options={"api_version": "v1beta"}) ; en JavaScript, initialisez new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } }).

Dans Bash, chargez votre clé API Gemini sans l’afficher dans le terminal, puis envoyez une requête POST vers https://generativelanguage.googleapis.com/v1beta/interactions. L’exemple ci-dessous associe une fonction locale différée (convert_currency) au serveur MCP météo de démonstration documenté par Google (https://gemini-api-demos.uc.r.appspot.com/mcp) :

read -rs GEMINI_API_KEY && export GEMINI_API_KEY

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-4-hydrogen",
    "input": "Check the temperature in London and convert 100 USD to EUR.",
    "tools": [
      {"type": "tool_search"},
      {
        "type": "function",
        "name": "convert_currency",
        "description": "Convert an amount from one currency to another using live mid-market rates.",
        "short_description": "Convert an amount between currencies.",
        "defer_loading": true,
        "parameters": {
          "type": "object",
          "properties": {
            "amount": {"type": "number"},
            "from": {"type": "string"},
            "to": {"type": "string"}
          },
          "required": ["amount", "from", "to"]
        }
      },
      {
        "type": "mcp_server",
        "name": "weather_service",
        "url": "https://gemini-api-demos.uc.r.appspot.com/mcp",
        "defer_loading": true
      }
    ]
  }'

Respectez quatre règles lors de la construction du tableau tools :

  • Omettez les champs name, description et parameters dans un objet tool_search côté serveur.
  • Envoyez le schéma parameters complet pour chaque function différée. Les schémas non chargés ne sont pas facturés, alors qu’un outil envoyé sans paramètres revient d’une recherche avec un schéma vide que le modèle ne peut pas appeler.
  • Utilisez le champ facultatif short_description uniquement avec defer_loading: true afin de remplacer une description longue dans la liste compacte des outils différés.
  • Pour les serveurs MCP distants, connectez uniquement des points de terminaison Streamable HTTP (les serveurs SSE ne sont pas pris en charge) et utilisez des noms de serveurs en snake_case sans -, comme indiqué dans Remote MCP. Si votre serveur distant échoue lors de la négociation ou de la validation de schéma, consultez notre guide de dépannage d’intégration de serveur MCP.

Vérifier la réponse côté serveur

Une réponse réussie de recherche côté serveur renvoie les étapes tool_search_call et tool_search_result dans steps au cours du même appel API, suivies de l’appel d’outil effectif. Pour les outils MCP distants tels que get_weather sur le serveur de démonstration, l’API exécute aussi l’appel distant et renvoie les étapes mcp_server_tool_call et mcp_server_tool_result dans la même réponse.

Pour vos propres fonctions, inspectez directement les éléments function_call dans steps. Ne vous fiez pas uniquement à status == "requires_action", car Google signale que status ne vaut pas toujours requires_action lorsqu’une étape function_call est présente. Exécutez la fonction localement, puis renvoyez un function_result au tour suivant.

Configurer la recherche côté client

Utilisez execution: "client" lorsque votre catalogue d’outils dépend des permissions utilisateur, d’espaces de noms internes ou d’intégrations ajoutées en cours de session. Les champs name et description sont tous deux obligatoires sur une définition tool_search côté client (omettre l’un ou l’autre renvoie une erreur 400), et aucun outil de la requête ne doit porter defer_loading.

L’extrait Python ci-dessous constitue un exemple de protocole minimal qui renvoie une déclaration fixe plutôt que d’interroger un registre réel. L’aller-retour est confirmé lorsque le script affiche une étape function_call pour get_billing_history avec {"user_id": 123} à partir de followup.steps :

from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

tools = [
    {
        "type": "tool_search",
        "execution": "client",
        "name": "search_tool_registry",
        "description": "Search internal tool namespaces such as billing and support when needed.",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {"type": "string"},
                "namespace": {"type": "string"},
            },
            "required": ["query"],
        },
    }
]

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Look up the billing history for user 123.",
    tools=tools,
)

for step in interaction.steps:
    if step.type == "function_call" and step.name == "search_tool_registry":
        # Minimal protocol example: replace with your own registry or permission filter.
        matches = [
            {
                "type": "function",
                "name": "get_billing_history",
                "description": "Retrieve billing history for a given user.",
                "parameters": {
                    "type": "object",
                    "properties": {"user_id": {"type": "integer"}},
                    "required": ["user_id"],
                },
            }
        ]
        followup = client.interactions.create(
            model="gemini-4-hydrogen",
            previous_interaction_id=interaction.id,
            tools=tools,
            input=[
                {
                    "type": "function_result",
                    "name": step.name,
                    "call_id": step.id,
                    "result": matches,
                }
            ],
        )
        for next_step in followup.steps:
            if next_step.type == "function_call":
                print(next_step.name, next_step.arguments)

Renvoyez des déclarations de fonctions complètes sous forme d’objets JSON dans le tableau function_result.result, jamais sous forme de chaîne JSON sérialisée, et incluez le name ainsi que le call_id correspondants issus du function_call de recherche. Si votre recherche côté client ne trouve aucun résultat, renvoyez un court texte indiquant l’absence de correspondance et listant ce que le modèle peut rechercher afin qu’il reformule sa requête.

État multi-tour, relecture sans état et erreurs courantes

Trois contraintes de cet aperçu provoquent la majorité des erreurs après le premier tour :

  • Renvoyez le tableau tools complet à chaque requête. L’API Interactions conserve l’historique des étapes lorsque vous transmettez previous_interaction_id, mais pas les déclarations d’outils entre deux requêtes. Omettre les outils aux tours suivants amène le modèle à ignorer des outils non déclarés ou à émettre des appels internes retriever: en mode serveur.
  • Les outils chargés ne se déchargent pas et un échec de recherche côté serveur renvoie du texte. Une fois un outil chargé par le modèle, son schéma reste en contexte jusqu’à la fin de la conversation. Si une requête côté serveur ne correspond à aucun outil différé, l’API renvoie une simple réponse texte au lieu d’une erreur structurée : ne vous appuyez pas sur tool_search_result pour détecter une absence de résultat.
  • Transmettez les étapes et signatures à l’identique lorsque store=false. À chaque tour sans état, envoyez tout l’historique des étapes dans input et renvoyez le tableau tools complet. Ajoutez chaque étape reçue (tool_search_call, tool_search_result, thought et function_call) sans modification, dans son ordre d’origine et avec sa signature intacte, suivie du nouveau function_result. Envoyer uniquement function_result supprime le contexte de recherche et déclenche une erreur 400. Utilisez une version du SDK qui reconnaît tool_search_call et tool_search_result, car les versions antérieures les interprètent comme des étapes inconnues et suppriment leurs champs. Ne différez aucun outil nommé explicitement dans vos instructions système ou dans la sortie d’un autre outil, sinon le modèle risque de l’appeler sans recherche préalable et d’échouer sur function_result.

Google documente des réponses HTTP 400 pour les modèles non compatibles, l’absence de tool_search côté serveur avec defer_loading, l’usage de short_description sans defer_loading: true, l’oubli de name ou description côté client, les étapes manquantes en mode sans état et les valeurs signature retirées. Le tableau suivant associe chaque message d’erreur documenté à sa cause et à sa correction :

Message d’erreur documentéCauseCorrection
deferred loading is not supported for this modeldefer_loading envoyé vers un modèle absent de la liste prise en chargePassez à gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash ou gemini-3.6-flash
tool_search tool must be specified when using defer_loading.Un outil function ou mcp_server définit defer_loading: true sans aucun outil tool_search dans la requêteAjoutez {"type": "tool_search"} ou supprimez defer_loading
When defer_loading is set on a FunctionDeclaration, a Tool with tool_search must also be provided in the request.Une fonction définit defer_loading: true sans tool_search côté serveur (par exemple seul execution: "client" est déclaré ou une requête suivante a omis tool_search)Retirez defer_loading en mode client, ou renvoyez le tableau tools complet incluant {"type": "tool_search"}
Cannot specify both client-side and server-side tool_search tools.La requête contient à la fois un tool_search côté serveur et un tool_search côté clientDéclarez exactement une seule entrée tool_search par requête
ToolSearch name must not be specified when execution mode is SERVER_SIDE.Un tool_search côté serveur définit name (la même erreur s’applique à description et parameters)Supprimez ce champ ; si vous passez à execution: "client", renseignez aussi name et description et retirez defer_loading de tous les outils
short_description can only be set if defer_loading is trueUne fonction définit short_description sans defer_loading: trueAjoutez defer_loading: true ou retirez short_description
Server side tool call context must be circulated when using deferred loading functions.Dans une requête sans état, l’historique contient un function_result pour un outil différé sans les étapes tool_search_call et tool_search_result qui l’ont chargéRenvoyez à l’identique chaque étape tool_search_call et tool_search_result, champ signature inclus
Server side tool call context must be circulated ... Missing circulated context for functions: FUNCTION_NAME (même quand toutes les étapes sont renvoyées)Le modèle a appelé une fonction différée qu’aucun tool_search n’avait chargée, généralement parce que son nom figure dans les instructions système ou la sortie d’un autre outilLaissez non différés les outils mentionnés par leur nom
Tool call part is missing thought_signature. / Tool response part is missing thought_signature.Dans une requête sans état, une étape tool_search_call (appel) ou tool_search_result (réponse) a été renvoyée sans son champ signatureRenvoyez les deux étapes de recherche sans modification en conservant leurs valeurs signature

Champs de facturation, cache de préfixe et seuil de rentabilité

Tool Retrieval n’entraîne aucuns frais dédiés. Chaque jeton est facturé aux tarifs standard d’entrée, de cache et de sortie indiqués sur la page tarification de l’API Gemini. Au 2026-11-20, gemini-4-hydrogen coûte $1.50 par 1M de jetons d’entrée, $0.075 par 1M de jetons d’entrée en cache et $7.50 par 1M de jetons de sortie (jetons de réflexion inclus) au niveau payant (Paid Tier). Le niveau gratuit (Standard Free Tier) est disponible pour gemini-4-hydrogen, gemini-3.8-flash et gemini-3.6-flash, tandis que gemini-4-argon est réservé au niveau payant à $2.00 en entrée, $0.10 en cache et $10.00 en sortie par 1M de jetons jusqu’au 30 novembre 2026, avant de passer à $4.00 / $0.20 / $20.00 à compter du 1er décembre 2026.

Vérifiez cinq champs de l’objet usage sur chaque réponse d’interaction pour suivre vos compteurs de jetons :

  • total_input_tokens : le prompt du premier appel au modèle dans la requête, incluant votre entrée, l’historique de conversation, les instructions système, les schémas d’outils non différés, le petit bloc fixe d’instructions tool_search et les entrées sur une ligne des outils différés (name plus short_description ou la première phrase de description, soit environ 26 jetons par outil différé selon les premiers tests de Google).
  • total_tool_use_tokens : les prompts des appels supplémentaires au modèle exécutés par l’API dans la même requête après l’exécution d’un outil côté serveur, y compris chaque recherche d’outil côté serveur. Chaque appel renvoie l’intégralité du contexte plus les nouveaux schémas chargés et est facturé au tarif d’entrée ; plusieurs recherches au cours d’un même tour ajoutent autant de passes.
  • total_cached_tokens : la portion du prompt servie depuis le cache implicite, facturée au tarif de cache plutôt qu’au tarif d’entrée.
  • total_output_tokens : les jetons de réponse générés, facturés au tarif de sortie.
  • total_thought_tokens : les jetons de réflexion générés, facturés au tarif de sortie.

Limite liée au seuil du cache de préfixe

L’API Interactions prend uniquement en charge le cache implicite ; le cache explicite n’est disponible ni sur l’API Interactions ni sur les modèles Gemini 4, selon la documentation Context caching. Puisque les schémas chargés s’ajoutent à l’endroit où le modèle les récupère plutôt qu’au début du prompt, vos instructions système, votre liste d’outils et les tours précédents forment un préfixe stable d’un tour à l’autre. Dès que ce préfixe dépasse la taille minimale mettable en cache du modèle, les requêtes ultérieures de la conversation, y compris l’appel supplémentaire effectué par chaque recherche côté serveur, peuvent être servies depuis le cache implicite et comptabilisées dans total_cached_tokens.

Cependant, au 2026-11-20, les quatre modèles compatibles avec Tool Retrieval exigent un minimum de 4,096 jetons d’entrée (soit 4 096 jetons ; la virgule sépare les milliers) pour activer le cache implicite. Si votre prompt ne dépassait 4,096 jetons que grâce aux schémas d’outils complets, le fait de différer ces outils peut faire passer votre requête sous le seuil minimal de mise en cache. Dans les échanges multi-tours et boucles d’agents sur les modèles Gemini 4, Gemini ne met en cache l’intégralité de la requête précédente que si la nouvelle requête ajoute au moins 2,050 jetons (soit 2 050 jetons ; la sortie du modèle, les jetons de réflexion et les résultats de fonctions comptent tous dans ce total) ; pour des ajouts plus petits, Gemini retraite les 2,050 derniers jetons de la requête précédente au tarif d’entrée standard.

Quand Tool Retrieval réduit la consommation ou coûte plus cher

La documentation Google fournit une estimation illustrative sur deux requêtes (nombres arrondis, hors jetons de sortie et mise en cache ; dans le tableau ci-dessous, la virgule sépare les milliers et non les décimales) dans laquelle le modèle charge deux outils de 400 jetons et renvoie un function_call sur la requête 1 suivi d’un function_result sur la requête 2 :

Scénario illustratif (estimation documentation Google)Chargement statique (jetons d’entrée)Tool Retrieval (jetons d’entrée + tool-use)Résultat net
200 outils (400 jetons chacun), contexte de 2,000 jetons2 × (2,000 + 80,000) = 164,000Requête 1 : 7,350 + passe de recherche 8,150 ; Requête 2 : 8,150 = ~23,650Économise ~86% des jetons côté entrée
10 outils (400 jetons chacun), contexte de 30,000 jetons2 × (30,000 + 4,000) = 68,000Requête 1 : 30,410 + passe de recherche 31,210 ; Requête 2 : 31,210 = ~92,830Coûte ~37% de jetons côté entrée en plus

Différer les outils est rentable lorsque votre bibliothèque est vaste et que la plupart des tours n’utilisent que quelques outils. Avec un petit jeu d’outils ou une longue conversation qui lance une recherche à presque chaque tour, la passe supplémentaire de recherche côté serveur (total_tool_use_tokens) peut dépasser le gain réalisé. Gardez vos outils les plus fréquents chargés dès le départ, différez la longue traîne et mesurez total_input_tokens, total_tool_use_tokens et total_cached_tokens sur votre propre trafic en parallèle du coût réellement facturé avant de déployer à grande échelle.

Prêt à optimiser votre workflow LLM ?

Connectez vos modèles via une API unique, gérez les clés et maîtrisez vos dépenses d’IA.

Commencer gratuitement