Quando si esegue il deployment di Agentic Workflows in più passaggi (come la sintesi di documenti su larga scala e la ricerca a lungo termine), l'esecuzione di agenti in background su modelli in tempo reale può creare una pressione inutile sull'infrastruttura e attivare errori di esaurimento delle risorse (429).
Gemini Enterprise Agent Platform offre un livello differito, uno scheduler ottimizzato per il throughput progettato specificamente per i workload con tolleranza alla latenza. Anziché trattare le attività autonome di lunga durata con la stessa urgenza immediata di una query di chat live, lo scheduler mette in coda gli Agentic Workflows complessi in più passaggi nelle ore non di punta per ottenere tassi di successo e throughput complessivo elevati.
Quando invii una richiesta utilizzando il livello differito, l'API accetta l'attività in modo asincrono e restituisce immediatamente un ID interazione. Il livello differito offre le seguenti funzionalità:
Tariffa scontata: ricevi uno sconto del 50% sui prezzi dell'inferenza del modello rispetto a una richiesta standard, in modo da poter gestire i costi dell'agente in produzione. Per saperne di più, consulta i prezzi.
Throughput più elevato: il livello differito riduce gli errori 429 (vincoli di capacità del modello) e i limiti di frequenza spostando i workload asincroni pesanti nelle ore non di punta, liberando la quota del livello Standard per le tue esigenze di produzione in tempo reale.
Timeout di completamento: il livello differito mira a completare il 95% delle attività entro 24 ore. Se un'attività non viene completata entro questo periodo di tempo, scade e passa allo stato
failed. Il tempo effettivo trascorso in coda dipende dalla capacità e dalla domanda attuali del cluster regionale.
Casi d'uso
Il livello differito è adatto ai casi d'uso che possono tollerare ore di tempo di risposta, come i seguenti esempi:
Finanza: ricerche di mercato e azionarie giornaliere o settimanali.
Aspetti legali e conformità: due diligence normativa e di fusioni e acquisizioni su più documenti.
Strategia: competitive intelligence continua e sintesi delle tendenze.
Sicurezza: analisi e correzione delle vulnerabilità del codebase.
Agenti supportati
Puoi configurare la pianificazione degli agenti autonomi per i seguenti agenti. Seleziona un agente per passare alle relative istruzioni di configurazione:
Per eseguire loop degli agenti personalizzati o di terze parti direttamente sui modelli Gemini, consulta Utilizza il livello Deferred.
Pianifica un agente ADK
In ADK, imposti il parametro service_tier su RunConfig per chiamata anziché configurare un livello fisso sull'agente o sul modello. L'impostazione service_tier=ServiceTier.DEFERRED mette in coda ogni chiamata al modello in un pool di capacità non di punta, mentre l'impostazione predefinita ServiceTier.STANDARD viene eseguita in modo sincrono. Questa impostazione per esecuzione consente a una singola definizione di agente di gestire sia le richieste interattive sia i workflow batch offline.
Quando invii una richiesta differita per un agente ADK, ADK automatizza l'invio, il polling e il recupero in background per te:
- L'ADK invia la richiesta del modello con l'esecuzione in background
attivata e il backend restituisce un ID interazione con lo stato
queuedoin_progress. - Mentre l'interazione rimane in attesa, l'ADK esegue il polling del backend con backoff esponenziale.
- Quando l'interazione raggiunge uno stato finale, ADK converte l'interazione completata in eventi di risposta del modello standard che utilizzi tramite l'interfaccia del runner.
Questa sezione illustra le seguenti attività per la pianificazione degli agenti ADK:
- Esamina i requisiti e le limitazioni prima di attivare il livello differito.
- Esegui un agente ADK sul livello differito
utilizzando
RunConfig(service_tier=ServiceTier.DEFERRED). - Esegui il deployment degli agenti ADK differiti su Agent Runtime, Cloud Run o Google Kubernetes Engine (GKE).
- Imponi una scadenza per il client per limitare il tempo di attesa lato client.
Per saperne di più sulla configurazione di ServiceTier in ADK, consulta Pianificazione differita nella documentazione di ADK.
Limitazioni per gli agenti ADK
Tieni presente i seguenti requisiti e limitazioni quando pianifichi gli agenti ADK nel livello differito:
- Richiede l'API Interactions: i livelli di pubblicazione si applicano solo ai modelli configurati per l'API Interactions, come
Gemini(use_interactions_api=True). Modelli di generazione di contenuti standard eManagedAgentignoranoservice_tier. - Incompatibile con lo streaming di token: l'esecuzione differita non può essere combinata con
StreamingMode.SSEinRunConfig. Quando chiami/run_sse, omettistreamingo imposta"streaming": false. Il passaggio di"streaming": truecon"service_tier": "deferred"restituisce HTTP422 Unprocessable Entity. - Limiti di connessione HTTP: su
adk api_server,/rune/run_ssemantengono aperta la connessione HTTP durante l'attesa in coda. Se un timeout del proxy o della piattaforma chiude la connessione (ad esempio il limite di 60 minuti di Cloud Run), il polling del client si interrompe. L'interazione con il backend viene comunque completata e genera addebiti. - Latenza della coda per turno: nei workflow multi-turno o di chiamata degli strumenti, ogni turno del modello invia una richiesta di interazione separata. Ogni turno comporta un'attesa in coda fuori dagli orari di punta.
- Nessun ripristino in corso tra i riavvii: l'ADK non rende persistenti gli ID interazione in corso nello spazio di archiviazione della sessione né si ricollega alle interazioni disconnesse. L'arresto di un processo client abbandona il ciclo di polling in attesa e una chiamata successiva avvia una nuova interazione.
Esegui un agente ADK sul livello differito
Per pianificare un agente ADK nel livello differito, configura il modello Gemini con use_interactions_api=True e passa RunConfig(service_tier=ServiceTier.DEFERRED) quando richiami l'esecutore:
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())
Sostituisci PROJECT_ID con l'ID progetto Google Cloud .
Mentre lo stato dell'interazione è queued o in_progress, runner.run_async()
non genera eventi fino al completamento dell'interazione. Verifica che il livello differito sia attivo controllando i seguenti messaggi nei log dell'applicazione:
- A livello di
INFO, i log di trasporto delle interazioniInteraction INTERACTION_ID is queued; waiting for the result.eInteraction INTERACTION_ID reached status completed.Quando il logging di debug è abilitato, il processore delle richieste registra ancheUsing service_tier from run_config: ServiceTier.DEFERRED. - Se
use_interactions_api=Truenon è impostato sul modello, ADK ignoraservice_tier, procede con la generazione standard e registra un avviso che indica che il modello non utilizza l'API Interactions.
Esegui il deployment degli agenti ADK differiti
Puoi configurare service_tier per richiesta anziché nella definizione dell'agente, in modo che un pacchetto dell'agente ADK (use_interactions_api=True) possa gestire sia i workload in tempo reale sia quelli differiti. Puoi eseguire il deployment di questo pacchetto in Agent Runtime, Cloud Run o GKE.
La tabella seguente mette a confronto le opzioni di deployment per i workload ADK differiti:
| Opzione di implementazione | Quando utilizzarlo | Modello di esecuzione | Timeout massimo | Come richiedere il livello differito |
|---|---|---|---|---|
| Agent Runtime | Job in background asincroni in cui Agent Platform gestisce le sessioni, viene eseguito senza mantenere aperta una connessione HTTP e scrive i risultati direttamente in Cloud Storage | Job in background gestito (run_query_job) |
168 ore (7 giorni; 24 ore per turno del modello) |
"run_config": {"service_tier": "deferred"} all'interno di
input
|
| Servizio Cloud Run | Endpoint HTTPS serverless che gestiscono sia richieste interattive sia workload differiti che vengono completati entro 60 minuti | HTTP o SSE serverless (adk deploy cloud_run) |
60 minuti (3600 secondi) |
"service_tier": "deferred" nel corpo della richiesta /run o /run_sse (con "streaming": false)
|
| Job Cloud Run | Workload batch serverless senza una connessione HTTP che potrebbero attendere più di 60 minuti (fino a 24 ore per turno del modello) | Container batch serverless (gcloud run jobs) |
168 ore (7 giorni) | RunConfig(service_tier=ServiceTier.DEFERRED) |
| GKE | Workload Kubernetes che richiedono networking personalizzato, controllo del ciclo di vita dei pod o nessun limite di timeout delle richieste serverless | Pod Kubernetes (adk deploy gke) |
Illimitato (pod e ingress configurati) |
"service_tier": "deferred" nel corpo della richiesta /run o /run_sse (con "streaming": false)
|
Se il modello utilizza l'endpoint global mentre il deployment viene eseguito in un endpoint regionale (ad esempio us-central1), passa client_kwargs={"location": "global"} a Gemini(...). Assicurati che il tuo account di servizio di runtime disponga del ruolo Agent Platform User (roles/aiplatform.user) nel tuo progetto.
Seleziona una destinazione di deployment per visualizzare le istruzioni di configurazione:
Agent Runtime
Quando esegui il deployment dell'agente in Agent Runtime, imposta agent_framework="google-adk" e includi google-adk>=2.10.0 in requirements. Concedi al service agent del motore di ragionamento (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.) il ruolo Storage Object Creator (roles/storage.objectCreator) sul bucket di output.
Per inviare un job di query asincrono con esecuzione differita, chiama client.runtimes.run_query_job() e passa "run_config": {"service_tier": "deferred"} all'interno di 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"
),
},
)
Sostituisci quanto segue:
PROJECT_ID: il tuo ID progetto Google Cloud .LOCATION: la regione supportata in cui è stato eseguito il deployment dell'agente, ad esempious-central1.RESOURCE_ID: l'ID numerico della risorsareasoningEnginedi cui hai eseguito il deployment.USER_IDeSESSION_ID: gli identificatori di utente e sessione per la chiamata.BUCKET_NAMEeOUTPUT_FILE: il bucket Cloud Storage e il prefisso dell'oggetto in cui Agent Runtime scrive gli eventi in streaming come JSON delimitato da nuova riga (application/x-ndjson, un oggetto JSON per riga).
Cloud Run
Configura un servizio Cloud Run o un job Cloud Run in base alla durata prevista della coda:
Servizio Cloud Run (
adk deploy cloud_run): esegue il deployment diadk api_serverdietro un endpoint HTTPS (/rune/run_sse). Passa-- --timeout=3600durante il deployment in modo che Cloud Run non chiuda la connessione HTTP dopo il timeout predefinito di 5 minuti:adk deploy cloud_run \ --project=PROJECT_ID \ --region=LOCATION \ --service_name=SERVICE_NAME \ AGENT_DIR \ -- --no-allow-unauthenticated --timeout=3600Sostituisci quanto segue:
PROJECT_ID: il tuo ID progetto Google Cloud .LOCATION: la regione Cloud Run, ad esempious-central1.SERVICE_NAME: il nome del tuo servizio Cloud Run.AGENT_DIR: il percorso della directory di origine dell'agente.
Prima di chiamare
/runo/run_sse, crea una sessione conPOST /apps/APP_NAME/users/USER_ID/sessions, doveAPP_NAMEcorrisponde per impostazione predefinita al nome della directory dell'agente. Per richiedere l'esecuzione differita, includi"service_tier": "deferred"come campo di primo livello nel corpo della richiesta JSON. Quando chiami/run_sse, omettistreamingo imposta"streaming": false(il passaggio di"streaming": truerestituisce HTTP422 Unprocessable Entity):{ "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 }Job Cloud Run (
gcloud run jobs deploy): esegue un container fino al completamento senza un ciclo di vita delle richieste HTTP e supporta--task-timeoutfino a 168 ore (7 giorni). PassaRunConfig(service_tier=ServiceTier.DEFERRED)arunner.run_async()nell'entrypoint del job ed esegui il deployment con--task-timeout=86400s(24 ore).
GKE
Pacchettizza ed esegui il deployment dell'agente ADK in un cluster GKE utilizzando adk deploy gke:
adk deploy gke \
--project=PROJECT_ID \
--region=LOCATION \
--cluster_name=CLUSTER_NAME \
--service_name=SERVICE_NAME \
AGENT_DIR
Sostituisci quanto segue:
PROJECT_ID: il tuo ID progetto Google Cloud .LOCATION: la regione del tuo cluster GKE a livello di regione, ad esempious-central1.CLUSTER_NAME: il nome del tuo cluster GKE.SERVICE_NAME: il nome del servizio Kubernetes per il tuo agente.AGENT_DIR: il percorso della directory di origine dell'agente.
Prima di chiamare /run o /run_sse, crea una sessione con POST
/apps/APP_NAME/users/USER_ID/sessions, dove
APP_NAME corrisponde per impostazione predefinita al nome della directory dell'agente. Per richiedere l'esecuzione differita, includi "service_tier": "deferred" come campo di primo livello nel corpo della richiesta JSON. Quando chiami /run_sse, ometti
streaming o imposta "streaming": false (il passaggio di "streaming": true restituisce
HTTP 422 Unprocessable Entity):
{
"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
}
Le richieste a /run e /run_sse mantengono aperta la connessione HTTP durante l'attesa in coda e l'esecuzione del modello. Aumenta i timeout del backend del bilanciatore del carico e dell'ingress GKE per tenere conto dei ritardi previsti della coda. Se la connessione client si chiude o scade, il server annulla il polling locale. L'interazione con il backend viene comunque eseguita e genera addebiti senza restituire un output.
Imponi una scadenza per il client
ADK non applica un timeout lato client all'attesa in coda, ma si affida al timeout di completamento di 24 ore del backend. Per limitare il tempo di attesa totale trascorso nella tua applicazione, racchiudi 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."
)
L'applicazione di un timeout del client interrompe il loop di polling lato client al successivo intervallo di sospensione, ma non annulla il lavoro sul backend. Anche dopo un timeout del client, l'interazione continua a essere eseguita fino al completamento e genera addebiti sul server.
Pianifica l'agente Gemini Deep Research
Utilizza l'API Interactions per creare, monitorare, annullare e recuperare i risultati di un'attività di Deep Research differita.
Crea un'attività differita
L'esempio seguente mostra come avviare un'attività di Deep Research utilizzando il livello differito con client.interactions.create():
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}")
Sostituisci PROJECT_ID con l'ID progetto Google Cloud .
Il metodo restituisce immediatamente status="queued" o status="in_progress"
e service_tier="deferred".
Monitora l'avanzamento delle attività
Durante l'attesa della capacità fuori picco e l'esecuzione attiva, l'interazione
status è queued o in_progress. Man mano che l'agente esegue i passaggi di pianificazione, ricerca e analisi, vengono aggiunti nuovi elementi all'elenco steps.
Puoi monitorare lo stato dell'attività in modo programmatico eseguendo il polling periodico dell'interazione o lo streaming degli aggiornamenti.
Sondaggi
Esegui il polling dell'interazione periodicamente (ad esempio ogni 15-30 secondi) finché l'interazione non raggiunge uno degli stati terminali: completed, failed, cancelled o 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
Puoi iscriverti agli aggiornamenti in tempo reale chiamando client.interactions.get()
con stream=True. Una volta che l'interazione entra nello stato in_progress, lo stream invia eventi come pensieri intermedi, delta di testo e aggiornamenti di stato man mano che si verificano.
Se la connessione si interrompe mentre l'attività è ancora queued o in_progress,
riconnettiti allo stream utilizzando client.interactions.get() con stream=True
e passa l'ultimo ID evento ricevuto a last_event_id. Se ometti last_event_id, l'API riproduce ogni evento dall'inizio.
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}")
Annulla un'attività
Puoi annullare un'attività mentre il suo stato è queued, in_progress o
requires_action. Quando annulli un'attività, il suo stato passa a cancelled.
Per annullare un'attività, utilizza client.interactions.cancel():
client.interactions.cancel(interaction.id)
Recupera l'output finale e l'utilizzo dei token
Quando l'interazione raggiunge lo stato completed, la trascrizione completa è disponibile nell'elenco steps. La risposta finale è il contenuto testuale dell'ultimo passaggio model_output.
Poiché l'interazione viene archiviata (store=True), puoi recuperare il risultato in qualsiasi momento utilizzando l'ID interazione di qualsiasi sessione:
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}"
)
Passaggi successivi
Esplora le guide correlate per le chiamate ai modelli asincrone, le interazioni stateful e gli agenti di ricerca gestiti:
- Esegui chiamate asincrone ai modelli per agenti personalizzati e di terze parti in Utilizza il livello Differito.
- Esamina i concetti fondamentali di sessione, strumento e stato nella panoramica dell'API Interactions.
- Pianifica e sintetizza workflow di ricerca in più passaggi in Utilizza l'agente Deep Research di Gemini.