Interactions API

Die Interactions API ist der neue Standard für die Entwicklung mit Gemini und wird für alle neuen Projekte empfohlen. Sie ist für Agenten-Workflows, serverseitige Statusverwaltung und komplexe multimodale Unterhaltungen mit mehreren Gesprächsrunden optimiert. Die ursprüngliche generateContent API wird weiterhin vollständig unterstützt.

Gründe für die Verwendung der Interactions API

  • Serverseitige Verlaufsverwaltung: Vereinfachte Abläufe mit mehreren Gesprächsrunden über previous_interaction_id. Der Server aktiviert den Status standardmäßig (store=true), Sie können aber auch zustandsloses Verhalten aktivieren, indem Sie store=false festlegen.
  • Beobachtbare Ausführungsschritte: Mit typisierten Schritten lassen sich komplexe Abläufe einfach debuggen und die Benutzeroberfläche für Zwischenereignisse (z. B. Gedanken oder Such-Widgets) rendern.
  • Für Agenten-Workflows entwickelt: Native Unterstützung für die mehrstufige Toolnutzung, Orchestrierung und komplexe Denkprozesse durch typisierte Ausführungsschritte.
  • Lang andauernde und Hintergrundaufgaben: Unterstützt das Auslagern zeitaufwendiger Vorgänge wie Deep Think und Deep Research an Hintergrundprozesse mit background=true.
  • Zugriff auf neue Modelle und Funktionen: Künftig werden neue Modelle, die über die Hauptmodellfamilie hinausgehen, sowie neue agentische Funktionen und Tools ausschließlich in der Interactions API eingeführt.

Verwenden Sie die Interactions API, wenn Sie ein neues Projekt starten, Agenten-Anwendungen entwickeln oder eine serverseitige Unterhaltungsverwaltung benötigen. Verwenden Sie generateContent, wenn Sie eine vorhandene Integration haben, die Ihren Anforderungen entspricht, oder wenn Sie eine Funktion benötigen, die in der Interactions API noch nicht verfügbar ist, z. B. die Batch API oder explizites Caching.

Jetzt starten

  • Coding-Agent einrichten: Stellen Sie eine Verbindung zum Gemini Docs MCP her und installieren Sie die gemini-interactions-api Funktion, um Ihrem Assistenten direkten Zugriff auf die neueste Entwicklerdokumentation und Best Practices zu ermöglichen. Coding-Agent einrichten →
  • Von generateContent migrieren: Wenn Sie eine vorhandene Integration haben, folgen Sie der Migrationsanleitung um zur Interactions API zu wechseln.
  • Kurzanleitung ausprobieren: Beginnen Sie mit einem minimalen funktionierenden Beispiel in der Kurzanleitung zur Interactions API.

Leitfäden für Funktionen

In diesen Leitfäden erfahren Sie mehr über die spezifischen Funktionen der Interactions API. Mit der Schaltfläche auf diesen Seiten können Sie zwischen „generateContent“ und „Interactions API“ wechseln:

Funktionsweise der Interactions API

Die Interactions API dreht sich um eine Kernressource: die Interaction. Eine Interaction stellt eine vollständige Gesprächsrunde oder Aufgabe dar. Sie fungiert als Sitzungsaufzeichnung und enthält den gesamten Verlauf einer Interaktion als chronologische Abfolge von Ausführungsschritten. Zu diesen Schritten gehören Gedanken des Modells, serverseitige oder clientseitige Toolaufrufe und -ergebnisse (z. B. function_call und function_result) sowie die endgültige model_output. Die gespeicherte Ressource (über interactions.get abgerufen) enthält auch user_input-Schritte für den vollständigen Kontext. Die Antwort von interactions.create gibt jedoch nur vom Modell generierte Schritte zurück.

Wenn Sie interactions.create aufrufen, erstellen Sie eine neue Interaction Ressource.

Ausgaben mit SDK-Hilfseigenschaften aufrufen

Die Interactions API gibt zwar eine strukturierte Zeitachse der Ausführungsschritte (z. B. Gedanken, Suchanfragen und Funktionsaufrufe) zurück, Sie müssen die Schritte aber nicht manuell durchlaufen, um die endgültige Modellantwort zu erhalten.

Die Google GenAI SDKs bieten Hilfseigenschaften direkt für das zurückgegebene Interaction-Objekt, um auf die Ausgaben für verschiedene Modalitäten zuzugreifen:

SDK-Hilfseigenschaft Rückgabetyp Beschreibung
interaction.output_text String Gibt die letzten Textblöcke in der Antwort des Modells zurück. Wenn die Antwort auf mehrere aufeinanderfolgende TextContent-Blöcke aufgeteilt ist, werden sie automatisch zusammengefügt. Frühere Textblöcke, die durch nicht textuelle Inhalte (z. B. Gedanken, Bilder, Audio oder Toolaufrufe) getrennt sind, werden nicht berücksichtigt. Bei komplexen oder verschachtelten multimodalen Antworten müssen Sie stattdessen manuell über steps iterieren.
interaction.output_image ImageContent oder None Gibt den letzten Bildblock zurück, der vom Modell in der aktuellen Anfrage generiert wurde.
interaction.output_audio AudioContent oder None Gibt den letzten Audioblock zurück, der vom Modell in der aktuellen Anfrage generiert wurde.

Für erweiterte Anwendungsfälle wie das Rendern von Zwischenprozessen, das Prüfen von Toolaufrufen Schritt für Schritt oder das Debuggen können Sie die Zeitachse der Rohdaten von interaction.steps weiterhin manuell prüfen und durchlaufen.

Serverseitige Statusverwaltung

Sie können die id einer abgeschlossenen Interaktion in einem nachfolgenden Aufruf mit dem previous_interaction_id Parameter verwenden, um die Unterhaltung fortzusetzen. Der Server verwendet diese ID, um den Unterhaltungsverlauf abzurufen. So müssen Sie den gesamten Chatverlauf nicht noch einmal senden.

Mit dem Parameter previous_interaction_id wird nur der Unterhaltungsverlauf (Eingaben und Ausgaben) beibehalten.previous_interaction_id Die anderen Parameter sind interaktionsbezogen und gelten nur für die spezifische Interaktion, die Sie gerade generieren:

  • tools
  • system_instruction
  • generation_config (einschließlich thinking_level, temperature usw.)

Das bedeutet, dass Sie diese Parameter in jeder neuen Interaktion noch einmal angeben müssen, wenn sie angewendet werden sollen. Diese serverseitige Statusverwaltung ist optional. Sie können auch im zustandslosen Modus arbeiten, indem Sie bei jeder Anfrage den vollständigen Unterhaltungsverlauf senden.

Datenspeicherung und -aufbewahrung

Standardmäßig speichert die API alle Interaction-Objekte (store=true), um die Verwendung von serverseitigen Statusverwaltungsfunktionen (mit previous_interaction_id), die Ausführung im Hintergrund (mit background=true) und die Beobachtbarkeit zu vereinfachen.

  • Kostenpflichtiges Abo: Das System behält Interaktionen 55 Tage lang bei.
  • Kostenlose Stufe: Das System behält Interaktionen 1 Tag lang bei.

Wenn Sie das nicht möchten, können Sie in Ihrer Anfrage store=false festlegen. Diese Einstellung ist unabhängig von der Statusverwaltung. Sie können die Speicherung für jede Interaktion deaktivieren. Beachten Sie jedoch, dass store=false nicht mit background=true kompatibel ist und die Verwendung von previous_interaction_id für nachfolgende Gesprächsrunden verhindert.

Sie können gespeicherte Interaktionen jederzeit mit der Methode „Löschen“ löschen, die in der API-Referenz beschrieben ist. Sie können Interaktionen nur löschen, wenn Sie die Interaktions-ID kennen.

Nach Ablauf der Aufbewahrungsfrist werden Ihre Daten automatisch gelöscht.

Das System verarbeitet Interaction-Objekte gemäß den Nutzungsbedingungen.

Best Practices

  • Cache-Trefferrate: Wenn Sie previous_interaction_id verwenden, um Unterhaltungen fortzusetzen, kann das System das implizite Caching für den Unterhaltungsverlauf einfacher nutzen. Das verbessert die Leistung und senkt die Kosten.
  • Interaktionen kombinieren: Sie können Agenten- und Modellinteraktionen innerhalb einer Unterhaltung kombinieren. Sie können beispielsweise einen spezialisierten Agenten wie den Deep Research Agent für die erste Datenerhebung verwenden und dann ein Standard-Gemini-Modell für Folgeaufgaben wie das Zusammenfassen oder Neuformatieren nutzen. Diese Schritte können Sie mit previous_interaction_id verknüpfen.

Unterstützte Modelle und Agenten

Modellname Typ Modell-ID
Gemini 3.5 Flash Modell gemini-3.5-flash
Gemini 3.1 Flash Lite Modell gemini-3.1-flash-lite
Gemini 3.1 Flash Lite (Vorabversion) Modell gemini-3.1-flash-lite-preview
Gemini 3.1 Pro (Vorabversion) Modell gemini-3.1-pro-preview
Gemini 3 Flash (Vorabversion) Modell gemini-3-flash-preview
Gemini 2.5 Pro Modell gemini-2.5-pro
Gemini 2.5 Flash Modell gemini-2.5-flash
Gemini 2.5 Flash Lite Modell gemini-2.5-flash-lite
Lyria 3 Clip (Vorabversion) Modell lyria-3-clip-preview
Lyria 3 Pro (Vorabversion) Modell lyria-3-pro-preview
Deep Research (Vorabversion) Agent deep-research-pro-preview-12-2025
Deep Research (Vorabversion) Agent deep-research-preview-04-2026
Deep Research (Vorabversion) Agent deep-research-max-preview-04-2026

SDKs

Sie können die aktuelle Version der Google GenAI SDKs verwenden, um auf die Interactions API zuzugreifen.

  • In Python ist das das Paket google-genai ab Version 1.55.0.
  • In JavaScript ist das das Paket @google/genai ab Version 1.33.0.

Weitere Informationen zum Installieren der SDKs finden Sie auf der Seite „ Bibliotheken“.

Beschränkungen

  • Betastatus: Die Interactions API befindet sich in der Betaphase oder Vorabversion. Änderungen an Funktionen und Schemas sind vorbehalten.
  • Remote-MCP: Gemini 3 unterstützt kein Remote-MCP. Diese Funktion wird bald eingeführt.

Die folgenden Funktionen werden von der generateContent API unterstützt, sind aber in der Interactions API noch nicht verfügbar:

Wichtige Änderungen

Die Interactions API befindet sich derzeit in der frühen Betaphase. Wir entwickeln und verfeinern die API-Funktionen, Ressourcenschemas und SDK-Schnittstellen aktiv auf Grundlage der tatsächlichen Nutzung und des Entwicklerfeedbacks. Daher kann es zu wichtigen Änderungen kommen.

Bisherige wichtige Änderungen:

  • Steps-Schema: Ein neues Steps-Array ersetzt das Outputs-Array und bietet eine strukturierte Zeitachse für jede Gesprächsrunde.

Informationen zur neuesten wichtigen Änderung und zur Migration finden Sie in der Migrationsanleitung für wichtige Änderungen (Mai 2026).

Weitere mögliche Updates umfassen Änderungen an Schemas für Eingabe und Ausgabe, SDK-Methodensignaturen und Objektstrukturen sowie an bestimmten Funktionen.

Für Produktionsarbeitslasten sollten Sie weiterhin die Standard generateContent API verwenden. Sie ist weiterhin der empfohlene Weg für stabile Bereitstellungen und wir werden sie aktiv weiterentwickeln und warten.

Feedback

Ihr Feedback ist entscheidend für die Entwicklung der Interactions API. Teilen Sie uns Ihre Meinung mit, melden Sie Fehler oder fordern Sie Funktionen in unserem Google AI Developer Community-Forum an.

Nächste Schritte