Guia do desenvolvedor para o Gemini 4 Argon

O Gemini 4 Argon é o modelo de fronteira do Google que se destaca no trabalho aprofundado em tarefas complexas do mundo real em vários domínios, incluindo programação, finanças, jurídico, segurança cibernética 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 Introdução ao Gemini 4.

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 raciocínio, 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 ou 32.768 tokens para solicitações HTTP diretas não transmitidas) até 1.048.576 tokens (menos os tokens de entrada) em GenerateContent. O SDK de IA generativa do Google processa continuation_token automaticamente em todas as solicitações, ou você pode gerenciar continuation_token no seu próprio loop de continuação.
  • Níveis de raciocínio: LOW, MEDIUM (padrão em gemini-4-argon) e HIGH (padrão em 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 6.144 tokens ou mais, com o armazenamento em cache durável ativado por padrão. O armazenamento em cache de contexto explícito não é aceito.
  • Compreensão agêntica de vídeos: disponibilidade geral e desativada por padrão.

Guia de início rápido

Antes de começar, você precisa se autenticar na Agent Platform usando o Application Default Credentials (ADC) ou uma chave de API. Consulte Introdução à plataforma de agentes do Gemini Enterprise para mais informações.

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

Teste no Agent Studio

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

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

Instalação

Faça upgrade para o SDK de IA generativa do Google mais recente (google-genai >= 2.30.1 para Python, @google/genai >= 2.29.1 para JavaScript, >= 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.30.1"

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)

Decodificações longas

Por padrão, uma única solicitação de API gera até 65.536 tokens de saída (ou 32.768 tokens para solicitações HTTP diretas não transmitidas), em que a saída inclui raciocínio, chamadas de função e a resposta final. Para gerar conclusões de até 1.048.576 tokens em GenerateContent (v1beta1), defina max_output_tokens como maior que 65.536 para solicitações de streaming ou maior que 32.768 para solicitações não transmitidas (até 1.048.576). O SDK de IA generativa do Google segue automaticamente continuation_token em todas as solicitações quando finish_reason é CONTINUATION (defina automatic_continuation=False em GenerateContentConfig para desativar a continuação automática) 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_FROM_REQUEST_1",
    "generationConfig": {
      "maxOutputTokens": 131072,
      "thinkingConfig": {"thinkingLevel": "HIGH"}
    }
  }'

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

O Gemini 4 Argon aplica as seguintes convenções:

  • Níveis de raciocínio: o 4 Argon oferece suporte a três thinking_level valores (thinking_budget e MINIMAL retornam um erro de validação HTTP 400):

    Nível de pensamento Cargas de trabalho recomendadas
    HIGH (padrão em gemini-4-argon-cyber-permissive) Engenharia de software com 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 de documentos e compreensão de vídeos.
    LOW Classificação, resumo e extração de metadados.

  • Limite unificado de tokens de entrada e saída e limites de saída de solicitação única:

    • 1,048,576 é o limite geral de tokens do modelo 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 de saída de solicitação única padrão (raciocínio + resposta do modelo) é de 65.536 tokens (ou 32.768 tokens para solicitações HTTP diretas não transmitidas).

  • Decodificações longas:

    • Como a decodificação longa funciona: a decodificação longa divide uma geração de até 1.048.576 tokens em várias inferências GenerateContent. Por exemplo, se uma tarefa exigir 256.000 tokens de saída (incluindo pensamentos, chamadas de função e a resposta final), a primeira solicitação de streaming vai gerar até 65.536 tokens de saída e emitir finish_reason=CONTINUATION com um continuation_token criptografado contendo um hash do comando original e o estado de geração até esse ponto. Incluir continuation_token em solicitações subsequentes com o comando original continua a geração de onde ela parou até que continuation_token não seja mais emitido e finish_reason=STOP. No Agent Studio, definir o limite de tokens de saída maior que 65.536 até 1.048.576 processa tokens de continuação automaticamente.
    • Quando usar a decodificação longa: a maioria das solicitações termina dentro do limite por solicitação (65.536 tokens ou 32.768 tokens para chamadas REST não transmitidas). Use a decodificação longa apenas quando uma resposta precisar de mais saída do que isso. A decodificação longa oferece mais espaço para o modelo raciocinar. Ela 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 Sim O modelo pode gastar mais de 65.536 tokens para explorar e verificar o raciocínio.
    As tarefas de programação e agênticas mais difíceis Sim Algumas tarefas precisam de mais de 65.536 tokens de raciocínio e código em uma resposta. A maioria das tarefas de programação e agênticas termina com menos de 65.536 tokens.
    Aproveitamentos 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 terminam bem abaixo de 32.768 tokens.
    Solicitações de um comprimento fixo, como "escreva um livro de 700.000 palavras" Não O modelo não segue metas de comprimento.
    Agentes que chamam ferramentas em muitas rodadas curtas Não Cada rodada é curta. Grandes saídas em cada rodada preenchem rapidamente o limite unificado de entrada e saída de 1.048.576 tokens.
    Comandos próximos ao limite de entrada de 1.048.576 tokens Não A saída só pode usar 1.048.576 tokens menos a entrada.
    Solicitações sensíveis à latência Não A decodificação longa pode ser executada por vários minutos.
    • Escolher uma opção de continuação: escolha uma das duas opções. A maioria dos desenvolvedores usa a opção 1. Todas as opções atingem o mesmo limite de 1.048.576 tokens em gemini-4-argon e gemini-4-argon-cyber-permissive.
    Dimensão Opção 1: SDK de IA generativa do Google (recomendado) Opção 2: seu próprio loop de streaming (streamGenerateContent) Opção 2: seu próprio loop não transmitido (generateContent)
    Quem inicia cada segmento SDKs de IA generativa do Google: Python (google-genai) 2.30.1, JavaScript (@google/genai) 2.29.1, Go 1.74.0, Java 1.77.0, .NET 1.26.0 e Kotlin 1.6.0. Você define max_output_tokens. Seu código, em cada ponto de verificação ou após um stream descartado Seu código, a cada 32.768 tokens
    Tokens por solicitação Até 65.536 por segmento 65.536 por stream, com um ponto de verificação a cada 5.000 tokens após 32.768 32.768 por solicitação
    Limite de tempo por solicitação 20 minutos 20 minutos 20 minutos
    Armazenamento Sem armazenamento no servidor (compatível com ZDR) Sem armazenamento no servidor (compatível com ZDR) Sem armazenamento no servidor (compatível com ZDR)
    Ideal para A maioria dos aplicativos Chamadores REST e aproveitamentos personalizados que transmitem Aproveitamentos de avaliação simples
    • Regras e limitações de implementação:
      • v1beta1 requisito da API (problema conhecido): a decodificação longa (continuation_token) em GenerateContent (generateContent e streamGenerateContent) é aceita apenas na API v1beta1 (não v1). O SDK de IA generativa do Google usa v1beta1 por padrão, a menos que api_version='v1' seja especificado em http_options; para chamadas REST diretas, use o caminho do endpoint v1beta1. A decodificação longa não é aceita na API Interactions.
      • Versões do SDK e compatibilidade com a OpenAI: faça upgrade para o SDK de IA generativa do Google mais recente (google-genai >= 2.30.1 para Python, @google/genai >= 2.29.1 para JavaScript, >= 1.74.0 para Go, >= 1.77.0 para Java, >= 1.26.0 para .NET ou >= 1.6.0 para Kotlin). Versões mais antigas do SDK e a camada de compatibilidade com a OpenAI não podem recuperar conclusões longas usando tokens de continuação. Para implementações de clientes personalizados, consulte as implementações de referência do SDK de IA generativa do Google em Python e JavaScript/TypeScript.
      • Reenvie a solicitação original com continuation_token: em um loop personalizado, defina max_output_tokens como maior que 65.536 (streaming) ou 32.768 (unário) até 1.048.576 e reenvie o contents, system_instruction e tools originais em cada solicitação de continuação, juntamente com o continuation_token mais recente (um campo de nível superior em GenerateContentRequest no 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 com solicitações somente de raciocínio: faça um loop enquanto finish_reason for CONTINUATION e continuation_token estiver presente, mesmo que uma solicitação tenha gasto todos os 32.768 ou 65.536 tokens pensando (parts: [{"text": ""}]). Se finish_reason for MAX_TOKENS quando continuation_token estiver presente, a geração atingiu o limite de max_output_tokens solicitado. Aumente max_output_tokens na solicitação. Combine as partes acumuladas em uma única rodada de model para o histórico multiturno somente após STOP.
      • Contagem de tokens, compactação e desconto de cache implícito de 95%:
        • No SDK de IA generativa do Google para Python (generate_content e generate_content_stream), o usage_metadata da resposta final ou do bloco acumula o total de tokens faturados em solicitações de continuação. Como cada solicitação de continuação preenche novamente as conclusões parciais anteriores como tokens de entrada, prompt_token_count aumenta cumulativamente em todas as solicitações de continuação. Não use prompt_token_count para acionar a compactação de contexto em estruturas de agentes. Em vez disso, leia initial_prompt_token_count (em GenerateContentResponse ou usage_metadata) e aguarde até que GenerateContent seja concluído (nenhum continuation_token presente) antes de compactar.
        • Em loops REST personalizados, usage_metadata é cumulativo em cada solicitação. Some o prompt_token_count, cached_content_token_count, candidates_token_count e thoughts_token_count finais em todas as solicitações.
        • Cada solicitação de continuação preenche novamente o comando mais os tokens decodificados anteriores e recebe automaticamente o desconto de armazenamento em cache de contexto implícito de 95% (mínimo de 6.144 tokens) quando as solicitações são executadas consecutivamente no TTL de cache de 15 a 20 minutos.
        • streamGenerateContent e generateContent retornam usage_metadata no final de cada solicitação (65.536 streaming / 32.768 unário), e o faturamento ocorre no final da solicitação.

  • 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): eles retornam um erro de HTTP 400. Remova-os das suas solicitações.

  • Armazenamento em cache de contexto: o armazenamento em cache de contexto explícito não é aceito. O armazenamento em cache implícito (com o armazenamento em cache durável ativado por padrão) é aplicado automaticamente a prefixos de comandos compartilhados de 6.144 tokens ou mais. Portanto, coloque conteúdo estático no início do comando.

  • Vídeo agêntico: os vídeos enviados são definidos como media_processing="static" por padrão. Defina media_processing="agentic" para ativar o processamento de vídeo agêntico.

  • Contagem e faturamento de tokens: cada token processado pelo modelo é contado e faturado, incluindo tokens de raciocínio e instruções internas do sistema de ferramentas e declarações de função ao usar o embasamento. O embasamento com a Pesquisa Google também continua sendo faturado por consulta.

  • Chamadas de função:

    • Simetria de rodada: cada FunctionResponse precisa corresponder ao id, name, e ordem do FunctionCall anterior.
    • Execução sequencial: prefira rodadas de execução de ferramentas sequenciais 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 chat:

    • Os payloads de histórico não podem terminar com uma rodada de função model.
    • Turnos de modelo preenchidos automaticamente não são aceitos.

Migrar para o 4 Argon do 3.1 Pro

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

  • O 4 Argon tem um limite unificado de 1.048.576 tokens na entrada e na saída (em que a saída inclui raciocínio, chamadas de função e a resposta final), em vez de limites de entrada e saída separados. A saída de solicitação única é limitada a 65.536 tokens (ou 32.768 tokens para solicitações HTTP diretas não transmitidas) e pode ser estendida até 1.048.576 tokens usando decodificações longas em GenerateContent (processadas automaticamente no SDK de IA generativa do Google ou usando continuation_token em loops personalizados).
  • thinking_budget retorna um erro HTTP 400 em vez de ser mapeado para um nível de raciocínio. MINIMAL também retorna um erro.
  • O armazenamento em cache de contexto explícito não é aceito.
  • 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 de 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.30.1 (Python), @google/genai >= 2.29.1 (JavaScript) ou o SDK de IA generativa do Google mais recente equivalente. Os tokens de entrada e saída (incluindo raciocínio e chamadas de função) compartilham o limite unificado de 1.048.576 tokens. Para saídas que excedam 65.536 tokens (até 1.048.576 tokens) em GenerateContent, defina max_output_tokens como maior que 65.536 para que o SDK de IA generativa do Google continue automaticamente em todas as solicitações (ou processe continuation_token no seu próprio loop REST).
  3. Substitua o parâmetro de orçamento 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).
  4. Remova o armazenamento em cache explícito e carregue o conteúdo estático do comando (6.144 tokens ou mais) para o armazenamento em cache implícito automático.
  5. Remova parâmetros que não têm efeito ou não são aceitos:
    • Remova temperature, top_p e top_k, que são ignorados.
    • Remova candidate_count, frequency_penalty e presence_penalty.
    • Remova todos os turnos de modelo preenchidos automaticamente dos históricos de conversas.

Lista de verificação de resumo para desenvolvedores

Problemas conhecidos

  • Decodificações longas em GenerateContent exigem v1beta1: a decodificação longa (continuation_token) na API GenerateContent (generateContent e streamGenerateContent) é aceita apenas na API v1beta1 (não v1). O SDK de IA generativa do Google usa v1beta1 por padrão, a menos que api_version='v1' seja definido em http_options; para chamadas REST diretas, use o caminho do endpoint v1beta1.

Outros recursos