Gemini API Tool Retrieval: tool_search, defer_loading und Abrechnung
Aktivieren Sie Tool Retrieval in der Vorschau der Gemini Interactions API (v1beta) mit tool_search und defer_loading. Vergleichen Sie serverseitigen und clientseitigen Modus, prüfen Sie die vier dokumentierten Modelle im Vergleich zum Google-Blog, richten Sie Remote-MCP und zustandsloses Replay ein, beheben Sie 400-Fehler und bewerten Sie Token-Abrechnung sowie implizites Präfix-Caching.
Inhalt

Tool Retrieval ist jetzt als Vorschau in der Gemini Interactions API (v1beta) verfügbar und lädt Parameter-Schemas von Tools über tool_search und defer_loading bei Bedarf nach. Das betrifft Entwickler, die Dutzende eigener Funktionen oder Remote-MCP-Server mit Gemini verbinden, und funktioniert ausschließlich über die Interactions API (nicht über generateContent). Um die Funktion mit Stand 2026-11-20 zu testen, rufen Sie v1beta/interactions mit einem der vier dokumentierten Modelle (gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash oder gemini-3.6-flash) auf, ergänzen {"type": "tool_search"} und setzen defer_loading: true bei allen Tools außerhalb Ihres Kernsets.
Zuerst die passende API-Route wählen
Google hat Tool Retrieval am 19. November 2026 im Google-Blog angekündigt und die Einrichtung in der AI-Studio-Dokumentation zu Tool retrieval veröffentlicht. Da die Funktion an die Vorschau der Interactions API (v1beta) gebunden ist, entscheidet Ihr aktueller Endpunkt darüber, ob Sie sie sofort einsetzen können.
| Route | Konto und Region | Abrechnungseinheit | Tool-Retrieval-Unterstützung | Wann geeignet |
|---|---|---|---|---|
Offizielle Gemini Interactions API (v1beta) | Google-AI-Studio-API-Schlüssel in einer unterstützten Region; Paid Tier für gemini-4-argon erforderlich | Pro 1M Eingabe-, Cache- und Ausgabetokens (Standard Free Tier für gemini-4-hydrogen, gemini-3.8-flash und gemini-3.6-flash verfügbar) | In der Vorschau unterstützt (tool_search, defer_loading, Remote-mcp_server) | Sie verwalten eine große Tool-Bibliothek und können v1beta/interactions direkt aufrufen |
Offizielle Gemini-generateContent-API | Gleiches Google-AI-Studio-Konto und unterstützte Region | Pro 1M Eingabe-, Cache- und Ausgabetokens | Nicht unterstützt | Sie nutzen weniger als ~20 stabile Tools, brauchen explizites Caching auf unterstützten Gemini-3- oder 2.5-Modellen oder können noch nicht migrieren |
| Pay-as-you-go-API-Gateway (wie BetterToken) | Eigenes BetterToken-Konto und ein in der Konsole erstellter API-Schlüssel | Pay-as-you-go-Guthaben, abgerechnet nach der aktuellen Abrechnungseinheit des jeweiligen Modells | Interactions API ist nicht dokumentiert; Unterstützung für Tool Retrieval ist ungeprüft | Sie bleiben modellübergreifend bei den dokumentierten nativen Gemini-generateContent- oder OpenAI-kompatiblen Chat-Completions-Endpunkten (prüfen Sie die Tool-Unterstützung pro Modell in der BetterToken-Dokumentation) |
Wenn Sie bei der regulären Gemini-generateContent-API oder OpenAI-kompatiblen Chat Completions bleiben, statt zur Interactions API zu wechseln, können Sie die Gemini-API-Referenz von BetterToken prüfen, um dokumentierte Endpunkte, Modell-IDs und die Tool-Unterstützung je Modell einzusehen.
Unterstützte Modelle und der Gemini-4-Fehler 400
Im Ankündigungsbeitrag vom 19. November 2026 schreibt Google, dass Tool Retrieval mit Gemini 3.6 und neueren Modellen einschließlich aller Gemini-4-Modelle funktioniert, und verlinkt auf die Seite Latest Gemini models. Dort stehen vier Gemini-4-Modelle: gemini-4-carbon, gemini-4-neon, gemini-4-hydrogen und gemini-4-argon.
Mit Stand 2026-11-20 führt die offizielle Liste der unterstützten Modelle für Tool retrieval jedoch nur vier Modell-IDs auf:
gemini-4-hydrogengemini-4-argongemini-3.8-flashgemini-3.6-flash
gemini-4-carbon und gemini-4-neon fehlen auf der Tool-Retrieval-Dokumentationsseite mit Stand 2026-11-20. Wenn Sie defer_loading an ein nicht unterstütztes Modell senden, antwortet die API mit HTTP 400 und der Meldung deferred loading is not supported for this model.
Beginnen Sie Ihre Integration mit gemini-4-hydrogen, das Google durchgängig in den Tool-Retrieval-Beispielen verwendet. Falls Sie von Flash-Modellen wechseln, hilft unser Leitfaden zu Preisen und Migration von Gemini 4 Hydrogen. Wenn Ihr Workflow auf gemini-4-carbon angewiesen ist, testen Sie das Live-Verhalten unter v1beta, bevor Sie defer_loading aktivieren, oder lesen Sie den Beitrag zu Preisen und Migration der Gemini 4 Carbon API, während Sie vorerst beim statischen Laden bleiben.
Serverseitige vs. clientseitige Suche
Die Interactions API unterstützt zwei sich gegenseitig ausschließende Modi: serverseitige Suche (Standard) und clientseitige Suche (execution: "client"). Beide halten die Schemas aus dem ersten Prompt heraus, unterscheiden sich aber bei Latenz, Implementierungsaufwand und Tool-Registrierung.
| Merkmal | Statisches Laden | Serverseitige Suche | Clientseitige Suche |
|---|---|---|---|
| Wie Schemas das Modell erreichen | Alle vorab gesendet | Gemini lädt verzögerte Schemas bei Bedarf | Ihre Anwendung liefert Schemas in function_result |
| Eigener Suchcode nötig | Keiner | Keiner | Eigene Suche, Sortierung und Filterung |
| Tools vorab deklariert | Ja | Ja | Nein |
| Remote-MCP-Unterstützung | Ja | Ja (defer_loading: true bei mcp_server) | Nicht zutreffend |
| Zusätzliche Netzwerk-Roundtrips | Keine | Keine (läuft innerhalb eines API-Aufrufs) | Ein Roundtrip pro Suche |
| Beste Eignung | Weniger als ~20 stabile Tools | Große, feste Tool-Bibliotheken oder mehrere MCP-Server | Eigene Verzeichnisse, benutzerbezogene Rechte, dynamische Tools während einer Sitzung |
Pro Anfrage darf nur ein einziger tool_search-Eintrag deklariert werden. Kombinieren Sie serverseitige und clientseitige tool_search-Einträge in derselben Anfrage, gibt die API den Fehler Cannot specify both client-side and server-side tool_search tools. zurück.
Serverseitige Suche und Remote-MCP einrichten
Die serverseitige Suche verlangt die API-Version v1beta. Zwar lässt der Codeausschnitt im Google-Blog api_version weg, doch der offizielle Tool-Retrieval-Leitfaden legt fest, dass die Vorschau v1beta erfordert: In Python initialisieren Sie genai.Client(http_options={"api_version": "v1beta"}), in JavaScript new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } }).
Laden Sie in Bash Ihren Gemini-API-Schlüssel ohne Ausgabe im Terminal und senden Sie dann eine POST-Anfrage an https://generativelanguage.googleapis.com/v1beta/interactions. Das folgende Beispiel kombiniert eine verzögerte lokale Funktion (convert_currency) mit Googles dokumentiertem Demo-Wetter-MCP-Server (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
}
]
}'
Beachten Sie vier Regeln beim Aufbau des tools-Arrays:
- Lassen Sie
name,descriptionundparametersbei einem serverseitigentool_search-Objekt vollständig weg. - Senden Sie bei jeder verzögerten
functiondas vollständigeparameters-Schema mit. Nicht geladene Schemas werden nicht abgerechnet; ein Tool ohne Parameter kommt dagegen aus einer Suche mit leerem Schema zurück und lässt sich vom Modell nicht aufrufen. - Verwenden Sie das optionale Feld
short_descriptionnur zusammen mitdefer_loading: true, um eine langedescriptionin der kompakten Liste verzögerter Tools zu ersetzen. - Verbinden Sie bei Remote-MCP-Servern ausschließlich Streamable-HTTP-Endpunkte (SSE-Server werden nicht unterstützt) und wählen Sie Servernamen in
snake_caseohne-, wie unter Remote MCP beschrieben. Falls bei Ihrem Remote-Server der Handshake oder die Schema-Prüfung fehlschlägt, nutzen Sie unseren Leitfaden zur Fehlerbehebung bei der MCP-Server-Integration.
Serverseitige Antwort prüfen
Eine erfolgreiche Antwort der serverseitigen Suche enthält im Feld steps noch im selben API-Aufruf die Schritte tool_search_call und tool_search_result, gefolgt vom eigentlichen Tool-Aufruf. Bei Remote-MCP-Tools wie get_weather auf dem Demo-Server führt die API zudem den entfernten Aufruf aus und liefert mcp_server_tool_call sowie mcp_server_tool_result in derselben Antwort mit.
Für eigene Funktionen prüfen Sie direkt die function_call-Einträge innerhalb von steps. Verlassen Sie sich nicht allein auf status == "requires_action", weil Google darauf hinweist, dass status trotz eines vorhandenen function_call-Schritts nicht immer requires_action lautet. Führen Sie die Funktion lokal aus und senden Sie im nächsten Zug ein function_result.
Clientseitige Suche einrichten
Setzen Sie execution: "client" ein, wenn Ihr Tool-Katalog von Benutzerrechten, internen Namensräumen oder erst während der Sitzung hinzugefügten Integrationen abhängt. Bei einer clientseitigen tool_search-Definition sind sowohl name als auch description Pflicht (fehlt eines davon, folgt ein 400-Fehler), und kein Tool der Anfrage darf defer_loading setzen.
Das folgende Python-Beispiel zeigt das minimale Protokoll und gibt eine feste Deklaration zurück, statt ein Produktivverzeichnis abzufragen. Der Durchlauf funktioniert, sobald das Skript aus followup.steps einen function_call-Schritt für get_billing_history mit {"user_id": 123} ausgibt:
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)
Geben Sie vollständige Funktionsdeklarationen als JSON-Objekte im Array function_result.result zurück und nicht als serialisierten JSON-String. Übernehmen Sie außerdem genau die Werte name und call_id aus dem zugehörigen Such-function_call. Findet Ihre clientseitige Suche keinen Treffer, senden Sie eine kurze Textantwort, die das fehlende Ergebnis meldet und nennt, wonach das Modell suchen kann, damit es seine Abfrage anpasst.
Mehrrunden-Zustand, zustandsloses Replay und typische Fehler
Drei Einschränkungen der Vorschau verursachen die meisten Fehler nach dem ersten Zug:
- Senden Sie bei jeder Anfrage das vollständige
tools-Array erneut. Die Interactions API speichert den Schrittverlauf, wenn Sieprevious_interaction_idübergeben, jedoch keine Tool-Deklarationen zwischen Anfragen. Fehlen die Tools in Folgeanfragen, übersieht das Modell nicht deklarierte Tools oder erzeugt im serverseitigen Modus interneretriever:-Aufrufe. - Geladene Tools lassen sich nicht entladen, und fehlgeschlagene serverseitige Suchen liefern Text. Sobald das Modell ein Tool geladen hat, bleibt dessen Schema für den Rest der Unterhaltung im Kontext. Trifft eine serverseitige Suchanfrage kein verzögertes Tool, antwortet die API mit normalem Text statt eines strukturierten Suchfehlers. Prüfen Sie Trefferlosigkeit daher nicht über
tool_search_result. - Übermitteln Sie Schritte und Signaturen bei
store=falseunverändert weiter. Übergeben Sie bei jeder zustandslosen Folgeanfrage den gesamten Schrittverlauf ininputund senden Sie das komplettetools-Array erneut. Hängen Sie jeden Antwortschritt (tool_search_call,tool_search_result,thoughtundfunction_call) unverändert, in ursprünglicher Reihenfolge und mit intaktersignaturean, gefolgt vom neuenfunction_result. Wer nurfunction_resultschickt, verliert den Suchkontext und erhält einen400-Fehler. Nutzen Sie eine SDK-Version, dietool_search_callundtool_search_resultkennt, da ältere SDKs diese als unbekannte Schritte parsen und ihre Felder entfernen. Halten Sie jedes Tool, dessen Name in Systemanweisungen oder Tool-Ausgaben steht, unverzögert; sonst ruft das Modell es eventuell ohne Suche auf und scheitert anfunction_result.
Google dokumentiert HTTP-400-Antworten für nicht unterstützte Modelle, fehlendes serverseitiges tool_search bei defer_loading, short_description ohne defer_loading: true, fehlendes name oder description im Client-Modus, fehlende zustandslose Schritte sowie entfernte signature-Werte. Die folgende Tabelle ordnet jeder dokumentierten Fehlermeldung ihre Ursache und Lösung zu:
| Dokumentierte Fehlermeldung | Ursache | Lösung |
|---|---|---|
deferred loading is not supported for this model | defer_loading an ein Modell außerhalb der unterstützten Liste gesendet | Zu gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash oder gemini-3.6-flash wechseln |
tool_search tool must be specified when using defer_loading. | Ein function- oder mcp_server-Tool setzt defer_loading: true, aber in der Anfrage fehlt ein tool_search-Tool | {"type": "tool_search"} hinzufügen oder defer_loading entfernen |
When defer_loading is set on a FunctionDeclaration, a Tool with tool_search must also be provided in the request. | Eine Funktion setzt defer_loading: true ohne serverseitiges tool_search (etwa weil nur execution: "client" deklariert ist oder eine Folgeanfrage tool_search weggelassen hat) | Im Client-Modus defer_loading entfernen oder das gesamte tools-Array inklusive {"type": "tool_search"} erneut senden |
Cannot specify both client-side and server-side tool_search tools. | Die Anfrage enthält sowohl ein serverseitiges als auch ein clientseitiges tool_search | Genau einen tool_search-Eintrag pro Anfrage deklarieren |
ToolSearch name must not be specified when execution mode is SERVER_SIDE. | Ein serverseitiges tool_search setzt name (derselbe Fehler tritt bei description und parameters auf) | Das Feld entfernen; beim Wechsel zu execution: "client" zusätzlich name und description angeben und defer_loading bei allen Tools entfernen |
short_description can only be set if defer_loading is true | Eine Funktion setzt short_description ohne defer_loading: true | defer_loading: true setzen oder short_description entfernen |
Server side tool call context must be circulated when using deferred loading functions. | In einer zustandslosen Anfrage enthält der Verlauf ein function_result für ein verzögertes Tool, aber nicht die zugehörigen Schritte tool_search_call und tool_search_result | Alle tool_search_call- und tool_search_result-Schritte unverändert inklusive signature zurücksenden |
Server side tool call context must be circulated ... Missing circulated context for functions: FUNCTION_NAME (auch wenn alle Schritte zurückgesendet wurden) | Das Modell hat eine verzögerte Funktion aufgerufen, die zuvor kein tool_search geladen hat, meist weil ihr Name in Systemanweisungen oder einer anderen Tool-Ausgabe stand | Namentlich erwähnte Tools nicht verzögert laden |
Tool call part is missing thought_signature. / Tool response part is missing thought_signature. | In einer zustandslosen Anfrage wurde ein Schritt tool_search_call (Aufrufteil) oder tool_search_result (Antwortteil) ohne sein signature-Feld zurückgesendet | Beide Suchschritte unverändert mit ihren signature-Werten zurücksenden |
Abrechnungsfelder, Präfix-Caching und Break-even-Rechnung
Für Tool Retrieval fällt keine eigene Funktionsgebühr an. Jeder Token wird zu den regulären Eingabe-, Cache- und Ausgabesätzen auf der Seite Gemini API pricing abgerechnet. Mit Stand 2026-11-20 kostet gemini-4-hydrogen im Paid Tier $1.50 pro 1M Eingabetokens, $0.075 pro 1M gecachte Eingabetokens und $7.50 pro 1M Ausgabetokens (einschließlich Thinking-Tokens). Der Standard Free Tier steht für gemini-4-hydrogen, gemini-3.8-flash und gemini-3.6-flash bereit. gemini-4-argon gibt es dagegen nur im Paid Tier für $2.00 Eingabe, $0.10 Cache und $10.00 Ausgabe pro 1M Tokens bis zum 30. November 2026; ab dem 1. Dezember 2026 steigen die Preise auf $4.00 / $0.20 / $20.00.
Prüfen Sie bei jeder Antwort fünf Felder unter usage, um den Tokenverbrauch nachzuvollziehen:
total_input_tokens: Der Prompt des ersten Modellaufrufs in der Anfrage. Er umfasst Ihre Eingabe, den Gesprächsverlauf, Systemanweisungen, Schemas nicht verzögerter Tools, den kleinen festentool_search-Anweisungsblock und einzeilige Einträge für verzögerte Tools (nameplusshort_descriptionoder erster Satz derdescription, etwa 26 Tokens pro verzögertem Tool in Googles frühen Tests).total_tool_use_tokens: Die Prompts zusätzlicher Modellaufrufe, welche die API innerhalb derselben Anfrage nach einem serverseitigen Tool-Lauf ausführt, einschließlich jeder serverseitigen Tool-Suche. Jeder Aufruf sendet den gesamten Kontext erneut samt neu geladenen Schemas und wird zum Eingabesatz abgerechnet; mehrere Suchen in einem Zug erzeugen mehrere Durchläufe.total_cached_tokens: Der Teil des Prompts aus dem impliziten Cache, abgerechnet zum günstigeren Cache-Satz statt zum Eingabesatz.total_output_tokens: Generierte Antworttokens, abgerechnet zum Ausgabesatz.total_thought_tokens: Generierte Thinking-Tokens, abgerechnet zum Ausgabesatz.
Einschränkung bei der Präfix-Cache-Schwelle
Die Interactions API unterstützt ausschließlich implizites Caching. Explizites Caching ist laut Context caching weder in der Interactions API noch für Gemini-4-Modelle verfügbar. Da geladene Schemas dort eingefügt werden, wo das Modell sie anfordert, und nicht am Anfang des Prompts, bleiben Systemanweisungen, Tool-Liste und frühere Züge über mehrere Züge hinweg ein unverändertes Präfix. Sobald dieses Präfix die minimale cachebare Größe des Modells überschreitet, können spätere Anfragen in der Unterhaltung, einschließlich des zusätzlichen Modellaufrufs jeder serverseitigen Suche, aus dem impliziten Cache bedient und in total_cached_tokens ausgewiesen werden.
Mit Stand 2026-11-20 erfordern jedoch alle vier unterstützten Tool-Retrieval-Modelle mindestens 4,096 Eingabetokens (entspricht 4 096 Tokens; das Komma dient als Tausendertrennzeichen) für implizites Caching. Wenn Ihr Prompt diese 4,096 Tokens zuvor nur wegen vollständiger Tool-Schemas überschritten hat, kann das Verzögern der Tools die Anfrage unter die Mindestgröße drücken. In Mehrrunden-Gesprächen und Agentenschleifen auf Gemini-4-Modellen speichert Gemini die gesamte vorherige Anfrage nur dann im Cache, wenn die neue Anfrage mindestens 2,050 Tokens (entspricht 2 050 Tokens) hinzufügt; Modellausgabe, Thinking-Tokens und Funktionsergebnisse zählen alle zu dieser Summe hinzu. Bei kleineren Ergänzungen verarbeitet Gemini die letzten 2,050 Tokens der vorherigen Anfrage erneut zum regulären Eingabesatz.
Wann Tool Retrieval Tokens spart oder mehr kostet
Googles Dokumentation zeigt eine beispielhafte Schätzung über zwei Anfragen (gerundete Werte, ohne Ausgabetokens und Caching; Kommas in der Tabelle trennen Tausenderstellen wie in der englischen Schreibweise). In diesem Beispiel lädt das Modell zwei Tools mit je 400 Tokens und liefert in der Antwort auf Anfrage 1 einen function_call zurück. Anschließend führt Ihre Anwendung die Funktion aus und sendet in Anfrage 2 das function_result:
| Beispielszenario (Schätzung der Google-Dokumentation) | Statisches Laden (Eingabetokens) | Tool Retrieval (Eingabe- + Tool-Use-Tokens) | Nettoergebnis |
|---|---|---|---|
| 200 Tools (je 400 Tokens), Kontext mit 2,000 Tokens | 2 × (2,000 + 80,000) = 164,000 | Anfrage 1: 7,350 + Suchdurchlauf 8,150; Anfrage 2: 8,150 = ~23,650 | Spart ~86% der eingabeseitigen Tokens |
| 10 Tools (je 400 Tokens), Kontext mit 30,000 Tokens | 2 × (30,000 + 4,000) = 68,000 | Anfrage 1: 30,410 + Suchdurchlauf 31,210; Anfrage 2: 31,210 = ~92,830 | Kostet ~37% mehr eingabeseitige Tokens |
Das Verzögern von Tools lohnt sich bei großen Bibliotheken, wenn die meisten Züge nur wenige Tools nutzen. Bei einem kleinen Tool-Set oder einer langen Unterhaltung, die fast in jedem Zug sucht, kann der zusätzliche serverseitige Suchdurchlauf (total_tool_use_tokens) die Einsparungen übersteigen. Halten Sie häufig genutzte Tools direkt geladen, verzögern Sie selten benötigte Tools und messen Sie vor dem breiten Rollout total_input_tokens, total_tool_use_tokens und total_cached_tokens zusammen mit den tatsächlichen Abrechnungskosten anhand Ihres eigenen Traffics.