Entwicklerleitfaden für die Interactions API

Die Interactions API bietet eine einheitliche, zustandsbehaftete Schnittstelle zum Erstellen generativer KI-Anwendungen mit Gemini-Modellen und autonomen Agenten auf der Gemini Enterprise Agent Platform. Mit der Interactions API können Sie Mehrfachdialoge führen, Antworten in Echtzeit streamen, strukturierte Ausgaben erzwingen, 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, müssen Sie Ihr Google Cloud-Projekt und Ihre Entwicklungsumgebung einrichten:

Melden Sie sich in Ihrem Google Cloud -Konto an. Wenn Sie mit Google Cloudnoch nicht vertraut sind, erstellen Sie einfach ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.
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
Verify that billing is enabled for your Google Cloud project.
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
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 person_add Grant access.

4. In the New principals field, enter your user identifier. This is typically the email address for a Google Account.

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

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

Verify that billing is enabled for your Google Cloud project.

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

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 person_add Grant access.

4. In the New principals field, enter your user identifier. This is typically the email address for a Google Account.

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

Wichtige Konzepte

Sehen Sie sich die folgenden Konzepte an, um zu verstehen, wie die Interactions API Status und Antworten verwaltet:

• Interaction: Die Interactions API dreht sich um eine Kernressource: eine Interaction. Ein Interaction stellt eine vollständige Runde in einer Unterhaltung oder Aufgabe dar und verfolgt die Chronologie der Gedanken des Modells, der Tool-Aufrufe und der endgültigen Ausgaben. Sie bietet eine einheitliche Umgebung für Prompt-Antwort-Interaktionen und komplexe, mehrstufige Agent-Workflows.
• Statusbehaftete 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. Durch Festlegen von store=False wird der zustandslose Modus aktiviert, wodurch die serverseitige Aufbewahrung deaktiviert wird und die Richtlinie zur Aufbewahrung von Daten auf null (Zero Data Retention, ZDR) eingehalten wird. Im zustandslosen Modus werden auch die Verkettung von previous_interaction_id und die asynchrone Ausführung (background=True) deaktiviert.
• Antworthilfen: In Google Gen AI SDK-Version 2.3.0 und höher sind praktische Eigenschaften 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 Array „steps“ manuell zu indexieren (z. B. interaction.steps[-1].content[0].text).

Voraussetzungen

Prüfen Sie, ob Ihre Umgebung und Ihre Anfragen die folgenden Anforderungen erfüllen, bevor Sie die Interactions API einbinden:

• Unterstützung von SDK-Versionen: Verwenden Sie das einheitliche Google Gen AI SDK (>= 2.3.0 für Python oder @google/genai >= 2.3.0 für TypeScript und JavaScript).

  • Für Eigenschaften des Antwort-Helpers und Agent-Funktionen ist Version 2.3.0 oder höher erforderlich, während Version 2.0.0 das steps-Basisschema unterstützt.
  • Die Legacy-SDKs (google-cloud-aiplatform, @google-cloud/vertexai und google-generativeai) unterstützen die Interactions API nicht.

• Unterstützte Modelle: Verwenden Sie unterstützte Gemini 3-Modelle oder höher. Ältere Modellfamilien unterstützen diese API nicht. Eine vollständige Liste der unterstützten Modelle finden Sie unter Unterstützte Modelle und Zur neuesten Modellversion migrieren.

• Rundenbezogene Parameter: Konfigurationsparameter wie tools, system_instruction und generation_config gelten nur für die aktuelle Runde. Übergeben Sie diese Parameter bei jeder nachfolgenden Interaktionsrunde, wenn sie in Ihrem Workflow für eine Multi-Turn-Unterhaltung erforderlich sind.

Google Gen AI SDK installieren

Installieren oder aktualisieren Sie das Google Gen AI SDK (>= 2.3.0) für Ihre bevorzugte Sprache:

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

npm install "@google/genai>=2.3.0"

Client authentifizieren

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

• Google Cloud Projekt mit Standardanmeldedaten für Anwendungen
• Express-Modus mit einem API-Schlüssel

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

Wir empfehlen, diese Authentifizierungsmethode für Unternehmensarbeitslasten und Produktionsbereitstellungen auf Google Cloudzu verwenden. Wenn Sie sich mit Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) authentifizieren möchten, initialisieren Sie den Client mit den folgenden Eigenschaften:

• enterprise=True
• project= Google Cloud 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 Ihre Projekt-ID vonGoogle Cloud .

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)

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);

curl -X POST "https://aiplatform.googleapis.com/v1beta1/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": [{
      "role": "user",
      "content": [{
        "type": "text",
        "text": "Explain serverless computing in one sentence."
      }]
    }]
  }'

Verbindung im Express-Modus herstellen (API-Schlüssel)

Wir empfehlen, diese Authentifizierungsmethode für schnelles Prototyping, einfache Skripts oder Umgebungen zu verwenden, die mit einem API-Schlüssel authentifiziert werden. Übergeben Sie Ihren API-Schlüssel beim Initialisieren des Clients oder im x-goog-api-key-HTTP-Header.

Ersetzen Sie im folgenden Codebeispiel API_KEY durch Ihren API-Schlüssel.

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)

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);

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

Häufige Interaktionsworkflows

Nachdem Sie Ihren Client konfiguriert haben, können Sie mit der Methode interactions.create Mehrfachdialoge erstellen, Ausgabetokens in Echtzeit streamen, schemavalidiertes JSON generieren, externe Funktionen aufrufen und autonome Agents ausführen.

Zustandsorientierte Mehrfachdialoge verwalten

Im Gegensatz zu zustandslosen Chat-APIs, bei denen Sie den vollständigen Nachrichtenverlauf mit jeder Anfrage noch einmal senden müssen, wird der Konversationsstatus in der Interactions API standardmäßig auf dem Server verwaltet (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 automatisch den gespeicherten Unterhaltungskontext ab und hängt den neuen Turn an. Wenn Sie store=False (store: false in TypeScript/JavaScript) festlegen, wird die serverseitige Persistenz deaktiviert und Sie können nachfolgende Turns nicht mit previous_interaction_id verketten.

# Turn 1: Start a 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}")

// Turn 1: Start a 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}`);

Antworten in Echtzeit streamen

Um die wahrgenommene Latenz für interaktive Anwendungen zu verringern, können Sie Modellantworten streamen, während sie generiert werden. Legen Sie stream=True (stream: true in TypeScript/JavaScript) beim Aufrufen von interactions.create fest, um einen iterierbaren Stream von serverseitig gesendeten Ereignissen zu erhalten. Filtern Sie nach step.delta-Ereignissen, um inkrementelle Textblöcke zu rendern, sobald sie eintreffen:

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()

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 direkt an den polymorphen Parameter response_format, z. B. ein JSON-Schema für ein Pydantic-Modell in Python oder ein Type-Schemaobjekt in TypeScript/JavaScript:

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)

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 (Tool-Nutzung) verwenden

Mithilfe von Funktionsaufrufen kann ein Modell die Ausführung benutzerdefinierter Funktionen oder externer APIs anfordern, um Informationen zu sammeln, bevor es eine endgültige Antwort formuliert. In einem zustandsorientierten Interaktionsworkflow folgt der Funktionsaufruf einem Muster mit zwei Zügen:

1. Tools deklarieren und übergeben: Geben Sie Ihre Funktionsdeklarationen im Parameter tools in der ursprünglichen 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 mit einem function_result-Element, das über call_id und previous_interaction_id verknüpft ist.

# 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)

// 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);
    }
}

Agents und lang andauernde Hintergrundaufgaben ausführen

Zusätzlich zu den Foundation Models können Sie mit der Interactions API mithilfe des Parameters agent spezielle autonome Agents aufrufen:

• antigravity-preview-05-2026: Ein universeller verwalteter Agent mit Codeausführung, Dateiverwaltung und Webbrowser in einer sicheren Sandbox-Linux-Umgebung. Weitere Informationen finden Sie unter Mit Agents interagieren.
• deep-research-preview-04-2026: Der Gemini Deep Research-Agent plant und führt mehrstufige Web-Rechercheaufgaben aus und fasst Ergebnisse aus mehreren Quellen in umfassenden Berichten zusammen. Weitere Informationen finden Sie unter Gemini Deep Research-Agent verwenden.
• Benutzerdefinierte Agenten: Benutzerdefinierte Agentenressourcen, die mit client.agents.create() konfiguriert und bereitgestellt werden.

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

Ersetzen Sie vor dem Ausprobieren 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

Mit der Interactions API können Sie auf hochgeladene Cloud Storage-Dateien zugreifen. Sehen Sie sich folgendes Beispiel an:

from google import genai

# Credentials must belong to an identity with storage.objects.get permissions
client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"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, werden Anfragen mit Endnutzeranmeldedaten (End-User Credentials, EUC) ausgewertet. Die API ruft Cloud Storage-Objekte mit der Identität des authentifizierten Aufrufers und nicht mit einem Hintergrundprojekt-Dienst-Agent ab.

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.

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 Object Viewer (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 mit der Google Cloud CLI Zugriff 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 Zugriff auf ein bestimmtes Dienstkonto für Anrufe zu gewähren:

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

Fehlerbehebung beim Zugriff auf Cloud Storage-Dateien

Wenn dem aufrufenden Prinzipal nicht genügend Berechtigungen zugewiesen sind, 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 GCS URIs.

Um dieses Problem zu beheben, weisen Sie dem authentifizierten Aufrufer die Rolle „Storage Object Viewer“ (roles/storage.objectViewer) für den Bucket oder das Objekt zu.

Wenn das angegebene Objekt nicht vorhanden ist oder die Bucket-Berechtigungen verhindern, dass der Aufrufer sieht, ob das Objekt vorhanden ist, gibt die Interactions API einen 404 Not Found-Fehler zurück, der dem folgenden ähnelt:

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 bestätigen Sie, dass der authentifizierte Aufrufer Lesezugriff auf den Bucket hat.

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/v1beta1/projects/PROJECT_ID/locations/LOCATION/interactions

Ersetzen Sie die folgenden Variablen in Ihren Anfragen:

• PROJECT_ID: Ihre Google Cloud Projekt-ID
• LOCATION: Auf global festlegen (oder auf eine unterstützte benutzerdefinierte Region, falls für Ihre Konfiguration erforderlich).

Umgebungsvariablen und Authentifizierung festlegen

Bevor Sie die curl-Beispiele in den folgenden Abschnitten ausführen, exportieren Sie Ihre Projekt-ID, die ID des Zielmodells oder ‑agents und ein OAuth 2.0-Zugriffstoken, das aus den 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"
}

Mehrfachdialog mit Zustandsverwaltung 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/v1beta1/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": [{
      "role": "user",
      "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/v1beta1/projects/${PROJECT_ID}/locations/global/interactions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${MODEL_ID}"'",
    "stream": true,
    "input": [{
      "role": "user",
      "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 das Präfix data:, das eine JSON-Nutzlast mit dem Inhalt von event_type und dem Schrittdelta enthält. curl hält die HTTP-Verbindung automatisch offen und schreibt eingehende Chunks in Echtzeit in stdout, bis die Interaktion abgeschlossen ist.

Verwalteten Agent im Hintergrund ausführen

Wenn Sie eine lang andauernde Aufgabe des verwalteten Agents asynchron ü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/v1beta1/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": [{
      "role": "user",
      "content": [{
        "type": "text",
        "text": "Analyze competitive positioning for commercial solar energy providers."
      }]
    }]
  }'

Nächste Schritte

• Weitere Informationen zu den wichtigsten Konzepten in der Interactions API – Übersicht.
• Hier finden Sie die Anfrage- und Antwortschemas in der Interactions API-Referenz.
• Informationen zur Interaktion mit verwalteten Agents und zur Verwendung des Gemini Deep Research Agent