Wenn Sie mehrstufige agentische Workflows bereitstellen (z. B. umfangreiche Dokumentsynthese und langwierige Recherchen), kann die Ausführung von Hintergrund-Agents auf Echtzeitmodellen unnötigen Druck auf die Infrastruktur ausüben und Fehler aufgrund von Ressourcenerschöpfung (429) auslösen.
Die Gemini Enterprise Agent Platform bietet eine verzögerte Stufe, einen durchsatzoptimierten Planer, der speziell für latenzunempfindliche Arbeitslasten entwickelt wurde. Anstatt langwierige autonome Aufgaben mit derselben unmittelbaren Dringlichkeit wie eine Live-Chat-Anfrage zu behandeln, stellt der Planer Ihre komplexen mehrstufigen Agenten-Workflows in eine Warteschlange, um sie zu Zeiten geringer Auslastung auszuführen. So werden hohe Erfolgsraten und ein hoher Gesamtdurchsatz angestrebt.
Wenn Sie eine Anfrage über die verzögerte Stufe senden, akzeptiert die API die Aufgabe asynchron und gibt sofort eine Interaktions-ID zurück. Die verzögerte Stufe bietet Folgendes:
Rabattierter Preis: Sie erhalten einen Rabatt von 50 % auf die Preise für die Modellinferenz im Vergleich zu einer Standardanfrage. So können Sie die Kosten für Ihre Agenten in der Produktion besser verwalten. Weitere Informationen finden Sie unter Preise.
Höherer Durchsatz: Die Deferred-Stufe reduziert 429-Fehler (Einschränkungen der Modellkapazität) und Ratenbegrenzungen, indem Ihre umfangreichen, asynchronen Arbeitslasten außerhalb der Spitzenzeiten verschoben werden. Dadurch wird Standard-Kontingent für Ihre Echtzeit-Produktionsanforderungen freigegeben.
Zeitüberschreitung bei Abschluss: Die zurückgestellte Stufe zielt darauf ab, 95 % der Aufgaben innerhalb von 24 Stunden abzuschließen. Wenn eine Aufgabe nicht innerhalb dieses Zeitfensters abgeschlossen wird, läuft sie ab und wechselt in den Status
failed. Die tatsächliche Zeit, die in der Warteschlange verbracht wird, hängt von der aktuellen regionalen Clusterkapazität und der Nachfrage ab.
Anwendungsfälle
Die verzögerte Stufe eignet sich gut für Anwendungsfälle, bei denen eine Bearbeitungszeit von mehreren Stunden akzeptabel ist, z. B.:
Finanzen: Tägliche oder wöchentliche Aktien- und Marktforschung.
Rechtliches und Compliance: Due-Diligence-Prüfung von mehreren Dokumenten im Zusammenhang mit gesetzlichen Bestimmungen sowie Fusionen und Übernahmen.
Strategie: Kontinuierliche Wettbewerbsanalyse und Trendbeobachtung.
Sicherheit: Scannen auf Sicherheitslücken in der Codebasis und Behebung dieser Sicherheitslücken.
Unterstützte KI-Agenten
Sie können die autonome Agentenplanung für die folgenden Agenten konfigurieren. Wählen Sie einen Agenten aus, um die entsprechende Einrichtungsanleitung aufzurufen:
Informationen zum Ausführen benutzerdefinierter oder Drittanbieter-Agentenschleifen direkt in Gemini-Modellen finden Sie unter Verzögerte Stufe verwenden.
ADK-Agenten planen
Im ADK legen Sie den Parameter service_tier für RunConfig pro Aufruf fest, anstatt eine feste Stufe für den KI-Agenten oder das Modell zu konfigurieren. Wenn Sie service_tier=ServiceTier.DEFERRED festlegen, wird jeder Modellaufruf in einen Kapazitätspool für Nebenzeiten eingereiht, während die Standardeinstellung ServiceTier.STANDARD synchron ausgeführt wird. Mit dieser Einstellung pro Ausführung kann eine Agentendefinition sowohl interaktive Anfragen als auch Offline-Batch-Workflows verarbeiten.
Wenn Sie eine verzögerte Anfrage für einen ADK-Agenten senden, automatisiert das ADK die Hintergrundübermittlung, das Polling und den Abruf für Sie:
- Das ADK sendet die Modellanfrage mit aktivierter Hintergrundausführung und das Backend gibt eine Interaktions-ID mit dem Status
queuedoderin_progresszurück. - Solange die Interaktion aussteht, fragt das ADK das Backend mit exponentiellem Backoff ab.
- Wenn die Interaktion einen endgültigen Status erreicht, wandelt das ADK die abgeschlossene Interaktion in Standardmodell-Antwort-Ereignisse um, die Sie über die Runner-Schnittstelle nutzen können.
In diesem Abschnitt werden die folgenden Aufgaben zum Planen von ADK-Agents behandelt:
- Lesen Sie die Anforderungen und Einschränkungen, bevor Sie die verzögerte Stufe aktivieren.
- ADK-Agenten auf der verzögerten Stufe
mit
RunConfig(service_tier=ServiceTier.DEFERRED)ausführen - Verzögerte ADK-Agenten in der Agent Runtime, in Cloud Run oder in der Google Kubernetes Engine (GKE) bereitstellen
- Erzwingen Sie eine Client-Frist, um die clientseitige Wartezeit zu begrenzen.
Weitere Informationen zur ServiceTier-Konfiguration im ADK finden Sie in der ADK-Dokumentation unter Verzögerte Planung.
Einschränkungen für ADK-Agenten
Beachten Sie die folgenden Anforderungen und Einschränkungen, wenn Sie ADK-Agents in der zurückgestellten Stufe planen:
- Erfordert die Interactions API: Bereitstellungsstufen gelten nur für Modelle, die für die Interactions API konfiguriert sind, z. B.
Gemini(use_interactions_api=True). Standardmodelle zur Inhaltsgenerierung undManagedAgentignorierenservice_tier. - Nicht mit Token-Streaming kompatibel: Die verzögerte Ausführung kann nicht mit
StreamingMode.SSEinRunConfigkombiniert werden. Lassen Sie beim Aufrufen von/run_ssestreamingweg oder legen Sie"streaming": falsefest. Wenn Sie"streaming": truemit"service_tier": "deferred"übergeben, wird HTTP422 Unprocessable Entityzurückgegeben. - HTTP-Verbindungslimits: Bei
adk api_serverhalten/runund/run_ssedie HTTP-Verbindung während der Wartezeit in der Warteschlange offen. Wenn die Verbindung durch ein Proxy- oder Plattform-Zeitlimit geschlossen wird (z. B. das 60-Minuten-Limit von Cloud Run), wird das Client-Polling beendet. Die Backend-Interaktion wird weiterhin bis zum Ende ausgeführt und es fallen Kosten an. - Warteschlangenlatenz pro Turn: In Workflows mit mehreren Turns oder Toolaufrufen wird für jeden Modell-Turn eine separate Interaktionsanfrage gesendet. Für jede Runde fällt eine eigene Wartezeit in der Warteschlange außerhalb der Spitzenzeiten an.
- Keine Wiederaufnahme laufender Interaktionen nach Neustarts: Das ADK speichert keine laufenden Interaktions-IDs im Sitzungsspeicher und stellt keine Verbindung zu getrennten Interaktionen wieder her. Wenn ein Clientprozess beendet wird, wird die ausstehende Abfrageschleife abgebrochen und ein nachfolgender Aufruf startet eine neue Interaktion.
ADK-Agenten auf der verzögerten Stufe ausführen
Wenn Sie einen ADK-Agenten auf der Deferred-Stufe planen möchten, konfigurieren Sie Ihr Gemini-Modell mit use_interactions_api=True und übergeben Sie RunConfig(service_tier=ServiceTier.DEFERRED), wenn Sie den Runner aufrufen:
import asyncio
from google.adk.agents import LlmAgent
from google.adk.agents import RunConfig
from google.adk.apps import App
from google.adk.models import ServiceTier
from google.adk.models.google_llm import Gemini
from google.adk.runners import InMemoryRunner
from google.genai import types
root_agent = LlmAgent(
name="batch_agent",
model=Gemini(
model="gemini-3.5-flash",
use_interactions_api=True,
client_kwargs={
"enterprise": True,
"project": "PROJECT_ID",
"location": "global",
},
),
instruction="Process input documents and produce summaries.",
)
app = App(
name="batch_app",
root_agent=root_agent,
)
runner = InMemoryRunner(app=app)
async def main() -> None:
session = await runner.session_service.create_session(
app_name=app.name,
user_id="user_123",
session_id="session_456",
)
run_config = RunConfig(service_tier=ServiceTier.DEFERRED)
async for event in runner.run_async(
user_id="user_123",
session_id=session.id,
new_message=types.Content(
role="user",
parts=[
types.Part.from_text(
text="Summarize quarterly performance metrics."
)
],
),
run_config=run_config,
):
if event.content and event.content.parts:
for part in event.content.parts:
if part.text:
print(part.text)
asyncio.run(main())
Ersetzen Sie dabei PROJECT_ID durch die ID Ihres Projekts in Google Cloud .
Solange der Interaktionsstatus queued oder in_progress ist, liefert runner.run_async() keine Ereignisse, bis die Interaktion abgeschlossen ist. Prüfen Sie, ob die verzögerte Stufe aktiv ist, indem Sie in Ihren Anwendungslogs nach den folgenden Meldungen suchen:
- Auf der Ebene
INFOwerden die Interaktions-TransportlogsInteraction INTERACTION_ID is queued; waiting for the result.undInteraction INTERACTION_ID reached status completed.protokolliert. Wenn das Debugging-Logging aktiviert ist, protokolliert der Anfrageprozessor auchUsing service_tier from run_config: ServiceTier.DEFERRED. - Wenn
use_interactions_api=Truefür das Modell nicht festgelegt ist, ignoriert das ADKservice_tier, fährt mit der Standardgenerierung fort und protokolliert eine Warnung, dass das Modell die Interactions API nicht verwendet.
Verzögerte ADK-Agenten bereitstellen
Sie konfigurieren service_tier pro Anfrage und nicht in der Agent-Definition. So kann ein ADK-Agent-Paket (use_interactions_api=True) sowohl Echtzeit- als auch verzögerte Arbeitslasten verarbeiten. Sie können dieses Paket in der Agent Runtime, in Cloud Run oder in der GKE bereitstellen.
In der folgenden Tabelle werden die Bereitstellungsoptionen für verzögerte ADK-Arbeitslasten verglichen:
| Bereitstellungsoption | Geeignet für | Ausführungsmodell | Maximales Zeitlimit | Verzögerte Stufe anfordern |
|---|---|---|---|---|
| Agent Runtime | Asynchrone Hintergrundjobs, bei denen die Agent Platform Sitzungen verwaltet, ohne eine HTTP-Verbindung offen zu halten, und Ergebnisse direkt in Cloud Storage schreibt | Verwalteter Hintergrundjob (run_query_job) |
168 Stunden (7 Tage; 24 Stunden pro Modellrunde) |
"run_config": {"service_tier": "deferred"} in
input
|
| Cloud Run-Dienst | Serverlose HTTPS-Endpunkte, die sowohl interaktive Anfragen als auch verzögerte Arbeitslasten verarbeiten, die innerhalb von 60 Minuten abgeschlossen werden | Serverloses HTTP oder SSE (adk deploy cloud_run) |
60 Minuten (3.600 Sekunden) |
"service_tier": "deferred" im Anfragetext von /run oder /run_sse (mit "streaming": false)
|
| Cloud Run-Job | Serverlose Batcharbeitslasten ohne HTTP-Verbindung, die möglicherweise länger als 60 Minuten warten (bis zu 24 Stunden pro Modellrunde) | Serverloser Batch-Container (gcloud run jobs) |
168 Stunden (7 Tage) | RunConfig(service_tier=ServiceTier.DEFERRED) |
| GKE | Kubernetes-Arbeitslasten, die benutzerdefinierte Netzwerke, die Steuerung des Pod-Lebenszyklus oder keine Zeitlimits für serverlose Anfragen erfordern | Kubernetes-Pods (adk deploy gke) |
Unbegrenzt (Pod und eingehender Traffic konfiguriert) |
"service_tier": "deferred" im Anfragetext von /run oder /run_sse (mit "streaming": false)
|
Wenn Ihr Modell den Endpunkt global verwendet, während Ihre Bereitstellung auf einem regionalen Endpunkt (z. B. us-central1) ausgeführt wird, übergeben Sie client_kwargs={"location": "global"} an Gemini(...). Achten Sie darauf, dass Ihr Laufzeitdienstkonto die Rolle „Agent Platform User“ (roles/aiplatform.user) für Ihr Projekt hat.
Wählen Sie ein Bereitstellungsziel aus, um die Konfigurationsanleitung aufzurufen:
Agent Runtime
Wenn Sie Ihren Agenten in Agent Runtime bereitstellen, legen Sie agent_framework="google-adk" fest und fügen Sie google-adk>=2.10.0 in requirements ein. Weisen Sie dem Reasoning Engine-Dienst-Agent (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.) die Rolle „Storage-Objekt-Ersteller“ (roles/storage.objectCreator) für den Ausgabe-Bucket zu.
Wenn Sie einen asynchronen, verzögerten Abfragejob mit langer Ausführungszeit senden möchten, rufen Sie client.runtimes.run_query_job() auf und übergeben Sie "run_config": {"service_tier": "deferred"} in input:
import json
import agentplatform
client = agentplatform.Client(
project="PROJECT_ID",
location="LOCATION",
)
job = client.runtimes.run_query_job(
name=(
"projects/PROJECT_ID"
"/locations/LOCATION"
"/reasoningEngines/RESOURCE_ID"
),
config={
"query": json.dumps({
"class_method": "async_stream_query",
"input": {
"user_id": "USER_ID",
"session_id": "SESSION_ID",
"message": "Summarize quarterly performance metrics.",
"run_config": {"service_tier": "deferred"},
},
}),
"output_gcs_uri": (
"gs://BUCKET_NAME"
"/OUTPUT_FILE.jsonl"
),
},
)
Ersetzen Sie Folgendes:
PROJECT_ID: Projekt-ID in Google Cloud .LOCATION: die unterstützte Region, in der Ihr Agent bereitgestellt wird, z. B.us-central1.RESOURCE_ID: die numerische ID der bereitgestelltenreasoningEngine-Ressource.USER_IDundSESSION_ID: die Nutzer- und Sitzungs-IDs für den Aufruf.BUCKET_NAMEundOUTPUT_FILE: der Cloud Storage-Bucket und das Objektpräfix, in die Agent Runtime gestreamte Ereignisse als durch Zeilenumbruch getrenntes JSON (application/x-ndjson, ein JSON-Objekt pro Zeile) schreibt.
Cloud Run
Konfigurieren Sie entweder einen Cloud Run-Dienst oder einen Cloud Run-Job basierend auf der erwarteten Warteschlangendauer:
Cloud Run-Dienst (
adk deploy cloud_run): Stelltadk api_serverhinter einem HTTPS-Endpunkt (/runund/run_sse) bereit. Übergeben Sie bei der Bereitstellung-- --timeout=3600, damit Cloud Run die HTTP-Verbindung nicht nach dem standardmäßigen Zeitlimit von 5 Minuten schließt:adk deploy cloud_run \ --project=PROJECT_ID \ --region=LOCATION \ --service_name=SERVICE_NAME \ AGENT_DIR \ -- --no-allow-unauthenticated --timeout=3600Ersetzen Sie Folgendes:
PROJECT_ID: Projekt-ID in Google Cloud .LOCATION: die Cloud Run-Region, z. B.us-central1.SERVICE_NAME: Der Name Ihres Cloud Run-Dienstes.AGENT_DIR: der Pfad zum Quellverzeichnis Ihres Agenten.
Bevor Sie
/runoder/run_sseaufrufen, erstellen Sie eine Sitzung mitPOST /apps/APP_NAME/users/USER_ID/sessions, wobeiAPP_NAMEstandardmäßig der Name Ihres Agentenverzeichnisses ist. Wenn Sie eine verzögerte Ausführung anfordern möchten, fügen Sie"service_tier": "deferred"als Feld auf oberster Ebene in den JSON-Anfragetext ein. Lassen Sie beim Aufrufen von/run_ssestreamingweg oder legen Sie"streaming": falsefest (wenn Sie"streaming": trueübergeben, wird HTTP422 Unprocessable Entityzurückgegeben):{ "app_name": "batch_app", "user_id": "user_123", "session_id": "session_456", "new_message": { "role": "user", "parts": [{"text": "Summarize batch results."}] }, "service_tier": "deferred", "streaming": false }Cloud Run-Job (
gcloud run jobs deploy): Führt einen Container bis zum Abschluss ohne HTTP-Anfrage-Lebenszyklus aus und unterstützt--task-timeoutbis zu 168 Stunden (7 Tage). Übergeben SieRunConfig(service_tier=ServiceTier.DEFERRED)anrunner.run_async()im Einstiegspunkt Ihres Jobs und stellen Sie den Job mit--task-timeout=86400s(24 Stunden) bereit.
GKE
Verpacken Sie Ihren ADK-Agenten und stellen Sie ihn mit adk deploy gke in einem GKE-Cluster bereit:
adk deploy gke \
--project=PROJECT_ID \
--region=LOCATION \
--cluster_name=CLUSTER_NAME \
--service_name=SERVICE_NAME \
AGENT_DIR
Ersetzen Sie Folgendes:
PROJECT_ID: Projekt-ID in Google Cloud .LOCATION: die Region Ihres regionalen GKE-Cluster, z. B.us-central1.CLUSTER_NAME: Name Ihres GKE-Clusters.SERVICE_NAME: der Kubernetes-Dienstname für Ihren Agenten.AGENT_DIR: der Pfad zum Quellverzeichnis Ihres Agenten.
Bevor Sie /run oder /run_sse aufrufen, erstellen Sie eine Sitzung mit POST
/apps/APP_NAME/users/USER_ID/sessions, wobei APP_NAME standardmäßig der Name Ihres Agentenverzeichnisses ist. Wenn Sie eine verzögerte Ausführung anfordern möchten, fügen Sie "service_tier": "deferred" als Feld auf oberster Ebene in den JSON-Anfragetext ein. Lassen Sie beim Aufrufen von /run_sse streaming weg oder legen Sie "streaming": false fest (wenn Sie "streaming": true übergeben, wird HTTP 422 Unprocessable Entity zurückgegeben):
{
"app_name": "batch_app",
"user_id": "user_123",
"session_id": "session_456",
"new_message": {
"role": "user",
"parts": [{"text": "Summarize batch results."}]
},
"service_tier": "deferred",
"streaming": false
}
Bei Anfragen an /run und /run_sse bleibt die HTTP-Verbindung während der Wartezeit in der Warteschlange und der Modellausführung geöffnet. Erhöhen Sie die Zeitlimits für GKE-Ingress und Load-Balancer-Back-Ends, um erwartete Verzögerungen in der Warteschlange zu berücksichtigen. Wenn die Clientverbindung geschlossen wird oder das Zeitlimit überschritten wird, bricht der Server die lokale Abfrage ab. Die Backend-Interaktion wird weiterhin ausgeführt und verursacht Kosten, ohne dass eine Ausgabe zurückgegeben wird.
Frist für Clients erzwingen
Das ADK wendet kein clientseitiges Zeitlimit auf die Warteschlange an, sondern verlässt sich auf das 24-Stunden-Zeitlimit des Backends. Wenn Sie die gesamte verstrichene Wartezeit in Ihrer Anwendung begrenzen möchten, verpacken Sie runner.run_async() in asyncio.timeout():
import asyncio
import logging
from google.adk.agents import RunConfig
from google.adk.models import ServiceTier
from google.genai import types
logger = logging.getLogger(__name__)
# Continues from the earlier example using existing runner and session objects:
async def run_with_deadline(runner, session) -> None:
message = types.Content(
role="user",
parts=[
types.Part.from_text(text="Generate quarterly financial summary.")
],
)
run_config = RunConfig(service_tier=ServiceTier.DEFERRED)
try:
async with asyncio.timeout(300):
async for event in runner.run_async(
user_id="user_123",
session_id=session.id,
new_message=message,
run_config=run_config,
):
if event.content and event.content.parts:
for part in event.content.parts:
if part.text:
print(part.text)
except TimeoutError:
logger.error(
"Client timeout exceeded after 300 seconds. The deferred interaction"
" continues to run and incur billing on the backend, so its output"
" cannot be retrieved."
)
Wenn Sie ein Client-Zeitlimit erzwingen, wird die clientseitige Abfrageschleife beim nächsten Ruheintervall beendet, aber die Arbeit im Backend wird nicht abgebrochen. Auch nach einer Client-Zeitüberschreitung wird die Interaktion bis zum Abschluss ausgeführt und es fallen Kosten auf dem Server an.
Gemini Deep Research-Agent planen
Mit der Interactions API können Sie eine verzögerte Deep Research-Aufgabe erstellen, überwachen, abbrechen und Ergebnisse abrufen.
Verzögerte Aufgabe erstellen
Das folgende Beispiel zeigt, wie Sie eine Deep Research-Aufgabe mit der verzögerten Stufe und client.interactions.create() starten:
import time
from google import genai
client = genai.Client(
enterprise=True,
project="PROJECT_ID",
location="global",
)
PROMPT = "Analyze the latest market trends in renewable energy storage."
DEEP_RESEARCH_AGENT = "deep-research-preview-04-2026"
interaction = client.interactions.create(
input=PROMPT,
agent=DEEP_RESEARCH_AGENT, # Agent identifier
service_tier="deferred", # Run on deferred tier for off-peak scheduling
background=True, # Return immediately instead of waiting for the answer
store=True, # Persist interaction state to poll or stream later
stream=False, # `stream` must be set to False during task creation
)
print(f"Interaction ID: {interaction.id}")
print(f"Status: {interaction.status}")
print(f"Service tier: {interaction.service_tier}")
Ersetzen Sie dabei PROJECT_ID durch die ID Ihres Projekts in Google Cloud .
Die Methode gibt sofort status="queued" oder status="in_progress" und service_tier="deferred" zurück.
Aufgabenfortschritt überwachen
Während die Interaktion status auf Kapazität außerhalb der Spitzenzeiten wartet und aktiv ausgeführt wird, ist sie queued oder in_progress. Während der Agent die Planungs-, Such- und Analyseschritte ausführt, werden der Liste steps neue Elemente hinzugefügt.
Sie können den Aufgabenstatus programmatisch verfolgen, indem Sie die Interaktion regelmäßig abfragen oder Updates streamen.
Umfragen
Fragen Sie die Interaktion regelmäßig ab (z. B. alle 15–30 Sekunden), bis die Interaktion einen der Endstatus erreicht: completed, failed, cancelled oder incomplete.
TERMINAL_STATES = ("completed", "failed", "cancelled", "incomplete")
POLL_INTERVAL_SECONDS = 15
TIMEOUT_MINUTES = 60
started = time.time()
deadline = started + TIMEOUT_MINUTES * 60
while True:
current = client.interactions.get(interaction.id)
elapsed = int(time.time() - started)
steps = getattr(current, "steps", None) or []
print(f"[{elapsed:>4}s] status={current.status} steps={len(steps)}")
if current.status in TERMINAL_STATES:
break
if time.time() >= deadline:
raise TimeoutError(
f"Still {current.status} after {TIMEOUT_MINUTES} min. The interaction "
"continues running server-side; re-run the check to resume polling."
)
time.sleep(POLL_INTERVAL_SECONDS)
print(f"\nFinished in {int(time.time() - started)}s with status={current.status}.")
Streaming
Sie können Echtzeitaktualisierungen abonnieren, indem Sie client.interactions.get() mit stream=True aufrufen. Sobald die Interaktion den Status in_progress erreicht, werden im Stream Ereignisse wie Zwischengedanken, Textdeltas und Statusaktualisierungen übertragen, sobald sie auftreten.
Wenn die Verbindung unterbrochen wird, während die Aufgabe noch queued oder in_progress ist, stellen Sie die Verbindung zum Stream mit client.interactions.get() und stream=True wieder her und übergeben Sie die zuletzt empfangene Ereignis-ID an last_event_id. Wenn Sie last_event_id weglassen, spielt die API jedes Ereignis von Anfang an ab.
INTERACTION_ID = interaction.id # from the create step
MAX_RECONNECTS = 5
STREAM_TIMEOUT = 300 # seconds
print(
f"streaming interaction: {INTERACTION_ID} (status={interaction.status})\n"
)
def render(event):
"""Prints one SSE event. Returns True once the interaction has finished."""
if event.event_type == "step.delta":
delta = event.delta
if delta.type == "text":
print(delta.text, end="", flush=True)
elif delta.type == "thought_summary":
summary = (getattr(delta.content, "text", "") or "").strip()
if summary:
print(f"\n[thinking] {summary[:200]}", flush=True)
elif delta.type.endswith("_call"):
queries = getattr(getattr(delta, "arguments", None), "queries", None)
print(
f"\n[{delta.type}] {', '.join(queries) if queries else ''}",
flush=True,
)
elif event.event_type == "interaction.status_update":
print(f"[status] {event.status}", flush=True)
elif event.event_type == "interaction.completed":
print(f"\n\n[status] {event.interaction.status}", flush=True)
return True
elif event.event_type == "error":
print(f"\n[error] {event.error.message}", flush=True)
return True
return False
last_event_id = None
finished = False
for attempt in range(MAX_RECONNECTS):
try:
# stream=True turns the GET into a live subscription. last_event_id=None on
# the first pass, so the server starts from the beginning of the run.
for event in client.interactions.get(
INTERACTION_ID,
stream=True,
last_event_id=last_event_id,
timeout=STREAM_TIMEOUT,
):
last_event_id = event.event_id or last_event_id
finished = render(event) or finished
except Exception as e: # pylint: disable=broad-except
# A dropped connection loses nothing: the run continues server-side and the
# next iteration reattaches from last_event_id.
print(f"\n[stream dropped: {type(e).__name__}] reattaching...", flush=True)
if finished:
break
# The server also closes the stream when the run ends, without an error.
if client.interactions.get(
INTERACTION_ID, timeout=STREAM_TIMEOUT
).status not in ("queued", "in_progress"):
break
else:
print(f"\n[gave up after {MAX_RECONNECTS} reconnects]")
print(f"\n\nStreamed interaction: {INTERACTION_ID}")
Aufgabe abbrechen
Sie können eine Aufgabe abbrechen, solange ihr Status queued, in_progress oder requires_action ist. Wenn Sie eine Aufgabe abbrechen, wechselt ihr Status zu cancelled.
Verwenden Sie client.interactions.cancel(), um eine Aufgabe abzubrechen:
client.interactions.cancel(interaction.id)
Endgültige Ausgabe und Tokennutzung abrufen
Wenn die Interaktion den Status completed erreicht, ist das vollständige Transkript in der Liste steps verfügbar. Die endgültige Antwort ist der Textinhalt des letzten model_output-Schritts.
Da die Interaktion gespeichert wird (store=True), können Sie das Ergebnis jederzeit mit der Interaktions-ID aus einer beliebigen Sitzung abrufen:
def get_final_text(completed_interaction):
"""Returns the text of the last model_output step."""
for step in reversed(getattr(completed_interaction, "steps", None) or []):
if getattr(step, "type", None) != "model_output":
continue
text = "".join(
part.text
for part in (getattr(step, "content", None) or [])
if getattr(part, "text", None)
)
if text:
return text
return ""
final = client.interactions.get(interaction.id)
print(f"Status: {final.status}\n")
print(get_final_text(final) or "(No text output)")
if final.usage:
print(
f"\nToken usage:\n"
f" Input tokens: {final.usage.total_input_tokens}\n"
f" Output tokens: {final.usage.total_output_tokens}\n"
f" Total tokens: {final.usage.total_tokens}"
)
Nächste Schritte
Weitere Informationen zu asynchronen Modellaufrufen, zustandsorientierten Interaktionen und verwalteten Forschungs-Agents finden Sie in den folgenden Anleitungen:
- Asynchrone Modellaufrufe für benutzerdefinierte und Drittanbieter-Agenten in Verzögerte Stufe verwenden ausführen.
- Lesen Sie die wichtigsten Konzepte zu Sitzungen, Tools und Zuständen in der Übersicht über die Interactions API.
- Mehrstufige Recherche-Workflows planen und zusammenfassen in Gemini Deep Research-Agent verwenden.