Funktionsaufrufe mit Gemini 3.8 Flash: call_id, iterative Tool-Schleifen und wie man sie testet

Gemini 3.8 Flash wurde am 2. September 2026 ausgeliefert, und Google hat es so konzipiert, dass es „Werkzeuge iterativ aufruft“: Bei einer schwierigen Aufgabe macht es einen Aufruf, überprüft das Ergebnis und macht einen weiteren, anstatt alles auf einmal zu erraten. Das sind gute Nachrichten für Agenten und ein neues Kopfzerbrechen für jeden, dessen Werkzeug-Loop für 3.7 Flash optimiert war. Zwei API-Details sind wichtiger als alles andere. Jedes Funktionsergebnis muss sowohl call_id als auch name enthalten, und die Interactions API, nicht generateContent, ist nun die primäre Methode, um den Loop auszuführen.

Dieser Leitfaden beschreibt den vollständigen Zwei-Zug-Ablauf auf der Interactions API, zeigt die veraltete generateContent-Struktur, die Sie wahrscheinlich noch verwenden, erklärt, warum das neue Modell mehr Züge und Tokens für Werkzeuge benötigt, und schließt mit einem Test-Setup ab, das Sie täglich ausführen können: Mocken Sie das Backend des Werkzeugs, verketten Sie beide Züge und stellen Sie sicher, dass die call_id den Roundtrip macht. Wenn Sie zuerst eine Modellübersicht benötigen, beginnen Sie mit was Gemini 3.8 Flash ist. Die unten stehenden Feldnamen stammen aus Googles Funktionsaufruf-Dokumentation.

Jede Anfrage hier ist reines HTTP mit JSON, sodass Sie sie in Apidog erstellen und debuggen können, bevor sie in den Anwendungscode gelangt.

Funktionsaufrufe auf Gemini 3.8 Flash auf einen Blick

Schritt 1: Das Werkzeug deklarieren

Auf der Interactions API ist ein Werkzeug ein flaches Objekt: ein type von function, ein name, eine description, die das Modell liest, um zu entscheiden, wann es aufgerufen werden soll, und ein JSON-Schema unter parameters. Halten Sie die Beschreibung spezifisch. „Den aktuellen Versandstatus einer Bestellung anhand ihrer ID nachschlagen“ wird zum richtigen Zeitpunkt aufgerufen; „Bestellhelfer“ wird zufällig aufgerufen.

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-3.8-flash",
    "input": "Where is order A1029 right now?",
    "generation_config": {"thinking_level": "low"},
    "tools": [{
      "type": "function",
      "name": "get_order_status",
      "description": "Look up the current shipping status of an order by its ID.",
      "parameters": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"]
      }
    }]
  }'

Zwei Entscheidungen in dieser Anfrage sind bewusst getroffen. thinking_level ist low, da ein einzelnes Nachschlagen das Standard-medium nicht benötigt; der Leitfaden zu den Thinking Levels behandelt, wann man es erhöhen sollte. Und es gibt keine temperature. Googles Gemini 3-Empfehlung ist, sie auf dem Standardwert 1.0 zu belassen, da ein Absenken zu Schleifen führen kann, was das Letzte ist, was Sie innerhalb einer Werkzeugschleife wollen.

Schritt 2: Den function_call-Schritt lesen

Die Interactions API antwortet nicht mit einer einzelnen Nachricht. Sie gibt die eigene id der Interaktion plus eine Liste von Ausführungsschritten zurück: Modellgedanken, Werkzeugaufrufe und schließlich einen model_output-Schritt, sobald das Modell eine Antwort hat. Wenn das Modell entscheidet, dass es Ihr Werkzeug benötigt, enthält die Liste einen function_call-Schritt anstelle eines model_output:

{
  "type": "function_call",
  "id": "call_8f2d...",
  "name": "get_order_status",
  "arguments": {"order_id": "A1029"}
}

Drei Felder, und Sie benötigen alle drei. id ist der Handle, den Sie als call_id zurücksenden. name sagt Ihnen, welche Funktion ausgeführt werden soll, und muss ebenfalls zurückgegeben werden. arguments ist bereits geparstes JSON, also validieren Sie es vor jeder Ausführung nach Ihren eigenen Regeln; das Modell füllt die von Ihnen deklarierte Form aus, aber es weiß nicht, dass Ihre Bestell-IDs fünf Zeichen lang sind.

Speichern Sie gleichzeitig die Interaktions-id vom Anfang der Antwort. Sie wird im nächsten Zug zu previous_interaction_id.

Schritt 3: Das Ergebnis mit call_id und name zurückgeben

Führen Sie Ihre Funktion aus und senden Sie dann eine zweite Anfrage, deren input ein function_result ist. Sowohl call_id als auch name sind bei Gemini 3.8 Flash erforderlich. Wenn eines davon weggelassen wird, schlägt der Aufruf fehl, was die häufigste Fehlerquelle ist, wenn Teams Schleifen, die für ältere Modelle geschrieben wurden, migrieren.

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-3.8-flash",
    "previous_interaction_id": "<interaction id from step 2>",
    "input": [{
      "type": "function_result",
      "name": "get_order_status",
      "call_id": "call_8f2d...",
      "result": [{"type": "text", "text": "{\"status\":\"in_transit\",\"eta\":\"2026-09-05\"}"}]
    }]
  }'

result ist eine Liste von Inhaltsteilen, und der Textteil enthält Ihr JSON als Zeichenkette. Da previous_interaction_id auf den vorherigen Zug verweist, hält der Server bereits den ursprünglichen Prompt, die Werkzeugdeklaration und die Argumentation des Modells; Sie müssen nichts davon erneut senden. Die Antwort ist eine weitere Schrittliste. Wenn sie mit model_output endet, sind Sie fertig, und das SDK legt den Text als interaction.output_text offen. Wenn sie einen weiteren function_call enthält, gehen Sie zurück zu Schritt 2. Diese Schleife ist das gesamte Muster.

In Python ist der Ablauf client.interactions.create(model="gemini-3.8-flash", input=..., ...) mit denselben JSON-Feldern als Schlüsselwortargumente, dann ein zweites create mit previous_interaction_id und der function_result-Liste als input. Die Anleitung zur Gemini 3.8 Flash API behandelt Schlüssel, Streaming und das Lesen der Token-Nutzung, falls der Endpunkt für Sie neu ist.

Das Äquivalent der veralteten generateContent-Methode

Die meisten bestehenden Gemini-Codes rufen immer noch models/gemini-3.8-flash:generateContent auf, und Google sagt, es bleibe „vollständig unterstützt“ ohne ein Enddatum. Die Terminologie ist anders; die Regel ist dieselbe. Werkzeuge werden unter functionDeclarations deklariert, das Modell antwortet mit einem functionCall-Teil, und Sie antworten mit einem functionResponse-Teil. Bei der veralteten Form enthält der functionCall-Teil des Modells eine id, und Ihr functionResponse-Teil muss denselben Wert in seinem eigenen id-Feld zusammen mit name und response wiederholen. Es ist derselbe Vertrag wie call_id auf der Interactions API unter einem anderen Feldnamen, und Googles Gemini 3-Anleitung ist explizit, dass sowohl die ID als auch der Name erforderlich sind.

Zwei praktische Unterschiede. Erstens ist generateContent zustandslos, sodass Sie die Konversation selbst führen: Die gesamte contents-Historie wird bei jedem Zug zurückgesendet, einschließlich des functionCall-Teils des Modells und aller zurückgegebenen Denk-Signaturen. Zweitens wird das Denken unter generationConfig.thinkingConfig.thinkingLevel anstelle von generation_config.thinking_level konfiguriert:

{"generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}}

Denk-Tokens erscheinen als usageMetadata.thoughtsTokenCount in der Antwort und werden als Ausgabe abgerechnet. Wenn Sie für ein neues Projekt zwischen den beiden APIs wählen, nehmen Sie Interactions: Der serverseitige Zustand eliminiert die Art von Fehlern, bei denen in einer erneut gesendeten Historie eine Signatur oder eine call_id fehlt.

Warum 3.8 Flash Werkzeuge iterativ aufruft und wie man die Schleife begrenzt

Googles Startbeitrag besagt, dass das Modell „härter arbeitet“: Bei komplexen Aufgaben „führt es zusätzliche Denk-Schritte aus und ruft Werkzeuge iterativ auf“, wobei es „kleinere Denkschritte“ unternimmt und seine Arbeit dabei überprüft. Google sagt auch, dass es „entwurfsbedingt mehr Tokens für länger dauernde und komplexe Aufgaben verwenden kann“. Artificial Analysis hat den Effekt gemessen: etwa 48.000 Ausgabe-Tokens pro Aufgabe in ihrem Index, +30 % gegenüber 3.7 Flash, und Kosten pro Aufgabe von 0,58 $ bei high gegenüber 0,40 $ für 3.7 Flash bei denselben Token-Preisen. Medium lag bei 0,41 $ und low bei 0,24 $.

Für eine Werkzeugschleife bedeutet dies mehr function_call-Schritte pro Aufgabe. Der Vorteil ist real: Tau3-Banking, AAs Werkzeugnutzungsbewertung, stieg um 12 Punkte auf 45 %. Der Nachteil ist, dass eine Schleife ohne Obergrenze jetzt länger läuft als im August. Vier Steuerungen, in der Reihenfolge ihrer Anwendung:

• Maximale Züge in Ihrem Harness. Zählen Sie function_call-Schritte pro Aufgabe und stoppen Sie bei einem von Ihnen gewählten Limit; 6 bis 10 ist ein vernünftiger Startbereich für Nachschlagen, höher für agentisches Coding. Wenn das Limit erreicht ist, senden Sie einen letzten Zug ohne Werkzeuge oder geben Sie einen Fehler an den Benutzer zurück. Das Modell wird sich nicht selbst begrenzen.
• thinking_level pro Route. low für Nachschlagen und Single-Hop-Werkzeuge, medium (Standard) für mehrstufige Arbeiten, high nur dort, wo die zusätzliche Überprüfung sich auszahlt. Senden Sie nicht minimal; 3.8 Flash gibt einen Validierungsfehler zurück.
• Timeouts auf beiden Seiten. Ein Timeout pro Anfrage beim Gemini-Aufruf und eine Wanduhr pro Aufgabe für die Schleife. AAs High-Reasoning-Läufe dauerten im Durchschnitt 2,5 Minuten pro Aufgabe, 0,8 Minuten bei low.
• Idempotente Werkzeuge. Ein iteratives Modell versucht es erneut. Machen Sie get_order_status sicher für den zweimaligen Aufruf, und alles mit Nebeneffekten (Rückerstattungen, Sendungen) erfordert einen Bestätigungsschritt.

Wenn Ihr Budget die zusätzlichen Züge nicht absorbieren kann, behandelt der Migrationsleitfaden von 3.7 auf 3.8 Flash, wie man 3.7 Flash, das weiterhin vollständig unterstützt wird, hinter einem Konfigurations-Flag beibehält.

Gedankensignaturen, parallele Aufrufe und strukturierte Ausgaben

Gedankensignaturen. Gemini 3-Modelle versehen ihre Argumentation mit Signaturen. Mit dem standardmäßigen gespeicherten Interactions-Flow handhabt previous_interaction_id diese für Sie. Wenn Sie store: false für ein zustandsloses Setup festlegen oder generateContent verwenden, müssen Sie Gedankenblöcke und Signaturen genau so zurücksenden, wie sie empfangen wurden, bei jedem Teiltyp. Kürzen, neu anordnen oder neu serialisieren Sie sie nicht; eine Signatur ist undurchsichtig, und jede Bearbeitung macht sie ungültig. Googles Interactions API-Dokumentation behandelt den Kompromiss zwischen gespeichertem und zustandslosem Setup.

Parallele Aufrufe. Die Antwort ist eine Liste, sodass sie mehr als einen function_call-Schritt enthalten kann, wenn das Modell mehrere unabhängige Nachschlagen gleichzeitig wünscht. Googles Funktionsaufruf-Dokumentation bestätigt, dass Gemini 3-Modelle bei jedem Aufruf eine eindeutige ID zurückgeben, genau damit die Ergebnisse in beliebiger Reihenfolge zurückkommen können. Behandeln Sie dies, indem Sie ein function_result pro Aufruf im selben input-Array zurückgeben, jeweils passend zu seiner eigenen call_id. Eine Übereinstimmung nur nach name ist nicht ausreichend; zwei Aufrufe derselben Funktion benötigen zwei verschiedene call_id-Werte.

Strukturierte Ausgaben. 3.8 Flash unterstützt strukturierte Ausgaben und Funktionsaufrufe mit demselben Modell. Das saubere Muster sind Werkzeuge für die Schleife und ein JSON-Schema für die endgültige Antwort, sodass die model_output, die die Schleife schließt, maschinenlesbar ist statt in Prosa. Googles Seiten für Funktionsaufrufe und strukturierte Ausgaben dokumentieren die Konfiguration. Fälschen Sie es nicht, indem Sie ein Dummy-Werkzeug deklarieren und seine arguments lesen; das bricht in dem Moment zusammen, in dem das Modell entscheidet, dass es nichts aufzurufen hat.

Alles oben Genannte geht davon aus, dass das Modell Ihr System über deklarierte Funktionen erreicht. Google listet auch "Computer use (Preview)" für 3.8 Flash auf; wenn eine strukturierte API das Bildschirmsteuern eines Agenten übertrifft, siehe Computer use vs. structured APIs.

Testen der Werkzeugschleife in Apidog

Eine Werkzeugschleife kann an drei Stellen fehlschlagen: bei der Deklaration, beim ID-Roundtrip und bei der endgültigen Antwort. Sie können alle drei in Apidog abdecken, ohne Ihr echtes Backend zu berühren.

1. Mocken Sie das Backend des Werkzeugs. Definieren Sie GET /orders/{order_id} als Endpunkt und aktivieren Sie dessen Mock-Server. Geben Sie ihm einen festen Antwortkörper, {"status": "in_transit", "eta": "2026-09-05"}, damit jeder Lauf identische Eingaben erhält und jede Änderung in der endgültigen Antwort des Modells auf das Modell zurückzuführen ist, nicht auf Ihre Datenbank. Ihr Harness verweist im Testsystem auf die Mock-URL und in der Produktion auf den echten Dienst.

2. Verketten Sie beide Züge in einem Testszenario. Speichern Sie GEMINI_API_KEY als Umgebungsvariable und referenzieren Sie sie als {{GEMINI_API_KEY}} im x-goog-api-key-Header. Erstellen Sie dann ein Szenario mit drei Schritten:

• Schritt A: POST an /v1beta/interactions mit dem Prompt und der get_order_status-Deklaration. Extrahieren Sie die Interaktions-id und die id, name sowie arguments.order_id des function_call-Schritts in Variablen.
• Schritt B: GET des Mock-Endpunkts mit {{order_id}}. Dies ist Ihr Schritt „Funktion ausführen“.
• Schritt C: POST des function_result mit call_id auf {{call_id}}, name auf {{tool_name}}, previous_interaction_id auf {{interaction_id}} und dem Body von Schritt B als Textteil.

3. Bestätigen Sie, was wichtig ist.

• Schritt A gibt 200 zurück und enthält einen Schritt, dessen type function_call ist, mit name gleich get_order_status.
• Das extrahierte arguments.order_id ist gleich A1029, was beweist, dass das Modell den Prompt geparst und das Schema eingehalten hat.
• Schritt C gibt 200 zurück und endet in einem Schritt, dessen type model_output ist, ohne einen zweiten function_call, was beweist, dass die von Ihnen gesendeten call_id und name akzeptiert wurden und die Schleife in einem Durchgang geschlossen wurde.
• Der endgültige Text enthält in_transit, was beweist, dass das Modell das Werkzeugergebnis anstelle seiner eigenen Vermutung verwendet hat.
• Wenn Sie dasselbe Szenario gegen generateContent ausführen, fügen Sie eine Obergrenze für usageMetadata.thoughtsTokenCount pro thinking_level hinzu. Das fängt die Kostensteigerung durch „härtere Arbeit“ ab, bevor sie auf Ihrer Rechnung erscheint.

Planen Sie das Szenario so, dass es täglich ausgeführt wird. Das Modellverhalten kann sich bei stillen Updates ändern, und eine Schleife, die letzte Woche in einem Durchgang geschlossen wurde, könnte plötzlich zwei benötigen. Der Leitfaden zum Testen von AI-Agenten-APIs geht tiefer auf mehrstufige Assertions ein, und Sie können Apidog herunterladen, um das Szenario vor jeglichen Kosten mit dem kostenlosen Tarif zu erstellen.

FAQ

Ist call_id bei Gemini 3.8 Flash erforderlich? Ja. Bei der Interactions API benötigt jedes function_result call_id und name; bei generateContent benötigt jede functionResponse die id des Aufrufs und name. Älterer Code, der nur den Namen gesendet hat, schlägt bei Gemini 3-Modellen fehl.

Warum läuft meine Werkzeugschleife bei 3.8 Flash mehr Züge als bei 3.7? Entwurfsbedingt. Google sagt, das Modell „ruft Werkzeuge iterativ auf“ und „kann mehr Tokens für länger laufende und komplexe Aufgaben verwenden“. Begrenzen Sie die Züge in Ihrem Harness und senken Sie das thinking_level; der Leitfaden zu den Thinking Levels enthält die gemessenen Kosten pro Stufe.

Kann ich generateContent immer noch für Funktionsaufrufe verwenden? Ja. Google nennt es veraltet, sagt aber, es bleibe „vollständig unterstützt“ ohne ein Enddatum. Sie führen die Historie selbst, einschließlich der Gedankensignaturen, und die Anruf-ID (bei dieser API als id bezeichnet) plus name sind weiterhin gültig.

Funktioniert thinking_level „minimal“ mit Werkzeugen? Nein. Es gibt einen Validierungsfehler bei 3.8 Flash zurück. Verwenden Sie low.

Wie viel kostet eine werkzeugintensive Aufgabe? Die Token-Preise betragen 0,75 $ Input und 3,75 $ Output pro 1 Million Tokens bis zum 31. Dezember 2026, wobei das Denken als Output abgerechnet wird. Artificial Analysis maß 0,58 $ pro Aufgabe bei high, 0,41 $ bei medium und 0,24 $ bei low in ihrem Index. Ihre Aufgaben werden sich unterscheiden, also überprüfen Sie die Token-Anzahlen und messen Sie.

Die Schleife mit einer Obergrenze ausliefern

Deklarieren Sie das Werkzeug, lesen Sie den function_call-Schritt und geben Sie function_result mit sowohl call_id als auch name unter previous_interaction_id zurück. Das ist der gesamte Vertrag. Was sich mit Gemini 3.8 Flash geändert hat, ist die Bereitschaft des Modells, zu schleifen, daher benötigt das Harness eine Zugbegrenzung, ein thinking_level pro Route und ein Timeout, bevor es in Produktion geht. Mocken Sie das Backend, verketten Sie die beiden Züge, stellen Sie sicher, dass die ID-Roundtrips funktionieren, und planen Sie den Lauf. Googles Seite Was ist neu in Gemini 3.8 Flash enthält die Migrationshinweise; der Pillar-Leitfaden enthält alles Weitere über das Modell.