Guia do desenvolvedor para o Gemini 4 Argon

O Gemini 4 Argon é o modelo de fronteira do Google que se destaca em trabalho profundo em tarefas complexas do mundo real em domínios como programação, finanças, direito, cibersegurança e ciência. É o primeiro modelo da família Gemini 4.

Este documento aborda as novidades do 4 Argon, as convenções de API que ele aplica, como migrar para ele e um guia de início rápido. Para uma visão geral da família Gemini 4, consulte Começar a usar o Gemini 4.

Quais são as novidades do Gemini 4 Argon?

  • Limite unificado de tokens de entrada e saída: o 4 Argon tem um limite unificado de 1.048.576 tokens que inclui tokens de entrada e saída (em que a saída inclui pensamento, chamadas de função e a resposta final).
  • Decodificações longas de até 1.048.576 tokens: estende a geração além do limite de saída de solicitação única (65.536 tokens ao fazer streaming ou 32.768 tokens para solicitações em primeiro plano que não são de streaming) até 1.048.576 tokens (menos os tokens de entrada) na API Interactions e no GenerateContent (v1beta1). O SDK de IA generativa do Google processa continuation_token automaticamente em todos os segmentos, ou você pode executar decodificações em segundo plano assíncronas gerenciadas pelo servidor (background=true) ou gerenciar continuation_token em um loop de continuação personalizado.
  • Níveis de raciocínio: LOW, MEDIUM (padrão no gemini-4-argon) e HIGH (padrão no gemini-4-argon-cyber-permissive).
  • Armazenamento em cache implícito com armazenamento em cache durável: o armazenamento em cache implícito é aplicado automaticamente a prefixos de comandos compartilhados de 4.096 tokens ou mais, com o armazenamento em cache durável ativado por padrão. Não há suporte para o armazenamento em cache de contexto explícito.
  • Compreensão agêntica de vídeos: em disponibilidade geral e desativada por padrão.

Guia de início rápido

Antes de começar, autentique-se na Agent Platform usando o Application Default Credentials (ADC) ou uma chave de API. Consulte Começar a usar a Gemini Enterprise Agent Platform para mais informações.

Nos blocos de código a seguir, substitua PROJECT_ID pelo ID do projeto.

Teste no Agent Studio

Para testar comandos e configurar gemini-4-argon na UI do Agent Studio:

  1. Abra o Agent Studio no seu projeto do Google Cloud e selecione gemini-4-argon no grupo do Gemini.
  2. Em Configurações do modelo, configure:
    • Nível de raciocínio: escolha Low, Medium (padrão) ou High.
    • Região: selecione Global, us ou eu.
    • Limite de tokens de saída: defina entre 32,768 e 1,048,576 (1,048,576 é o padrão). O Agent Studio processa tokens de continuação automaticamente para respostas que excedem o limite de uma única solicitação.

Instalação

Faça upgrade para o SDK de IA generativa do Google mais recente. A continuação automática na API Interactions requer google-genai >= 2.34.0 para Python, @google/genai >= 2.32.0 para JavaScript/TypeScript, >= 1.77.0 para Go ou >= 1.80.0 para Java (no GenerateContent, a continuação automática requer >= 2.30.1 para Python, >= 2.29.1 para JavaScript/TypeScript, >= 1.74.0 para Go, >= 1.77.0 para Java, >= 1.26.0 para .NET ou >= 1.6.0 para Kotlin):

pip install --upgrade "google-genai>=2.34.0"

Solicitação básica

Python (GenerateContent)

from google import genai
from google.genai import types

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

response = client.models.generate_content(
    model="gemini-4-argon",
    contents="Design a lock-free ring buffer in Rust for multi-producer, single-consumer telemetry ingestion.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(
            thinking_level="MEDIUM",  # Default: "MEDIUM" (Valid: "LOW", "MEDIUM", "HIGH")
        ),
    ),
)
print(response.text)

Python (API Interactions)

from google import genai

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

# Turn 1: Initial request (stored server-side by default)
turn1 = client.interactions.create(
    model="gemini-4-argon",
    input="Design a lock-free ring buffer in Rust for multi-producer, single-consumer telemetry ingestion.",
    store=True,
)
print(turn1.output_text)

# Turn 2: Continue the conversation using previous_interaction_id
turn2 = client.interactions.create(
    model="gemini-4-argon",
    input="Add a bounded backpressure policy and unit tests for concurrent writers.",
    previous_interaction_id=turn1.id,
)
print(turn2.output_text)

REST

curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-4-argon:generateContent" \
-d '{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Provide an architectural review of this Go interface."
        }
      ]
    }
  ],
  "generationConfig": {
    "thinkingConfig": {
      "thinkingLevel": "MEDIUM"
    }
  }
}'

Resposta estruturada

from pydantic import BaseModel, Field
from google import genai
from google.genai import types

class ArchitectureReview(BaseModel):
    component: str = Field(description="Service or module name")
    bottlenecks: list[str] = Field(description="Throughput or latency bottlenecks")
    recommended_changes: list[str] = Field(description="Concrete refactoring steps")

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

response = client.models.generate_content(
    model="gemini-4-argon",
    contents="Review a synchronous order-processing pipeline backed by a single primary database at 15,000 writes/sec.",
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        response_schema=ArchitectureReview,
        thinking_config=types.ThinkingConfig(thinking_level="HIGH"),
    ),
)
print(response.text)

Exemplos de decodificação longa

Por padrão, um único segmento de API em primeiro plano gera até 65.536 tokens de saída ao fazer streaming ou 32.768 tokens de saída ao não fazer streaming, em que a saída inclui pensamento, chamadas de função e a resposta final. Para gerar conclusões de até 1.048.576 tokens (menos os tokens de entrada), use decodificações longas na API Interactions ou na GenerateContent. Para opções de continuação, transições de status e regras de validação, consulte Decodificações longas.

Usar decodificações longas com a API Interactions

Em google-genai >= 2.34.0 (Python), @google/genai >= 2.32.0 (JavaScript/TypeScript), Go >= 1.77.0 e Java >= 1.80.0, interactions.create() segue automaticamente continuation_token entre segmentos sempre que um segmento retorna status="requires_continuation". Também é possível desativar (automatic_continuation=False) para executar um loop personalizado armazenado (store=True) ou sem estado (store=False):

Python (SDK automático)

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

# Automatic continuation is enabled by default in google-genai >= 2.34.0.
# Unary calls merge all segments into one Interaction with summed usage.
interaction = client.interactions.create(
    model="gemini-4-argon",
    input="Write a complete formal proof of the prime number theorem.",
    generation_config={
        "max_output_tokens": 256000,
        "thinking_level": "high",
    },
)
print(interaction.output_text)
print(f"Merged segment IDs: {interaction.continuation_ids}")
print(f"Initial input tokens: {interaction.usage.initial_input_tokens}")

# Optional: Delete each stored server segment (last segment first) before its 7-day TTL expires.
for segment_id in reversed(interaction.continuation_ids or [interaction.id]):
    client.interactions.delete(id=segment_id)

# Streaming yields events across all segments in order. Intermediate segments
# emit interaction.completed with status="requires_continuation".
stream = client.interactions.create(
    model="gemini-4-argon",
    input="Write a complete formal proof of the prime number theorem.",
    stream=True,
    generation_config={
        "max_output_tokens": 256000,
        "thinking_level": "high",
    },
)
for event in stream:
    if event.event_type == "step.delta" and getattr(event.delta, "text", None):
        print(event.delta.text, end="", flush=True)
    elif (
        event.event_type == "interaction.completed"
        and event.interaction.status != "requires_continuation"
    ):
        print(f"\nFinal status: {event.interaction.status}")

# Set automatic_continuation=False to return after a single segment.
single_segment = client.interactions.create(
    model="gemini-4-argon",
    input="Write a complete formal proof of the prime number theorem.",
    generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
    automatic_continuation=False,
)

Python (loop personalizado)

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

prompt = "Write a complete formal proof of the prime number theorem."

# Stored loop (store=True, default): chain previous_interaction_id + continuation_token
# without resending input.
segment = client.interactions.create(
    model="gemini-4-argon",
    input=prompt,
    store=True,
    generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
    automatic_continuation=False,
)
full_text = segment.output_text or ""

while segment.status == "requires_continuation" and segment.continuation_token:
    segment = client.interactions.create(
        model="gemini-4-argon",
        previous_interaction_id=segment.id,
        continuation_token=segment.continuation_token,
        generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
        automatic_continuation=False,
    )
    full_text += segment.output_text or ""

# If status == "incomplete", max_output_tokens was exhausted; raise max_output_tokens
# to continue (leaving default automatic_continuation=True lets the SDK finish remaining segments).
if segment.status == "incomplete" and segment.continuation_token:
    segment = client.interactions.create(
        model="gemini-4-argon",
        previous_interaction_id=segment.id,
        continuation_token=segment.continuation_token,
        generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
    )
    full_text += segment.output_text or ""

# Stateless loop (store=False): resend original input + continuation_token
# with no previous_interaction_id.
stateless_seg = client.interactions.create(
    model="gemini-4-argon",
    input=prompt,
    store=False,
    generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
    automatic_continuation=False,
)
stateless_text = stateless_seg.output_text or ""
while stateless_seg.status == "requires_continuation" and stateless_seg.continuation_token:
    stateless_seg = client.interactions.create(
        model="gemini-4-argon",
        input=prompt,
        store=False,
        continuation_token=stateless_seg.continuation_token,
        generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
        automatic_continuation=False,
    )
    stateless_text += stateless_seg.output_text or ""

REST (armazenado)

# Segment 1: Start a stored interaction (store=true by default)
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-argon",
    "store": true,
    "input": "Write a complete formal proof of the prime number theorem.",
    "generation_config": {
      "max_output_tokens": 131072,
      "thinking_level": "high"
    }
  }'

# Segment 2: When status is "requires_continuation", pass previous_interaction_id
# and continuation_token without resending input
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-argon",
    "store": true,
    "previous_interaction_id": "SEGMENT_1_ID",
    "continuation_token": "CONTINUATION_TOKEN",
    "generation_config": {
      "max_output_tokens": 131072,
      "thinking_level": "high"
    }
  }'

REST (sem estado)

# Segment 1: Stateless interaction (store=false)
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-argon",
    "store": false,
    "input": "Write a complete formal proof of the prime number theorem.",
    "generation_config": {
      "max_output_tokens": 131072,
      "thinking_level": "high"
    }
  }'

# Segment 2: Resend the original input and continuation_token (no previous_interaction_id)
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-argon",
    "store": false,
    "input": "Write a complete formal proof of the prime number theorem.",
    "continuation_token": "CONTINUATION_TOKEN",
    "generation_config": {
      "max_output_tokens": 131072,
      "thinking_level": "high"
    }
  }'

Para execução assíncrona gerenciada pelo servidor (background=True com store=True) ou recuperação de checkpoints de streaming (eventos interaction.status_update emitidos em 32.768 tokens de saída e a cada 5.000 tokens depois disso), use os seguintes padrões:

Python (segundo plano)

import time
from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

# Start a server-managed background long decode (requires store=True)
interaction = client.interactions.create(
    model="gemini-4-argon",
    input="Write a complete formal proof of the prime number theorem.",
    background=True,
    store=True,
    generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
)

while interaction.status in ("queued", "in_progress"):
    time.sleep(10)
    interaction = client.interactions.get(id=interaction.id)

print(f"Status: {interaction.status}")
print(interaction.output_text)

# Optional: Cancel an in-progress background interaction and resume later
# from its persisted checkpoint continuation_token (if >= 32,768 tokens decoded).
# cancelled = client.interactions.cancel(id=interaction.id)
# if cancelled.continuation_token:
#     resumed = client.interactions.create(
#         model="gemini-4-argon",
#         previous_interaction_id=cancelled.id,
#         continuation_token=cancelled.continuation_token,
#         background=True,
#         generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
#     )

REST (segundo plano)

# Start a server-managed background long decode (requires store=true)
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-argon",
    "background": true,
    "store": true,
    "input": "Write a complete formal proof of the prime number theorem.",
    "generation_config": {
      "max_output_tokens": 256000,
      "thinking_level": "high"
    }
  }'

# Poll the interaction until status reaches completed, incomplete, failed, or cancelled
curl -s -X GET \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID"

# Optional: Cancel an in-progress background decode
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID/cancel"

# Optional: Resume a cancelled background decode from its checkpoint continuation_token
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-argon",
    "background": true,
    "store": true,
    "previous_interaction_id": "INTERACTION_ID",
    "continuation_token": "CONTINUATION_TOKEN",
    "generation_config": {
      "max_output_tokens": 256000,
      "thinking_level": "high"
    }
  }'

Python (pontos de verificação de streaming)

from google import genai
from google.genai import errors

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

# With default automatic_continuation=True, stream=True automatically
# reconnects from the latest interaction.status_update checkpoint (32,768
# output tokens, then every 5,000 tokens) if no output was yielded after the
# checkpoint. If a disconnect occurs after output was yielded since the last
# checkpoint, the SDK raises ContinuationInterruptedError so you can resume
# from err.continuation_token.
stream = client.interactions.create(
    model="gemini-4-argon",
    input="Write a complete formal proof of the prime number theorem.",
    stream=True,
    store=True,
    generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
)

try:
    for event in stream:
        if event.event_type == "step.delta" and getattr(event.delta, "text", None):
            print(event.delta.text, end="", flush=True)
except errors.ContinuationInterruptedError as err:
    # Resuming from a mid-segment checkpoint regenerates any output yielded
    # after that checkpoint.
    if err.interaction_id and err.continuation_token:
        resumed_stream = client.interactions.create(
            model="gemini-4-argon",
            previous_interaction_id=err.interaction_id,
            continuation_token=err.continuation_token,
            stream=True,
            store=True,
            generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
        )
        for event in resumed_stream:
            if event.event_type == "step.delta" and getattr(event.delta, "text", None):
                print(event.delta.text, end="", flush=True)

REST (checkpoints de streaming)

# Start a streaming interaction; save interaction.id from interaction.created
# and the latest continuation_token from interaction.status_update SSE events
curl -N -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-argon",
    "stream": true,
    "store": true,
    "input": "Write a complete formal proof of the prime number theorem.",
    "generation_config": {
      "max_output_tokens": 256000,
      "thinking_level": "high"
    }
  }'

# Resume a dropped stream from the last saved checkpoint continuation_token
# (for store=false, resend the original input instead of previous_interaction_id)
curl -N -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-argon",
    "stream": true,
    "store": true,
    "previous_interaction_id": "SEGMENT_ID",
    "continuation_token": "CHECKPOINT_CONTINUATION_TOKEN",
    "generation_config": {
      "max_output_tokens": 256000,
      "thinking_level": "high"
    }
  }'

Usar decodificações longas com GenerateContent

No GenerateContent (v1beta1), defina max_output_tokens como maior que 65.536 para solicitações de streaming ou maior que 32.768 para solicitações que não são de streaming (até 1.048.576). O SDK de IA generativa do Google segue automaticamente continuation_token em todos os segmentos quando finish_reason é CONTINUATION (defina automatic_continuation=False em GenerateContentConfig para desativar) ou você pode transmitir continuation_token em um loop personalizado:

Python (SDK - Recomendado)

from google import genai
from google.genai import types

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

# Automatic continuation is enabled by default in google-genai >= 2.30.1.
# Chunks across all continuation requests are yielded as a single stream.
for chunk in client.models.generate_content_stream(
    model="gemini-4-argon",
    contents="Write a complete formal proof of the prime number theorem.",
    config=types.GenerateContentConfig(
        max_output_tokens=256000,
        thinking_config=types.ThinkingConfig(thinking_level="HIGH"),
    ),
):
    print(chunk.text, end="")

# Set automatic_continuation=False to disable automatic continuation.
for chunk in client.models.generate_content_stream(
    model="gemini-4-argon",
    contents="Write a complete formal proof of the prime number theorem.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="HIGH"),
        automatic_continuation=False,
    ),
):
    print(chunk.text, end="")

REST (loop de continuação personalizado)

# Request 1: Initial request with maxOutputTokens > 32,768
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-4-argon:generateContent" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "Write a complete formal proof of the prime number theorem."}]
    }],
    "generationConfig": {
      "maxOutputTokens": 131072,
      "thinkingConfig": {"thinkingLevel": "HIGH"}
    }
  }'

# Request 2: Resend the original request with top-level continuationToken
# from Request 1 (candidates[0].continuationToken)
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-4-argon:generateContent" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "Write a complete formal proof of the prime number theorem."}]
    }],
    "continuationToken": "CONTINUATION_TOKEN",
    "generationConfig": {
      "maxOutputTokens": 131072,
      "thinkingConfig": {"thinkingLevel": "HIGH"}
    }
  }'

Regras obrigatórias de API e convenções comportamentais

O 4 Argon aplica as convenções nas seções a seguir para níveis de pensamento, limites de tokens, armazenamento em cache, parâmetros de geração e execução de ferramentas em várias interações.

Níveis de raciocínio

O Argon 4 é compatível com três valores thinking_level (thinking_budget e MINIMAL retornam um erro de validação HTTP 400). A tabela a seguir lista cada nível de pensamento e as cargas de trabalho recomendadas:

Nível de raciocínio Cargas de trabalho recomendadas
HIGH (padrão em gemini-4-argon-cyber-permissive) Engenharia de software de vários arquivos, provas formais, design de arquitetura e descoberta de vulnerabilidades.
MEDIUM (padrão em gemini-4-argon) Programação geral, uso de ferramentas, perguntas e respostas sobre documentos e compreensão de vídeos.
LOW Classificação, resumo e extração de metadados.

Limites de tokens, armazenamento em cache e faturamento

4 O Argon aplica as seguintes regras de token, armazenamento em cache, mídia e faturamento:

  • Limite unificado de tokens de entrada e saída e limites de saída de solicitação única: os orçamentos de tokens e os limites por solicitação funcionam da seguinte maneira:
    • O limite geral de tokens do modelo é de 1,048,576 tokens e inclui tokens de entrada e saída (em que a saída inclui raciocínio, chamadas de função e a resposta final). max_output_tokens controla o limite de tokens de saída para a geração (até 1,048,576 menos os tokens de entrada). Definir max_output_tokens como maior que 1,048,576 retorna um erro HTTP 400.
    • Para evitar conclusões longas não intencionais, o limite padrão de saída de solicitação única (processamento + resposta do modelo) é de 65.536 tokens (ou 32.768 tokens para solicitações HTTP diretas sem streaming).
  • Decodificações longas: as respostas em primeiro plano de segmento único geram até 65.536 tokens de saída ao fazer streaming ou 32.768 tokens de saída ao não fazer streaming. Para estender a saída de turno único até 1.048.576 tokens (menos tokens de entrada) na API Interactions ou GenerateContent (v1beta1), consulte Decodificações longas.
  • Armazenamento em cache de contexto: não há suporte para o armazenamento em cache de contexto explícito. O armazenamento em cache implícito (com o armazenamento em cache durável ativado por padrão) é aplicado automaticamente a prefixos de comando compartilhados de 4.096 tokens ou mais. Portanto, coloque o conteúdo estático no início do comando.
  • Vídeo agêntico: os vídeos enviados usam media_processing="static" como padrão. Defina media_processing="agentic" como ativado para processamento agêntico de vídeos.
  • Contagem e faturamento de tokens: cada token processado pelo modelo é contado e faturado, incluindo tokens de raciocínio, instruções do sistema de ferramentas internas e declarações de função ao usar o embasamento. O embasamento com a Pesquisa Google também continua sendo cobrado por consulta.

Parâmetros, chamada de função e validação de chat

O 4 Argon aplica as seguintes regras para parâmetros de geração, chamadas de ferramentas e histórico de conversas:

  • Parâmetros de amostragem ignorados (temperature, top_k, top_p): o back-end ignora valores personalizados. Controle a profundidade do raciocínio com thinking_level e o formato de saída com response_schema.
  • Parâmetros não aceitos (frequency_penalty, presence_penalty, candidate_count): retornam um erro de HTTP 400. Remova-os das suas solicitações.

  • Chamada de função: as declarações de ferramentas e as rodadas de execução seguem estas regras:

    • Simetria de turno: cada FunctionResponse precisa corresponder ao id, name e à ordem do FunctionCall anterior.
    • Execução sequencial: priorize as execuções sequenciais de ferramentas em loops de ferramentas de várias etapas.

    • Formatação pré-ferramenta: separe as instruções inline com \n\n e evite texto não estruturado antes das chamadas de ferramenta. Para registrar o estado intermediário antes de uma chamada de ferramenta, use uma declaração de função dedicada:

      {
  "name": "update",
  "description": "Update working notes before tool execution",
  "parameters": {
    "type": "OBJECT",
    "properties": {
      "previous_step": {"type": "STRING"},
      "plan": {"type": "STRING"},
      "next_step": {"type": "STRING"}
    },
    "required": ["previous_step", "plan", "next_step"]
  }
}

  • Validação da sequência de conversa: os payloads de conversa multiturno aplicam as seguintes restrições:

    • Os payloads de histórico não podem terminar com uma vez de função model.
    • Não há suporte para turnos de modelo preenchidos automaticamente.

Decodificações longas

A decodificação longa divide uma geração de até 1.048.576 tokens (menos os tokens de entrada) em vários segmentos na API Interactions ou GenerateContent (v1beta1). Na API Interactions, cada segmento em primeiro plano gera até 65.536 tokens de saída ao fazer streaming (stream=true) ou 32.768 tokens de saída ao não fazer streaming (stream=false) e retorna status="requires_continuation" com um continuation_token criptografado. Se preferir, defina background=true (store=true) para que o servidor execute o loop de continuação de forma assíncrona e armazene a saída mesclada em um Interaction. No GenerateContent, os segmentos de streaming geram até 65.536 tokens de saída, e os segmentos que não são de streaming geram até 32.768 tokens de saída antes de emitir finish_reason=CONTINUATION com continuation_token, continuando até finish_reason=STOP. No Agent Studio, definir o limite de tokens de saída acima de 65.536 até 1.048.576 processa os tokens de continuação automaticamente. Para exemplos de código executáveis, consulte os exemplos do guia de início rápido de decodificação longa.

Quando usar a decodificação longa

A maioria das solicitações é concluída dentro do limite por solicitação (65.536 tokens ou 32.768 tokens para chamadas REST sem streaming). Use a decodificação longa somente quando uma resposta precisar de mais saída do que isso. A decodificação longa dá ao modelo mais espaço para raciocinar, mas não torna as respostas mais longas (use thinking_level para controlar a profundidade do raciocínio).

Carga de trabalho Usar decodificação longa? Por quê?
Matemática, ciência, pesquisa e provas formais complexas Sim O modelo pode gastar mais de 65.536 tokens para explorar e verificar o raciocínio.
As tarefas agênticas e de programação mais difíceis Sim Algumas tarefas precisam de mais de 65.536 tokens de raciocínio e código em uma única resposta. A maioria das tarefas de programação e agênticas é concluída com menos de 65.536 tokens.
Ambientes de avaliação que param no limite de saída Sim A decodificação longa evita respostas cortadas quando o modelo gasta uma solicitação inteira de 65.536 ou 32.768 tokens no raciocínio.
Chat, perguntas e respostas, resumo, classificação e extração Não Essas tarefas são concluídas com bem menos de 32.768 tokens.
Solicitações de tamanho fixo, como "Escreva um livro de 700.000 palavras" Não O modelo não segue as metas de tamanho.
Agentes que chamam ferramentas em muitas interações curtas Não Cada turno é curto. As saídas grandes em cada turno preenchem rapidamente o limite unificado de 1.048.576 tokens de entrada e saída.
Comandos próximos ao limite de entrada de 1.048.576 tokens Não A saída pode usar apenas 1.048.576 tokens menos sua entrada.
Solicitações sensíveis à latência Não A decodificação longa pode levar vários minutos.

Escolha uma opção de continuação

Selecione um padrão de continuação com base na superfície da API, na postura de armazenamento e no ambiente de execução. Todas as opções na tabela a seguir atingem o mesmo limite de 1.048.576 tokens (menos tokens de entrada) em gemini-4-argon e gemini-4-argon-cyber-permissive.

Opção de continuação Superfície da API Quem inicia cada segmento Tokens por segmento Limite de tempo por solicitação Armazenamento do servidor Ideal para
Continuação automática do SDK de IA generativa do Google (recomendado) API Interactions (v1beta1) SDKs de IA generativa do Google: Python (google-genai >= 2.34.0), JavaScript/TypeScript (@google/genai >= 2.32.0), Go (>= 1.77.0) e Java (>= 1.80.0) Até 65.536 (stream=true) ou 32.768 (stream=false) 20 minutos por segmento Armazenamento de sete dias no servidor por padrão (store=true) ou nenhum (store=false) A maioria dos aplicativos da API Interactions com ou sem estado
Loop em segundo plano gerenciado pelo servidor (background=true) API Interactions (v1beta1) Loop do servidor da Agent Platform; seu código faz uma sondagem em get Gerenciado do lado do servidor até max_output_tokens Assíncrono (não é necessário abrir um stream de cliente) Armazenamento do servidor por sete dias (store=true necessário) Jobs assíncronos, autores de chamadas em outras linguagens por REST e persistência de registro único
Loop armazenado em primeiro plano personalizado (store=true) API Interactions (v1beta1) Seu código (previous_interaction_id + continuation_token, sem input) Até 65.536 (stream=true, checkpoints a cada 5.000 tokens após 32.768) ou 32.768 (stream=false) 20 minutos por segmento Armazenamento de sete dias no servidor (store=true) Chamadores REST e recuperação de checkpoint personalizada
Loop personalizado sem estado em primeiro plano (store=false) API Interactions (v1beta1) Seu código (input + continuation_token original, sem previous_interaction_id) Até 65.536 (stream=true, checkpoints a cada 5.000 tokens após 32.768) ou 32.768 (stream=false) 20 minutos por segmento Sem armazenamento no servidor (fluxos de trabalho de retenção zero de dados) Harnesses REST personalizados que exigem execução sem estado
Continuação automática do SDK de IA generativa do Google (recomendado) GenerateContent (v1beta1) SDKs de IA generativa do Google: Python (>= 2.30.1), JavaScript/TypeScript (>= 2.29.1), Go (>= 1.74.0), Java (>= 1.77.0), .NET (>= 1.26.0) e Kotlin (>= 1.6.0) Até 65.536 (generate_content_stream) ou 32.768 (generate_content) 20 minutos por segmento Sem armazenamento no servidor (fluxos de trabalho de retenção zero de dados) Aplicativos GenerateContent atuais
Loop de continuação personalizado GenerateContent (v1beta1) Seu código (contents original + continuation_token) Até 65.536 (streamGenerateContent, checkpoints a cada 5.000 tokens após 32.768) ou 32.768 (generateContent) 20 minutos por segmento Sem armazenamento no servidor (fluxos de trabalho de retenção zero de dados) Chamadores REST GenerateContent diretos e harnesses de avaliação

Versão da API e requisitos do SDK

As decodificações longas exigem as seguintes versões de API e do SDK:

  • Requisito da API v1beta1 (problema conhecido): a decodificação longa (continuation_token) na API Interactions e GenerateContent (generateContent e streamGenerateContent) só é compatível com a API v1beta1 (não v1) na Agent Platform. O SDK de IA generativa do Google usa v1beta1 por padrão, a menos que api_version='v1' seja especificado em http_options (ou api_version="v1" em interactions.create). Para chamadas REST diretas, use o caminho do endpoint /v1beta1/.
  • Versões do SDK e compatibilidade com a OpenAI: para continuar automaticamente na API Interactions, faça upgrade para Python google-genai >= 2.34.0, JavaScript/TypeScript @google/genai >= 2.32.0, Go >= 1.77.0 ou Java >= 1.80.0. Para outras linguagens na API Interactions, chame a API REST diretamente com background=true ou um loop de continuação personalizado. Para continuar automaticamente no GenerateContent, faça upgrade para o Python >= 2.30.1, JavaScript/TypeScript >= 2.29.1, Go >= 1.74.0, Java >= 1.77.0, .NET >= 1.26.0 ou Kotlin >= 1.6.0. As versões anteriores do SDK e a camada de compatibilidade com a OpenAI não podem recuperar conclusões longas usando tokens de continuação.

Regras de continuação da API Interactions

As seguintes transições de status, regras de encadeamento e comportamentos de armazenamento se aplicam a decodificações longas na API Interactions.

Valores de status e orçamento de tokens de saída

Quando generation_config.max_output_tokens é omitido em uma solicitação de API Interactions, o orçamento total de saída é definido como 65.536 tokens por padrão. Assim, uma chamada sem streaming é interrompida em 32.768 tokens com status="requires_continuation", e um segundo segmento pode gerar os 32.768 tokens restantes. Defina generation_config.max_output_tokens como até 1,048,576 (menos tokens de entrada) para decodificações mais longas nos modos de primeiro plano e background=true. O servidor retorna os seguintes valores de status:

  • requires_continuation: o limite de saída por segmento (32.768 sem streaming ou 65.536 com streaming) foi atingido antes de max_output_tokens. Transmita o continuation_token retornado na próxima solicitação para continuar a decodificação.
  • incomplete: o orçamento total de max_output_tokens foi esgotado. Continuar com continuation_token sem aumentar max_output_tokens retorna um erro HTTP 400 (max_output_tokens has already been exhausted). Aumente max_output_tokens na próxima solicitação para retomar a decodificação.
  • completed: a geração foi concluída naturalmente e continuation_token foi limpo.

Encadeamento, alternância de modo e armazenamento de segmentos

As solicitações de continuação na API Interactions aplicam as seguintes regras:

  • Continuação armazenada (store=true, padrão): transmita previous_interaction_id definido como o segmento id que emitiu o continuation_token junto com continuation_token e omita input (o segmento armazenado já contém a entrada de turno). Sempre pareie cada continuation_token com o previous_interaction_id do segmento que o emitiu. Transmitir um continuation_token em uma interação já completed retorna um erro HTTP 400.
  • Continuação sem estado (store=false): omita previous_interaction_id e reenvie o input original com continuation_token em cada segmento.
  • Alternar os modos store entre os segmentos: é possível alternar do modo armazenado (store=true) para o sem estado (store=false) no meio da decodificação omitindo previous_interaction_id e reenviando o input original com continuation_token. Não é possível mudar de sem estado (store=false) para armazenada (store=true) porque não há uma interação pai armazenada para previous_interaction_id.
  • Alternância e ramificação de modo em primeiro plano e background=true: as continuações armazenadas (store=true) podem alternar entre a execução em primeiro plano (background=false) e em segundo plano (background=true) em todos os segmentos, incluindo a retomada de uma interação background=true cancelada do checkpoint continuation_token (persistente após 32.768 tokens de saída) no modo em segundo plano ou em primeiro plano. Reutilizar os mesmos previous_interaction_id e continuation_token cria continuações ramificadas independentes.
  • Aplicação de limite de turno: iniciar um novo turno do usuário (previous_interaction_id com um novo input e sem continuation_token) em um segmento com o status requires_continuation ou incomplete retorna um erro HTTP 400. Termine de continuar a decodificação para completed ou ramifique sua próxima vez na interação mais recente de completed. Quando o segmento final chegar a completed, transmitir o id desse segmento final como previous_interaction_id vai reconstruir o histórico completo da conversa em todos os segmentos anteriores.
  • Consistência de parâmetros entre segmentos: alterar model, system_instruction ou declarações de função (tools) em um segmento de continuação retorna um erro HTTP 400. Mantenha thinking_level e as ferramentas integradas inalteradas em todos os segmentos (consulte Problemas conhecidos).
  • Comportamento de segmento único get, list e delete: no modo de primeiro plano (background=false), cada segmento é armazenado como um recurso Interaction separado (interactions.get(id) retorna apenas esse segmento, interactions.list() lista cada segmento separadamente e interactions.delete(id) exclui apenas esse segmento; ao excluir uma cadeia de segmentos, exclua na ordem inversa, do último segmento para trás). No SDK de IA generativa do Google com automatic_continuation=True (stream=False), interactions.create() mescla todos os segmentos no retorno e preenche interaction.continuation_ids com os IDs de segmento ordenados (terminando com interaction.id). Se um segmento posterior falhar, exceder um timeout numérico por chamada ou cair no meio do stream depois que o progresso tiver sido feito além de um ponto de verificação retomável, o SDK vai gerar ContinuationInterruptedError com partial_interaction, continuation_token, interaction_id e continuation_ids para que você possa retomar de continuation_token.

Regras de loop personalizado do GenerateContent

Em um loop de continuação GenerateContent personalizado, siga estas regras:

  • Defina max_output_tokens como um valor maior que 65.536 (streaming) ou 32.768 (não streaming) até 1.048.576 e reenvie os valores originais de contents, system_instruction e tools em cada solicitação de continuação, junto com o continuation_token mais recente (um campo de nível superior em GenerateContentRequest na REST ou em GenerateContentConfig no SDK de IA Generativa do Google).
  • Não anexe a saída parcial do modelo a contents nem envie um comando de acompanhamento pedindo que o modelo continue.
  • Continue o loop enquanto finish_reason for CONTINUATION e continuation_token estiver presente, mesmo que um segmento tenha gasto todos os 32.768 ou 65.536 tokens em raciocínio (parts: [{"text": ""}]). Se finish_reason for MAX_TOKENS quando continuation_token estiver presente, gere max_output_tokens na próxima solicitação.
  • Combine as partes acumuladas em uma única rodada model para o histórico de várias rodadas somente após STOP.

Contagem de tokens, compactação e armazenamento em cache implícito

A contabilização e o armazenamento em cache de tokens em segmentos de continuação funcionam da seguinte maneira:

  • Na API Interactions, as chamadas interactions.create() que não são de streaming com automatic_continuation=True e as interações background=true gerenciadas pelo servidor somam as contagens de tokens em todos os segmentos em usage (total_input_tokens, total_cached_tokens, total_output_tokens, total_thought_tokens, total_tokens), preservando a contagem de comandos do primeiro segmento em usage.initial_input_tokens. Em loops personalizados em primeiro plano e eventos interaction.completed transmitidos, o usage de cada segmento informa apenas o delta desse segmento. Portanto, some os campos usage em todos os segmentos para ver o total de tokens faturados.
  • No GenerateContent, o SDK de IA generativa do Google para Python (generate_content e generate_content_stream) acumula o total de tokens faturados em todos os segmentos no usage_metadata final e preserva initial_prompt_token_count. Em loops REST personalizados, some os valores finais de prompt_token_count, cached_content_token_count, candidates_token_count e thoughts_token_count em todos os segmentos.
  • Como cada segmento de continuação em primeiro plano preenche novamente a conversa e os tokens gerados anteriormente como entrada, usage.total_input_tokens (na API Interactions) e prompt_token_count (em GenerateContent) aumentam entre os segmentos. Não use contagens de entrada cumulativas para acionar a compactação de contexto em estruturas de agentes. Em vez disso, verifique usage.initial_input_tokens (ou initial_prompt_token_count em GenerateContent) e compacte somente após o término da rodada (status="completed" ou sem continuation_token).
  • Cada segmento de continuação preenche novamente o comando e os tokens decodificados anteriormente e recebe automaticamente o desconto de 95% de armazenamento em cache de contexto implícito (mínimo de 4.096 tokens) quando os segmentos são executados consecutivamente dentro do TTL de cache de 15 a 20 minutos. Os segmentos concluídos são faturados no final de cada segmento, mesmo que um segmento posterior falhe ou seja cancelado.

Migre do 3.1 Pro para o 4 Argon

O comportamento a seguir é diferente de gemini-3.1-pro-preview:

  • 4 O Argon tem um limite unificado de 1.048.576 tokens para entrada e saída (em que a saída inclui raciocínio, chamadas de função e a resposta final), em vez de limites separados para entrada e saída. A saída de solicitação única é limitada a 65.536 tokens ao fazer streaming (ou 32.768 tokens para solicitações em primeiro plano que não são de streaming) e pode ser estendida para até 1.048.576 tokens usando decodificações longas na API Interactions ou GenerateContent (processada automaticamente no SDK de IA generativa do Google, com background=true na API Interactions ou usando continuation_token em loops personalizados).
  • thinking_budget retorna um erro HTTP 400 em vez de ser mapeado para um nível de pensamento. MINIMAL também retorna um erro.
  • Não há suporte para o armazenamento em cache de contexto explícito.
  • Cada token processado pelo modelo é faturado, incluindo instruções internas do sistema de ferramentas e declarações de função ao usar o embasamento.

Para uma comparação lado a lado, consulte Migrar do Gemini 3.1 Pro.

 client = genai.Client(
     enterprise=True,
     project="PROJECT_ID",
     location="global", # Supports "global", "us", and "eu"
 )

 response = client.models.generate_content(
-    model="gemini-3.1-pro-preview",
+    model="gemini-4-argon",
     contents=prompt,
     config=types.GenerateContentConfig(
-        temperature=0.0,
-        cached_content="projects/.../cachedContents/...", # Explicit caching unsupported
         thinking_config=types.ThinkingConfig(
-            thinking_budget=16384, # Returns HTTP 400 instead of mapping silently
-            thinking_level="MINIMAL", # MINIMAL unsupported on Gemini 4 Argon
+            thinking_level="MEDIUM", # Valid: "LOW", "MEDIUM" (default), "HIGH"
         ),
     ),
 )

Para migrar do gemini-3.1-pro-preview, faça o seguinte:

  1. Atualize o ID do modelo para gemini-4-argon (ou gemini-4-argon-cyber-permissive para cargas de trabalho de cibersegurança aprovadas pelo Fairwind).
  2. Faça upgrade para o SDK de IA generativa do Google mais recente e considere o limite unificado de tokens de entrada e saída: faça upgrade para google-genai >= 2.34.0 (Python), @google/genai >= 2.32.0 (JavaScript/TypeScript), Go >= 1.77.0 ou Java >= 1.80.0 para a continuação automática da API Interactions (ou >= 2.30.1 Python / >= 2.29.1 JavaScript em GenerateContent). Os tokens de entrada e saída (incluindo pensamento e chamadas de função) compartilham o limite unificado de 1.048.576 tokens. Para saídas que excedem 65.536 tokens (até 1.048.576 tokens) na API Interactions ou GenerateContent, defina max_output_tokens como um valor maior que 65.536 para que o SDK de IA generativa do Google continue automaticamente entre os segmentos (ou use background=true ou um loop continuation_token personalizado).
  3. Substitua o parâmetro de limite de raciocínio: substitua thinking_budget e MINIMAL por thinking_level definido como LOW, MEDIUM (padrão em gemini-4-argon) ou HIGH (padrão em gemini-4-argon-cyber-permissive) (use "low", "medium" ou "high" em minúsculas na API Interactions).
  4. Remova o armazenamento em cache explícito e carregue o conteúdo estático do comando (4.096 tokens ou mais) para o armazenamento em cache implícito automático.
  5. Remova os parâmetros que não têm efeito ou não são compatíveis: remova os campos de geração ignorados e rejeitados da seguinte maneira:
    • Remova temperature, top_p e top_k, que são ignorados.
    • candidate_count, frequency_penalty e presence_penalty foram removidos.
    • Remova todos os turnos de modelo preenchidos automaticamente dos históricos de conversas.

Lista de verificação de resumo para desenvolvedores

Problemas conhecidos

Os seguintes problemas conhecidos se aplicam a 4 decodificações longas do Argon:

  • As decodificações longas exigem v1beta1: a decodificação longa (continuation_token) na API Interactions e na API GenerateContent (generateContent e streamGenerateContent) só é compatível com a API v1beta1 (não v1) na plataforma de agentes. O SDK de IA generativa do Google usa v1beta1 por padrão, a menos que api_version='v1' esteja definido em http_options (ou api_version="v1" em interactions.create). Para chamadas REST diretas, use o caminho do endpoint /v1beta1/.
  • Mudanças de parâmetros em segmentos de continuação da API Interactions: mudar model, system_instruction ou declarações de função em segmentos de continuação retorna um erro HTTP 400, enquanto mudanças no meio da decodificação em generation_config.thinking_level ou ferramentas integradas (google_search, code_execution, url_context) não são rejeitadas pela validação do servidor. Mantenha as ferramentas integradas e thinking_level inalteradas em todos os segmentos de um loop de continuação.

Outros recursos