Usar o nível adiado

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_id turnos 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:

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:

Antes de começar

Em um projeto do Google Cloud com faturamento ativado, conclua as seguintes etapas de configuração de pré-requisito:

  1. Faça login na sua Conta do Google.

    Se você ainda não tiver uma, inscreva-se agora.

  2. Instale a CLI do Google Cloud.

  3. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

  4. Para inicializar a CLI gcloud, execute o seguinte comando:

    gcloud init
  5. Verifique se você tem as permissões necessárias para concluir este guia.

  6. 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
  7. 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.

  8. Instale a CLI do Google Cloud.

  9. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

  10. Para inicializar a CLI gcloud, execute o seguinte comando:

    gcloud init
  11. Verifique se você tem as permissões necessárias para concluir este guia.

  12. 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
  13. 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 :

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 , como my-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 , como my-agent-project.
  • INTERACTION_ID: o ID de interação retornado quando você criou a chamada de modelo adiada, como v1_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 , como my-agent-project.
  • INTERACTION_ID: o ID da interação retornado quando você criou a chamada de modelo adiada, como v1_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 , como my-agent-project.
  • PREVIOUS_INTERACTION_ID: o ID da vez anterior de completed ou requires_action, como v1_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 , como my-agent-project.
  • PREVIOUS_INTERACTION_ID: o ID da interação concluída ou que requer ação da rodada anterior, como v1_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 , como my-agent-project.
  • INTERACTION_ID: o ID de uma interação queued ou in_progress, como v1_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 , como my-agent-project.
  • INTERACTION_ID: o ID de uma interação em fila ou em andamento a ser cancelada, como v1_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_action ou requires_continuation são cobradas pela taxa adiada.
  • Ativações canceladas: uma ativação que você cancela enquanto está queued não é faturada. Se você cancelar um turno enquanto ele estiver in_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_creations no momento da criação. Até 500 concurrent_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.create e 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:

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)
  • A política constraints/vertexai.disableAPIStorage é aplicada.
  • interactions.create se conecta a uma curva queued ou in_progress ou define input em requires_continuation.
  • interactions.delete segmenta uma curva queued ou in_progress.
  • Use um projeto que permita a persistência do estado da API.
  • Encadeie apenas as últimas interações. Em requires_continuation, transmita continuation_token e omita input.
  • Cancele as ativações antes de excluí-las.
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")
  • O autor da chamada não tem roles/aiplatform.user.
  • O autor da chamada não tem storage.objects.get nas entradas gs://.
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.
  • Tente novamente após o atraso do cabeçalho Retry-After com espera e jitter.
  • Solicite aumentos de cota ajustáveis em Cotas e limites do nível adiado. Os limites diários de capacidade de processamento são fixos.
status="failed"
  • Ocorreu uma falha no modelo ou na ferramenta upstream, ou o turno excedeu a janela de conclusão de 24 horas.
  • A solicitação usa um modelo *-cyber*, e o projeto não tem acesso à lista de permissões.
  • Inspecione o campo error retornado por interactions.get e envie uma nova solicitação interactions.create.
  • Para modelos Cyber, confirme o acesso à lista de permissões com sua equipe de conta do Google Cloud .

A seguir

Confira os guias relacionados e a documentação de referência para cargas de trabalho assíncronas e com estado do Gemini: