Interactions API

Die Interactions API ist der neue empfohlene Standard für die Entwicklung mit Gemini. Sie ist für agentische Workflows, serverseitige Statusverwaltung und komplexe multimodale Multi-Turn-Unterhaltungen optimiert. Die ursprüngliche generateContent API wird weiterhin vollständig unterstützt.

Vorteile der Interactions API

  • Serverseitige Verlaufsverwaltung: Vereinfachte Abläufe mit mehreren Durchgängen über previous_interaction_id. Der Server aktiviert den Status standardmäßig (store=true). Sie können jedoch das statuslose Verhalten aktivieren, indem Sie store=false festlegen.
  • Beobachtbare Ausführungsschritte: Durch die typisierten Schritte lassen sich komplexe Abläufe einfach debuggen und die Benutzeroberfläche für Zwischenereignisse (z. B. Gedanken oder Such-Widgets) rendern.
  • Für agentische Workflows entwickelt: Native Unterstützung für die mehrstufige Tool-Nutzung, Orchestrierung und komplexe Reasoning-Abläufe durch typisierte Ausführungsschritte.
  • Lang andauernde und Hintergrundaufgaben: Unterstützt das Auslagern zeitaufwendiger Vorgänge an Hintergrundprozesse mit background=true. Dies wird sowohl für Modelle (z. B. Deep Think) als auch für Agents (z. B. Deep Research) unterstützt.
  • Zugriff auf neue Modelle und Funktionen: Künftig werden neue Modelle, die über die Kernfamilie hinausgehen, sowie neue agentische Funktionen und ‑Tools ausschließlich über die Interactions API eingeführt.

Verwenden Sie die Interactions API, wenn Sie ein neues Projekt starten, Agent-basierte Anwendungen entwickeln oder die serverseitige Konversationsverwaltung 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 den gemini-interactions-api-Skill, damit Ihr Assistent direkten Zugriff auf die neuesten Entwicklerdokumente und Best Practices hat. Coding-Agent einrichten →
  • Von generateContent migrieren: Wenn Sie eine bestehende Integration haben, folgen Sie der Migrationsanleitung, um zur Interactions API zu wechseln.
  • Kurzanleitung ausprobieren: In der Kurzanleitung für die Interactions API finden Sie ein minimales funktionierendes Beispiel.

Leitfäden für Funktionen

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

Funktionsweise der Interactions API

Die Interactions API dreht sich um eine zentrale Ressource: die Interaction. Ein Interaction stellt einen vollständigen Zug in einer Unterhaltung oder Aufgabe dar. Es dient als Sitzungsaufzeichnung und enthält den gesamten Verlauf einer Interaktion als chronologische Abfolge von Ausführungsschritten. Diese Schritte umfassen Modellüberlegungen, serverseitige oder clientseitige Tool-Aufrufe und Ergebnisse (z. B. function_call und function_result) sowie die endgültige model_output. Die gespeicherte Ressource (abgerufen über interactions.get) enthält auch user_input-Schritte für den vollständigen Kontext. Die interactions.create-Antwort gibt jedoch nur vom Modell generierte Schritte zurück.

Wenn Sie einen Aufruf an interactions.create senden, erstellen Sie eine neue Interaction-Ressource.

Über SDK-Hilfseigenschaften auf Ausgaben zugreifen

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

Die Google GenAI SDKs bieten praktische Attribute 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 diese automatisch zusammengefügt. Sie enthält keine früheren Textblöcke, die durch Nicht-Textinhalte (z. B. Gedanken, Bilder, Audio oder Tool-Aufrufe) getrennt sind. 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.

Bei komplexen Anwendungsfällen, z. B. beim Rendern von Zwischenüberlegungen, beim Untersuchen von schrittweisen Toolaufrufen oder beim Debuggen, können Sie die Roh-interaction.steps-Zeitachse weiterhin manuell untersuchen und durchlaufen.

Serverseitige Statusverwaltung

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

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

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

Das bedeutet, dass Sie diese Parameter bei 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.

Ausführung im Hintergrund

Bei Aufgaben mit langer Laufzeit können Sie Interaktionen im Hintergrund ausführen, indem Sie background=true in Ihrer Anfrage festlegen. Dies wird für beide unterstützt:

  • Modelle: Nützlich für Aufgaben, die länger dauern, z. B. Aufgaben, bei denen Denken verwendet wird.
  • KI-Agenten: Erforderlich für lang andauernde Agenten-Workflows wie Deep Research.

Wenn die App im Hintergrund ausgeführt wird:

  • Sie müssen store=true (Standard) festlegen, da die Interaktionsressource vom System gespeichert werden muss, damit Sie sie später abrufen können.
  • Der erste Aufruf von interactions.create wird sofort mit dem Status in_progress zurückgegeben.
  • Sie können den Status und die Ergebnisse der Interaktion abrufen, indem Sie interactions.get mit der Interaktions-ID aufrufen oder Webhooks konfigurieren, um Benachrichtigungen zu erhalten, wenn die Interaktion abgeschlossen ist.
  • Sie können die Interaktion auch streamen, um Fortschrittsaktualisierungen zu erhalten.

Datenspeicherung und ‑aufbewahrung

Standardmäßig werden alle Interaktionsobjekte (store=true) von der API gespeichert, um die Verwendung von serverseitigen Funktionen zur Statusverwaltung (mit previous_interaction_id), die Ausführung im Hintergrund (mit background=true) und die Beobachtbarkeit zu vereinfachen.

  • Aboversion: Das System speichert Interaktionen 55 Tage lang.
  • Kostenlose Stufe: Das System behält Interaktionen einen Tag lang bei.

Wenn Sie das nicht möchten, können Sie store=false in Ihrer Anfrage 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 Turns verhindert.

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

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

Das System verarbeitet Interaktionsobjekte gemäß den Nutzungsbedingungen.

Best Practices

  • Cache-Trefferquote: Wenn Sie previous_interaction_id verwenden, um Unterhaltungen fortzusetzen, kann das System den impliziten Cache für den Unterhaltungsverlauf leichter nutzen. Das verbessert die Leistung und senkt die Kosten.
  • Interaktionen mischen: Sie können Agent- und Modellinteraktionen in einem Gespräch mischen. 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 Umformatieren nutzen. Diese Schritte lassen sich mit dem previous_interaction_id verknüpfen.

Unterstützte Modelle und KI-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 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-Vorschau 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 dies das Paket google-genai ab Version 1.55.0.
  • In JavaScript ist das das @google/genai-Paket 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 bzw. in der Vorschau. Funktionen und Schemas können sich ändern.
  • 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 noch nicht in der Interactions API verfügbar:

Wichtige Änderungen

Die Interactions API befindet sich derzeit in einer frühen Betaphase. Wir entwickeln und optimieren die API-Funktionen, Ressourcenschemas und SDK-Schnittstellen auf Grundlage der praktischen Nutzung und des Entwicklerfeedbacks. Daher kann es zu grundlegenden Änderungen kommen.

Bestehende nicht abwärtskompatible Änderungen:

  • Schrittschema: Ein neues Schritte-Array ersetzt das Ausgaben-Array und bietet eine strukturierte Zeitachse für jede Interaktion.

Informationen zur letzten nicht abwärtskompatiblen Änderung und zur Migration finden Sie im Migrationsleitfaden für nicht abwärtskompatible Änderungen (Mai 2026).

Andere potenzielle Aktualisierungen können Änderungen an Schemas für Ein- und Ausgabe, SDK-Methodensignaturen und Objektstrukturen sowie an bestimmten Funktionsweisen umfassen.

Für Produktionsarbeitslasten sollten Sie weiterhin die Standard-API generateContent verwenden. Es ist weiterhin der empfohlene Weg für stabile Bereitstellungen und wir werden es weiterhin aktiv entwickeln und pflegen.

Feedback

Ihr Feedback ist für die Entwicklung der Interactions API von entscheidender Bedeutung. Im Google AI Developer Community-Forum können Sie Ihre Meinung äußern, Fehler melden oder Funktionen anfragen.

Nächste Schritte