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_idTurns 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:
- Gemini 4 Carbon (
gemini-4-carbon) - Gemini 4 Argon (
gemini-4-argon) - Gemini 3.8 Flash (
gemini-3.8-flash) - Gemini 3.7 Flash (
gemini-3.7-flash) - Gemini 3.6 Flash (
gemini-3.6-flash) - Gemini 3.5 Flash-Lite (
gemini-3.5-flash-lite) - Gemini 3.5 Flash (
gemini-3.5-flash) - Gemini 3.1 Flash-Lite (
gemini-3.1-flash-lite) - Gemini 3.1 Pro (
gemini-3.1-pro-preview)
Wenn Ihr Projekt über Ihr Google Cloud Account-Management-Team Zugriff auf die Zulassungsliste hat, können Sie auch die folgenden Cyber-Modelle verwenden:
- Gemini 4 Carbon for Cyber (
gemini-4-carbon-cyber-permissive) - Gemini 4 Argon Cyber Permissive (
gemini-4-argon-cyber-permissive)
Hinweis
Führen Sie in einem vorhandenen Google Cloud -Projekt mit aktivierter Abrechnung die folgenden erforderlichen Einrichtungsschritte aus:
-
Melden Sie sich in Ihrem Google-Konto an.
Wenn Sie noch kein Konto haben, melden Sie sich hier für ein neues Konto an.
-
Installieren Sie die Google Cloud CLI.
-
Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.
-
Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:
gcloud init -
Prüfen Sie, ob Sie die Berechtigungen haben, die für diese Anleitung erforderlich sind.
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 Rollengcloud services enable aiplatform.googleapis.com
-
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.
-
Installieren Sie die Google Cloud CLI.
-
Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.
-
Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:
gcloud init -
Prüfen Sie, ob Sie die Berechtigungen haben, die für diese Anleitung erforderlich sind.
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 Rollengcloud services enable aiplatform.googleapis.com
-
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 vorherigencompleted- oderrequires_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 einerqueued- oderin_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_actionoderrequires_continuationenden, werden zum verzögerten Tarif abgerechnet. - Abgebrochene Turns: Ein Turn, den Sie abbrechen, während er
queuedist, wird nicht in Rechnung gestellt. Wenn Sie eine Runde abbrechen, während sie den Statusin_progresshat, 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
failedenden, 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_creationszum Zeitpunkt der Erstellung. Bis zu 500concurrent_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:
- Unterstützte Kontrollen:
VPC Service Controls
(VPC-SC; externe
mcp_server-Tools sind innerhalb eines Perimeters nicht zulässig), Access Transparency (AXT), Cloud-Audit-Logs und FedRAMP High. - Nicht unterstützte Kontrollen: Zustandslose Zero-Data Retention (
store=falseund Erzwingung vonconstraints/vertexai.disableAPIStoragegeben beide HTTP400mit"code": "invalid_request"zurück), vom Kunden verwaltete Verschlüsselungsschlüssel (CMEK), Datenstandort, DoD IL5 und ITAR.
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) |
|
|
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") |
|
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" |
|
|
Nächste Schritte
Sehen Sie sich die zugehörigen Anleitungen und Referenzdokumentationen für asynchrone und zustandsorientierte Gemini-Arbeitslasten an:
- Vergleichen Sie die Rechenmodelle unter Nutzungsoptionen.
- Zustandsorientierte Multi-Turn-Anwendungen im Entwicklerleitfaden für die Interactions API erstellen
- Planen Sie ADK-Agenten und verwaltete Rechercheausführungen unter Planung autonomer Agenten.
- Methodenschemas finden Sie in der Interactions API-Referenz.