Verzögerte Stufe verwenden

Mit der Stufe „Verzögert“ können Sie asynchrone, mehrstufige Gemini-Modellaufrufe für benutzerdefinierte Agenten zu einem rabattierten Preis auf der Gemini Enterprise Agent Platform ausführen. In der Interactions API stellt die Agent Platform jede zurückgestellte Runde für die Hintergrundausführung innerhalb eines 24-Stunden-Ziels in die Warteschlange und behält den Status 7 Tage lang bei.

Die Stufe „Verzögert“ eignet sich für latenzunempfindliche agentische Arbeitslasten, die eine Kontrolle pro Durchgang erfordern, z. B.:

  • Mehrstufige Programmier- und Sicherheits-Agents: Scans auf Sicherheitslücken in Repositories, automatisierte Codemigrationen und Regressionstriage.
  • Dokumenten- und Forschungspipelines: Technische Designprüfungen, Finanz-Backtesting und Multi-Dokumenten-Synthese mit Toolaufrufen.
  • Offline-Agentenbewertungen: Groß angelegte Qualitätsbenchmarks, die previous_interaction_id Turns ohne Echtzeit-Latenzbeschränkungen verketten.

Informationen zum Vergleichen aller Rechenmodelle finden Sie unter Verbrauchsoptionen. Informationen zum Planen von ADK-Agenten (Agent Development Kit) oder verwalteten Ausführungen für den Gemini Deep Research-Agenten finden Sie unter Planung autonomer Agenten.

Unterstützte Modelle und Standorte

Die Stufe „Verzögert“ wird ausschließlich auf dem Endpunkt global (locations/global auf aiplatform.googleapis.com) unterstützt. Wenn Sie eine Anfrage mit service_tier="deferred" an einen regionalen Endpunkt oder an die multiregionalen Endpunkte us oder eu senden, wird HTTP 400 ("code": "invalid_request") zurückgegeben.

Die folgenden Gemini-Hauptmodelle unterstützen die Deferred-Stufe auf dem global-Endpunkt:

Wenn Ihr Projekt über Ihr Google Cloud Account-Management-Team Zugriff auf die Zulassungsliste hat, können Sie auch die folgenden Cyber-Modelle verwenden:

Hinweis

Führen Sie in einem vorhandenen Google Cloud -Projekt mit aktivierter Abrechnung die folgenden erforderlichen Einrichtungsschritte aus:

  1. Melden Sie sich in Ihrem Google-Konto an.

    Wenn Sie noch kein Konto haben, melden Sie sich hier für ein neues Konto an.

  2. Installieren Sie die Google Cloud CLI.

  3. Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

  4. Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:

    gcloud init
  5. Prüfen Sie, ob Sie die Berechtigungen haben, die für diese Anleitung erforderlich sind.

  6. Aktivieren Sie die Agent Platform API, falls sie noch nicht aktiviert ist:

    Rollen, die zum Aktivieren von APIs erforderlich sind

    Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Inhaberrolle (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen

    gcloud services enable aiplatform.googleapis.com
  7. Wenn Sie eine lokale Shell verwenden, erstellen Sie lokale Authentifizierungsdaten für Ihr Nutzerkonto:

    gcloud auth application-default login

    Wenn Sie Cloud Shell verwenden, ist dies nicht erforderlich.

    Wenn ein Authentifizierungsfehler zurückgegeben wird und Sie einen externen Identitätsanbieter (IdP) verwenden, prüfen Sie, ob Sie sich mit Ihrer föderierten Identität in der gcloud CLI angemeldet haben.

  8. Installieren Sie die Google Cloud CLI.

  9. Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

  10. Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:

    gcloud init
  11. Prüfen Sie, ob Sie die Berechtigungen haben, die für diese Anleitung erforderlich sind.

  12. Aktivieren Sie die Agent Platform API, falls sie noch nicht aktiviert ist:

    Rollen, die zum Aktivieren von APIs erforderlich sind

    Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Inhaberrolle (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen

    gcloud services enable aiplatform.googleapis.com
  13. Wenn Sie eine lokale Shell verwenden, erstellen Sie lokale Authentifizierungsdaten für Ihr Nutzerkonto:

    gcloud auth application-default login

    Wenn Sie Cloud Shell verwenden, ist dies nicht erforderlich.

    Wenn ein Authentifizierungsfehler zurückgegeben wird und Sie einen externen Identitätsanbieter (IdP) verwenden, prüfen Sie, ob Sie sich mit Ihrer föderierten Identität in der gcloud CLI angemeldet haben.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Google Cloud -Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen, Überwachen und Abbrechen von verzögerten Modellaufrufen benötigen:

  • Verzögerte Interaktionen erstellen, abfragen, abbrechen und löschen: Agent Platform User (roles/aiplatform.user)
  • Verzögerte Interaktionen überwachen (schreibgeschützt): Agent Platform Viewer (roles/aiplatform.viewer)
  • Multimodale Eingabedateien aus Cloud Storage lesen (optional): Storage-Objekt-Betrachter (roles/storage.objectViewer)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Google Gen AI SDK installieren

Wenn Sie eine Clientbibliothek verwenden, installieren oder aktualisieren Sie das Google Gen AI SDK (@google/genai >= 2.32.0 oder google-genai >= 2.34.0) in Ihrer Entwicklungsumgebung:

Node.js

npm install @google/genai@latest

Python

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

Verzögerte Modellaufrufe erstellen und verwalten

Führen Sie die folgenden Verfahren in der Umgebung aus, die Sie unter Vorbereitung eingerichtet haben. Die REST-Beispiele werden mit Ihren gcloud CLI-Anmeldedaten authentifiziert und die Google Gen AI SDK-Beispiele verwenden Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC). Wenn ein Aufruf einen Fehler zurückgibt, finden Sie weitere Informationen unter Fehlerbehebung.

Verzögerten Modellaufruf erstellen

Reichen Sie einen asynchronen Zug ein, indem Sie interactions.create mit service_tier="deferred", background=true und store=true aufrufen. Lassen Sie stream weg oder legen Sie dafür false fest. Ersetzen Sie vor dem Ausführen eines Beispiels PROJECT_ID durch die Projekt-ID Ihres Projekts in Google Cloud , z. B. my-agent-project.

REST

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • PROJECT_ID: Ihre Google Cloud -Projekt-ID, z. B. my-agent-project.

HTTP-Methode und URL:

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

JSON-Text anfordern:

{
  "model": "gemini-4-argon",
  "input": "In two sentences, explain how a circuit breaker differs from exponential backoff in a distributed microservice architecture.",
  "service_tier": "deferred",
  "background": true,
  "store": true
}

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Die Antwort enthält eine JSON-Nutzlast, die in etwa so aussieht:

{
  "id": "v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0",
  "model": "gemini-4-argon",
  "status": "queued",
  "service_tier": "deferred",
  "steps": []
}

Node.js

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

async function createDeferredInteraction(projectId) {
  const ai = new GoogleGenAI({
    enterprise: true,
    project: projectId,
    location: "global",
  });

  const interaction = await ai.interactions.create({
    model: "gemini-4-argon",
    input:
      "In two sentences, explain how a circuit breaker differs from exponential backoff in a distributed microservice architecture.",
    service_tier: "deferred",
    background: true,
    store: true,
  });

  console.log(`Interaction ID: ${interaction.id}`);
  console.log(`Status: ${interaction.status}`);
  console.log(`Service tier: ${interaction.service_tier}`);
  return interaction.id ?? "";
}

await createDeferredInteraction("PROJECT_ID");

Die Ausgabe sieht etwa so aus:

Interaction ID: v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0
Status: queued
Service tier: deferred

Python

from google import genai

def create_deferred_interaction(project_id: str) -> str:
    client = genai.Client(
        enterprise=True,
        project=project_id,
        location="global",
    )

    interaction = client.interactions.create(
        model="gemini-4-argon",
        input=(
            "In two sentences, explain how a circuit breaker differs from "
            "exponential backoff in a distributed microservice architecture."
        ),
        service_tier="deferred",
        background=True,
        store=True,
    )

    print(f"Interaction ID: {interaction.id}")
    print(f"Status: {interaction.status}")
    print(f"Service tier: {interaction.service_tier}")
    return interaction.id or ""

create_deferred_interaction("PROJECT_ID")

Die Ausgabe sieht etwa so aus:

Interaction ID: v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0
Status: queued
Service tier: deferred

Status abfragen und Tokennutzung abrufen

Fragen Sie interactions.get mit Backoff ab, während status den Wert queued oder in_progress hat. Wenn die Runde einen endgültigen Status erreicht, lesen Sie output_text und usage.

Die Stufe „Verzögert“ zielt darauf ab, 95 % der Turns innerhalb von 24 Stunden abzuschließen, ohne ein guthabenbasiertes Latenz-SLA. In der folgenden Tabelle werden die status-Werte einer Interaction-Ressource beschrieben:

Status Endgültige Fassung Bedeutung und nächster Schritt
queued Nein Akzeptiert und wartet auf Kapazität. Fragen Sie interactions.get mit Backoff ab. Fordern Sie stream=true noch nicht an.
in_progress Nein Laufen. Fragen Sie interactions.get weiter ab oder hängen Sie einen SSE-Stream mit stream=true an.
requires_action Ja Die Runde endete mit einem vom Modell ausgegebenen function_call-Schritt. Führen Sie das Tool aus und erstellen Sie dann mit previous_interaction_id eine neue Runde.
requires_continuation Ja Eine lange Decodierungsrunde wurde mit einer Teilausgabe und einem continuation_token beendet. Fahren Sie mit previous_interaction_id und continuation_token fort, lassen Sie input weg und erhöhen Sie max_output_tokens.
completed Ja Der Zug ist beendet. Lies output_text und usage oder gib id als previous_interaction_id im nächsten Zug weiter.
incomplete Ja Der Turn wurde vorzeitig beendet, z. B. wenn max_output_tokens erreicht wurde. Prüfen Sie die partiellen steps und usage.
failed Ja Bei der Runde ist ein Laufzeitfehler aufgetreten oder das 24-Stunden-Zeitfenster für die Fertigstellung wurde überschritten. Die API verwendet keinen expired-Status. Prüfen Sie error und senden Sie dann eine neue Anfrage.
cancelled Ja Ein Aufruf von interactions.cancel hat die Runde vor dem Abschluss beendet.

Wenn eine Runde mit langer Decodierung als requires_continuation endet, setzen Sie sie fort, indem Sie interactions.create mit previous_interaction_id, continuation_token, background=true, store=true und service_tier="deferred" aufrufen. Lassen Sie input weg und legen Sie max_output_tokens höher als die bisher generierten Tokens fest. Informationen zur Abrechnung der einzelnen endgültigen Status finden Sie unter Preise und Abrechnung.

Ersetzen Sie vor dem Ausführen eines Beispiels die folgenden Werte:

  • PROJECT_ID: Ihre Google Cloud -Projekt-ID, z. B. my-agent-project.
  • INTERACTION_ID: Die Interaktions-ID, die beim Erstellen des verzögerten Modellaufrufs zurückgegeben wurde, z. B. v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.

REST

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • PROJECT_ID: Ihre Google Cloud -Projekt-ID, z. B. my-agent-project.
  • INTERACTION_ID: die Interaktions-ID, die beim Erstellen des verzögerten Modellaufrufs zurückgegeben wurde, z. B. v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.

HTTP-Methode und URL:

GET https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Die Antwort enthält eine JSON-Nutzlast, die in etwa so aussieht:

{
  "id": "v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0",
  "model": "gemini-4-argon",
  "status": "completed",
  "service_tier": "deferred",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Exponential backoff increases the wait time between retries to give a struggling service time to recover. A circuit breaker stops sending requests once failures pass a threshold, failing fast until the downstream service is healthy again."
        }
      ]
    }
  ],
  "usage": {
    "total_input_tokens": 27,
    "total_output_tokens": 41,
    "total_tokens": 68
  }
}

Node.js

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

const PENDING_STATES = new Set(["queued", "in_progress"]);
const MAX_DELAY_MS = 30000;
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function waitForDeferredInteraction(projectId, interactionId) {
  const ai = new GoogleGenAI({
    enterprise: true,
    project: projectId,
    location: "global",
  });

  let delayMs = 5000;
  let current = await ai.interactions.get(interactionId);

  while (PENDING_STATES.has(current.status)) {
    await sleep(delayMs);
    delayMs = Math.min(delayMs * 2, MAX_DELAY_MS);
    current = await ai.interactions.get(interactionId);
  }

  console.log(`Status: ${current.status}`);
  if (current.status === "failed") {
    throw new Error(`Deferred turn failed: ${JSON.stringify(current.error)}`);
  }
  if (current.output_text) {
    console.log(current.output_text);
  }
  if (current.usage) {
    console.log(`Input tokens: ${current.usage.total_input_tokens}`);
    console.log(`Output tokens: ${current.usage.total_output_tokens}`);
    console.log(`Total tokens: ${current.usage.total_tokens}`);
  }
  return current.output_text ?? "";
}

await waitForDeferredInteraction(
  "PROJECT_ID",
  "INTERACTION_ID",
);

Die Ausgabe sieht etwa so aus:

Status: completed
Exponential backoff increases the wait time between retries to give a struggling service time to recover. A circuit breaker stops sending requests once failures pass a threshold, failing fast until the downstream service is healthy again.
Input tokens: 27
Output tokens: 41
Total tokens: 68

Python

import time
from google import genai

PENDING_STATES = frozenset({"queued", "in_progress"})
MAX_DELAY_SECONDS = 30.0

def wait_for_deferred_interaction(
    project_id: str,
    interaction_id: str,
) -> str:
    client = genai.Client(
        enterprise=True,
        project=project_id,
        location="global",
    )

    delay_seconds = 5.0
    current = client.interactions.get(interaction_id)

    while current.status in PENDING_STATES:
        time.sleep(delay_seconds)
        delay_seconds = min(delay_seconds * 2.0, MAX_DELAY_SECONDS)
        current = client.interactions.get(interaction_id)

    print(f"Status: {current.status}")
    if current.status == "failed":
        raise RuntimeError(f"Deferred turn failed: {current.error}")
    if current.output_text:
        print(current.output_text)
    if current.usage:
        print(f"Input tokens: {current.usage.total_input_tokens}")
        print(f"Output tokens: {current.usage.total_output_tokens}")
        print(f"Total tokens: {current.usage.total_tokens}")
    return current.output_text or ""

wait_for_deferred_interaction(
    "PROJECT_ID",
    "INTERACTION_ID",
)

Die Ausgabe sieht etwa so aus:

Status: completed
Exponential backoff increases the wait time between retries to give a struggling service time to recover. A circuit breaker stops sending requests once failures pass a threshold, failing fast until the downstream service is healthy again.
Input tokens: 27
Output tokens: 41
Total tokens: 68

Optional: Ausgabe während eines Aufrufs streamen

Nachdem interactions.get status="in_progress" gemeldet hat, können Sie einen Server-Sent Events (SSE)-Stream mit stream=true anhängen und abgebrochene Verbindungen mit last_event_id fortsetzen:

REST

Hängen Sie ?stream=true an die interactions.get-URL an. Hängen Sie beim Wiederherstellen der Verbindung auch &last_event_id=EVENT_ID an und ersetzen Sie EVENT_ID durch die zuletzt empfangene Ereignis-ID.

Node.js

Iterieren Sie über await ai.interactions.get(interactionId, { stream: true, last_event_id: lastEventId }), zeichnen Sie event.event_id auf und lesen Sie event.delta?.text bei step.delta-Ereignissen.

Python

Iterieren Sie über client.interactions.get(interaction_id, stream=True, last_event_id=last_event_id), zeichnen Sie event.event_id auf und lesen Sie event.delta.text bei step.delta-Ereignissen.

Weitere Informationen zum SSE-Streaming und zur Wiederherstellung der Verbindung finden Sie im Entwicklerleitfaden für die Interactions API.

Verzögerte Multi-Turn-Workflows verketten

Sie können eine Unterhaltung mit mehreren Schritten fortsetzen oder Ergebnisse der Toolausführung zurückgeben, indem Sie die id einer completed- oder requires_action-Interaktion in previous_interaction_id übergeben. Felder auf Turn-Ebene wie tools, system_instruction und generation_config werden nicht automatisch übernommen. Übergeben Sie sie daher bei jedem Turn, für den sie erforderlich sind. Verkettete Turns sind weiterhin für das implizite Kontext-Caching geeignet, obwohl im Cache gespeicherte Präfixe bei mehrstündigen Wartezeiten in der Warteschlange ablaufen können. Schemas für Tool-Ergebnisschritte finden Sie im Entwicklerleitfaden für die Interactions API.

Ersetzen Sie vor dem Ausführen eines Beispiels die folgenden Werte:

  • PROJECT_ID: Ihre Google Cloud -Projekt-ID, z. B. my-agent-project.
  • PREVIOUS_INTERACTION_ID: die ID des vorherigen completed- oder requires_action-Turns, z. B. v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.

REST

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • PROJECT_ID: Ihre Google Cloud -Projekt-ID, z. B. my-agent-project.
  • PREVIOUS_INTERACTION_ID: die ID der abgeschlossenen oder erforderlichen Interaktion aus der vorherigen Runde, z. B. v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.

HTTP-Methode und URL:

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

JSON-Text anfordern:

{
  "model": "gemini-4-argon",
  "previous_interaction_id": "PREVIOUS_INTERACTION_ID",
  "input": "Draft a one-paragraph rollout checklist for adding a circuit breaker to a payment gateway client without causing false trips.",
  "service_tier": "deferred",
  "background": true,
  "store": true
}

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Die Antwort enthält eine JSON-Nutzlast, die in etwa so aussieht:

{
  "id": "v1_Ch1Lm9RUXhPNlJqS1lBMk56UjdVOGdnPT0",
  "model": "gemini-4-argon",
  "previous_interaction_id": "v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0",
  "status": "queued",
  "service_tier": "deferred",
  "steps": []
}

Node.js

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

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

const followUp = await ai.interactions.create({
  model: "gemini-4-argon",
  previous_interaction_id: "PREVIOUS_INTERACTION_ID",
  input:
    "Draft a one-paragraph rollout checklist for adding a circuit breaker to a payment gateway client without causing false trips.",
  service_tier: "deferred",
  background: true,
  store: true,
});

console.log(`Follow-up ID: ${followUp.id} (${followUp.status})`);

Die Ausgabe sieht etwa so aus:

Follow-up ID: v1_Ch1Lm9RUXhPNlJqS1lBMk56UjdVOGdnPT0 (queued)

Python

from google import genai

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

follow_up = client.interactions.create(
    model="gemini-4-argon",
    previous_interaction_id="PREVIOUS_INTERACTION_ID",
    input=(
        "Draft a one-paragraph rollout checklist for adding a circuit "
        "breaker to a payment gateway client without causing false trips."
    ),
    service_tier="deferred",
    background=True,
    store=True,
)

print(f"Follow-up ID: {follow_up.id} ({follow_up.status})")

Die Ausgabe sieht etwa so aus:

Follow-up ID: v1_Ch1Lm9RUXhPNlJqS1lBMk56UjdVOGdnPT0 (queued)

Verzögerten Modellaufruf abbrechen

Wenn Sie eine verzögerte Interaktion beenden möchten, deren status queued oder in_progress ist, rufen Sie interactions.cancel auf. Wenn Sie interactions.cancel für eine Interaktion in einem anderen Status aufrufen, wird HTTP 409 ("code": "aborted") zurückgegeben. Informationen dazu, wie sich ein Abbruch auf die Abrechnung auswirkt, finden Sie unter Preise und Abrechnung.

Ersetzen Sie vor dem Ausführen eines Beispiels die folgenden Werte:

  • PROJECT_ID: Ihre Google Cloud -Projekt-ID, z. B. my-agent-project.
  • INTERACTION_ID: die ID einer queued- oder in_progress-Interaktion, z. B. v1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ.

REST

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • PROJECT_ID: Ihre Google Cloud -Projekt-ID, z. B. my-agent-project.
  • INTERACTION_ID: die ID einer Interaktion, die sich in der Warteschlange befindet oder gerade ausgeführt wird und abgebrochen werden soll, z. B. v1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ.

HTTP-Methode und URL:

POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID/cancel

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Die Antwort enthält eine JSON-Nutzlast, die in etwa so aussieht:

{
  "id": "v1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ",
  "model": "gemini-4-argon",
  "status": "cancelled",
  "service_tier": "deferred"
}

Node.js

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

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

const cancelled = await ai.interactions.cancel("INTERACTION_ID");
console.log(`Status: ${cancelled.status}`);

Die Ausgabe sieht so aus:

Status: cancelled

Python

from google import genai

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

cancelled = client.interactions.cancel("INTERACTION_ID")
print(f"Status: {cancelled.status}")

Die Ausgabe sieht so aus:

Status: cancelled

Preise, Kontingente und Sicherheitsmaßnahmen

Prüfen Sie die Abrechnungsregeln, Kontingente, Nutzlastlimits und Sicherheitskontrollen, bevor Sie Produktionsarbeitslasten in der Deferred-Stufe ausführen.

Preise und Abrechnung

Verzögerte Modellaufrufe werden mit einem Rabatt von 50 % im Vergleich zu den Standardtarifen für Pay as you go für Eingabe-, Ausgabe- und Thinking-Tokens abgerechnet. Für die Abrechnung gelten die folgenden Regeln:

  • Rabattstapelung: Der aufgeschobene Rabatt wird mit Vertragsrabatten und Rabatten für implizites Kontext-Caching kombiniert und zusätzlich zum Cache-Preis angewendet.
  • Kein Fallback auf Standardpreise: Zurückgestellte Anfragen werden nie auf Standard-PayGo umgestellt oder herabgestuft. Sie werden also nicht zu nicht rabattierten On-Demand-Preisen abgerechnet.
  • Abrechnung nach Modellaufruf: Jeder Modellaufruf, der von einem Turn ausgeführt wird, wird abgerechnet. Runden, die mit completed, incomplete, requires_action oder requires_continuation enden, werden zum verzögerten Tarif abgerechnet.
  • Abgebrochene Turns: Ein Turn, den Sie abbrechen, während er queued ist, wird nicht in Rechnung gestellt. Wenn Sie eine Runde abbrechen, während sie den Status in_progress hat, werden bereits gestartete Modellaufrufe in Rechnung gestellt, einschließlich eines Aufrufs, der während der Generierung unterbrochen wird.
  • Fehlgeschlagene Turns: Turns mit einem einzelnen Aufruf, die mit failed enden, einschließlich Turns, die das 24-Stunden-Zeitfenster überschreiten, werden nicht in Rechnung gestellt. In einer mehrstufigen serverseitigen Toolschleife werden abgeschlossene Modellaufrufe vor einem Fehler in Rechnung gestellt, der fehlgeschlagene Aufruf jedoch nicht.
  • Verkettete Runden: Jede Runde in einer previous_interaction_id-Kette wird separat abgerechnet. Wenn Sie eine spätere Runde abbrechen oder eine spätere Runde fehlschlägt, hat das keine Auswirkungen auf die Kosten für frühere Runden.

Die Token-Preise pro Modell finden Sie auf der Preisseite für die Agent Platform.

Kontingente, Nutzlastlimits und Aufbewahrung

Die Stufe „Verzögert“ hat kein eigenes Kontingent für Modellaufrufe. Verzögerte Aufrufe teilen sich das Flex-Kontingent für Pay as you go (flex_requests_per_minute_per_project_per_base_model, 3.000 RPM), das bei jedem Modellaufruf geprüft wird, nachdem interactions.create den Wert queued zurückgegeben hat. Zu den wichtigsten Projektkontingenten und Systemlimits gehören:

  • Kontingente für Erstellung und Nebenläufigkeit: Bis zu 100 Anfragen pro Minute oder unbegrenzt für stateful_genai_interaction_creations zum Zeitpunkt der Erstellung. Bis zu 500 concurrent_interaction_generations, je nach Kontingentstufe.
  • Täglicher zustandsorientierter Durchsatz (festgelegt): 240 GiB pro Tag geschrieben und 480 GiB pro Tag gelesen pro Projekt.
  • Nutzlast- und Aufbewahrungslimits: Bis zu 9, 75 MiB unkomprimierter HTTP-Text pro interactions.create-Aufruf und 7 Tage Aufbewahrung des Status. Ketten unterstützen bis zu 100 verschiedene Cloud Storage-URIs (gs://).

Die vollständige Kontingenttabelle und eine Anleitung für die Console finden Sie unter Kontingente und Limits für die verzögerte Stufe.

Sicherheits- und Compliance-Einstellungen

Da die Stufe „Verzögert“ den Status auf dem Endpunkt global in die Warteschlange stellt und beibehält, sollten Sie prüfen, ob die unterstützten Governance-Einstellungen Ihren Compliance-Anforderungen entsprechen:

Die vollständige Feature-Matrix finden Sie unter Sicherheitskontrollen für generative KI.

Fehlerbehebung

In der folgenden Tabelle werden häufige Fehler auf der Stufe „Verzögert“ und deren Behebung beschrieben:

Fehler oder Status Allgemeine Ursachen Lösung
400 (error.code: "invalid_request"; Endpunkt, Flags oder Modell) Nicht-global-Endpunkt, nicht unterstütztes Modell oder ungültige background-, store- oder stream-Flags für interactions.create. Legen Sie als Ziel locations/global mit einem unterstützten Modell fest, legen Sie background=true und store=true fest und lassen Sie stream=true weg.
400 (error.code: "invalid_request"; Nutzlast, URIs oder Tools) Unkomprimierter Text überschreitet 9, 75 MiB, Kette überschreitet 100 gs://-URIs oder externe mcp_server-Tools innerhalb von VPC-SC. Übergeben Sie große Dateien als gs://-URIs (maximal 100 pro Kette) und lassen Sie externe mcp_server-Tools in VPC-SC weg.
400 (error.code: "invalid_request" am interactions.create; status: "FAILED_PRECONDITION" am interactions.delete)
  • Die Richtlinie constraints/vertexai.disableAPIStorage wird erzwungen.
  • interactions.create wird an eine queued- oder in_progress-Runde angehängt oder legt input für requires_continuation fest.
  • interactions.delete zielt auf eine queued- oder in_progress-Abbiegung ab.
  • Verwenden Sie ein Projekt, das die API-Statuspersistenz zulässt.
  • Verketten Sie nur die letzten Turns. Am requires_continuation, continuation_token bestanden und input ausgelassen.
  • Brechen Sie aktive Turns ab, bevor Sie sie löschen.
401 (status: "UNAUTHENTICATED" oder error.code: "authentication") Ihre gcloud CLI-Anmeldedaten (REST-Beispiele) oder Standardanmeldedaten für Anwendungen (Google Gen AI SDK-Beispiele) fehlen oder sind abgelaufen. Führen Sie für REST-Beispiele gcloud auth login aus. Führen Sie für Google Gen AI SDK-Beispiele gcloud auth application-default login aus. Wiederholen Sie dann die Anfrage.
403 (status: "PERMISSION_DENIED" oder error.code: "permission_denied")
  • Der Aufrufer hat nicht die Berechtigung roles/aiplatform.user.
  • Der Aufrufer hat nicht die Berechtigung storage.objects.get für gs://-Eingaben.
roles/aiplatform.user gewähren. Gewähren Sie für Cloud Storage-Eingaben auch roles/storage.objectViewer.
404 (error.code: "not_found"; status: "NOT_FOUND" am interactions.delete) Die Interaktion oder previous_interaction_id ist nicht vorhanden oder wurde gelöscht. Möglicherweise gehört sie auch zu einem Nicht-global-Endpunkt oder ist älter als die 7-tägige Aufbewahrungsdauer. Prüfen Sie die Interaktions-ID am Endpunkt global. Wenn der übergeordnete Turn abgelaufen ist, starte eine neue Kette ohne previous_interaction_id.
409 (error.code: "aborted") interactions.cancel zielt auf eine Interaktion ab, die bereits einen endgültigen Status hat: requires_action, requires_continuation, completed, incomplete, failed oder cancelled. Prüfe zuerst status mit interactions.get. Sie können nur queued- und in_progress-Interaktionen abbrechen.
429 (error.code: "too_many_requests") Das Projekt hat ein projektbezogenes Kontingent überschritten, z. B. die Rate für die Erstellung von Interaktionen, die Anzahl gleichzeitiger Interaktionsgenerierungen oder den täglichen zustandsorientierten Durchsatz.
status="failed"
  • Es ist ein Fehler im Upstream-Modell oder ‑Tool aufgetreten oder die Runde hat das 24-Stunden-Zeitfenster für die Fertigstellung überschritten.
  • Die Anfrage verwendet ein *-cyber*-Modell und das Projekt hat keinen Zugriff auf die Zulassungsliste.
  • Prüfen Sie das Feld error, das von interactions.get zurückgegeben wird, und senden Sie dann eine neue interactions.create-Anfrage.
  • Für Cyber-Modelle müssen Sie den Zugriff auf die Zulassungsliste mit Ihrem Google Cloud -Account-Management-Team bestätigen.

Nächste Schritte

Sehen Sie sich die zugehörigen Anleitungen und Referenzdokumentationen für asynchrone und zustandsorientierte Gemini-Arbeitslasten an: