Guia para desenvolvedores do Gemini 3.8 Flash

O Gemini 3.8 Flash é nosso modelo mais inteligente até o momento, oferecendo melhorias significativas em relação ao 3.7 Flash em engenharia de software, tarefas agênticas e raciocínio em várias etapas crítico em domínios especializados. O 3.8 Flash oferece ganhos substanciais em relação ao 3.7 Flash, muitas vezes se aproximando da performance de modelos de fronteira de custo mais alto.

Este documento aborda as novidades do 3.8 Flash, como ele se encaixa na família de modelos do Gemini, como migrar para o 3.8 Flash e fornece um guia de início rápido para usar o 3.8 Flash.

Como ele se encaixa na família Gemini?

A linha Gemini Flash é o principal modelo de trabalho agêntico na família Gemini 3, preenchendo a lacuna entre os modelos Pro de raciocínio profundo e os modelos Gemini Flash-Lite de alta capacidade, oferecendo alta eficiência de token e processamento multimodal de várias etapas.

Em comparação com o 3.7 Flash, o 3.8 Flash oferece melhor precisão e performance mais confiável ao custo de maior consumo de tokens. No entanto, o 3.8 Flash também vem com controle de esforço por meio de níveis de raciocínio para você modular esse consumo. No nível de raciocínio médio, ainda é possível resolver tarefas agênticas complexas, reduzindo o consumo de tokens. Também é possível usar níveis de raciocínio mais baixos para tarefas sensíveis à latência para evitar completamente a sobrecarga de computação. Se você quiser otimizar a eficiência de computação, considere usar o 3.7 Flash.

Especificações e comparações de modelos

A tabela a seguir é uma comparação que abrange algumas das especificações entre o 3.8 Flash, o 3.7 Flash e o 3.1 Pro:

Consulte a página do modelo 3.8 Flash para conferir a lista completa de recursos, ferramentas e opções de consumo compatíveis.

O que há de novo no Gemini 3.8 Flash?

A tabela a seguir compara os benchmarks de avaliação de desenvolvedores padrão entre o Gemini 3.8 Flash e o 3.7 Flash:

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 o artigo 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

Verifique se você está usando o SDK google-genai mais recente:

pip install --upgrade google-genai

Solicitação básica

from google import genai

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

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

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-3.8-flash:generateContent \
-d '{
  "contents": {
    "role": "USER",
    "parts": { "text": "Why is the sky blue?" },
  },
}'

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

O Gemini 3.8 Flash aplica rigorosamente as seguintes convenções de API padrão da família Gemini 3:

• Parâmetros de amostragem descontinuados (temperature, top_k, top_p): esses parâmetros são ignorados pelo back-end. Em vez disso, é possível controlar o determinismo usando thinking_level (LOW, MEDIUM, HIGH) e response_schema ou json_schema.
• Parâmetros não compatíveis (frequency_penalty, presence_penalty, candidate_count): a transmissão de frequency_penalty, presence_penalty ou candidate_count vai gerar um erro de API ativo. Remova-os do código do cliente legado.

• Regras de chamada de função estritas: um turno FunctionResponse precisa corresponder estritamente ao id, name e à contagem de execução do FunctionCall anterior.

  • Recursos multimodais: sempre coloque recursos multimodais no payload de resposta.
  • Formatação e texto pré-ferramenta: formate instruções inline usando \n\n. Se você encontrar erros Malformed_Function_Call vinculados ao texto pré-ferramenta, limpe o comentário principal antes das chamadas de ferramenta.

  • Para transmitir notas de trabalho intermediárias ou atualizações de status antes de uma chamada de ferramenta, envolva-as em uma chamada de função update() dedicada em vez de emitir XML ou texto bruto:

    {
      "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 um turno de função "model".
  • Os turnos de modelo preenchidos automaticamente não são compatíveis e precisam ser removidos durante o upgrade.
  • Os turnos vazios no histórico de conversas são descartados automaticamente ou produzem erros de validação.

3.8 Flash do 3.7 Flash ou 3.6 Flash

Para migrar para o 3.8 Flash do 3.7 Flash ou 3.6 Flash, siga estas etapas:

1. Atualize o ID do modelo: mude a string do modelo nas chamadas de API para gemini-3.8-flash.
2. Substitua o parâmetro de orçamento de raciocínio: substitua as configurações de número inteiro thinking_budget pelo enum de string thinking_level definido como um dos seguintes valores:
   • HIGH: recomendado para controle de qualidade visual denso, detecção de movimento em fração de segundo (esportes, edição) ou raciocínio de várias etapas em vídeos de mais de 60 minutos.
   • MEDIUM: o nível de raciocínio padrão. Esse nível oferece um equilíbrio ideal para perguntas e respostas gerais de vídeo, resumo de palestras e recuperação de clipes.
   • LOW: recomendado para tarefas como pesquisas rápidas focadas em transcrição ou extração básica de metadados.
3. Remova parâmetros descontinuados e não compatíveis:
   • Remova temperature, top_p e top_k.
   • 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

Outros recursos

• Página do modelo Gemini 3.8 Flash
• Notebook introdutório