Interactions API – Übersicht

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

Vorteile der Interactions API

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

  • Eine API für Modelle und Agents: Ein einheitlicher Endpunkt und ein einheitliches Muster zum direkten Aufrufen von Standard-Gemini-Modellen sowie von spezialisierten Agents (z. B. Gemini Deep Research Agent und benutzerdefinierte verwaltete Agents).
  • Neue sofort einsatzbereite Funktionen: Funktionen wie der optionale serverseitige Konversationsstatus mit previous_interaction_id, beobachtbare Ausführungsschritte für das Debugging und das Rendern der Benutzeroberfläche sowie die Hintergrundausführung für zeitaufwendige Aufgaben mit background=true.
  • Einführung neuer Funktionen: Künftig werden alle neuen Modelle, multimodalen Funktionen, Tools und Agent-Funktionen in der Interactions API unterstützt.

Funktionsweise der Interactions API

Die Interactions API dreht sich um die Ressource Interaction. Ein Interaction stellt eine vollständige Runde in einer Unterhaltung oder Aufgabe dar und fungiert als Sitzungsaufzeichnung, die eine chronologische Reihenfolge der Ausführung enthältsteps:

  • user_input: Die Eingabenachrichten, multimodalen Dateien oder Tool-Ergebnisse, die für den Zug bereitgestellt werden. 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 in diesem Zug generierten Schritte zurückgeben.
  • thought: Zusammenfassungen der Zwischenbegründung, die vom Modell oder Agenten generiert werden, während es seine Antwort plant.
  • Tool-Aufruf- und Ergebnisschritte: Clientseitige oder serverseitige Tool-Aufrufe und Ausgaben (z. B. function_call und function_result).
  • model_output: Der endgültige Text, das strukturierte JSON oder die multimodalen Inhalte, die vom Modell oder Agent generiert wurden.

Wenn Sie interactions.create aufrufen, verarbeitet die Agent Platform Ihre Eingabe, führt alle konfigurierten serverseitigen Tools oder Agent-Schleifen aus und gibt die resultierende Interaction-Ressource zurück.

Unterstützte Modelle

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

Klicken Sie, um unterstützte Modelle zu maximieren.

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

  • gemini-omni-flash-preview: Leistungsstarkes multimodales Modell für die Videogenerierung, ‑bearbeitung und ‑steuerung per Prompt.
  • lyria-3-clip-preview und lyria-3-pro-preview: Modelle für generative Musik für Hi-Fi-Audio-Clips und Kompositionen für ganze Songs (nur in zustandslosen Interaktionen mit store=false unterstützt).

Unterstützte KI-Agenten

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

  • antigravity-preview-05-2026: Autonomer Agent für allgemeine Zwecke, der für mehrstufige Problemlösung, Programmierung, Dateioperationen und die Verwendung von Tools entwickelt wurde.
  • deep-research-preview-04-2026: Gemini Deep Research-Agent für die autonome, mehrstufige Web-Recherche und ‑Synthese.
  • Benutzerdefinierte verwaltete KI‑Agenten, die in der Agent Platform bereitgestellt werden.

Funktionen und Spezifikationen

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

Zustandsverwaltung

Standardmäßig werden Anfragen in der Interactions API gespeichert, damit Sie die serverseitigen Funktionen zur Statusverwaltung 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 Webfundierung für Unternehmen: Fundiert Modellantworten mit Echtzeit-Webinformationen aus der Google Suche oder der Webfundierung für Unternehmen.
  • Agent Search und RAG Engine auf der Gemini Enterprise Agent Platform: Mit Agent Search und RAG Engine werden Modellantworten auf private Unternehmensdatenspeicher und Dokumentrepositorys gestützt.
  • xAI Search: Verbindet Modelle mit Echtzeit-Social-Search und Wissensfundierung.
  • Parallel Search: Modellantworten werden mit öffentlichen Echtzeit-Webdaten fundiert, die von der Such-API von Parallel Web Systems bereitgestellt werden.
  • Code-Ausführung: Das Modell kann Python-Code in einer sicheren Sandbox-Umgebung generieren und ausführen.
  • Funktionsaufrufe: Ermöglichen es Modellen, eine Verbindung zu externen Tools, APIs und Datenbanken herzustellen, indem sie strukturierte Funktionsargumente zurückgeben.

Die Interactions API unterstützt die Web-Fundierung für 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 auf Grundlage des Tokenverbrauchs abgerechnet.

Die Abrechnung unterbrochener oder nicht erfüllter Anfragen erfolgt so:

  • Manuelle Abbrüche: Wenn eine Interaktion vor Abschluss abgebrochen wird (z. B. durch Senden einer Abbruchanfrage), werden Ihnen die bis zum Zeitpunkt des Abbruchs verbrauchten Tokens in Rechnung gestellt.
  • Fehlgeschlagene Anfragen: Wenn eine Interaktionsanfrage aufgrund eines internen Systemfehlers oder eines Back-End-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 Sicherheits-, Compliance- und Datenstandort-Aspekte:

  • Sicherheits- und Compliance-Zertifizierungen: Die Interactions API-Vorabversion unterstützt weder FedRAMP noch kundenverwaltete Verschlüsselungsschlüssel (Customer-Managed Encryption Keys, CMEK) und entspricht nicht den Anforderungen des Department of Defense (DoD) Impact Level 5 (IL5) oder der International Traffic in Arms Regulations (ITAR).
  • VPC Service Controls: Die Interactions API-Vorschau unterstützt VPC Service Controls (VPC-SC), um Ihren API-Perimeter zu schützen.
  • Datenstandort: Die Interactions API-Vorabversion unterstützt keinen Datenstandort und es gibt keine Zusagen zur Sitzungsspeicherung.
  • Endpunkte: Die Interactions API-Vorabversion unterstützt nur globale Endpunkte (locations/global).

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

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

Nächste Schritte