Entwicklerleitfaden für die Interactions API

Die Interactions API bietet eine einheitliche, zustandsorientierte Oberfläche zum Erstellen von generativen KI-Anwendungen mit Gemini-Modellen und autonomen Agenten auf der Gemini Enterprise Agent Platform. Mit der Interactions API können Sie den Sitzungsspeicher und mehrstufige Unterhaltungen verwalten, Echtzeitantworten streamen, strukturierte Ausgaben erzwingen, integrierte Tools und Grounding aufrufen, Funktionsaufrufe ausführen und lang andauernde Hintergrundaufgaben orchestrieren.

In diesem Leitfaden erfahren Sie, wie Sie das Google Gen AI SDK installieren, Ihren Client authentifizieren und gängige Interaktionsworkflows implementieren. Konzeptionelle Details zum Interaktionslebenszyklus finden Sie in der Übersicht über die Interactions API.

Hinweis

Bevor Sie Anfragen an die Interactions API senden können, müssen Sie Ihr Google Cloud-Projekt und Ihre Entwicklungsumgebung einrichten:

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. Make sure that you have the following role or roles on the project: Agent Platform User (roles/aiplatform.user)

    Check for the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.

    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.
    3. Click Grant access.

    4. In the New principals field, enter your user identifier. This is typically the identifier for a user in a workforce identity pool. For details, see Represent workforce pool users in IAM policies, or contact your administrator.

    5. Click Select a role, then search for the role.
    6. To grant additional roles, click Add another role and add each additional role.
    7. Click Save.

Wichtige Konzepte

In den folgenden Abschnitten wird beschrieben, wie die Interactions API den Status und die Antworten verwaltet:

  • Interaction: Die Interactions API basiert auf einer zentralen Ressource: einer Interaction. Ein Interaction stellt eine vollständige Runde in einer Unterhaltung oder Aufgabe dar und verfolgt die Chronologie der Modellgedanken, Toolaufrufe und endgültigen Ausgaben. Sie bietet eine einheitliche Umgebung für Prompt-Antwort-Interaktionen und komplexe, mehrstufige Agenten-Workflows.

  • Zustandsorientierte Aufbewahrung: Interaktionen werden standardmäßig serverseitig gespeichert (store=True in Python oder store: true in TypeScript/JavaScript). Gespeicherte Interaktionen bleiben 7 Tage lang erhalten und werden danach automatisch gelöscht. Wenn Sie store=False festlegen, wird der zustandslose Modus aktiviert. Dadurch wird die serverseitige Datenaufbewahrung deaktiviert und die Zero Data Retention (ZDR) eingehalten. Im zustandslosen Modus werden auch die previous_interaction_id-Verkettung und die asynchrone Ausführung (background=True) deaktiviert.

  • Antwort-Hilfsprogramme: Ab Version 2.3.0 des Google Gen AI SDK sind praktische Attribute für die Interaktionsantwort verfügbar, darunter interaction.output_text, interaction.output_image und interaction.output_audio. Verwenden Sie interaction.output_text, um Textantworten zu lesen, anstatt das Schritte-Array manuell zu indexieren (z. B. interaction.steps[-1].content[0].text).

Voraussetzungen

Ihre Umgebung und Ihre Anfragen müssen die folgenden Anforderungen erfüllen, bevor Sie die Interactions API einbinden können:

  • Unterstützung von SDK-Versionen: Verwenden Sie eine der unterstützten Google Gen AI SDK-Bibliotheken.

  • Unterstützte Modelle: Verwenden Sie unterstützte Gemini 3-Modelle oder höher. Frühere Modellfamilien unterstützen diese API nicht. Eine vollständige Liste der unterstützten Modelle finden Sie unter Unterstützte Modelle und Zu den neuesten Modellversionen migrieren.

  • Turn-bezogene Parameter: Konfigurationsparameter wie tools, system_instruction und generation_config gelten nur für den aktuellen Turn. Übergeben Sie diese Parameter bei jeder nachfolgenden Interaktionsrunde, wenn Ihr Workflow sie für eine Unterhaltung mit mehreren Runden erfordert.

  • Lange Decodierungen auf Gemini 4 Argon: Wenn Sie Single-Turn-Ausgaben mit mehr als 65.536 Tokens (bis zu 1.048.576 Tokens abzüglich Eingabe-Tokens) auf gemini-4-argon oder gemini-4-argon-cyber-permissive generieren möchten, verwenden Sie die automatische Fortsetzung des Google Gen AI SDK (google-genai >= 2.34.0 für Python, @google/genai >= 2.32.0 für TypeScript/JavaScript, Go >= 1.77.0, Java >= 1.80.0), background=True oder continuation_token auf dem v1beta1-Endpunkt. Codebeispiele und Fortsetzungsregeln finden Sie im Entwicklerhandbuch für Gemini 4 Argon unter „Lange Decodierungen“.

Google Gen AI SDK installieren

Installieren oder aktualisieren Sie das Google Gen AI SDK für Ihre bevorzugte Sprache:

Python

pip install --upgrade "google-genai>=2.3.0"

TypeScript / JavaScript

npm install "@google/genai>=2.3.0"

Go

go get google.golang.org/genai

Java

<dependencies>
  <dependency>
    <groupId>com.google.genai</groupId>
    <artifactId>google-genai</artifactId>
    <version>1.78.0</version>
  </dependency>
</dependencies>

Client authentifizieren

Sie können mit einer der folgenden Authentifizierungsmethoden eine Verbindung zur Interactions API auf der Agent Platform herstellen:

Verbindung über ein Google Cloud -Projekt mit Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) herstellen

Verwenden Sie diese Authentifizierungsmethode für Unternehmensarbeitslasten und Produktionsbereitstellungen in Google Cloud. Initialisieren Sie den Client mit den folgenden Attributen, um sich mit Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) zu authentifizieren:

  • enterprise=True
  • project="PROJECT_ID"
  • location="global"

Wenn Sie noch keine lokalen Anmeldedaten konfiguriert haben, führen Sie gcloud auth application-default login aus.

Ersetzen Sie im folgenden Codebeispiel PROJECT_ID durch IhreGoogle Cloud -Projekt-ID.

Python

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain serverless computing in one sentence.",
)

print(interaction.output_text)

TypeScript / JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
    enterprise: true,
    project: "PROJECT_ID",
    location: "global",
});

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Explain serverless computing in one sentence.",
});

console.log(interaction.output_text);

REST

curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Explain serverless computing in one sentence."
      }]
    }]
  }'

Verbindung im Expressmodus (API-Schlüssel) herstellen

Verwenden Sie diese Authentifizierungsmethode für schnelles Prototyping, einfache Skripts oder Umgebungen, die sich mit einem API-Schlüssel authentifizieren. Übergeben Sie Ihren API-Schlüssel beim Initialisieren des Clients oder im HTTP-Header x-goog-api-key.

Ersetzen Sie im folgenden Codebeispiel API_KEY durch Ihren API-Schlüssel und PROJECT_ID durch Ihre Projekt-ID von Google Cloud .

Python

from google import genai

client = genai.Client(
    enterprise=True,
    api_key="API_KEY",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain serverless computing in one sentence.",
)

print(interaction.output_text)

TypeScript / JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
    enterprise: true,
    apiKey: "API_KEY",
});

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Explain serverless computing in one sentence.",
});

console.log(interaction.output_text);

REST

curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" \
  -H "x-goog-api-key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Explain serverless computing in one sentence."
      }]
    }]
  }'

Häufige Interaktions-Workflows

Nachdem Sie Ihren Client konfiguriert haben, können Sie die Methode interactions.create verwenden, um den Sitzungsspeicher und Multi-Turn-Unterhaltungen zu verwalten, Ausgabetokens in Echtzeit zu streamen, schemavalidiertes JSON zu generieren, integrierte Tools und Fundierung aufzurufen, externe Funktionen aufzurufen und autonome Agenten auszuführen.

Sitzungsspeicher und Unterhaltungsstatus verwalten

Die Interactions API unterstützt sowohl die serverseitige zustandsorientierte Speicherung (store=True, Standard) als auch die clientseitig verwaltete zustandslose Ausführung (store=False). In der folgenden Tabelle werden die zustandsorientierten und zustandslosen Interaktionsmodi verglichen:

Funktion Zustandsorientierter Modus (store=true, Standard) Zustandsloser Modus (store=false)
Serverseitige Persistenz Eingaben, Zwischenschritte und Ausgaben werden 7 Tage lang auf dem Server gespeichert. Deaktiviert die serverseitige Interaktionsspeicherung, um Workflows mit Zero Data Retention (ZDR) zu unterstützen.
Kontext in mehreren Schritten Verknüpft die Interaktionen, indem die vorherige Interaktion id in previous_interaction_id übergeben wird. Erfordert die Übergabe des vollständigen Arrays der vorherigen Unterhaltung steps in input bei jeder Runde. Wenn Sie previous_interaction_id übergeben, wird der Fehler 400 Bad Request zurückgegeben.
Ausführung im Hintergrund (background=true) Unterstützt für langlaufende Modell- und Agenteninteraktionen. Nicht unterstützt. Die asynchrone Ausführung im Hintergrund erfordert eine serverseitige Statuspersistenz.
Methoden für den Sitzungslebenszyklus Unterstützt das Abrufen (get), Auflisten (list), Abbrechen (cancel) und Löschen (delete) von Interaktionen. Nach Abschluss der synchronen oder Streaming-Antwort nicht mehr abrufbar.
Verschlüsselung ruhender Daten Standardmäßig mit einem Google-owned and Google-managed encryption keyoder mit kundenverwalteten Verschlüsselungsschlüsseln (CMEK) in den multiregionalen Standorten us und eu verschlüsselt. Es wird kein Interaktionsstatus im Ruhezustand gespeichert.

Zustandsorientierte Multi-Turn-Unterhaltungen ausführen

Standardmäßig speichert die Interactions API den Unterhaltungsstatus auf dem Server (store=True in Python oder store: true in TypeScript/JavaScript). Wenn Sie eine bestehende Unterhaltung fortsetzen möchten, übergeben Sie die id der vorherigen Interaktion an den Parameter previous_interaction_id. Die Agent Platform ruft den gespeicherten Unterhaltungskontext ab, hängt den neuen Turn an und verwendet im Cache gespeicherte Präfixtokens wieder.

Beachten Sie beim Verketten von Interaktionen über Endpunkte hinweg die folgenden Standortregeln:

  • Gleicher Standort: Sie können Interaktionen innerhalb desselben Standorts verketten (z. B. global zu global, us zu us oder eu zu eu).

  • An verschiedenen Standorten: Die Verkettung über verschiedene Endpunktstandorte hinweg (zwischen global und us oder eu oder zwischen us und eu) wird nicht unterstützt. An jedem Endpunkt wird der Interaktionsstatus in einem isolierten Speicher gespeichert. Wenn Sie also auf eine Interaktions-ID verweisen, die an einem anderen Ort erstellt wurde, wird der Fehler 404 Not Found zurückgegeben.

Ersetzen Sie im folgenden Beispiel PROJECT_ID durch Ihre Google CloudProjekt-ID:

Python

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

# Turn 1: Start a stateful conversation (store=True by default)
turn1 = client.interactions.create(
    model="gemini-3.8-flash",
    input="Hi! My name is John. I am working on AI agents.",
    store=True,
)
print(f"Turn 1: {turn1.output_text}")

# Turn 2: Reference the stored conversation state using previous_interaction_id
turn2 = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is my name?",
    previous_interaction_id=turn1.id,
)
print(f"Turn 2: {turn2.output_text}")

TypeScript / JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
    enterprise: true,
    project: "PROJECT_ID",
    location: "global",
});

// Turn 1: Start a stateful conversation (store: true by default)
const turn1 = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Hi! My name is John. I am working on AI agents.",
    store: true,
});
console.log(`Turn 1: ${turn1.output_text}`);

// Turn 2: Reference the stored conversation state using previous_interaction_id
const turn2 = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "What is my name?",
    previous_interaction_id: turn1.id,
});
console.log(`Turn 2: ${turn2.output_text}`);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client =
    Client.builder()
        .enterprise(true)
        .project("PROJECT_ID")
        .location("global")
        .build();

// Turn 1: Start a stateful conversation (store is true by default)
CreateModelInteraction req1 =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Hi! My name is John. I am working on AI agents."))
        .store(true)
        .build();

Interaction turn1 =
    client.interactions.create(CreateInteractionRequestBody.of(req1)).interaction().orElseThrow();
System.out.println("Turn 1: " + turn1.outputText().orElse(""));

// Turn 2: Reference the stored conversation state using previousInteractionId
CreateModelInteraction req2 =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .previousInteractionId(turn1.id().orElseThrow())
        .input(InteractionsInput.of("What is my name?"))
        .build();

Interaction turn2 =
    client.interactions.create(CreateInteractionRequestBody.of(req2)).interaction().orElseThrow();
System.out.println("Turn 2: " + turn2.outputText().orElse(""));

REST

# Turn 1: Start a stateful conversation
curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "store": true,
    "input": "Hi! My name is John. I am working on AI agents."
  }'

# Turn 2: Pass the interaction ID from Turn 1 in previous_interaction_id
curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "previous_interaction_id": "PREVIOUS_INTERACTION_ID",
    "input": "What is my name?"
  }'

Zustandslose Multi-Turn-Unterhaltungen ausführen

Wenn Ihre Arbeitslast Zero Data Retention (ZDR) erfordert, legen Sie für jede Anfrage explizit store=False (store: false in TypeScript/JavaScript oder "store": false in REST) fest.

Im zustandslosen Modus verwalten Sie den Unterhaltungsverlauf auf dem Client, indem Sie eine Liste von Step-Objekten (user_input, thought, function_call, function_result und model_output) verwalten und das akkumulierte steps-Array in input bei jeder Runde senden:

Python

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

history = [
    {
        "type": "user_input",
        "content": [{"type": "text", "text": "Hi! My name is John."}],
    }
]

# Turn 1: Stateless request (store=False)
turn1 = client.interactions.create(
    model="gemini-3.8-flash",
    input=history,
    store=False,
)
print(f"Turn 1: {turn1.output_text}")

# Append the model's generated steps and the next user turn to local history
history.extend(turn1.steps)
history.append(
    {
        "type": "user_input",
        "content": [{"type": "text", "text": "What is my name?"}],
    }
)

# Turn 2: Send the full step history with store=False
turn2 = client.interactions.create(
    model="gemini-3.8-flash",
    input=history,
    store=False,
)
print(f"Turn 2: {turn2.output_text}")

TypeScript / JavaScript

import { GoogleGenAI, Step } from "@google/genai";

const ai = new GoogleGenAI({
    enterprise: true,
    project: "PROJECT_ID",
    location: "global",
});

const history: Step[] = [
    {
        type: "user_input",
        content: [{ type: "text", text: "Hi! My name is John." }],
    },
];

// Turn 1: Stateless request (store: false)
const turn1 = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: history,
    store: false,
});
console.log(`Turn 1: ${turn1.output_text}`);

// Append the model's generated steps and the next user turn to local history
if (turn1.steps) {
    history.push(...turn1.steps);
}
history.push({
    type: "user_input",
    content: [{ type: "text", text: "What is my name?" }],
});

// Turn 2: Send the full step history with store: false
const turn2 = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: history,
    store: false,
});
console.log(`Turn 2: ${turn2.output_text}`);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.UserInputContent;
import com.google.genai.gaos.models.interactions.UserInputStep;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.ArrayList;
import java.util.List;

Client client =
    Client.builder()
        .enterprise(true)
        .project("PROJECT_ID")
        .location("global")
        .build();

List<Step> history = new ArrayList<>();
history.add(
    Step.of(
        UserInputStep.builder()
            .content(
                List.of(
                    UserInputContent.of(
                        TextContent.builder().text("Hi! My name is John.").build())))
            .build()));

// Turn 1: Stateless request (store(false))
CreateModelInteraction req1 =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofSteps(history))
        .store(false)
        .build();

Interaction turn1 =
    client.interactions.create(CreateInteractionRequestBody.of(req1)).interaction().orElseThrow();
System.out.println("Turn 1: " + turn1.outputText().orElse(""));

// Append the model's generated steps and the next user turn to local history
turn1.steps().ifPresent(history::addAll);
history.add(
    Step.of(
        UserInputStep.builder()
            .content(
                List.of(
                    UserInputContent.of(
                        TextContent.builder().text("What is my name?").build())))
            .build()));

// Turn 2: Send the full step history with store(false)
CreateModelInteraction req2 =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofSteps(history))
        .store(false)
        .build();

Interaction turn2 =
    client.interactions.create(CreateInteractionRequestBody.of(req2)).interaction().orElseThrow();
System.out.println("Turn 2: " + turn2.outputText().orElse(""));

REST

curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "store": false,
    "input": [
      {
        "type": "user_input",
        "content": [{"type": "text", "text": "Hi! My name is John."}]
      },
      {
        "type": "model_output",
        "content": [{"type": "text", "text": "Hello John! How can I help you today?"}]
      },
      {
        "type": "user_input",
        "content": [{"type": "text", "text": "What is my name?"}]
      }
    ]
  }'

Aufbewahrung und Sitzungslebenszyklus

Für gespeicherte Interaktionen (store=True) gelten die folgenden Aufbewahrungs- und Verzweigungsregeln:

  • 7-tägige Gültigkeitsdauer (TTL): Jede gespeicherte Interaktion bleibt ab dem created-Zeitstempel 7 Tage lang erhalten und wird nach Ablauf der 7-tägigen TTL automatisch gelöscht.

  • Unabhängiger über- und untergeordneter Speicher: Wenn Sie eine neue Runde mit previous_interaction_id verketten, kopiert die Agent Platform den Verlauf der übergeordneten Unterhaltung in den neuen Interaktionsdatensatz. Da in jeder Runde eine eigene Kopie des Unterhaltungsverlaufs gespeichert wird, hat das Ablaufen oder Löschen einer früheren Runde die folgenden Auswirkungen:

    • Fortsetzung ab einem späteren Turn ist erfolgreich: Wenn Turn 1 (interaction_1) abläuft oder gelöscht wird, nachdem Turn 2 (interaction_2) bereits erstellt wurde, können Sie Turn 3 weiterhin mit previous_interaction_id=interaction_2.id erstellen, bis interaction_2 selbst abläuft oder gelöscht wird.

    • Verzweigung von einem abgelaufenen oder gelöschten Turn schlägt fehl: Wenn Sie versuchen, eine neue Interaktion zu erstellen, die direkt auf eine abgelaufene oder gelöschte Interaktions-ID in previous_interaction_id verweist, wird der Fehler 400 Bad Request (Previous Interaction ID not found) zurückgegeben.

Gespeicherte Interaktionen abrufen, auflisten, abbrechen und löschen

Mit den folgenden Methoden können Sie gespeicherte Interaktionen während ihres gesamten Lebenszyklus prüfen und verwalten:

  • Interaktion abrufen (interactions.get): Ruft die vollständige Interaction-Ressource anhand der id ab, einschließlich user_input-Schritten, Zwischenschritten (thought) und Toolschritten sowie model_output-Schritten. Legen Sie stream=True (und optional last_event_id) fest, um eine laufende Interaktion zu streamen oder fortzusetzen.

  • Interaktionen auflisten (interactions.list): Fragt gespeicherte Interaktions-IDs in Ihrem Projekt über REST mit page_size (Standard 10, maximal 500) und page_token ab. Gibt eine Liste von InteractionMetadata-Ressourcen zurück.

  • Laufende Interaktion abbrechen (interactions.cancel): Hält eine asynchrone Hintergrundinteraktion (background=True) an, die sich im Status in_progress oder requires_action befindet, und ändert ihren Status in cancelled. Ihnen werden alle Tokens in Rechnung gestellt, die vor der Kündigung generiert wurden.

  • Gespeicherte Interaktion löschen (interactions.delete): Entfernt eine gespeicherte Interaktion endgültig, bevor ihre 7-tägige TTL abläuft. Es können nur Interaktionen in einem Endzustand (completed, failed oder cancelled) gelöscht werden. Wenn eine Interaktion noch im Hintergrund ausgeführt wird, müssen Sie sie abbrechen, bevor Sie sie löschen können.

Ersetzen Sie im folgenden Beispiel PROJECT_ID durch Ihre Google CloudProjekt-ID und INTERACTION_ID durch die Zielinteraktions-ID:

Python

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

# Retrieve a stored interaction by ID
interaction = client.interactions.get(id="INTERACTION_ID")
print(f"Status: {interaction.status}")

# Cancel an in-progress background interaction
cancelled = client.interactions.cancel(id="INTERACTION_ID")
print(f"After cancel: {cancelled.status}")

# Delete a completed, failed, or cancelled interaction before its 7-day TTL
client.interactions.delete(id="INTERACTION_ID")
print("Interaction deleted.")

TypeScript / JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
    enterprise: true,
    project: "PROJECT_ID",
    location: "global",
});

// Retrieve a stored interaction by ID
const interaction = await ai.interactions.get("INTERACTION_ID");
console.log(`Status: ${interaction.status}`);

// Cancel an in-progress background interaction
const cancelled = await ai.interactions.cancel("INTERACTION_ID");
console.log(`After cancel: ${cancelled.status}`);

// Delete a completed, failed, or cancelled interaction before its 7-day TTL
await ai.interactions.delete("INTERACTION_ID");
console.log("Interaction deleted.");

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.operations.CancelInteractionByIdResponse;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;
import com.google.genai.gaos.models.operations.GetInteractionByIdResponse;

Client client =
    Client.builder()
        .enterprise(true)
        .project("PROJECT_ID")
        .location("global")
        .build();

String interactionId = "INTERACTION_ID";

// Retrieve a stored interaction by ID
GetInteractionByIdResponse getResponse =
    client.interactions.get(new GetInteractionByIdRequest(interactionId));
Interaction interaction = getResponse.interaction().orElseThrow();
System.out.println("Status: " + interaction.status().map(InteractionStatus::value).orElse(""));

// Cancel an in-progress background interaction
CancelInteractionByIdResponse cancelResponse = client.interactions.cancel(interactionId);
Interaction cancelled = cancelResponse.interaction().orElseThrow();
System.out.println("After cancel: " + cancelled.status().map(InteractionStatus::value).orElse(""));

// Delete a completed, failed, or cancelled interaction before its 7-day TTL
client.interactions.delete(interactionId);
System.out.println("Interaction deleted.");

REST

# Retrieve a stored interaction by ID
curl -X GET "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

# List stored interactions (up to 500 per page)
curl -X GET "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions?page_size=10" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

# Cancel an in-progress background interaction
curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID/cancel" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

# Delete a completed, failed, or cancelled interaction
curl -X DELETE "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

Speicherkontingente und Limits für zustandsorientierten Speicher

Zusätzlich zu den Limits für Modell-Tokens und Anfrageraten gelten für zustandsorientierte Interaktionen (store=True) die folgenden Speicher- und Nebenläufigkeitslimits auf Projektebene:

Kontingent oder Systemlimit Standardlimit (pro Projekt) Beschreibung
Durchsatz für die Erstellung zustandsorientierter Interaktionen pro Tag 240 GiB pro Tag Maximales Gesamtvolumen an Interaktionsdaten, die pro Tag über interactions.create Anfragen mit store=true in den serverseitigen Speicher geschrieben werden.
Durchsatz für das Abrufen zustandsorientierter Interaktionen pro Tag 480 GiB pro Tag Maximales Gesamtvolumen der gespeicherten Interaktionsdaten, die pro Tag über interactions.get-Anfragen und Multi-Turn-Anfragen gelesen werden, die vorherige Turns mit previous_interaction_id laden.
Gleichzeitige zustandsorientierte Interaktionen 500 gleichzeitige Interaktionen Maximale Anzahl aktiver zustandsorientierter Interaktionen, die gleichzeitig in einem Projekt ausgeführt werden.

Weitere Informationen zum Aufrufen und Verwalten von Kontingenten auf der Agent Platform finden Sie unter Kontingente und Systemlimits.

Antworten in Echtzeit streamen

Um die wahrgenommene Latenz für interaktive Anwendungen zu reduzieren, können Sie Modellantworten streamen, während sie generiert werden. Legen Sie stream=True (stream: true in TypeScript/JavaScript) fest, wenn Sie interactions.create aufrufen, um einen iterierbaren Stream von serverseitigen Ereignissen zu erhalten. Filtern Sie nach step.delta-Ereignissen, um inkrementelle Textblöcke bei ihrem Eintreffen zu rendern:

Python

response = client.interactions.create(
    model="gemini-3.8-flash",
    input="Write a short poem about debugging.",
    stream=True,
)

for event in response:
    if event.event_type == "step.delta" and hasattr(event.delta, "text"):
        print(event.delta.text, end="", flush=True)
print()

TypeScript / JavaScript

const responseStream = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Write a short poem about debugging.",
    stream: true,
});

for await (const event of responseStream) {
    if (event.event_type === "step.delta" && event.delta && "text" in event.delta) {
        process.stdout.write(event.delta.text);
    }
}
console.log();

Strukturierte Ausgabe generieren

Wenn Ihre Anwendung Antworten in einem vorhersehbaren, maschinenlesbaren Format erfordert, können Sie die Modellausgabe so einschränken, dass sie einem bestimmten JSON-Schema entspricht. Übergeben Sie Ihr Zielschema, z. B. ein Pydantic-Modell-JSON-Schema in Python oder ein Type-Schemaobjekt in TypeScript/JavaScript, direkt an den polymorphen Parameter response_format:

Python

from pydantic import BaseModel, Field

class Book(BaseModel):
    title: str = Field(description="The title of the book")
    author: str = Field(description="The book's author")
    year_published: int

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Recommend one famous sci-fi book.",
    response_format=Book.model_json_schema(),
)

# The output text is valid JSON matching the Book schema
print(interaction.output_text)

TypeScript / JavaScript

import { Type } from "@google/genai";

const BookSchema = {
    type: Type.OBJECT,
    properties: {
        title: { type: Type.STRING, description: "The title of the book" },
        author: { type: Type.STRING, description: "The book's author" },
        yearPublished: { type: Type.INTEGER },
    },
    required: ["title", "author", "yearPublished"],
};

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Recommend one famous sci-fi book.",
    response_format: BookSchema,
});

console.log(interaction.output_text);

Funktionsaufrufe (Toolnutzung) verwenden

Mit Funktionsaufrufen kann ein Modell die Ausführung benutzerdefinierter Funktionen oder externer APIs anfordern, um Informationen zu erfassen, bevor eine endgültige Antwort formuliert wird. In einem zustandsorientierten Interaktionsworkflow folgen Funktionsaufrufe einem Muster mit zwei Schritten:

  1. Tools deklarieren und übergeben: Geben Sie Ihre Funktionsdeklarationen im Parameter tools in der ersten Anfrage an.

  2. Ausführen und Ergebnisse zurückgeben: Prüfen Sie die Antwortschritte (interaction.steps) auf function_call-Schritte, führen Sie Ihre lokale Funktion mit dem vom Modell bereitgestellten arguments aus und senden Sie eine Folgeinteraktion, die ein function_result-Element enthält, das über call_id und previous_interaction_id verknüpft ist.

Python

# Define a declarative function tool schema
stock_tool = {
    "type": "function",
    "name": "get_stock_price",
    "description": "Gets the stock price for a given ticker symbol.",
    "parameters": {
        "type": "object",
        "properties": {
            "ticker": {"type": "string", "description": "The stock ticker symbol"}
        },
        "required": ["ticker"],
    },
}

def get_stock_price(ticker: str) -> float:
    """Executes the local tool function."""
    if ticker.upper() == "GOOG":
        return 175.50
    return 100.0

# Turn 1: Pass the tool declaration to the model
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is the stock price of GOOG?",
    tools=[stock_tool],
)

# Inspect the interaction steps for function call requests
for step in interaction.steps:
    if step.type == "function_call" and step.name == "get_stock_price":
        ticker_arg = step.arguments.get("ticker")
        price = get_stock_price(ticker_arg)

        # Turn 2: Submit the function execution result to the conversation
        final_turn = client.interactions.create(
            model="gemini-3.8-flash",
            input=[{
                "type": "function_result",
                "call_id": step.id,
                "result": {"price": price},
            }],
            previous_interaction_id=interaction.id,
        )
        print(final_turn.output_text)

TypeScript / JavaScript

// Define a declarative function tool schema
const stockTool = {
    type: "function",
    name: "getStockPrice",
    description: "Gets the stock price for a given ticker symbol.",
    parameters: {
        type: "object",
        properties: {
            ticker: { type: "string", description: "The stock ticker symbol" },
        },
        required: ["ticker"],
    },
};

function getStockPrice({ ticker }: { ticker: string }): number {
    if (ticker.toUpperCase() === "GOOG") return 175.50;
    return 100.00;
}

// Turn 1: Pass the tool declaration to the model
const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "What is the stock price of GOOG?",
    tools: [stockTool],
});

// Inspect the interaction steps for function call requests
for (const step of interaction.steps ?? []) {
    if (step.type === "function_call" && step.name === "getStockPrice") {
        const tickerArg = step.arguments.ticker as string;
        const price = getStockPrice({ ticker: tickerArg });

        // Turn 2: Submit the function execution result to the conversation
        const finalTurn = await ai.interactions.create({
            model: "gemini-3.8-flash",
            input: [{
                type: "function_result",
                call_id: step.id,
                result: { price },
            }],
            previous_interaction_id: interaction.id,
        });
        console.log(finalTurn.output_text);
    }
}

Integrierte Tools verwenden

Zusätzlich zu clientseitigen Funktionsaufrufen unterstützt die Interactions API integrierte serverseitige Tools für Gemini 3-Modelle. Wenn Sie ein integriertes Tool im Parameter tools aktivieren, führt die Agent Platform das Tool während eines einzelnen interactions.create-Aufrufs auf dem Server aus und zeichnet die Schritte für den Toolaufruf (*_call) und die Ausgabe (*_result) in interaction.steps auf.

Die Interactions API unterstützt die folgenden integrierten Tools:

  • Code-Ausführung ({"type": "code_execution"}): Generiert und führt Python-Code in einer Sandbox-Umgebung aus, um Berechnungen, Datenanalysen und codebasierte Schlussfolgerungen durchzuführen. Informationen zu unterstützten Bibliotheken, zur Abrechnung und zu Einschränkungen finden Sie unter Code-Ausführung.

  • URL-Kontext ({"type": "url_context"}): Ruft Inhalte von öffentlichen Web-URLs ab, die in Ihrem Prompt enthalten sind, und analysiert sie. Weitere Informationen zum Index-Caching, zu Live-Abrufen und zur Kombination von URL-Kontext mit der Suche finden Sie unter URL-Kontext.

  • Fundierung mit der Google Suche ({"type": "google_search"}): Fundiert Modellantworten mit Webinformationen in Echtzeit und gibt Inline-Zitate zurück. Weitere Informationen finden Sie unter Antworten mit der Google Suche fundieren.

  • Computernutzung ({"type": "computer_use"}): Ermöglicht Automatisierungs-Workflows für Browser und Benutzeroberflächen. Informationen zu Konfigurations- und Sicherheitseinstellungen finden Sie unter Computernutzung.

Python-Code ausführen

Wenn Sie die Codeausführung aktivieren möchten, fügen Sie {"type": "code_execution"} in die Liste tools ein. Das zurückgegebene interaction.steps-Array enthält code_execution_call-Schritte (mit arguments.code und arguments.language), code_execution_result-Schritte (mit result und is_error) und den letzten model_output-Schritt.

Ersetzen Sie im folgenden Beispiel PROJECT_ID durch Ihre Google CloudProjekt-ID:

Python

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Calculate the 50th Fibonacci number and find its closest prime.",
    tools=[{"type": "code_execution"}],
)

for step in interaction.steps:
    if step.type == "code_execution_call":
        print(f"Generated code:\n{step.arguments.code}")
    elif step.type == "code_execution_result":
        print(f"Execution result:\n{step.result}")
    elif step.type == "model_output":
        for content in step.content:
            if content.type == "text":
                print(content.text)

TypeScript / JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
    enterprise: true,
    project: "PROJECT_ID",
    location: "global",
});

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Calculate the 50th Fibonacci number and find its closest prime.",
    tools: [{ type: "code_execution" }],
});

for (const step of interaction.steps ?? []) {
    if (step.type === "code_execution_call") {
        console.log(`Generated code:\n${step.arguments?.code}`);
    } else if (step.type === "code_execution_result") {
        console.log(`Execution result:\n${step.result}`);
    } else if (step.type === "model_output") {
        for (const content of step.content ?? []) {
            if (content.type === "text") {
                console.log(content.text);
            }
        }
    }
}

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CodeExecution;
import com.google.genai.gaos.models.interactions.CodeExecutionCallStep;
import com.google.genai.gaos.models.interactions.CodeExecutionResultStep;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;

Client client =
    Client.builder()
        .enterprise(true)
        .project("PROJECT_ID")
        .location("global")
        .build();

CreateModelInteraction request =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(
            InteractionsInput.of(
                "Calculate the 50th Fibonacci number and find its closest prime."))
        .tools(List.of(CodeExecution.builder().build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(request)).interaction().orElseThrow();

for (Step step : interaction.steps().orElse(List.of())) {
    if (step instanceof CodeExecutionCallStep callStep) {
        callStep
            .arguments()
            .flatMap(args -> args.code())
            .ifPresent(code -> System.out.println("Generated code:\n" + code));
    } else if (step instanceof CodeExecutionResultStep resultStep) {
        resultStep
            .result()
            .ifPresent(res -> System.out.println("Execution result:\n" + res));
    }
}
System.out.println(interaction.outputText().orElse(""));

REST

curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Calculate the 50th Fibonacci number and find its closest prime.",
    "tools": [{"type": "code_execution"}]
  }'

Webseiteninhalte mit URL-Kontext abrufen

Wenn Sie dem Modell ermöglichen möchten, Webseiten abzurufen und zu analysieren, auf die in Ihrem Prompt verwiesen wird, fügen Sie {"type": "url_context"} in die Liste tools ein. Die API zeichnet die abgerufenen URLs in den Schritten url_context_call und url_context_result auf und fügt dem generierten Text in model_output url_citation-Anmerkungen hinzu.

Ersetzen Sie im folgenden Beispiel PROJECT_ID durch Ihre Projekt-ID in Google Cloudund YOUR_URL_1 und YOUR_URL_2 durch die öffentlichen URLs, die Sie vergleichen möchten:

Python

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Compare the key findings from YOUR_URL_1 and YOUR_URL_2.",
    tools=[{"type": "url_context"}],
)

print(interaction.output_text)

TypeScript / JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
    enterprise: true,
    project: "PROJECT_ID",
    location: "global",
});

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Compare the key findings from YOUR_URL_1 and YOUR_URL_2.",
    tools: [{ type: "url_context" }],
});

console.log(interaction.output_text);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.URLContext;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;

Client client =
    Client.builder()
        .enterprise(true)
        .project("PROJECT_ID")
        .location("global")
        .build();

CreateModelInteraction request =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(
            InteractionsInput.of(
                "Compare the key findings from YOUR_URL_1 and YOUR_URL_2."))
        .tools(List.of(URLContext.builder().build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(request)).interaction().orElseThrow();

System.out.println(interaction.outputText().orElse(""));

REST

curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Compare the key findings from YOUR_URL_1 and YOUR_URL_2.",
    "tools": [{"type": "url_context"}]
  }'

Antworten mit der Google Suche fundieren

Durch die Fundierung werden Gemini-Modelle mit überprüfbaren externen Quellen verbunden, um Halluzinationen zu reduzieren und aktuelle Antworten mit Quellenangaben zu liefern. Eine Übersicht über die Fundierungsoptionen auf der Agent Platform finden Sie in der Übersicht über die Fundierung, unter Fundierung mit der Google Suche und unter Webfundierung für Unternehmen.

Wenn Sie die Fundierung mit der Google Suche aktivieren, indem Sie {"type": "google_search"} in der Liste tools übergeben, gibt die Interactions API Such- und Attributionsdaten direkt in der interaction.steps-Zeitachse zurück:

  • google_search_call: Enthält die vom Modell ausgegebenen Suchanfragen (step.arguments.queries).

  • google_search_result: Enthält Suchvorschläge (result[].search_suggestions), ein HTML/CSS-Snippet, das zum Rendern von Suchvorschlägen in Benutzeroberflächen verwendet wird. Webressourcen mit Quell-URLs und Titeln werden als Inline-url_citation-Anmerkungen für model_output-Textblöcke bereitgestellt.

  • Inline-url_citation-Anmerkungen: Jeder text-Inhaltsblock (TextContent) innerhalb eines model_output-Schritts kann ein annotations-Array enthalten. Jede url_citation-Annotation identifiziert den Zeichen- oder Bytebereich (start_index und end_index) im Antworttext zusammen mit der Quelle title und url.

Ersetzen Sie im folgenden Beispiel PROJECT_ID durch Ihre Google CloudProjekt-ID:

Python

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Who won the 2026 Super Bowl?",
    tools=[{"type": "google_search"}],
)

print(interaction.output_text)

# Parse inline url_citation annotations from model_output steps
print("\nSources:")
for step in interaction.steps:
    if step.type == "model_output" and step.content:
        for content in step.content:
            if content.type == "text" and getattr(content, "annotations", None):
                for annotation in content.annotations:
                    if annotation.type == "url_citation":
                        span = content.text[annotation.start_index:annotation.end_index]
                        print(f"- [{annotation.title}]({annotation.url}) (cited text: {span!r})")

TypeScript / JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
    enterprise: true,
    project: "PROJECT_ID",
    location: "global",
});

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Who won the 2026 Super Bowl?",
    tools: [{ type: "google_search" }],
});

console.log(interaction.output_text);

// Parse inline url_citation annotations from model_output steps
console.log("\nSources:");
for (const step of interaction.steps ?? []) {
    if (step.type === "model_output") {
        for (const content of step.content ?? []) {
            if (content.type === "text" && content.annotations) {
                for (const annotation of content.annotations) {
                    if (annotation.type === "url_citation") {
                        const span = content.text.slice(
                            annotation.start_index,
                            annotation.end_index,
                        );
                        console.log(
                            `- [${annotation.title}](${annotation.url}) (cited text: "${span}")`,
                        );
                    }
                }
            }
        }
    }
}

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Annotation;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.URLCitation;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;

Client client =
    Client.builder()
        .enterprise(true)
        .project("PROJECT_ID")
        .location("global")
        .build();

CreateModelInteraction request =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Who won the 2026 Super Bowl?"))
        .tools(List.of(GoogleSearch.builder().build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(request)).interaction().orElseThrow();

System.out.println(interaction.outputText().orElse(""));

// Parse inline URLCitation annotations from ModelOutputStep blocks
System.out.println("\nSources:");
for (Step step : interaction.steps().orElse(List.of())) {
    if (step instanceof ModelOutputStep outputStep) {
        for (Content content : outputStep.content().orElse(List.of())) {
            if (content instanceof TextContent textContent) {
                for (Annotation annotation : textContent.annotations().orElse(List.of())) {
                    if (annotation instanceof URLCitation citation) {
                        System.out.printf(
                            "- %s: %s (span: %d..%d)%n",
                            citation.title().orElse(""),
                            citation.url().orElse(""),
                            citation.startIndex().orElse(0L),
                            citation.endIndex().orElse(0L));
                    }
                }
            }
        }
    }
}

REST

# Request
curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Who won the 2026 Super Bowl?",
    "tools": [{"type": "google_search"}]
  }'

Die Antwort enthält die Schritte google_search_call, google_search_result und model_output mit Inline-url_citation-Annotationen:

{
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROA",
  "model": "gemini-3.8-flash",
  "status": "completed",
  "steps": [
    {
      "type": "google_search_call",
      "id": "search_call_1",
      "arguments": {
        "queries": ["2026 Super Bowl winner"]
      }
    },
    {
      "type": "google_search_result",
      "call_id": "search_call_1",
      "result": [
        {
          "search_suggestions": "<!-- HTML and CSS for search suggestions -->"
        }
      ]
    },
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "The Seattle Seahawks won Super Bowl LX on February 8, 2026.",
          "annotations": [
            {
              "type": "url_citation",
              "start_index": 0,
              "end_index": 59,
              "title": "Super Bowl LX",
              "url": "https://example.com/super-bowl-lx"
            }
          ]
        }
      ]
    }
  ]
}

Agenten und lang andauernde Hintergrundaufgaben ausführen

Zusätzlich zu Foundation Models können Sie mit der Interactions API spezialisierte autonome Agenten über den Parameter agent aufrufen:

  • antigravity-preview-05-2026: Verwalteter Agent für allgemeine Zwecke mit Codeausführung, Dateiverwaltung und Websuche in einer sicheren Linux-Sandbox-Umgebung. Weitere Informationen finden Sie unter Mit Agenten interagieren.
  • deep-research-preview-04-2026: Gemini Deep Research Agent, der mehrstufige Web-Rechercheaufgaben plant und ausführt und Ergebnisse aus mehreren Quellen in umfassenden Berichten zusammenfasst. Weitere Informationen finden Sie unter Gemini Deep Research-Agent verwenden.
  • Benutzerdefinierte KI-Agenten: Benutzerdefinierte KI-Agenten-Ressourcen, die mit client.agents.create() konfiguriert und bereitgestellt werden.

Da die Ausführung von KI-Agenten-Workflows oft mehrere Minuten dauert, sollten Sie sie asynchron im Hintergrund ausführen, indem Sie background=True festlegen. Die API gibt sofort ein Interaction-Objekt mit einem id zurück, das Sie mit client.interactions.get() abfragen können, bis interaction.status zu completed wechselt:

Ersetzen Sie vor dem Ausführen dieses Beispiels PROJECT_ID durch die Projekt-ID Ihres Projekts inGoogle Cloud .

import time
from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

interaction = client.interactions.create(
    input="Analyze competitive positioning for solar energy providers.",
    agent="deep-research-preview-04-2026",
    background=True,
)

print(f"Research started: {interaction.id}")

while True:
    interaction = client.interactions.get(interaction.id)
    if interaction.status == "completed":
        print(interaction.output_text)
        break
    elif interaction.status in ("failed", "cancelled"):
        print(f"Research ended with status: {interaction.status}")
        break
    time.sleep(10)

Auf hochgeladene Cloud Storage-Dateien zugreifen

Sie können die Interactions API verwenden, um auf hochgeladene Cloud Storage-Dateien zuzugreifen. Ersetzen Sie im folgenden Beispiel PROJECT_ID durch dieGoogle Cloud Projekt-ID Ihres Projekts:

from google import genai

# Credentials must belong to an identity with storage.objects.get permissions
client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "user_input",
            "content": [
                {"type": "text", "text": "Summarize the attached document:"},
                {
                    "type": "document",
                    "uri": "gs://my-secure-bucket/quarterly_report.pdf",
                    "mime_type": "application/pdf",
                },
            ],
        }
    ],
)

print(interaction.output_text)

Wenn Sie Cloud Storage-URIs (z. B. gs://bucket-name/path/to/file) an die Interactions API übergeben, wird bei Anfragen der Lesezugriff mit den Anmeldedaten des Aufrufers überprüft, bevor der Agent Platform Service Agent (service-PROJECT_NUMBER@gcp-sa-aiplatform.) des aufrufenden Projekts das Objekt aus Cloud Storage abruft.

Wenn Sie Cloud Storage-Dateien in einer Interaktionsanfrage übergeben möchten, muss das aufrufende Hauptkonto (Nutzerkonto, Dienstkonto oder föderierte Identität) die Berechtigung storage.objects.get für alle referenzierten Objekte haben. Gewähren Sie für projektübergreifende Cloud Storage-Buckets oder Cloud Storage-Buckets mit benutzerdefinierten IAM-Richtlinien sowohl dem aufrufenden Hauptkonto als auch dem Dienst-Agent des aufrufenden Projekts Lesezugriff.

Jede Standard-Gemini-Modellinteraktionsanfrage unterstützt bis zu 100 verschiedene Cloud Storage-URIs (gs://) (bis zu 2 GiB minus 500 KiB pro Datei). Wenn Sie zustandsorientierte Runden mit previous_interaction_id verketten, zählt die Agent Platform eindeutige gs://-URIs kumulativ über den Unterhaltungsverlauf und die aktuelle Runde hinweg. Interaktionen mit verwalteten KI-Agenten (Anfragen, bei denen agent anstelle von model festgelegt wird), Gemini Omni-Modelle und Lyria 3-Modelle sind von diesem Limit von 100 URIs ausgenommen.

IAM-Rollen für den Zugriff auf Cloud Storage-Dateien konfigurieren

Weisen Sie eine der vordefinierten Standardrollen zu, die die Berechtigung storage.objects.get enthalten:

  • Storage-Objekt-Betrachter (roles/storage.objectViewer): Lesezugriff auf Objekte (empfohlen).

  • Storage-Objekt-Nutzer (roles/storage.objectUser): Lese- und Schreibzugriff auf Objekte.

Verwenden Sie den folgenden Befehl, um einem Nutzerkonto Zugriff über die Google Cloud CLI zu gewähren:

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member="user:user-email@example.com" \
    --role="roles/storage.objectViewer"

Verwenden Sie den folgenden Befehl, um einem bestimmten aufrufenden Dienstkonto Zugriff zu gewähren:

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member="serviceAccount:sa-name@PROJECT_ID." \
    --role="roles/storage.objectViewer"

Fehlerbehebung beim Zugriff auf Cloud Storage-Dateien

Wenn das aufrufende Hauptkonto nicht über ausreichende Berechtigungen verfügt, gibt die Interactions API einen 403 Forbidden-Fehler zurück, der in etwa so aussieht:

Access error:
PERMISSION_DENIED - 403 Forbidden: Calling principal lacks
storage.objects.get on one or more Cloud Storage URIs.

Weisen Sie dem authentifizierten Aufrufer (und dem Agent Platform-Dienst-Agent des aufrufenden Projekts für projektübergreifende oder benutzerdefinierte IAM-Cloud Storage-Buckets) die Rolle „Storage Object Viewer“ (roles/storage.objectViewer) für den Cloud Storage-Bucket oder das Cloud Storage-Objekt zu, um dieses Problem zu beheben.

Wenn das angegebene Objekt nicht vorhanden ist oder wenn Bucket-Berechtigungen verhindern, dass der Aufrufer sieht, ob das Objekt vorhanden ist, gibt die Interactions API einen 404 Not Found-Fehler zurück, der in etwa so aussieht:

Access error:
NOT_FOUND - 404 Not Found: The object does not exist, or bucket
permissions prevent revealing object existence.

Prüfen Sie zur Behebung dieses Problems, ob der Cloud Storage-URI korrekt ist und ob der authentifizierte Aufrufer Lesezugriff auf den Bucket hat.

Wenn eine Modellinteraktionsanfrage mehr als 100 verschiedene Cloud Storage-URIs im aktuellen Turn und im verknüpften previous_interaction_id-Verlauf referenziert, gibt die Interactions API einen 400 Bad Request-Fehler zurück, der in etwa so aussieht:

INVALID_ARGUMENT - 400 Bad Request: Request references 101 distinct gs:// URIs, which exceeds the maximum of 100.

Führen Sie einen der folgenden Schritte aus, um das Problem zu lösen:

  • Starten Sie eine neue Interaktion ohne previous_interaction_id, wenn Dateien aus früheren Runden nicht mehr benötigt werden.
  • Kombinieren Sie kleinere Dokumente oder übergeben Sie zusätzliche Dateien inline innerhalb des Limits für die Anfrage-Nutzlast (256 MiB komprimiert für synchrone oder Streaming-Anfragen oder 9,75 MiB unkomprimiert, wenn service_tier auf deferred gesetzt ist und background und store auf true gesetzt sind).
  • Verwenden Sie generateContent für Anfragen, die auf gs://-URIs verweisen, bis zu den Limits für Modellelemente pro Modalität (3.000 Bilder und PDFs kombiniert, 1.000 Audiodateien und 10 Videos oder bis zu 6.500 Dateien, wenn Nur-Text-Dateien enthalten sind).

Interaktionsdaten mit CMEK verschlüsseln

Bei zustandsorientierten Interaktionen (store=True in Python oder store: true in TypeScript/JavaScript) werden Interaktionsdaten bis zu 7 Tage lang im Ruhezustand gespeichert. Wenn Sie diese Daten mit Ihrem eigenen Verschlüsselungsschlüssel anstelle einesGoogle-owned and Google-managed encryption keyschützen möchten, verwenden Sie ein Bereitstellungsprofil. Ein Bereitstellungsprofil verknüpft einen Cloud Key Management Service-Schlüssel mit einem Projekt, einem Standort und einem API-Bereich. Solange ein Bereitstellungsprofil vorhanden ist, verschlüsselt die Agent Platform gespeicherte Interaktionsdaten automatisch. Das Format Ihrer Interaktionsanfrage ändert sich nicht.

CMEK für Bereitstellungsprofile für die Interactions API wird in den Multiregionen us und eu unterstützt. Die Region global wird nicht unterstützt.

So richten Sie CMEK für die Interactions API ein:

  1. Aktivieren Sie die Cloud KMS API und die Agent Platform API in Ihrem Projekt. Siehe Vorbereitung.
  2. Erstellen Sie einen Cloud KMS-Schlüssel in der multiregionalen Region us oder eu. Weitere Informationen finden Sie unter Schlüsselbund und Schlüssel erstellen.
  3. Gewähren Sie dem Dienst-Agenten der Gemini Enterprise Agent Platform die Rolle roles/cloudkms.cryptoKeyEncrypterDecrypter für den Schlüssel. Weitere Informationen finden Sie unter Agent Platform-Berechtigungen gewähren.

  4. Erstellen Sie ein Bereitstellungsprofil in derselben Multiregion (us oder eu), das scope auf INTERACTIONS_API und cmekConfig.encryptionSpec.kmsKeyName auf Ihren Schlüssel setzt:

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/servingProfiles?servingProfileId=SERVING_PROFILE_ID" \
  -d '{
    "displayName": "Interactions API CMEK profile",
    "description": "CMEK for Interactions API",
    "scope": "INTERACTIONS_API",
    "cmekConfig": {
      "encryptionSpec": {
        "kmsKeyName": "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_NAME/cryptoKeys/KEY_NAME"
      }
    }
  }'

    Warten Sie, bis der lang andauernde Erstellungsvorgang abgeschlossen ist ("done": true). Weitere Informationen zum Verwalten, Aktualisieren oder Löschen von Bereitstellungsprofilen finden Sie unter Bereitstellungsprofil erstellen.

  5. Senden Sie Ihre Interaktionsanfragen an dieselbe multiregionale us- oder eu-Instanz wie Ihr Bereitstellungsprofil. Der CMEK für das Bereitstellungsprofil ist auf dem global-Endpunkt nicht verfügbar.

    • Google Gen AI SDK: Initialisieren Sie den Client mit location="us" oder location="eu" (location: "us" oder location: "eu" in TypeScript/JavaScript).
    • REST: Senden Sie Anfragen an den multiregionalen Endpunkt https://aiplatform.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/interactions, wobei LOCATION entweder us oder eu ist.

    Wenn Sie den Schlüssel deaktivieren oder den Zugriff des Dienst-Agents widerrufen, schlagen Anfragen zum Erstellen oder Lesen gespeicherter Interaktionen mit dem Fehler FAILED_PRECONDITION fehl.

Erweiterte REST-Workflows

Für shellbasierte Automatisierung, CI/CD-Pipelines oder Umgebungen ohne Python- oder TypeScript/JavaScript-Laufzeit können Sie die Interactions API direkt über HTTP mit curl aufrufen.

REST-Endpunkt

Senden Sie POST-Anfragen an den folgenden Interactions API-Endpunkt:

POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/interactions

Ersetzen Sie die folgenden Variablen in Ihren Anfragen:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID
  • LOCATION: Auf global (oder us oder eu mit dem multiregionalen Host https://aiplatform.LOCATION.rep.googleapis.com für Datenstandort oder CMEK) festgelegt.

Umgebungsvariablen und Authentifizierung festlegen

Bevor Sie die curl-Beispiele in den folgenden Abschnitten ausführen, exportieren Sie Ihre Projekt-ID, die Zielmodell- oder Agenten-ID und ein OAuth 2.0-Zugriffstoken, das aus Standardanmeldedaten für Anwendungen generiert wurde:

PROJECT_ID="PROJECT_ID"
MODEL_ID="gemini-3.8-flash"
AGENT_ID="deep-research-preview-04-2026"
ACCESS_TOKEN=$(gcloud auth print-access-token)

Synchrones Antwortformat

Eine synchrone POST-Anfrage gibt ein JSON-interaction-Objekt zurück, das die eindeutigen Metadaten für Interaktion id, Ausführung status, Unterhaltung steps und Token usage enthält:

{
  "id": "your-interaction-id",
  "status": "completed",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Serverless computing is a cloud execution model where the cloud provider dynamically manages the allocation and provisioning of servers, charging customers based on actual usage rather than pre-purchased capacity."
        }
      ]
    }
  ],
  "usage": {
    "total_tokens": 24751,
    "total_input_tokens": 23894,
    "total_output_tokens": 857
  },
  "created": "2026-05-08T10:44:43Z",
  "updated": "2026-05-08T10:44:43Z",
  "environment_id": "your-environment-id",
  "object": "interaction"
}

Zustandsorientierte Multi-Turn-Interaktion fortsetzen

Wenn Sie eine gespeicherte Unterhaltung über REST fortsetzen möchten, übergeben Sie die id aus einer vorherigen Antwort im Feld previous_interaction_id des JSON-Anfragetexts.

Bevor Sie dieses Beispiel ausprobieren, ersetzen Sie PREVIOUS_INTERACTION_ID durch die id, die von einer vorherigen Interaktion zurückgegeben wurde.

curl -X POST "https://aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/interactions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${MODEL_ID}"'",
    "store": true,
    "previous_interaction_id": "PREVIOUS_INTERACTION_ID",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Can you elaborate on that?"
      }]
    }]
  }'

Ausgabe mit vom Server gesendeten Ereignissen streamen

Wenn Sie inkrementelle Updates über REST streamen möchten, fügen Sie "stream": true in den JSON-Anfragetext ein:

curl -X POST "https://aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/interactions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${MODEL_ID}"'",
    "stream": true,
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Write a long story about space travel."
      }]
    }]
  }'

Wenn "stream": true festgelegt ist, antwortet der Server mit Transfer-Encoding: chunked und Content-Type: text/event-stream (Server-Sent Events). Jedes Ereignis im Stream enthält ein data:-Präfix mit einer JSON-Nutzlast mit dem event_type- und dem Schritt-Delta-Inhalt. curl hält die HTTP-Verbindung automatisch offen und schreibt eingehende Blöcke in Echtzeit in stdout, bis die Interaktion abgeschlossen ist.

Verwalteten KI-Agenten im Hintergrund ausführen

Wenn Sie eine asynchrone verwaltete Agent-Aufgabe mit langer Ausführungszeit über REST starten möchten, geben Sie das Ziel agent an, legen Sie "background": true fest und konfigurieren Sie "environment": "remote":

curl -X POST "https://aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/interactions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "'"${AGENT_ID}"'",
    "environment": "remote",
    "background": true,
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Analyze competitive positioning for commercial solar energy providers."
      }]
    }]
  }'

Nächste Schritte

In den folgenden Ressourcen finden Sie weitere Informationen zur Interactions API, zu integrierten Tools und zur Fundierung: