Usa el nivel diferido para ejecutar llamadas asíncronas y de varios turnos al modelo de Gemini para agentes personalizados con una tarifa con descuento en Gemini Enterprise Agent Platform. En la API de Interactions, Agent Platform pone en cola cada turno diferido para su ejecución en segundo plano dentro de un objetivo de 24 horas y conserva el estado durante 7 días.
El nivel diferido se adapta a las cargas de trabajo de agentes tolerantes a la latencia que necesitan control por turno, como las siguientes:
- Agentes de seguridad y programación de varios pasos: Análisis de vulnerabilidades de repositorios, migraciones de código automatizadas y clasificación de regresiones.
- Canalizaciones de documentos y de investigación: Revisiones de diseño técnico, pruebas retrospectivas financieras y síntesis de varios documentos con llamadas a herramientas.
- Evaluaciones de agentes sin conexión: Son comparativas de calidad a gran escala que encadenan
turnos de
previous_interaction_idsin restricciones de latencia en tiempo real.
Para comparar todos los modelos de procesamiento, consulta Opciones de consumo. Para programar agentes del Kit de desarrollo de agentes (ADK) o ejecuciones administradas en el agente de Gemini Deep Research, consulta Programación de agentes autónomos.
Modelos y ubicaciones compatibles
El nivel diferido se admite exclusivamente en el extremo global
(locations/global en aiplatform.googleapis.com). El envío de una solicitud con
service_tier="deferred" a un extremo regional o a los extremos multirregionales us o eu
devuelve HTTP 400 ("code": "invalid_request").
Los siguientes modelos de Gemini principales admiten el
nivel diferido en el extremo global:
- 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)
Si tu proyecto tiene acceso a la lista de entidades permitidas a través de tu equipo de cuentas de Google Cloud , también puedes usar los siguientes modelos de Cyber:
- Gemini 4 Carbon para ciberseguridad (
gemini-4-carbon-cyber-permissive) - Gemini 4 Argon Cyber Permissive (
gemini-4-argon-cyber-permissive)
Antes de comenzar
En un proyecto de Google Cloud con la facturación habilitada, completa los siguientes pasos de configuración de requisitos previos:
-
Accede a tu Cuenta de Google.
Si todavía no tienes una cuenta, regístrate para obtener una nueva.
-
Instala Google Cloud CLI.
-
Si usas un proveedor de identidad externo (IdP), primero debes acceder a gcloud CLI con tu identidad federada.
-
Para inicializar gcloud CLI, ejecuta el siguiente comando:
gcloud init -
Verifica que tengas los permisos necesarios para completar esta guía.
Habilita la API de Agent Platform si aún no está habilitada:
Roles necesarios para habilitar las APIs
Para habilitar las APIs, necesitas el permiso
serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtenerlo a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.gcloud services enable aiplatform.googleapis.com
-
Si usas una shell local, crea credenciales de autenticación locales para tu cuenta de usuario:
gcloud auth application-default login
No es necesario que lo hagas si usas Cloud Shell.
Si se muestra un error de autenticación y usas un proveedor de identidad externo (IdP), confirma que accediste a gcloud CLI con tu identidad federada.
-
Instala Google Cloud CLI.
-
Si usas un proveedor de identidad externo (IdP), primero debes acceder a gcloud CLI con tu identidad federada.
-
Para inicializar gcloud CLI, ejecuta el siguiente comando:
gcloud init -
Verifica que tengas los permisos necesarios para completar esta guía.
Habilita la API de Agent Platform si aún no está habilitada:
Roles necesarios para habilitar las APIs
Para habilitar las APIs, necesitas el permiso
serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtenerlo a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.gcloud services enable aiplatform.googleapis.com
-
Si usas una shell local, crea credenciales de autenticación locales para tu cuenta de usuario:
gcloud auth application-default login
No es necesario que lo hagas si usas Cloud Shell.
Si se muestra un error de autenticación y usas un proveedor de identidad externo (IdP), confirma que accediste a gcloud CLI con tu identidad federada.
Roles obligatorios
Para obtener los permisos que necesitas para crear, supervisar y cancelar llamadas de modelos diferidas, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto de Google Cloud :
-
Crea, sondea, cancela y borra interacciones diferidas:
Usuario de Agent Platform (
roles/aiplatform.user) -
Supervisar las interacciones diferidas (solo lectura):
Visualizador de Agent Platform (
roles/aiplatform.viewer) -
Lee archivos de entrada multimodales desde Cloud Storage (opcional):
Visualizador de objetos de almacenamiento (
roles/storage.objectViewer)
Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.
También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.
Instala el SDK de IA generativa de Google
Si usas una biblioteca cliente, instala o actualiza el SDK de IA generativa de Google
(@google/genai >= 2.32.0 o google-genai >= 2.34.0) en tu entorno de
desarrollo:
Node.js
npm install @google/genai@latest
Python
pip install --upgrade "google-genai>=2.34.0"
Crea y administra llamadas de modelos diferidas
Ejecuta los siguientes procedimientos en el entorno que configuraste en Antes de comenzar. Los ejemplos de REST se autentican con tus credenciales de gcloud CLI, y los ejemplos del SDK de IA generativa de Google usan las credenciales predeterminadas de la aplicación (ADC). Si una llamada devuelve un error, consulta Solución de problemas.
Crea una llamada al modelo diferida
Envía un turno asíncrono llamando a interactions.create con service_tier="deferred", background=true y store=true. Omite stream
o configúralo como false. Antes de ejecutar una muestra, reemplaza
PROJECT_ID por el ID del proyecto de Google Cloud , como
my-agent-project.
REST
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
PROJECT_ID: Es el ID del proyecto de Google Cloud , comomy-agent-project.
Método HTTP y URL:
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions
Cuerpo JSON de la solicitud:
{
"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
}
Para enviar tu solicitud, expande una de estas opciones:
La respuesta devuelve una carga útil de JSON similar a la siguiente:
{
"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");
El resultado es similar a lo siguiente:
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")
El resultado es similar a lo siguiente:
Interaction ID: v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0
Status: queued
Service tier: deferred
Sondea el estado y recupera el uso de tokens
Sondea interactions.get con retirada mientras status sea queued o
in_progress. Cuando el turno alcance un estado final, lee output_text y
usage.
El nivel Diferido tiene como objetivo completar el 95% de los turnos en un plazo de 24 horas
sin un ANS de latencia respaldado por créditos. En la siguiente tabla, se describen los valores de status
de un recurso Interaction:
| Estado | Final | Significado y próximo paso |
|---|---|---|
queued |
No | Se aceptó y está esperando capacidad. Sondea interactions.get con retirada. No solicites stream=true todavía. |
in_progress |
No | Carrera. Sigue sondeando interactions.get o adjunta un flujo de SSE con stream=true. |
requires_action |
Sí | El turno finalizó en un paso function_call emitido por el modelo. Ejecuta la herramienta y, luego, crea un turno nuevo con previous_interaction_id. |
requires_continuation |
Sí | Un turno de decodificación largo se detuvo con un resultado parcial y un continuation_token. Reanuda con previous_interaction_id y continuation_token, omite input y aumenta max_output_tokens. |
completed |
Sí | Finalizó el turno. Lee output_text y usage, o pasa id como previous_interaction_id en el siguiente turno. |
incomplete |
Sí | El turno se detuvo antes de tiempo, por ejemplo, cuando llegó a max_output_tokens. Inspecciona los archivos parciales steps y usage. |
failed |
Sí | El turno tuvo un error de tiempo de ejecución o superó el período de finalización de 24 horas. La API no usa un estado expired. Inspecciona error y, luego, envía una solicitud nueva. |
cancelled |
Sí | Una llamada a interactions.cancel detuvo el turno antes de que finalizara. |
Si un turno de decodificación larga finaliza como requires_continuation, reanúdalo llamando a interactions.create con previous_interaction_id, continuation_token, background=true, store=true y service_tier="deferred". Omite input y
establece max_output_tokens en un valor más alto que los tokens generados hasta el momento. Para obtener información sobre cómo
se factura cada estado final, consulta Precios y facturación.
Antes de ejecutar un ejemplo, realiza los siguientes reemplazos:
PROJECT_ID: Es el ID del proyecto de Google Cloud , comomy-agent-project.INTERACTION_ID: Es el ID de interacción que se devuelve cuando creaste la llamada diferida al modelo, comov1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.
REST
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
PROJECT_ID: Es el ID del proyecto de Google Cloud , comomy-agent-project.INTERACTION_ID: Es el ID de interacción que se muestra cuando creaste la llamada al modelo diferida, comov1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.
Método HTTP y URL:
GET https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID
Para enviar tu solicitud, expande una de estas opciones:
La respuesta devuelve una carga útil de JSON similar a la siguiente:
{
"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",
);
El resultado es similar a lo siguiente:
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",
)
El resultado es similar a lo siguiente:
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
Opcional: Transmite el resultado mientras se ejecuta una llamada
Después de que interactions.get informe status="in_progress", puedes adjuntar un
flujo de eventos enviados por el servidor (SSE) con stream=true y reanudar las conexiones
interrumpidas con last_event_id:
REST
Agrega ?stream=true a la URL de interactions.get. Cuando vuelvas a conectarte, agrega también &last_event_id=EVENT_ID y reemplaza EVENT_ID por el ID del último evento recibido.
Node.js
Itera en await ai.interactions.get(interactionId, { stream: true,
last_event_id: lastEventId }), registra event.event_id y lee event.delta?.text en eventos step.delta.
Python
Itera en client.interactions.get(interaction_id, stream=True,
last_event_id=last_event_id), registra event.event_id y lee event.delta.text en eventos step.delta.
Para obtener más información sobre la transmisión y la reconexión de SSE, consulta la guía para desarrolladores de la API de Interactions.
Encadena flujos de trabajo diferidos de varios turnos
Continúa una conversación de varios turnos o devuelve los resultados de la ejecución de la herramienta pasando
el id de una interacción completed o requires_action en
previous_interaction_id. Los campos con alcance de turno, como tools,
system_instruction y generation_config, no se transfieren automáticamente,
así que pásalos en cada turno que los requiera. Los turnos encadenados siguen siendo aptos para
el almacenamiento en caché de contexto implícito, aunque los prefijos almacenados en caché
pueden vencer en esperas de cola de varias horas. Para ver los esquemas de pasos de resultados de herramientas, consulta la guía para desarrolladores de la API de Interactions.
Antes de ejecutar un ejemplo, realiza los siguientes reemplazos:
PROJECT_ID: Es el ID del proyecto de Google Cloud , comomy-agent-project.PREVIOUS_INTERACTION_ID: Es el ID del turnocompletedorequires_actionanterior, comov1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.
REST
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
PROJECT_ID: Es el ID del proyecto de Google Cloud , comomy-agent-project.PREVIOUS_INTERACTION_ID: Es el ID de interacción completado o que requiere acción del turno anterior, comov1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.
Método HTTP y URL:
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions
Cuerpo JSON de la solicitud:
{
"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
}
Para enviar tu solicitud, expande una de estas opciones:
La respuesta devuelve una carga útil de JSON similar a la siguiente:
{
"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})`);
El resultado es similar a lo siguiente:
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})")
El resultado es similar a lo siguiente:
Follow-up ID: v1_Ch1Lm9RUXhPNlJqS1lBMk56UjdVOGdnPT0 (queued)
Cómo cancelar una llamada diferida al modelo
Para detener una interacción diferida cuyo status es queued o in_progress, llama a interactions.cancel. Si se llama a interactions.cancel en una interacción con cualquier otro estado, se muestra el código HTTP 409 ("code": "aborted"). Para obtener información sobre cómo la cancelación afecta la facturación, consulta Precios y facturación.
Antes de ejecutar un ejemplo, realiza los siguientes reemplazos:
PROJECT_ID: Es el ID del proyecto de Google Cloud , comomy-agent-project.INTERACTION_ID: Es el ID de una interacción dequeuedoin_progress, comov1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ.
REST
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
PROJECT_ID: Es el ID del proyecto de Google Cloud , comomy-agent-project.INTERACTION_ID: Es el ID de una interacción en cola o en curso que se cancelará, comov1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ.
Método HTTP y URL:
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID/cancel
Para enviar tu solicitud, expande una de estas opciones:
La respuesta devuelve una carga útil de JSON similar a la siguiente:
{
"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}`);
Esta es la salida:
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}")
Esta es la salida:
Status: cancelled
Precios, cuotas y controles de seguridad
Revisa las reglas de facturación, las cuotas, los límites de carga útil y los controles de seguridad antes de ejecutar cargas de trabajo de producción en el nivel diferido.
Precios y facturación
Las llamadas de modelos diferidas se facturan con un 50% de descuento en comparación con las tarifas de pago por uso estándar para los tokens de entrada, salida y razonamiento. La facturación sigue estas reglas:
- Acumulación de descuentos: El descuento diferido se acumula con los descuentos de contratos y los descuentos de tokens de almacenamiento en caché de contexto implícito, que se aplican sobre la tarifa almacenada en caché.
- No hay resguardo a las tarifas estándar: Las solicitudes diferidas nunca se desbordan ni cambian a la versión estándar de pago por uso, por lo que no se facturan con tarifas a pedido sin descuento.
- Facturación por llamada al modelo: Se factura cada llamada al modelo que realiza un turno.
Los turnos que finalizan como
completed,incomplete,requires_actionorequires_continuationse facturan con la tarifa diferida. - Turnos cancelados: No se factura un turno que cancelas mientras está en estado
queued. Si cancelas un turno mientras estáin_progress, se facturan las llamadas al modelo que ya comenzaron, incluida una llamada que se interrumpe a mitad de la generación. - Turnos con errores: No se facturan los turnos de una sola llamada que finalizan como
failed, incluidos los turnos que superan el período de finalización de 24 horas. En un bucle de herramientas del servidor de varios pasos, se facturan las llamadas al modelo completadas antes de un error, pero no la llamada con error. - Turnos encadenados: Cada turno de una cadena de
previous_interaction_idse factura por separado. Cancelar un turno posterior o que falle un turno posterior no cambia los cargos de los turnos anteriores.
Para conocer las tarifas de tokens por modelo, consulta la página de precios de Agent Platform.
Cuotas, límites de carga útil y retención
El nivel Diferido no tiene su propia cuota de llamadas al modelo. Las llamadas
aplazadas comparten la cuota de pago por uso de Flex
(flex_requests_per_minute_per_project_per_base_model, 3,000 RPM), que
se verifica en cada llamada al modelo después de que interactions.create devuelve queued. Las cuotas de proyecto y los límites del sistema clave incluyen lo siguiente:
- Cuotas de creación y simultaneidad: Hasta 100 RPM o ilimitadas para
stateful_genai_interaction_creationsen el momento de la creación. Hasta 500concurrent_interaction_generations, según tu nivel de cuota. - Capacidad de procesamiento con estado diaria (fija): 240 GiB por día escritos y 480 GiB por día leídos por proyecto.
- Límites de carga útil y retención: Hasta 9.75 MiB de cuerpo HTTP sin comprimir por llamada de
interactions.createy 7 días de retención de estado. Las cadenas admiten hasta 100 URIs de Cloud Storage (gs://) distintos.
Para obtener la tabla de cuotas completa y las instrucciones de la consola, consulta Cuotas y límites del nivel diferido.
Controles de seguridad y cumplimiento
Debido a que el nivel diferido pone en cola y conserva el estado en el extremo de global,
verifica que los controles de administración admitidos coincidan con tus requisitos de
cumplimiento:
- Controles compatibles:
Controles del servicio de VPC
(VPC-SC; no se permiten herramientas externas de
mcp_serverdentro de un perímetro), Transparencia de acceso (AXT), Registros de auditoría de Cloud y FedRAMP High. - Controles no admitidos: Retención de cero datos sin estado (
store=falsey la aplicación forzosa deconstraints/vertexai.disableAPIStoragedevuelven HTTP400con"code": "invalid_request"), claves de encriptación administradas por el cliente (CMEK), residencia de datos, DoD IL5 y ITAR.
Para ver la matriz de funciones completa, consulta Controles de seguridad para la IA generativa.
Solucionar problemas
En la siguiente tabla, se describen los errores comunes en el nivel diferido y cómo resolverlos:
| Error o estado | Causas habituales | Solución |
|---|---|---|
400 (error.code: "invalid_request"; extremo, marcas o modelo) |
Extremo que no es global, modelo no compatible o marcas background, store o stream no válidas en interactions.create. |
Orienta locations/global con un modelo compatible, establece background=true y store=true, y omite stream=true. |
400 (error.code: "invalid_request"; carga útil, URIs o herramientas) |
El cuerpo sin comprimir supera los 9.75 MiB, la cadena supera los 100 URI de gs:// o las herramientas externas de mcp_server dentro de VPC-SC. |
Pasa archivos grandes como URIs de gs:// (como máximo 100 por cadena) y omite las herramientas externas de mcp_server dentro del VPC-SC. |
400 (error.code: "invalid_request" el interactions.create; status: "FAILED_PRECONDITION" el interactions.delete) |
|
|
401 (status: "UNAUTHENTICATED" u error.code: "authentication") |
Faltan tus credenciales de gcloud CLI (muestras de REST) o ADC (muestras del SDK de IA generativa de Google), o bien vencieron. | Para ver ejemplos de REST, ejecuta gcloud auth login. Para ver ejemplos del SDK de IA generativa de Google, ejecuta gcloud auth application-default login. Luego, vuelve a intentar ejecutar la solicitud. |
403 (status: "PERMISSION_DENIED" u error.code: "permission_denied") |
|
Otorgar roles/aiplatform.user. Para las entradas de Cloud Storage, también otorga roles/storage.objectViewer. |
404 (error.code: "not_found"; status: "NOT_FOUND" el interactions.delete) |
La interacción o previous_interaction_id no existe o se borró. También podría pertenecer a un extremo que no sea de global o tener una antigüedad superior al período de retención de 7 días. |
Verifica el ID de interacción en el extremo global. Si el turno principal venció, inicia una nueva cadena sin previous_interaction_id. |
409 (error.code: "aborted") |
interactions.cancel se orienta a una interacción que ya se encuentra en un estado final: requires_action, requires_continuation, completed, incomplete, failed o cancelled. |
Primero, verifica status con interactions.get. Solo puedes cancelar las interacciones queued y in_progress. |
429 (error.code: "too_many_requests") |
El proyecto superó una cuota por proyecto, como la tasa de creación de interacciones, las generaciones de interacciones simultáneas o la capacidad de procesamiento con estado diaria. |
|
status="failed" |
|
|
¿Qué sigue?
Explora las guías y la documentación de referencia relacionadas para las cargas de trabajo asíncronas y con estado de Gemini:
- Compara los modelos de procesamiento en Opciones de consumo.
- Crea aplicaciones de varios turnos con estado en la guía para desarrolladores de la API de Interactions.
- Programa agentes del ADK y ejecuciones de investigación administradas en Programación de agentes autónomos.
- Explora los esquemas de métodos en la referencia de la API de Interactions.