Use o nível Diferido para executar chamadas assíncronas de modelo do Gemini em vários turnos para agentes personalizados com um preço com desconto na Gemini Enterprise Agent Platform. Na API Interactions, a Agent Platform coloca cada turno adiado em uma fila para execução em segundo plano em um período de 24 horas e retém o estado por 7 dias.
O nível Diferido é adequado para cargas de trabalho de agentes tolerantes à latência que precisam de controle por turno, como:
- Agentes de segurança e programação em várias etapas: verificações de vulnerabilidade de repositórios, migrações de código automatizadas e triagem de regressão.
- Pipelines de documentos e pesquisa: revisões de design técnico, backtesting financeiro e síntese de vários documentos com chamada de ferramenta.
- Avaliações de agentes off-line: comparativos de qualidade em grande escala que encadeiam
previous_interaction_idturnos sem restrições de latência em tempo real.
Para comparar todos os modelos de computação, consulte Opções de consumo. Para programar agentes do Kit de Desenvolvimento de Agente (ADK) ou execuções gerenciadas no Deep Research do Gemini, consulte Programação de agentes autônomos.
Modelos e locais compatíveis
O nível Diferido é compatível exclusivamente com o endpoint global
(locations/global em aiplatform.googleapis.com). O envio de uma solicitação com
service_tier="deferred" para um endpoint regional ou para os endpoints multirregionais us ou eu
retorna HTTP 400 ("code": "invalid_request").
Os seguintes modelos do Gemini principais são compatíveis com o nível adiado no endpoint 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)
Se o projeto tiver acesso à lista de permissões pela equipe de conta do Google Cloud , também será possível usar os seguintes modelos cibernéticos:
- Gemini 4 Carbon para segurança cibernética (
gemini-4-carbon-cyber-permissive) - Gemini 4 Argon Cyber Permissive (
gemini-4-argon-cyber-permissive)
Antes de começar
Em um projeto do Google Cloud com faturamento ativado, conclua as seguintes etapas de configuração de pré-requisito:
-
Faça login na sua Conta do Google.
Se você ainda não tiver uma, inscreva-se agora.
-
Instale a CLI do Google Cloud.
-
Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.
-
Para inicializar a CLI gcloud, execute o seguinte comando:
gcloud init -
Verifique se você tem as permissões necessárias para concluir este guia.
Ative a API Agent Platform, se ainda não estiver ativada:
Funções necessárias para ativar APIs
Para ativar APIs, você precisa da permissão
serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.gcloud services enable aiplatform.googleapis.com
-
Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário:
gcloud auth application-default login
Isso não é necessário se você estiver usando o Cloud Shell.
Se um erro de autenticação for retornado e você estiver usando um provedor de identidade externo (IdP), confirme se você fez login na CLI gcloud com sua identidade federada.
-
Instale a CLI do Google Cloud.
-
Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.
-
Para inicializar a CLI gcloud, execute o seguinte comando:
gcloud init -
Verifique se você tem as permissões necessárias para concluir este guia.
Ative a API Agent Platform, se ainda não estiver ativada:
Funções necessárias para ativar APIs
Para ativar APIs, você precisa da permissão
serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.gcloud services enable aiplatform.googleapis.com
-
Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário:
gcloud auth application-default login
Isso não é necessário se você estiver usando o Cloud Shell.
Se um erro de autenticação for retornado e você estiver usando um provedor de identidade externo (IdP), confirme se você fez login na CLI gcloud com sua identidade federada.
Funções exigidas
Para receber as permissões necessárias para criar, monitorar e cancelar chamadas de modelo adiadas, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto do Google Cloud :
-
Criar, consultar, cancelar e excluir interações adiadas:
Usuário da Agent Platform (
roles/aiplatform.user) -
Monitorar interações adiadas (somente leitura):
Leitor da Agent Platform (
roles/aiplatform.viewer) -
Ler arquivos de entrada multimodais do Cloud Storage (opcional):
Leitor de objetos do Storage (
roles/storage.objectViewer)
Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.
Instalar o SDK de IA generativa do Google
Se você usa uma biblioteca de cliente, instale ou faça upgrade do SDK de IA generativa do Google
(@google/genai >= 2.32.0 ou google-genai >= 2.34.0) no seu ambiente de
desenvolvimento:
Node.js
npm install @google/genai@latest
Python
pip install --upgrade "google-genai>=2.34.0"
Criar e gerenciar chamadas de modelo adiadas
Execute os procedimentos a seguir no ambiente que você configurou em Antes de começar. Os exemplos de REST são autenticados com suas credenciais da CLI gcloud, e os exemplos do SDK de IA generativa do Google usam o Application Default Credentials (ADC). Se uma chamada retornar um erro, consulte Solução de problemas.
Criar uma chamada de modelo adiada
Envie uma rodada assíncrona chamando interactions.create com
service_tier="deferred", background=true e store=true. Omita stream
ou defina como false. Antes de executar uma amostra, substitua
PROJECT_ID pelo ID do projeto do Google Cloud , como
my-agent-project.
REST
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
PROJECT_ID: o ID do projeto do Google Cloud , comomy-agent-project.
Método HTTP e URL:
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions
Corpo JSON da solicitação:
{
"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 a solicitação, expanda uma destas opções:
A resposta retorna um payload JSON semelhante ao seguinte:
{
"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");
O resultado será o seguinte:
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")
O resultado será o seguinte:
Interaction ID: v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0
Status: queued
Service tier: deferred
Consultar o status e recuperar o uso de tokens
Pesquise interactions.get com espera enquanto status for queued ou
in_progress. Quando a rodada atingir um status final, leia output_text e
usage.
O nível Diferido tem como meta concluir 95% das interações em até 24 horas,
sem um SLA de latência com garantia de crédito. A tabela a seguir descreve os valores status
de um recurso Interaction:
| Status | Final | Significado e próxima etapa |
|---|---|---|
queued |
Não | Aceito e aguardando capacidade. Pesquise interactions.get com espera. Não solicite o stream=true ainda. |
in_progress |
Não | Em execução. Continue a sondar interactions.get ou anexe um stream de SSE com stream=true. |
requires_action |
Sim | A rodada terminou em uma etapa function_call emitida pelo modelo. Execute a ferramenta e crie uma nova vez com previous_interaction_id. |
requires_continuation |
Sim | Uma rodada de decodificação longa foi interrompida com saída parcial e um continuation_token. Retome com previous_interaction_id e continuation_token, omita input e aumente max_output_tokens. |
completed |
Sim | A vez terminou. Leia output_text e usage ou passe id como previous_interaction_id na próxima vez. |
incomplete |
Sim | A curva foi interrompida antes do tempo, como quando chegou a max_output_tokens. Inspecione os arquivos parciais steps e usage. |
failed |
Sim | A rodada atingiu um erro de tempo de execução ou excedeu a janela de conclusão de 24 horas. A API não usa um status expired. Inspecione error e envie uma nova solicitação. |
cancelled |
Sim | Uma chamada para interactions.cancel interrompeu a vez antes de terminar. |
Se uma rodada de decodificação longa terminar como requires_continuation, retome-a chamando
interactions.create com previous_interaction_id, continuation_token,
background=true, store=true e service_tier="deferred". Omita input e
defina max_output_tokens como um valor maior do que os tokens gerados até o momento. Para saber como
cada status final é faturado, consulte Preços e faturamento.
Antes de executar um exemplo, faça as seguintes substituições:
PROJECT_ID: o ID do projeto do Google Cloud , comomy-agent-project.INTERACTION_ID: o ID de interação retornado quando você criou a chamada de modelo adiada, comov1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.
REST
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
PROJECT_ID: o ID do projeto do Google Cloud , comomy-agent-project.INTERACTION_ID: o ID da interação retornado quando você criou a chamada de modelo adiada, comov1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.
Método HTTP e URL:
GET https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID
Para enviar a solicitação, expanda uma destas opções:
A resposta retorna um payload JSON semelhante ao seguinte:
{
"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",
);
O resultado será o seguinte:
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",
)
O resultado será o seguinte:
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: transmitir a saída enquanto uma chamada é executada
Depois que interactions.get informar status="in_progress", será possível anexar um
stream de eventos enviados pelo servidor (SSE) com stream=true e retomar as conexões
interrompidas com last_event_id:
REST
Anexe ?stream=true ao URL interactions.get. Ao se reconectar, anexe também &last_event_id=EVENT_ID, substituindo EVENT_ID pelo ID do último evento recebido.
Node.js
Itere sobre
await ai.interactions.get(interactionId, { stream: true,
last_event_id: lastEventId }), registre event.event_id e leia
event.delta?.text em eventos step.delta.
Python
Itere sobre
client.interactions.get(interaction_id, stream=True,
last_event_id=last_event_id), registre event.event_id e leia
event.delta.text em eventos step.delta.
Para mais informações sobre streaming e reconexão de SSE, consulte o guia para desenvolvedores da API Interactions.
Encadear fluxos de trabalho adiados de vários turnos
Continue uma conversa multiturno ou retorne os resultados da execução da ferramenta transmitindo
o id de uma interação completed ou requires_action em
previous_interaction_id. Os campos com escopo de turno, como tools,
system_instruction e generation_config, não são transferidos automaticamente.
Portanto, transmita-os em cada turno que os exigir. As interações encadeadas continuam qualificadas para o
armazenamento em cache de contexto implícito, embora os prefixos armazenados em cache
possam expirar em esperas de fila de várias horas. Para esquemas de etapas de resultados de ferramentas, consulte
o guia para desenvolvedores da API Interactions.
Antes de executar um exemplo, faça as seguintes substituições:
PROJECT_ID: o ID do projeto do Google Cloud , comomy-agent-project.PREVIOUS_INTERACTION_ID: o ID da vez anterior decompletedourequires_action, comov1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.
REST
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
PROJECT_ID: o ID do projeto do Google Cloud , comomy-agent-project.PREVIOUS_INTERACTION_ID: o ID da interação concluída ou que requer ação da rodada anterior, comov1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.
Método HTTP e URL:
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions
Corpo JSON da solicitação:
{
"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 a solicitação, expanda uma destas opções:
A resposta retorna um payload JSON semelhante ao seguinte:
{
"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})`);
O resultado será o seguinte:
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})")
O resultado será o seguinte:
Follow-up ID: v1_Ch1Lm9RUXhPNlJqS1lBMk56UjdVOGdnPT0 (queued)
Cancelar uma chamada de modelo adiada
Para interromper uma interação adiada em que status é queued ou in_progress, chame
interactions.cancel. Chamar interactions.cancel em uma interação em qualquer
outro status retorna HTTP 409 ("code": "aborted"). Para saber como o cancelamento
afeta o faturamento, consulte Preços e faturamento.
Antes de executar um exemplo, faça as seguintes substituições:
PROJECT_ID: o ID do projeto do Google Cloud , comomy-agent-project.INTERACTION_ID: o ID de uma interaçãoqueuedouin_progress, comov1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ.
REST
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
PROJECT_ID: o ID do projeto do Google Cloud , comomy-agent-project.INTERACTION_ID: o ID de uma interação em fila ou em andamento a ser cancelada, comov1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ.
Método HTTP e URL:
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID/cancel
Para enviar a solicitação, expanda uma destas opções:
A resposta retorna um payload JSON semelhante ao seguinte:
{
"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}`);
A saída é esta:
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}")
A saída é esta:
Status: cancelled
Preços, cotas e controles de segurança
Revise as regras de faturamento, as cotas, os limites de payload e os controles de segurança antes de executar cargas de trabalho de produção no nível Deferred.
Preços e faturamento
As chamadas de modelo adiadas são cobradas com um desconto de 50% em comparação com as taxas de pagamento por uso padrão para tokens de entrada, saída e token de raciocínio. O faturamento segue estas regras:
- Acúmulo de descontos: o desconto diferido se acumula com descontos de contrato e de tokens de armazenamento em cache de contexto implícito, aplicando-se sobre a taxa em cache.
- Sem fallback para as taxas padrão: as solicitações adiadas nunca são transferidas ou rebaixadas para o PayGo padrão, portanto, não são faturadas com as taxas sob demanda sem desconto.
- Faturamento por chamada de modelo: cada chamada de modelo feita por uma rodada é faturada.
As interações que terminam como
completed,incomplete,requires_actionourequires_continuationsão cobradas pela taxa adiada. - Ativações canceladas: uma ativação que você cancela enquanto está
queuednão é faturada. Se você cancelar um turno enquanto ele estiverin_progress, as chamadas de modelo que já começaram serão cobradas, incluindo uma chamada que foi interrompida no meio da geração. - Turnos com falha: turnos de chamada única que terminam como
failed, incluindo turnos que excedem a janela de conclusão de 24 horas, não são faturados. Em um loop de ferramenta do lado do servidor de várias etapas, as chamadas de modelo concluídas antes de uma falha são faturadas, mas a chamada com falha não. - Turnos encadeados: cada turno em uma cadeia de
previous_interaction_idé faturado separadamente. O cancelamento ou a falha de uma rodada posterior não altera as cobranças das rodadas anteriores.
Para saber as taxas de token por modelo, consulte a página de preços da Agent Platform.
Cotas, limites de payload e retenção
O nível Diferido não tem uma cota própria de chamadas de modelo. As chamadas
adiadas compartilham a cota de pagamento por uso do Flex
(flex_requests_per_minute_per_project_per_base_model, 3.000 RPM), que
é verificada em cada chamada de modelo depois que interactions.create retorna queued. As principais cotas de projeto e limites do sistema incluem:
- Cotas de criação e simultaneidade: até 100 RPM ou ilimitado para
stateful_genai_interaction_creationsno momento da criação. Até 500concurrent_interaction_generations, dependendo do seu nível de cota. - Capacidade de processamento diária com estado (fixa): 240 GiB por dia gravados e 480 GiB por dia lidos por projeto.
- Limites de payload e retenção: até 9, 75 MiB de corpo HTTP não compactado por chamada
interactions.createe retenção de estado de sete dias. As cadeias oferecem suporte a até 100 URIs distintos do Cloud Storage (gs://).
Para ver a tabela de cotas completa e as instruções do console, consulte Cotas e limites do nível adiado.
Controles de segurança e compliance
Como o nível adiado coloca em fila e mantém o estado no endpoint global, verifique se os controles de governança compatíveis correspondem aos seus requisitos de conformidade:
- Controles compatíveis:
VPC Service Controls
(VPC-SC; ferramentas externas do
mcp_servernão são permitidas dentro de um perímetro), Transparência no acesso (AXT), Registros de auditoria do Cloud e FedRAMP High. - Controles não compatíveis: retenção de dados zero sem estado (
store=falsee a aplicação deconstraints/vertexai.disableAPIStorageretornam HTTP400com"code": "invalid_request"), chaves de criptografia gerenciadas pelo cliente (CMEK), residência de dados, DoD IL5 e ITAR.
Para ver a matriz de recursos completa, consulte Controles de segurança para IA generativa.
Resolver problemas
A tabela a seguir descreve erros comuns no nível adiado e como resolvê-los:
| Erro ou status | Causas comuns | Resolução |
|---|---|---|
400 (error.code: "invalid_request"; endpoint, flags ou modelo) |
Endpoint que não é global, modelo não compatível ou flags background, store ou stream inválidas em interactions.create. |
Segmente locations/global com um modelo compatível, defina background=true e store=true e omita stream=true. |
400 (error.code: "invalid_request"; payload, URIs ou ferramentas) |
O corpo não compactado excede 9, 75 MiB, a cadeia excede 100 URIs de gs:// ou ferramentas externas de mcp_server dentro do VPC-SC. |
Transmita arquivos grandes como URIs do gs:// (no máximo 100 por cadeia) e omita ferramentas externas do mcp_server dentro do VPC-SC. |
400 (error.code: "invalid_request" em interactions.create; status: "FAILED_PRECONDITION" em interactions.delete) |
|
|
401 (status: "UNAUTHENTICATED" ou error.code: "authentication") |
Suas credenciais da CLI gcloud (exemplos de REST) ou do ADC (exemplos do SDK de IA generativa do Google) estão ausentes ou expiraram. | Para exemplos de REST, execute gcloud auth login. Para exemplos do SDK de IA generativa do Google, execute gcloud auth application-default login. Em seguida, tente fazer a solicitação novamente. |
403 (status: "PERMISSION_DENIED" ou error.code: "permission_denied") |
|
Conceder roles/aiplatform.user. Para entradas do Cloud Storage, conceda também roles/storage.objectViewer. |
404 (error.code: "not_found"; status: "NOT_FOUND" em interactions.delete) |
A interação ou previous_interaction_id não existe ou foi excluída. Ele também pode pertencer a um endpoint que não seja do global ou ser mais antigo que o período de armazenamento de 7 dias. |
Verifique o ID da interação no endpoint global. Se a vez do familiar responsável tiver expirado, inicie uma nova sequência sem previous_interaction_id. |
409 (error.code: "aborted") |
interactions.cancel segmenta uma interação que já está em um status final: requires_action, requires_continuation, completed, incomplete, failed ou cancelled. |
Verifique status com interactions.get primeiro. Só é possível cancelar as interações queued e in_progress. |
429 (error.code: "too_many_requests") |
O projeto excedeu uma cota por projeto, como a taxa de criação de interações, as gerações de interações simultâneas ou a capacidade diária com estado. |
|
status="failed" |
|
|
A seguir
Confira os guias relacionados e a documentação de referência para cargas de trabalho assíncronas e com estado do Gemini:
- Compare os modelos de computação em Opções de consumo.
- Crie aplicativos multiturno com estado no guia para desenvolvedores da API Interactions.
- Programe agentes do ADK e execuções de pesquisa gerenciadas em Programação de agentes autônomos.
- Confira os esquemas de métodos na referência da API Interactions.