O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

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

Janela de contexto: a janela de contexto de 1.048.576 tokens é compartilhada entre tokens de entrada, pensamento e saída.
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 para solicitações de streaming ou 32.768 tokens para solicitações HTTP diretas não transmitidas) até 1.048.576 tokens 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, autentique-se 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.

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

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

response = client.models.generate_content(
  model="gemini-4-argon",
  contents="How does AI work?",
)
print(response.text)

Python (API Interactions)

from google import genai

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

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)

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 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": "Why is the sky blue?" }
  }
}'

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 pensamento e saída (ou 32.768 tokens para solicitações HTTP diretas não transmitidas). Para gerar conclusões de até 1.048.576 tokens no GenerateContent (v1beta1), defina max_output_tokens como maior que 65.536 (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
# and stop at a single request.
single_request_response = client.models.generate_content(
    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(single_request_response.text)

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 comportamentais

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

Janela de contexto e limites de saída de solicitação única:
- A janela de contexto de 1.048.576 tokens é compartilhada entre tokens de entrada, pensamento e saída. Definir max_output_tokens 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 (pensamento + 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. Quando uma solicitação atinge o limite de saída por solicitação antes de terminar, a API retorna finish_reason=CONTINUATION e um continuation_token criptografado contendo um hash do comando original e o estado de geração até esse ponto. Inclua continuation_token em solicitações subsequentes com o comando original 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 os 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). 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 difíceis	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 pensamento 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 pensamento.
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 "escrever um livro de 700.000 palavras"	Não	O modelo não segue metas de comprimento.
Agentes que chamam ferramentas em muitos turnos curtos	Não	Cada turno é curto. Grandes saídas em cada turno preenchem rapidamente a janela compartilhada 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.

Como escolher uma opção de continuação: 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	O SDK (`automatic_continuation=True` por padrão). Defina `max_output_tokens` maior que 65.536 (até 1.048.576) para saídas acima de 65.536 tokens.	Seu código, em cada ponto de verificação ou após um fluxo descartado	Seu código, a cada 32.768 tokens
Tokens por solicitação	Até 65.536 por segmento	65.536 por fluxo	32.768 por solicitação
Limite de tempo por solicitação	20 minutos	20 minutos	20 minutos
Armazenamento e ZDR	Sem armazenamento do servidor (compatível com ZDR)	Sem armazenamento do servidor (compatível com ZDR)	Sem armazenamento do 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 a implementação de referência do SDK de IA generativa do Google .
- Reenviar a solicitação original com continuation_token: em um loop personalizado, defina max_output_tokens maior que 65.536 (streaming) ou 32.768 (unário) até 1.048.576, e reenvie os contents, system_instruction e tools originais em cada solicitação de continuação junto 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 pensamento: 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 um único turno 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 ou do bloco final 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 e 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 continuation_token e 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 de tokens e faturamento: cada token processado pelo modelo é contado e faturado, incluindo tokens de raciocínio e instruções e declarações de função do sistema de ferramentas internas ao usar o embasamento. O embasamento com a Pesquisa Google também continua sendo faturado por consulta.
Chamadas de função:
- Simetria de turno: cada FunctionResponse precisa corresponder ao id, name, e ordem do FunctionCall anterior.
- Execução sequencial: prefira turnos 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.
Validação da sequência de chat:
- Os payloads de histórico não podem terminar com um turno de função model.
- Os 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:

A janela de contexto é uma janela de 1.048.576 tokens compartilhada por entrada, pensamento e saída, 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 pensamento. 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 do sistema de ferramentas internas e declarações de função ao usar o embasamento.

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

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

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).
Faça upgrade para o SDK de IA generativa do Google mais recente e considere a janela de contexto compartilhada: faça upgrade para google-genai >= 2.30.1 (Python) ou o SDK de IA generativa do Google mais recente equivalente. Os tokens de entrada, pensamento e saída compartilham a janela de contexto de 1.048.576 tokens. Para saídas que excedam 65.536 tokens (até 1.048.576 tokens) em GenerateContent, defina max_output_tokens 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).
Substitua o parâmetro de orçamento de raciocínio: substitua thinking_budget e MINIMAL por thinking_level definido como um dos seguintes valores:
- 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 de documentos e compreensão de vídeos.
- LOW: classificação, resumo e extração de metadados.
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.
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

ID do modelo de destino: gemini-4-argon (ou gemini-4-argon-cyber-permissive para projetos aprovados pelo Fairwind) e faça upgrade para o SDK de IA generativa do Google mais recente (Python google-genai >= 2.30.1, JS @google/genai >= 2.29.1, Go >= 1.74.0, Java >= 1.77.0, .NET >= 1.26.0, Kotlin >= 1.6.0)

Local: global, us ou eu

Orçamento para uma janela de contexto de 1.048.576 tokens (compartilhada entre tokens de entrada, pensamento, e saída) e um limite de saída de solicitação única de 65.536 tokens (32.768 tokens para chamadas HTTP diretas não transmitidas) ou defina max_output_tokens até 1.048.576 em GenerateContent para decodificações longas.

Use thinking_level (MEDIUM por padrão em gemini-4-argon, HIGH por padrão em gemini-4-argon-cyber-permissive; valores válidos: LOW, MEDIUM, HIGH). Remova thinking_budget e MINIMAL.

Remova os seguintes parâmetros: frequency_penalty, presence_penalty, candidate_count, temperature, top_p e top_k.

Remova todos os turnos de modelo preenchidos automaticamente dos históricos de solicitações de conversa multiturno.

Remova as chamadas de armazenamento em cache explícito e coloque o conteúdo estático do comando (6.144 tokens ou mais) primeiro para o armazenamento em cache implícito.

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.