Guia para desenvolvedores do Gemini 3.6 Flash

O Gemini 3.6 Flash é um modelo de alta velocidade e econômico da família Gemini 3. Projetado para oferecer recursos agênticos quase profissionais sem comprometer a performance ou o valor, o modelo agora está disponível para desenvolvedores que usam a API Gemini e para empresas que usam a Gemini Enterprise Agent Platform.

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

Como ele se encaixa na família Gemini?

O Gemini 3.6 Flash é o principal modelo agêntico da família Gemini 3. Ele preenche a lacuna entre os modelos Pro de raciocínio profundo e os modelos Flash-Lite de alta capacidade. Em comparação com o Gemini 3.5 Flash, o 3.6 Flash oferece uma qualidade significativamente maior na orquestração de ferramentas de várias etapas, na refatoração de código de pilha completa e no raciocínio visual, usando menos tokens e turnos de raciocínio. Ele oferece recursos quase profissionais com a velocidade e o preço do Flash.

Especificações e comparações de modelos

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

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

O que há de novo no Gemini 3.6 Flash?

O 3.6 Flash é otimizado para orquestração de várias etapas, refatoração de código de pilha completa e raciocínio geral com eficiência de token significativamente melhor do que seus antecessores.

Atualizações de recursos e performance

A seguir, confira a lista de mudanças nos recursos e na performance do 3.6 Flash em relação aos modelos anteriores:

• Redução de tokens e turnos: consome menos tokens e conclui fluxos de trabalho de várias etapas em menos etapas de raciocínio e turnos conversacionais do que o 3.5 Flash.
• Geração de código aprimorada: produz um código mais limpo com taxas mais baixas de falha de compilação e revisão em ambientes de criação de aplicativos, prototipagem e agentes de IDE.
• Viés de ação reduzido: resolve tarefas de diagnóstico somente leitura sem fazer edições não solicitadas no espaço de trabalho ou alterar o estado prematuramente.
• Raciocínio multimodal e espacial: oferece performance aprimorada na interpretação de gráficos , conversão de projetos visuais e geração de layouts da Web com vários elementos.
• Suporte ao uso do computador: compatível como uma ferramenta integrada para automação UI agêntica.
• Preferência de estilo de interface: melhor na criação de código funcional, embora os avaliadores humanos tenham notado uma preferência por modelos anteriores para apresentação de front-end e layout visual. Isso pode ser atenuado fornecendo diretrizes de design explícitas.

Mudanças de parâmetros comportamentais e de API

A seguir, confira a lista de mudanças de parâmetros comportamentais e de API do 3.6 Flash em relação aos modelos anteriores:

• Concisão da etapa: usa menos etapas de raciocínio do que o 3.5 Flash. Embora isso reduza a latência e o custo na refatoração de código e nos fluxos de trabalho de ferramentas, pode causar saídas antecipadas em acompanhamentos conversacionais de várias etapas em que são necessárias cadeias de iteração mais longas.
• Inspeção programática antecipada: prefere executar scripts de código de diagnóstico (execute_code) para inspecionar problemas antes de alterar o estado com mais frequência do que o 3.5 Flash. Embora isso melhore a precisão do diagnóstico na refatoração complexa de back-end, pode ocasionalmente levar à execução de etapas extras de inspeção exploratória em tarefas simples de script e da Web de front-end em que a versão anterior geraria código diretamente.
• Esforço padrão: mantém o nível de esforço padrão médio introduzido no 3.5 Flash.
• Nenhuma substituição de amostragem: os valores personalizados para temperature, top-k, ou top-p parâmetros não são mais aceitos. A definição de valores personalizados será ignorada na superfície da API. Em vez disso, use thinking_level ou esquemas JSON estruturados para controlar o determinismo de saída.
• Restrições de penalidade de frequência e presença: os valores personalizados para esses parâmetros não são mais aceitos. A definição deles agora vai gerar um erro de API ativo.
• As solicitações de API em que o último turno de entrada tem o papel de "Modelo" não são aceitas.
• Os turnos vazios no histórico de conversas são descartados.
• As assinaturas de pensamento inválidas agora vão produzir erros.
• Chamada de função estrita: FunctionResponse precisa corresponder estritamente ao id, name e contagem de execução do FunctionCall anterior. Anexe instruções inline diretamente no texto de resposta da função, separadas por duas novas linhas (\n\n).

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 à Gemini Enterprise Agent Platform 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.6-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.6-flash:generateContent \
-d '{
  "contents": {
    "role": "USER",
    "parts": { "text": "Why is the sky blue?" },
  },
}'

Migrar para o 3.6 Flash do 3.5 Flash ou do 3.1 Pro

Para migrar para o 3.6 Flash do 3.5 Flash ou do 3.1 Pro, siga estas etapas:

1. Atualize o ID do modelo: mude a string do modelo nas chamadas de API para gemini-3.6-flash.
2. Adapte seu código às novas regras da API da família Gemini 3: o Gemini 3.6 Flash aplica estritamente as regras de parâmetros e as convenções de API estabelecidas na família Gemini 3:
   • Remova a temperatura, o Top-K e o Top-P: remova esses parâmetros personalizados do payload. Embora eles não gerem um erro, o modelo os ignorará completamente. Em vez disso, use o parâmetro thinking_level ou as saídas estruturadas json_schema para controlar o determinismo de saída.
   • Remova as penalidades de frequência e presença: remova todas as configurações personalizadas de penalidades de frequência ou presença para evitar que as chamadas de API gerem erros de tempo de execução.
   • Verifique se a integração do chat não tenta o preenchimento prévio do modelo: revise as matrizes do histórico de mensagens para garantir que o payload da API não termine com um turno de usuário ou modelo vazio. Se o último objeto na matriz de histórico for um papel "model" (API GenerateContent) ou um tipo "model_output" (API Interactions), reestruture a sequência para evitar acionar um erro de validação estrita.
   • Use thinking_level: remova instâncias do parâmetro descontinuado thinking_budget e use thinking_level em vez disso.
   • Aplique convenções de chamada de função estritas: o FunctionResponse precisa corresponder estritamente ao id, name e contagem de execução do FunctionCall anterior. Se você precisar anexar instruções inline, coloque-as diretamente no texto de resposta da função, separadas por duas novas linhas (\n\n).
3. Considere as mudanças no fluxo de trabalho:
   • Se o aplicativo depende de loops conversacionais de várias etapas, teste os fluxos de trabalho para garantir que a nova concisão da etapa do modelo não acione saídas prematuras.
   • Ao criar agentes de script básicos ou de front-end, monitore chamadas execute_code exploratórias desnecessárias devido ao novo viés do modelo em relação à inspeção programática antecipada.

Soluções alternativas para requisitos de texto pré-ferramenta

Se o comando exigir que o modelo gere texto estruturado (XLM, YAML, Json, etc) (por exemplo, <UPDATE>...</UPDATE>) imediatamente antes de fazer uma chamada de ferramenta, a chamada de ferramenta poderá falhar ocasionalmente com um erro Malformed_Function_Call. Você pode usar uma das seguintes soluções alternativas para resolver esse problema:

• (Recomendado) Instrua o modelo a colocar as notas pré-ferramenta em uma chamada de função update() dedicada em vez de texto bruto. Consulte a próxima seção para instruções detalhadas de implementação.
• Instrua o modelo a escrever notas como cabeçalhos Markdown (por exemplo, # UPDATE, ## PLAN) em vez de texto estruturado.
• Não exija que o modelo gere texto antes das chamadas de ferramenta.

Solução recomendada: encapsular notas de trabalho em uma chamada de função dedicada

Em vez da instrução original:

Before calling a tool, in every response you MUST first output a single
`<UPDATE>` part as specified, don't skip this part or any of required sub-tags
within `<UPDATE>`.

Use esta instrução atualizada:

Before calling any other tool, in every response you MUST first call `update`
with all required parameters (previous_step, plan, next_step, external).

Atualize todas as referências ao formato XML <UPDATE> antigo na solicitação do cliente. Em seguida, adicione a declaração de função correspondente para a função de atualização:

{
  "name": "update",
  "description": "Update working notes (previous step analysis, plan, next step, external note).",
  "parameters": {
    "type": "OBJECT",
    "properties": {
      "previous_step": {
        "type": "STRING",
        "description": "Key findings and outcomes since the previous step."
      },
      "plan": {
        "type": "STRING",
        "description": "The current status of the plan."
      },
      "next_step": {
        "type": "STRING",
        "description": "Brief explanation of the immediate next action according to the plan."
      },
      "external": {
        "type": "STRING",
        "description": "A short, plain-language note shown to the User about what you are ABOUT TO DO next."
      }
    },
    "required": [
      "previous_step",
      "plan",
      "next_step",
      "external"
    ]
  }
}

O modelo fará duas chamadas na mesma etapa: a chamada update() que substitui o XML estruturado e a chamada de função real que ele quer fazer.

Outros recursos

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