Interactions API – Übersicht

Die Interactions API bietet eine einheitliche, zustandsbehaftete Schnittstelle zum Erstellen von Anwendungen mit generativer KI und agentischen Workflows mit Gemini-Modellen und ‑Agenten, die auf der Gemini Enterprise Agent Platform gehostet werden. Es gibt zwar eine Überschneidung mit der vorhandenen generateContent API, aber die generateContent API wird weiterhin vollständig unterstützt.

Gründe für die Verwendung der Interactions API

Die Interactions API bietet mehrere entscheidende Vorteile für das Erstellen von Anwendungen mit generativer KI und agentischen Workflows:

  • Eine einzige API für Modelle und Agenten: Ein einheitlicher Endpunkt und ein einheitliches Muster zum direkten Aufrufen von Standard-Gemini-Modellen sowie spezialisierten Agenten (z. B. Gemini Deep Research Agent und benutzerdefinierte verwaltete Agenten).
  • Neue Funktionen sofort verfügbar: Funktionen wie optionaler serverseitiger Unterhaltungsstatus mit previous_interaction_id, beobachtbare Ausführungsschritte für das Debugging und die UI-Wiedergabe sowie die Hintergrundausführung für zeitaufwendige Aufgaben mit background=true.
  • Hier werden neue Funktionen eingeführt: Künftig werden alle neuen Modelle, multimodalen Funktionen, Tools und agentischen Funktionen in der Interactions API unterstützt.

Funktionsweise der Interactions API

Die Interactions API dreht sich um die Interaction Ressource. Eine Interaction stellt eine vollständige Runde in einer Unterhaltung oder Aufgabe dar und fungiert als Sitzungsaufzeichnung mit einer chronologischen Abfolge von Ausführungsschritten (steps):

  • user_input: Die Eingabenachrichten, multimodalen Dateien oder Toolergebnisse, die für die Runde bereitgestellt wurden. Gespeicherte Interaktionen, die mit interactions.get abgerufen werden, enthalten user_input-Schritte für den vollständigen Kontext, während interactions.create-Antworten nur die Schritte zurückgeben, die während dieser Runde generiert wurden.
  • thought: Zusammenfassungen der Zwischenschritte, die vom Modell oder Agenten generiert werden, während er seine Antwort plant.
  • Toolaufruf- und Ergebnisschritte: Clientseitige oder serverseitige Toolaufrufe und ‑ausgaben (z. B. function_call und function_result).
  • model_output: Der endgültige Text, strukturierte JSON oder multimodale Inhalt, der vom Modell oder Agenten erstellt wurde.

Wenn Sie interactions.create aufrufen, verarbeitet die Agent Platform Ihre Eingabe, führt alle konfigurierten serverseitigen Tools oder Agentenschleifen aus und gibt die resultierende Interaction Ressource zurück. Code beispiele für Python, TypeScript/JavaScript und REST finden Sie im Entwicklerleitfaden zur Interactions API.

Unterstützte Modelle

Die folgenden Gemini-Modelle unterstützen die Interactions API:

Klicken Sie, um die unterstützten Modelle zu maximieren.

Zusätzlich zu den oben aufgeführten Modellen unterstützt die Interactions API die folgenden spezialisierten multimodalen Modelle und Audiogeneratoren:

  • gemini-omni-flash-preview: Leistungsstarkes multimodales Modell für die Unterhaltungsvideogenerierung, ‑bearbeitung und ‑steuerung.
  • lyria-3-clip-preview und lyria-3-pro-preview: Modelle zur Musikgenerierung für hochwertige Audioclips und vollständige Songkompositionen (nur bei zustandslosen Interaktionen mit store=false unterstützt).

Unterstützte Agenten

Sie können die folgenden Agenten über die Interactions API aufrufen, indem Sie anstelle von model den Parameter agent angeben:

  • antigravity-preview-05-2026: Autonomer Agent für allgemeine Zwecke, konzipiert für mehrstufige Problemlösung, Coding, Dateioperationen und Toolnutzung.
  • deep-research-preview-04-2026: Gemini Deep Research Agent für autonome, mehrstufige Web-Recherche und ‑Synthese.
  • Benutzerdefinierte verwaltete Agenten die auf der Agent Platform bereitgestellt werden.

Funktionen und Spezifikationen

In den folgenden Abschnitten werden die Kernfunktionen, technischen Spezifikationen und betrieblichen Aspekte der Interactions API beschrieben.

Zustandsverwaltung

Standardmäßig speichert die Interactions API Anfragen, sodass Sie die serverseitigen Funktionen zur Zustandsverwaltung mit previous_interaction_id nutzen können. Sie können das zustandslose Verhalten aktivieren, indem Sie store=false festlegen.

Unterstützte Tools und Fundierung

Die folgenden integrierten Tools, Fundierungsanbieter und Suchfunktionen werden für Gemini 3-Modelle in der Interactions API unterstützt:

  • Fundierung mit der Google Suche und Web Grounding for Enterprise: Fundiert Modellantworten mit Echtzeit-Webinformationen aus der Google Suche oder Web Grounding for Enterprise.
  • Agent Search und RAG Engine auf der Gemini Enterprise Agent Platform: Fundiert Modellantworten anhand privater Unternehmensdatenspeicher und Dokument repositorys mit Agent Search und RAG Engine.
  • xAI Search: Verbindet Modelle mit der Echtzeit-Suche in sozialen Medien und der Wissens fundierung.
  • Parallel Search: Fundiert Modellantworten mit öffentlichen Echtzeit-Webdaten die von der Such-API von Parallel Web Systems bereitgestellt werden.
  • Code-Ausführung: Ermöglicht dem Modell, Python-Code in einer sicheren Sandbox-Umgebung zu generieren und auszuführen.
  • Funktionsaufrufe: Ermöglicht Modellen, eine Verbindung zu externen Tools, APIs und Datenbanken herzustellen, indem strukturierte Funktions argumente zurückgegeben werden.

Die Interactions API unterstützt Web Grounding for Enterprise und die Fundierung mit der Google Suche. Ihre Nutzung dieser Funktionen unterliegt zusätzlich den dienstspezifischen Nutzungsbedingungen.

Abrechnung

Die Nutzung der Interactions API wird basierend auf dem Tokenverbrauch abgerechnet.

Die Abrechnung für unterbrochene oder nicht erfüllte Anfragen erfolgt so:

  • Manuelle Stornierungen: Wenn eine Interaktion vor Abschluss storniert wird (z. B. durch Senden einer Stornierungsanfrage), werden Ihnen die bis zum Zeitpunkt der Stornierung verbrauchten Tokens in Rechnung gestellt.
  • Fehlgeschlagene Anfragen: Wenn eine Interaktionsanfrage aufgrund eines internen Systemfehlers oder eines Backend-Fehlers fehlschlägt, wird Ihnen die fehlgeschlagene Anfrage nicht in Rechnung gestellt.

Sicherheit und Compliance

Während der Vorschau gelten für die Interactions API die folgenden Aspekte in Bezug auf Sicherheit, Compliance und Datenstandort:

  • Sicherheits- und Compliance-Zertifizierungen: Die Vorschau der Interactions API unterstützt FedRAMP nicht und entspricht nicht den Anforderungen von Department of Defense (DoD) Impact Level 5 (IL5) oder International Traffic in Arms Regulations (ITAR).
  • Kundenverwaltete Verschlüsselungsschlüssel (CMEK): Die Interactions API unterstützt CMEK für gespeicherte Interaktionsdaten über Serving-Profile (mit scope auf INTERACTIONS_API gesetzt) in den Multi-Regionen us und eu.
  • VPC Service Controls: Die Vorschau der Interactions API unterstützt VPC Service Controls (VPC-SC), um Ihren API-Perimeter zu schützen.
  • Datenstandort: Die Vorschau der Interactions API unterstützt den Datenstandort nicht und gibt keine Zusicherungen zur Sitzungsspeicherung.
  • Endpunkte: Die Vorschau der Interactions API unterstützt den globalen Endpunkt (locations/global) sowie die Multiregion-Endpunkte us und eu (locations/us und locations/eu), wenn CMEK verwendet wird.

Unterstützte SDKs

Sie können über das einheitliche Google Gen AI SDK oder direkte REST-Aufrufe auf die Interactions API zugreifen:

  • Python: google-genai Version 2.3.0 oder höher
  • TypeScript / JavaScript: @google/genai Version 2.3.0 oder höher
  • Go: google.golang.org/genai
  • Java: com.google.genai:google-genai

Ältere SDKs (google-cloud-aiplatform, @google-cloud/vertexai und google-generativeai) unterstützen die Interactions API nicht.

Nächste Schritte