Gemini 2.5 Acaba: Migra Para o 4 Argon em 12 Passos

A Google confirmou uma data que obriga milhares de equipas de engenharia a agir: o Gemini 2.5 Pro, o Gemini 2.5 Flash e o Gemini 2.5 Flash-Lite deixam de estar disponíveis a 20 de outubro de 2026, segundo a documentação oficial da Google Cloud. Quem ainda tem código em produção a chamar esses modelos tem uma janela curta para migrar antes que os pedidos à API comecem a falhar. Este tutorial mostra, passo a passo, como mover uma aplicação real do Gemini 2.5 para o Gemini 4 Argon e para o Gemini 3.8 Flash, os dois sucessores que a Google já lista como disponíveis.

Vamos construir um projeto funcional do zero: chave de API, SDK atualizado, camada de routing entre modelos, migração de function calling e um plano de testes para não quebrar nada no dia do corte. No final, tens um script completo pronto para adaptar ao teu próprio produto.

Se geres uma equipa de engenharia, vale pensar nesta migração como um projeto com prazo fixo, não como uma tarefa de manutenção que se arrasta na lista de pendências. Datas de aposentadoria de modelos de IA costumam ser anunciadas com meses de antecedência, mas acabam tratadas como “para depois” até à última semana, quando qualquer imprevisto (uma dependência de SDK desatualizada, um teste automatizado que não previa o novo formato de resposta) já não tem tempo de ser resolvido com calma. Trata este guia como uma checklist que podes correr já esta semana, não no dia 19 de outubro.

Porque a migração do Gemini 2.5 é urgente agora

A Google não deixou margem para ambiguidade: a página oficial de versões de modelos da plataforma Gemini Enterprise Agent marca 20 de outubro de 2026 como a data de fim de vida do Gemini 2.5 Pro, do Gemini 2.5 Flash e do Gemini 2.5 Flash-Lite. A própria Google recomenda, na mesma documentação, que quem ainda depende desses modelos migre para gerações mais recentes antes da aposentadoria. Isto não é um aviso vago de “legacy” sem prazo. É uma data fixa, já publicada.

O que torna este momento particular é que a Google não substituiu o Gemini 2.5 por um único modelo. Substituiu-o por uma família nova com papéis diferentes. O Gemini 4 Argon assume o lugar de modelo principal, focado em raciocínio profundo em tarefas complexas e de longa duração, segundo a apresentação da Google e a página de modelos da DeepMind. O Gemini 3.8 Flash já aparece disponível na documentação da API Gemini, atualizada a 9 de outubro de 2026, como a opção rápida para cargas de trabalho de baixa latência. Há ainda o Gemini 3.5 Flash-Lite, lançado a 21 de julho de 2026 e com suporte previsto até, pelo menos, 21 de julho de 2027, para tarefas simples e de alto volume.

Uma curiosidade que vale notar antes de começares: a cobertura de outubro indica que a Google decidiu não lançar o modelo “Gemini 3.5 Pro” que era esperado pelo mercado. Em vez disso, o Gemini 4 Argon ocupa diretamente esse espaço, descrito como maior do que a antiga linha Pro. Isto significa que, se o teu código espera um salto incremental de “2.5 para 3.5”, vais encontrar uma geração à frente do que talvez estivesses a planear.

Gemini 4 Argon vs Gemini 3.8 Flash vs Gemini 2.5: tabela comparativa

Antes de tocar em código, vale organizar o que muda entre gerações. A tabela seguinte resume o estado de cada modelo em outubro de 2026, com base na documentação oficial da Google e da DeepMind.

Modelo	Estado em outubro de 2026	Foco declarado pela Google	Data-chave
Gemini 2.5 Pro	Aposentado a 20/10/2026	Raciocínio avançado, geração anterior	Fim de vida: 20 out 2026
Gemini 2.5 Flash	Aposentado a 20/10/2026	Uso geral rápido, geração anterior	Fim de vida: 20 out 2026
Gemini 2.5 Flash-Lite	Aposentado a 20/10/2026	Tarefas simples e leves	Fim de vida: 20 out 2026
Gemini 3.5 Flash-Lite	Ativo	Sucessor leve, alto volume	Lançado 21 jul 2026
Gemini 3.8 Flash	Ativo	Respostas rápidas, baixa latência	Documentado a 9 out 2026
Gemini 4 Argon	Ativo, modelo principal	Raciocínio profundo em workflows longos	Listado na página de modelos DeepMind

Para quem compara com o ecossistema aberto, vale ainda a referência do Mistral Large 4, lançado em outubro de 2026 como modelo multimodal MoE com cerca de 1 bilião de parâmetros totais e aproximadamente 52 mil milhões de parâmetros ativos por token, com contexto de 1 milhão de tokens, segundo o acompanhamento de lançamentos de IA do mês. Não é um substituto direto do Gemini, mas serve de referência de escala para quem está a decidir entre API gerida e modelos abertos na mesma migração.

Repara que a tabela separa dois tipos de mudança que costumam ser confundidos numa migração apressada: a aposentadoria pura e simples (as três linhas do Gemini 2.5, que vão deixar de responder a partir de 20 de outubro) e a introdução de capacidades novas (o Gemini 4 Argon, que não é apenas “mais um modelo”, mas sim uma mudança de categoria no tipo de tarefa que a Google o posiciona para resolver). Tratar a migração só como uma troca de nome de modelo ignora essa segunda parte, e é precisamente aí que a maioria dos problemas de comportamento inesperado surge depois do deploy.

Pré-requisitos e versões necessárias

Este tutorial assume um ambiente de desenvolvimento Python, mas os mesmos passos aplicam-se a Node.js com pequenas adaptações de sintaxe. Antes de avançar, confirma que tens:

Python 3.10 ou superior (ou Node.js 18 LTS ou superior, se preferires JavaScript)
Uma chave de API Gemini válida, obtida no Google AI Studio
O SDK oficial google-genai na versão mais recente disponível no PyPI
Acesso ao código fonte da aplicação atual que ainda chama o Gemini 2.5
Uma conta de faturação ativa na Google Cloud, se usares a via Vertex AI em vez da API pública
Um ambiente de testes isolado da produção, para validar a migração sem risco

Um aviso importante antes de escreveres uma linha de código: os nomes “Gemini 4 Argon” e “Gemini 3.8 Flash” são os nomes de apresentação usados pela Google e pela DeepMind. O identificador exato que vais escrever no parâmetro model= da chamada à API pode diferir ligeiramente (por exemplo, usar um sufixo de versão ou uma data). Confirma sempre o identificador atual na página oficial de modelos da Gemini API antes de colocar código em produção. Os exemplos abaixo usam um identificador ilustrativo que deves validar no teu próprio painel.

API Gemini vs Vertex AI: qual via escolher para a migração

Antes de escolheres o caminho de migração, decide por qual via vais aceder aos modelos novos. A Google oferece duas portas de entrada diferentes para a mesma família de modelos, e a escolha afeta diretamente como vais gerir chaves, faturação e limites de utilização.

A primeira via é a API pública do Gemini, acedida através de uma chave de API gerada no Google AI Studio. É a opção mais simples para projetos pequenos, protótipos ou aplicações que já usavam esta via com o Gemini 2.5. A segunda via é o Vertex AI, dentro da Google Cloud, pensada para equipas que já têm um projeto GCP com faturação, gestão de identidade (IAM) e integração com outros serviços da nuvem, como Cloud Run ou BigQuery.

Se a tua aplicação atual já corre dentro da Google Cloud, migrar via Vertex AI costuma trazer vantagens de governação: controlo de acesso mais granular, quotas por projeto e integração nativa com os logs do Cloud Logging. Se o teu caso de uso é mais simples ou corre fora da infraestrutura da Google, a API pública com chave direta continua a ser o caminho com menos atrito. Este tutorial usa a API pública nos exemplos de código por ser a via mais acessível para reproduzir localmente, mas a lógica de routing e fallback dos próximos passos aplica-se de igual forma às duas vias, só muda a forma como inicializas o cliente.

Passo 1 e 2: criar a chave de API e preparar o ambiente

Começa por gerar (ou confirmar) a tua chave de API no Google AI Studio. Se já tens uma aplicação em produção com Gemini 2.5, provavelmente já tens uma chave, mas vale a pena criar uma nova chave só para o processo de migração, para conseguires isolar o tráfego de testes do tráfego real nos logs da Google Cloud.

Cria um ambiente virtual limpo e um ficheiro .env para guardar a chave fora do código fonte:

python3 -m venv venv-migracao
source venv-migracao/bin/activate

# cria o ficheiro .env na raiz do projeto
cat > .env << 'EOF'
GEMINI_API_KEY=coloca_aqui_a_tua_chave
EOF

echo ".env" >> .gitignore

Nunca comites a chave de API ao repositório. Se trabalhas em equipa, usa um gestor de segredos (Secret Manager da Google Cloud, Doppler ou Vault) em vez de distribuir o ficheiro .env por email ou chat.

Passo 3 e 4: atualizar o SDK e auditar o código legado

Com o ambiente pronto, instala a versão mais recente do SDK google-genai. Se o teu projeto ainda usa o SDK antigo google-generativeai, este é o momento certo para migrar também o SDK, não só o modelo.

pip install -U google-genai python-dotenv

# procura todas as referências ao Gemini 2.5 no teu projeto
grep -rn "gemini-2.5" --include="*.py" .
grep -rn "gemini-2.5" --include="*.js" --include="*.ts" .

O comando grep acima é propositadamente simples: o objetivo é listar todos os ficheiros que precisam de alteração antes de começares a editar. Em projetos maiores, exporta este resultado para um ficheiro de texto e transforma-o numa checklist de migração, com uma linha por ficheiro e uma coluna para marcar “migrado” à medida que avanças.

Presta atenção especial a três tipos de ficheiro durante a auditoria: configuração de ambiente (variáveis que fixam o nome do modelo), código de infraestrutura como Terraform ou manifests Kubernetes que referenciam o modelo em texto plano, e testes automatizados que fazem mock de respostas do Gemini 2.5. Os três costumam ficar esquecidos numa migração apressada.

Passo 5: migrar a primeira chamada para o Gemini 4 Argon

Antes de qualquer alteração, guarda o comportamento atual do Gemini 2.5 como referência. Este snippet representa uma chamada típica que hoje corre em produção:

from google import genai
import os
from dotenv import load_dotenv

load_dotenv()
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

# chamada atual, ainda em Gemini 2.5
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Resume este relatório financeiro em três frases."
)
print(response.text)

A migração em si costuma ser trivial em código, mas arriscada em comportamento. Troca apenas o identificador do modelo e corre o mesmo conjunto de prompts de teste, comparando as respostas lado a lado:

response = client.models.generate_content(
    model="gemini-4-argon",  # confirma o identificador exato na documentação
    contents="Resume este relatório financeiro em três frases."
)
print(response.text)

Não assumas que a resposta vai ter o mesmo tom, extensão ou formato. O Gemini 4 Argon foi apresentado pela Google com foco declarado em raciocínio profundo para fluxos de trabalho complexos e longos, o que pode produzir respostas mais elaboradas do que o Gemini 2.5 Flash entregava para o mesmo prompt simples. Se o teu produto depende de respostas curtas e previsíveis, vais precisar de ajustar o prompt, não só o nome do modelo.

Passo 6: ajustar prompts para raciocínio longo

Modelos orientados a raciocínio profundo tendem a beneficiar de instruções mais explícitas sobre o formato de saída desejado. Se o teu caso de uso é resumo, extração de dados ou classificação, ganha o hábito de fixar o formato no próprio prompt em vez de confiar no estilo “natural” do modelo anterior.

Um exemplo prático: em vez de “Resume este relatório em três frases”, passa a escrever “Resume este relatório em exatamente três frases, sem introdução nem conclusão, apenas os três pontos numerados”. Esta mudança reduz a variação entre respostas do Gemini 2.5 e do Gemini 4 Argon, porque força os dois modelos a convergir para a mesma estrutura, independentemente de quão mais elaborado seja o raciocínio interno do novo modelo.

Se a tua aplicação lida com documentos longos, revisita também a estratégia de chunking. Não assumas que a janela de contexto do Gemini 4 Argon é idêntica à do Gemini 2.5 Pro só porque ambos pertencem a uma linha “Pro-like”. Confirma o limite atual na documentação oficial antes de remover lógica de divisão de texto que já tinhas implementada, porque um limite mal calculado só se revela em produção, quando um documento real excede o esperado.

Passo 7: adicionar o Gemini 3.8 Flash para respostas rápidas

Nem toda a tua aplicação precisa de raciocínio profundo. Para endpoints com exigência de baixa latência (autocomplete, moderação em tempo real, respostas de chat curtas), o Gemini 3.8 Flash, já listado como disponível na documentação oficial atualizada a 9 de outubro de 2026, é o caminho mais direto.

response = client.models.generate_content(
    model="gemini-3.8-flash",  # confirma o identificador exato na documentação
    contents="Classifica este comentário como positivo, negativo ou neutro. Responde só com a palavra.",
    config={"max_output_tokens": 10}
)
print(response.text.strip())

Repara no parâmetro max_output_tokens baixo: para tarefas de classificação ou extração curta, limitar o tamanho da resposta reduz custo e latência sem sacrificar qualidade. É uma otimização que vale a pena revisitar durante a migração, porque muitas aplicações antigas nunca tinham esse limite definido.

Passo 8: construir uma camada de routing entre modelos

A maioria das aplicações reais não usa um único modelo para tudo. Faz mais sentido construir uma função de routing que decide, por tarefa, se deve chamar o Gemini 4 Argon (quando a tarefa exige raciocínio longo) ou o Gemini 3.8 Flash (quando a prioridade é velocidade). Isto também facilita o rollback: se um dos modelos tiver um problema, basta ajustar a função de routing, sem tocar no resto da aplicação.

def escolher_modelo(tarefa: str, complexidade: str = "normal") -> str:
    """Escolhe o modelo Gemini certo com base no tipo de tarefa."""
    tarefas_rapidas = {"classificacao", "moderacao", "autocomplete"}

    if tarefa in tarefas_rapidas and complexidade != "alta":
        return "gemini-3.8-flash"
    return "gemini-4-argon"


def gerar_resposta(client, tarefa, prompt, complexidade="normal"):
    modelo = escolher_modelo(tarefa, complexidade)
    try:
        resposta = client.models.generate_content(model=modelo, contents=prompt)
        return resposta.text, modelo
    except Exception as erro:
        # fallback para o modelo rápido se o principal falhar
        if modelo != "gemini-3.8-flash":
            resposta = client.models.generate_content(
                model="gemini-3.8-flash", contents=prompt
            )
            return resposta.text, "gemini-3.8-flash (fallback)"
        raise erro

Esta estrutura, mesmo simples, já resolve dois problemas de uma vez: separa a lógica de negócio da escolha de modelo e dá-te um ponto único de fallback caso um dos modelos tenha indisponibilidade pontual durante a transição.

Passo 9: migrar function calling e ferramentas

Se a tua aplicação usa function calling (tool use) para ligar o modelo a bases de dados, APIs internas ou cálculos, este é o ponto onde a migração costuma dar mais trabalho. O esquema de declaração de funções geralmente mantém compatibilidade entre gerações do SDK, mas o comportamento do modelo ao decidir quando chamar uma função pode mudar.

from google.genai import types

ferramenta_stock = types.Tool(
    function_declarations=[
        types.FunctionDeclaration(
            name="consultar_stock",
            description="Consulta a quantidade em stock de um produto pelo SKU",
            parameters={
                "type": "object",
                "properties": {"sku": {"type": "string"}},
                "required": ["sku"],
            },
        )
    ]
)

response = client.models.generate_content(
    model="gemini-4-argon",
    contents="Quanto stock temos do produto SKU-4521?",
    config=types.GenerateContentConfig(tools=[ferramenta_stock]),
)

if response.function_calls:
    for chamada in response.function_calls:
        print(chamada.name, chamada.args)

Testa cada ferramenta isoladamente depois da migração, com pelo menos dez variações do mesmo pedido em linguagem natural. Modelos diferentes têm sensibilidades diferentes à forma como o pedido é escrito, e uma ferramenta que era chamada de forma fiável no Gemini 2.5 pode exigir uma descrição mais explícita para ser chamada com a mesma fiabilidade no modelo novo.

Vale também rever o número de ferramentas que passas numa única chamada. Se a tua aplicação acumulou, ao longo do tempo, uma dezena de funções diferentes disponíveis ao mesmo tempo para o Gemini 2.5, confirma se essa mesma quantidade continua a funcionar bem com o modelo novo antes de assumires que sim. Em aplicações com muitas ferramentas, divide-as por contexto de conversa sempre que possível, passando ao modelo só as funções relevantes para aquele pedido específico, em vez do catálogo completo. Isto tende a melhorar a taxa de acerto em qualquer geração de modelo, não é uma particularidade desta migração, mas é um bom momento para rever se essa prática já está implementada no teu código.

Passo 10: gerir tokens, contexto e custos

Uma migração de modelo é também uma boa oportunidade para rever custos. Antes de assumires que o novo modelo vai custar o mesmo (ou menos) que o Gemini 2.5, mede o consumo real de tokens em ambiente de teste durante pelo menos uma semana de tráfego representativo.

Item a verificar	Porque importa	Como medir
Tokens de entrada médios	Prompts mais elaborados para raciocínio longo consomem mais tokens	Logar `usage_metadata` de cada resposta
Tokens de saída médios	Respostas mais detalhadas aumentam custo por chamada	Comparar com baseline do Gemini 2.5
Taxa de chamadas a ferramentas	Cada function call pode gerar uma ronda extra de tokens	Contar chamadas por sessão
Latência p95	Raciocínio mais profundo pode aumentar tempo de resposta	Medir com logging estruturado em produção de teste
Taxa de erro/fallback	Indica instabilidade durante a transição	Monitorizar a camada de routing do Passo 8

Guarda estes números antes e depois da migração num mesmo painel. Sem essa comparação direta, qualquer decisão sobre custos depois do corte de 20 de outubro vai ser feita no escuro.

Passo 11 e 12: testar em paralelo, publicar e monitorizar

Com o código migrado, não faças um corte direto de produção. Corre os dois caminhos em paralelo durante alguns dias: envia o mesmo pedido real para o Gemini 2.5 (enquanto ainda está disponível) e para o modelo novo, grava as duas respostas, mas só mostra ao utilizador final a resposta do modelo antigo. Isto dá-te um conjunto de dados real para comparar qualidade sem arriscar a experiência do utilizador.

Depois de validares um volume razoável de comparações, faz um rollout gradual: começa por direcionar 5% do tráfego real para o modelo novo, sobe para 25%, depois 50%, e só avanças para 100% quando as métricas de erro e latência estiverem estáveis. Mantém o código do Gemini 2.5 disponível (mesmo que não seja chamado) até ao dia 20 de outubro, como plano de recuo rápido se algo correr mal com o rollout.

Depois do corte, remove o código legado do Gemini 2.5 definitivamente. Código morto que aponta para um modelo desativado não serve de rede de segurança, só de confusão para quem herdar o projeto mais tarde.

Durante o período de rollout gradual, regista cada decisão de routing com detalhe suficiente para reconstruíres o que aconteceu, caso precises de investigar um incidente depois. Um log estruturado em JSON, em vez de texto livre, facilita filtrar por modelo, tarefa ou percentagem de rollout mais tarde num painel do Cloud Logging ou equivalente:

import json
import time

def registar_evento(tarefa, modelo, duracao, sucesso, erro=None):
    evento = {
        "timestamp": time.time(),
        "tarefa": tarefa,
        "modelo": modelo,
        "duracao_s": duracao,
        "sucesso": sucesso,
        "erro": str(erro) if erro else None,
    }
    print(json.dumps(evento))

Com este tipo de registo, consegues responder em segundos a perguntas como “quantos fallbacks tivemos na última hora” ou “qual a latência média do Gemini 4 Argon nas tarefas de resumo”, em vez de teres de reconstruir essa informação a partir de logs de texto não estruturados depois do incidente já ter acontecido.

Projeto completo: script de migração funcional

Junta as peças anteriores num único ficheiro funcional. Este script combina a camada de routing, o fallback e um registo simples de métricas, pronto para adaptares ao teu projeto real.

import os
import time
import logging
from google import genai
from dotenv import load_dotenv

load_dotenv()
logging.basicConfig(level=logging.INFO)
log = logging.getLogger("migracao-gemini")

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

TAREFAS_RAPIDAS = {"classificacao", "moderacao", "autocomplete"}
MODELO_PRINCIPAL = "gemini-4-argon"
MODELO_RAPIDO = "gemini-3.8-flash"


def escolher_modelo(tarefa: str, complexidade: str = "normal") -> str:
    if tarefa in TAREFAS_RAPIDAS and complexidade != "alta":
        return MODELO_RAPIDO
    return MODELO_PRINCIPAL


def gerar_resposta(tarefa: str, prompt: str, complexidade: str = "normal"):
    modelo = escolher_modelo(tarefa, complexidade)
    inicio = time.time()
    try:
        resposta = client.models.generate_content(model=modelo, contents=prompt)
        duracao = round(time.time() - inicio, 2)
        log.info("tarefa=%s modelo=%s duracao=%ss", tarefa, modelo, duracao)
        return resposta.text, modelo
    except Exception as erro:
        log.warning("falha no modelo=%s erro=%s, a tentar fallback", modelo, erro)
        if modelo != MODELO_RAPIDO:
            resposta = client.models.generate_content(
                model=MODELO_RAPIDO, contents=prompt
            )
            return resposta.text, f"{MODELO_RAPIDO} (fallback)"
        raise


if __name__ == "__main__":
    texto, modelo_usado = gerar_resposta(
        tarefa="resumo",
        prompt="Resume em três pontos as vantagens de migrar modelos de IA com testes A/B.",
    )
    print(f"Modelo usado: {modelo_usado}")
    print(texto)

Este script é deliberadamente pequeno. Em produção, substitui os print e o logging básico por um sistema de observabilidade real (OpenTelemetry, Datadog ou equivalente) e liga a escolha de modelo a feature flags para controlares o rollout gradual descrito no Passo 11 sem precisares de novo deploy a cada ajuste de percentagem.

5 erros comuns ao migrar do Gemini 2.5

A maioria dos problemas que aparecem em migrações deste tipo não vem do próprio modelo novo, vem de pressupostos que a equipa trouxe sem questionar da geração anterior. Os seis pontos abaixo resumem os erros que mais frequentemente transformam uma migração simples numa semana de incidentes.

Trocar o nome do modelo só num ficheiro. Variáveis de ambiente, Terraform, testes automatizados e documentação interna costumam ter referências separadas ao nome do modelo. Uma auditoria com grep incompleta deixa referências antigas espalhadas, e cada uma delas é um ponto de falha potencial depois de 20 de outubro.
Assumir que os parâmetros de raciocínio são iguais. Configurações de “thinking budget” ou equivalentes ajustadas para o Gemini 2.5 Pro não produzem o mesmo comportamento de custo e latência no Gemini 4 Argon sem reajuste. O que era um valor calibrado ao longo de meses de produção não se transfere automaticamente para um modelo com um perfil de raciocínio diferente.
Não testar function calling isoladamente. Um esquema de ferramenta que funcionava bem numa geração pode precisar de descrições mais explícitas para manter a mesma taxa de acerto noutra. Testar só o fluxo completo da aplicação, sem isolar cada ferramenta, torna difícil identificar qual delas degradou.
Ignorar diferenças de janela de contexto. Remover lógica de chunking sem confirmar o limite atual do modelo novo é um erro que só aparece quando um documento real excede o esperado, já em produção, normalmente com o cliente mais importante da empresa a enviar o ficheiro maior do trimestre.
Fazer o corte sem fallback. Migrar 100% do tráfego de uma vez, sem camada de routing nem plano de recuo, transforma qualquer instabilidade pontual do modelo novo numa falha total do produto, exatamente no momento em que menos margem existe para reagir.
Comparar modelos com uma amostra pequena de prompts. Validar a migração com cinco ou dez exemplos manuais dá uma falsa sensação de confiança. Diferenças de comportamento entre gerações de modelo só se revelam com consistência estatística quando testadas contra centenas de pedidos reais, não contra uma demonstração interna.

Resolução de problemas: 8 cenários comuns

Mesmo com uma migração planeada com cuidado, é normal encontrar erros pontuais nos primeiros dias de rollout. A tabela seguinte cobre os cenários mais frequentes reportados em migrações deste tipo, junto com a causa mais provável e o caminho mais rápido de resolução, para não perderes tempo a investigar do zero cada novo alerta.

Problema	Causa provável	Solução
Erro “model not found”	Identificador do modelo incorreto ou desatualizado	Confirma o identificador exato na documentação oficial da Gemini API
Erro 429 (rate limit)	Tráfego de teste e de produção a partilhar a mesma chave	Usa chaves de API separadas para testes e produção
Resposta vazia do modelo	Filtro de segurança a bloquear o conteúdo sem erro explícito	Inspeciona `response.candidates[0].finish_reason`
Function call nunca é acionada	Descrição da ferramenta pouco específica para o novo modelo	Reescreve a descrição com exemplos concretos de quando usar a função
Latência muito acima do esperado	Raciocínio profundo do Gemini 4 Argon em tarefa que não precisa dele	Redireciona a tarefa para o Gemini 3.8 Flash na camada de routing
Custo por chamada mais alto que o previsto	Respostas mais longas por falta de limite de tokens de saída	Define `max_output_tokens` explicitamente
Falha de autenticação após rotação de chave	Variável de ambiente antiga ainda em cache no processo	Reinicia o processo e confirma o `.env` carregado
Resultados inconsistentes entre testes A/B	Amostra de comparação pequena ou não representativa	Aumenta o volume de pedidos comparados antes de decidir

Dicas avançadas para produção

Depois da migração base funcionar, vale investir em quatro práticas que reduzem risco a longo prazo. Primeiro, versiona os teus prompts como código, num ficheiro separado com histórico de alterações, em vez de os deixares espalhados dentro da lógica de negócio. Isto facilita comparar qual versão de prompt funcionou melhor com qual modelo, e dá-te um registo claro de quando e porque cada prompt mudou, útil quando alguém perguntar, três meses depois, porque uma resposta específica saiu diferente do esperado.

Segundo, liga a escolha de modelo a um sistema de feature flags em vez de a uma constante no código. Assim consegues ajustar a percentagem de rollout, ou reverter completamente para o modelo rápido em caso de incidente, sem precisar de um novo deploy. Ferramentas como LaunchDarkly, Unleash ou uma simples tabela de configuração numa base de dados cumprem este papel sem complexidade excessiva.

Terceiro, configura alertas de custo específicos para o período de transição. Um pico inesperado de consumo de tokens nos primeiros dias depois do rollout é normal enquanto afinas os parâmetros, mas só é detetável a tempo se tiveres um alerta automático, não uma revisão manual da fatura ao fim do mês.

Quarto, mantém um “modo de emergência” documentado e testado: um procedimento conhecido por toda a equipa para reverter 100% do tráfego para o modelo de fallback em menos de cinco minutos, sem depender de uma pessoa específica estar disponível. Numa migração com prazo fixo como esta, a diferença entre um incidente contido e uma crise de produto costuma estar em quão rápido a equipa consegue executar esse procedimento sob pressão, não em quão sofisticada é a arquitetura no papel.

Perguntas frequentes

Até quando posso continuar a usar o Gemini 2.5?
Segundo a documentação oficial da Google Cloud, o Gemini 2.5 Pro, o Gemini 2.5 Flash e o Gemini 2.5 Flash-Lite deixam de estar disponíveis a 20 de outubro de 2026. Depois dessa data, chamadas à API com esses modelos devem falhar.

O Gemini 4 Argon substitui o Gemini 2.5 Pro ou é um modelo diferente?
É descrito pela Google como maior do que a antiga linha Pro, com foco em raciocínio profundo em workflows complexos. Não é apenas um “2.5 Pro com novo nome”: o comportamento e, provavelmente, o custo por chamada diferem, por isso a validação com testes A/B antes do corte total é essencial.

Preciso de migrar o SDK, ou só o nome do modelo?
Se ainda usas o SDK antigo google-generativeai, aproveita esta migração para passar ao SDK atual google-genai, que é o caminho recomendado pela Google para novos desenvolvimentos. Misturar os dois SDKs no mesmo projeto, mesmo que tecnicamente funcione durante a transição, tende a criar confusão de manutenção a médio prazo, por isso vale terminar a troca do SDK por completo em vez de a deixar parcial.

O Gemini 3.8 Flash é suficiente para a maioria das tarefas?
Para classificação, moderação, autocomplete e respostas curtas, sim, é a opção recomendada pela documentação oficial pela sua baixa latência. Para raciocínio em múltiplos passos ou análise de documentos longos, o Gemini 4 Argon tende a ser mais adequado.

Existe um “Gemini 3.5 Pro” que devo considerar em vez do Argon?
Não. A cobertura de outubro de 2026 indica que a Google não lançou esse modelo, optando por avançar diretamente para o Gemini 4 Argon como sucessor da linha Pro.

Como testo a migração sem arriscar os utilizadores atuais?
Usa o método descrito no Passo 11: corre o modelo novo em paralelo ao Gemini 2.5 (enquanto ainda está ativo), grava as duas respostas, mas só mostra ao utilizador a resposta do modelo antigo até teres confiança suficiente nos resultados do modelo novo.

O Gemini 3.5 Flash-Lite também vai ser aposentado em breve?
Não há indicação disso na documentação atual. O Gemini 3.5 Flash-Lite foi lançado a 21 de julho de 2026 com ciclo de vida previsto até, pelo menos, 21 de julho de 2027.

Vale a pena comparar com modelos abertos como o Mistral Large 4 nesta migração?
Pode valer a pena como referência de custo e escala, já que o Mistral Large 4, lançado em outubro de 2026 e seguido pelo acompanhamento de lançamentos de IA de outubro, é um modelo aberto MoE de grande dimensão. Mas a decisão entre API gerida e modelo aberto depende de requisitos de infraestrutura que vão além do âmbito desta migração pontual.

Quanto tempo demora, na prática, uma migração como esta?
Depende do tamanho da base de código, mas para uma aplicação de média dimensão, com uma dúzia de pontos de chamada à API, um cronograma realista costuma envolver uma a duas semanas de auditoria e migração de código, seguidas de outra semana de testes em paralelo e rollout gradual antes do corte final. Deixar isto para a última semana antes de 20 de outubro é o erro de planeamento mais comum que esta checklist tenta evitar.

Gemini 2.5 Acaba: Migra Para o 4 Argon em 12 Passos [2026]