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

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.
| Option | Compte et région | Unité de facturation | Prise en charge de Tool Retrieval | Quand 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-argon | Par 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 generateContent | Même compte Google AI Studio et région prise en charge | Par 1M de jetons d’entrée, en cache et de sortie | Non prise en charge | Vous 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 console | Solde prépayé à l’usage facturé selon l’unité courante de chaque modèle | L’API Interactions n’est pas documentée ; la prise en charge de Tool Retrieval n’est pas vérifiée | Vous 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-hydrogengemini-4-argongemini-3.8-flashgemini-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ère | Chargement statique | Recherche côté serveur | Recherche côté client |
|---|---|---|---|
| Transmission des schémas au modèle | Tous envoyés dès le départ | Gemini charge les schémas différés à la demande | Votre application renvoie les schémas dans function_result |
| Code de recherche à écrire | Aucun | Aucun | Recherche, classement et filtrage personnalisés |
| Outils déclarés à l’avance | Oui | Oui | Non |
| Prise en charge MCP distant | Oui | Oui (defer_loading: true sur mcp_server) | Non applicable |
| Allers-retours réseau supplémentaires | Aucun | Aucun (exécuté au sein d’un seul appel API) | Un aller-retour par recherche |
| Meilleur cas d’usage | Moins de ~20 outils stables | Grandes bibliothèques fixes d’outils ou plusieurs serveurs MCP | Registres 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,descriptionetparametersdans un objettool_searchcôté serveur. - Envoyez le schéma
parameterscomplet pour chaquefunctiondiffé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_descriptionuniquement avecdefer_loading: trueafin de remplacer unedescriptionlongue 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_casesans-, 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
toolscomplet à chaque requête. L’API Interactions conserve l’historique des étapes lorsque vous transmettezprevious_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 internesretriever: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_resultpour 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 dansinputet renvoyez le tableautoolscomplet. Ajoutez chaque étape reçue (tool_search_call,tool_search_result,thoughtetfunction_call) sans modification, dans son ordre d’origine et avec sasignatureintacte, suivie du nouveaufunction_result. Envoyer uniquementfunction_resultsupprime le contexte de recherche et déclenche une erreur400. Utilisez une version du SDK qui reconnaîttool_search_callettool_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 surfunction_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é | Cause | Correction |
|---|---|---|
deferred loading is not supported for this model | defer_loading envoyé vers un modèle absent de la liste prise en charge | Passez à 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ête | Ajoutez {"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é client | Dé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 true | Une fonction définit short_description sans defer_loading: true | Ajoutez 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 outil | Laissez 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 signature | Renvoyez 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’instructionstool_searchet les entrées sur une ligne des outils différés (nameplusshort_descriptionou la première phrase dedescription, 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 jetons | 2 × (2,000 + 80,000) = 164,000 | Requê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 jetons | 2 × (30,000 + 4,000) = 68,000 | Requête 1 : 30,410 + passe de recherche 31,210 ; Requête 2 : 31,210 = ~92,830 | Coû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.