Interactions API

Die Interactions API ist das neue Standard-Primitive für die Entwicklung mit Gemini und wird für alle neuen Projekte empfohlen. 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: 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 agentische Workflows entwickelt: Native Unterstützung für die mehrstufige Tool-Nutzung, Orchestrierung und komplexe Reasoning-Abläufe durch typisierte Ausführungsschritte.
  • Lang andauernde Aufgaben und Hintergrundaufgaben: Unterstützt das Auslagern zeitaufwendiger Vorgänge wie Deep Think und Deep Research in Hintergrundprozesse mit background=true.
  • 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, agentische 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 die Überlegungen des Modells, 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 interactions.create aufrufen, erstellen Sie eine neue Interaction-Ressource.

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 (Ein- 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 neu angeben müssen, wenn sie angewendet werden sollen. Diese serverseitige Statusverwaltung ist optional. Sie können auch im zustandslosen Modus arbeiten, indem Sie den vollständigen Unterhaltungsverlauf in jeder Anfrage senden.

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 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 Züge verhindert.

Sie können gespeicherte Interaktionen jederzeit mit der Löschmethode in der API-Referenz löschen. 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 einer Unterhaltung 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.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-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 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 bzw. in der Vorschau. Funktionen und Schemas können sich ändern.
  • Remote-MCP: Gemini 3 unterstützt keine Remote-MCPs. 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 der frühen Betaphase. Wir entwickeln und optimieren die API-Funktionen, Ressourcenschemas und SDK-Schnittstellen basierend auf der tatsächlichen Nutzung und dem Feedback von Entwicklern.

Daher kann es zu funktionsgefährdenden Änderungen kommen. Aktualisierungen können Änderungen an folgenden Elementen umfassen:

  • Schemas für Ein- und Ausgabe.
  • SDK-Methodensignaturen und Objektstrukturen.
  • Spezifische Verhaltensweisen von Funktionen.

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