Guia para desenvolvedores do Gemini 3.5 Flash

O Gemini 3.5 Flash é um modelo de alta velocidade e custo-benefício da família Gemini 3. Projetado para oferecer recursos agênticos quase profissionais sem comprometer o desempenho ou o valor, o modelo agora está em disponibilidade geral (GA) para desenvolvedores que usam a API Gemini e para empresas que usam a Gemini Enterprise Agent Platform.

Este documento aborda as novidades do 3.5 Flash, quando usá-lo, como migrar para ele e um guia de início rápido para usá-lo.

Como ele se encaixa na família Gemini?

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

	Gemini 3.5 Flash	Gemini 3.1 Pro	Gemini 3.1 Flash-Lite
ID do modelo	gemini-3.5-flash	gemini-3.1-pro-preview	gemini-3.1-flash-lite
Etapa do lançamento	GA	Pré-lançamento	GA
Tipos de entrada	Texto, imagem, áudio, vídeo	Texto, imagem, áudio, vídeo	Texto, imagem, áudio, vídeo
Tipos de saída	Texto	Texto	Texto
Janela de contexto	1.048.576	1.048.576	1.048.576
Tamanho máximo do token de saída	65.536	65.536	65.536
Regiões compatíveis	Global, multirregional, Américas, Europa, Ásia-Pacífico	Global	Global, multirregional
Níveis de raciocínio disponíveis	MINIMAL, LOW, MEDIUM, HIGH (padrão: MEDIUM)	LOW, MEDIUM, HIGH (padrão: HIGH)	MINIMAL, LOW, MEDIUM, HIGH (padrão: MINIMAL)
Foco principal	Tarefas equilibradas, chamada de ferramentas e raciocínio intermediário	Tarefas de raciocínio profundo e alta complexidade	Tarefas de alto volume, sensíveis a custos e latência

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

Detalhamento do caso de uso

A estratégia recomendada para Agentic Workflows usa uma abordagem em camadas para otimizar a qualidade, a velocidade e o custo:

• Gemini Pro: reserve para processos cognitivos de alta complexidade que exigem raciocínio profundo, como planejamento inicial de raiz, solução de problemas complexos, programação difícil e tomada de decisões críticas.
• Gemini Flash: use como o principal "motor" para tarefas de execução, chamadas de ferramentas e etapas de raciocínio intermediárias, oferecendo o melhor equilíbrio entre desempenho e eficiência.
• Gemini Flash-Lite: implante para tarefas estruturais e de pré-processamento de alto volume e baixa latência, em que a velocidade e o custo são fundamentais, como roteamento de intenção, extração de dados, marcação e classificação.

O que há de novo no Gemini 3.5 Flash?

O Gemini 3.5 Flash traz as seguintes mudanças e melhorias para a linha de modelos do Gemini:

• Desempenho de ponta sustentado: nosso modelo Gemini Flash mais inteligente, otimizado para tarefas agênticas e de programação em grande escala.
• Execução agêntica: implantação de subagentes, resolução de problemas e loops do agente rápidos em grande escala.
• Programação aprimorada: ciclos de programação iterativos, exploração rápida e prototipagem para testar caminhos alternativos e explorar soluções de forma dinâmica.
• Longo alcance: fluxos de trabalho de várias etapas e uso de ferramentas em escala.
• Preservação de raciocínio: o modelo mantém o raciocínio intermediário em conversas de vários turnos automaticamente. Não é necessário fazer mudanças na API.
• Novo nível de pensamento padrão: o nível de pensamento padrão mudou de HIGH para MEDIUM.
• Melhoria no raciocínio do LOW: o nível de raciocínio baixo agora está significativamente melhor para tarefas de código e agênticas que exigem menos etapas, oferecendo alta qualidade com menor latência e custo.

Confira mais detalhes na seção Principais mudanças.

Observação: talvez você note um aumento nas contagens de tokens informadas. A infraestrutura atualizada conta com precisão todos os componentes da solicitação, incluindo metadados complexos, como esquemas de resposta e chamadas de função, que eram subcontados em versões anteriores.

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 Começar a usar a Gemini Enterprise Agent Platform para mais informações.

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

Instalação

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

pip install --upgrade google-genai

Solicitação básica

Python

from google import genai

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

response = client.models.generate_content(
  model="gemini-3.5-flash",
  contents="How does AI work?",
)
print(response.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-3.5-flash:generateContent \
-d '{
  "contents": {
    "role": "USER",
    "parts": { "text": "Why is the sky blue?" },
  },
}'

Mudanças importantes

Esta seção descreve em mais detalhes as seguintes mudanças introduzidas no Gemini 3.5 Flash:

• Novo nível de reflexão padrão (MEDIUM)
• Preservação de raciocínio
• Descontinuado: parâmetros de amostragem
• Descontinuado: thinking_budget

Novo nível de raciocínio padrão

O nível de raciocínio padrão para os modelos do Gemini 3 agora é MEDIUM, mudando de HIGH na versão de pré-lançamento do Gemini 3 Flash. O nível de raciocínio MEDIUM gera resultados consistentes em uma ampla variedade de tarefas, além de ser mais rápido e econômico.

Os níveis de raciocínio disponíveis são:

• MINIMAL: corresponde à configuração "sem raciocínio" para a maioria das consultas. O modelo pode pensar muito pouco para tarefas complexas, como programação. Minimiza a latência para aplicativos de chat ou de alta capacidade de processamento.
• LOW: raciocínio leve para a maioria das tarefas, com alta velocidade e custo mais baixo.
• MEDIUM: (padrão) configuração equilibrada para a maioria das tarefas que exigem raciocínio.
• HIGH: maximiza o raciocínio para otimizar o desempenho da tarefa. O modelo pode levar mais tempo do que a configuração MEDIUM para gerar o primeiro token, mas a saída será mais completa.

Por exemplo, use HIGH para quebra-cabeças lógicos, problemas matemáticos ou cenários complicados em que o modelo precisa raciocinar em várias etapas:

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
   model="gemini-3.5-flash",
   contents="A farmer has chickens and rabbits. There are 35 heads and 94 legs. How many chickens and how many rabbits does he have? Show your step-by-step logic.",
   config=types.GenerateContentConfig(
       thinking_config=types.ThinkingConfig(
           thinking_level=types.ThinkingLevel.HIGH
       )
   ),
)
print(response.text)

O parâmetro thinking_level é opcional. Se omitido, o 3.5 Flash vai usar a configuração padrão (MEDIUM).

Observação: o parâmetro thinking_level e o parâmetro legado thinking_budget são exclusivos um do outro. O uso de ambos em uma solicitação vai retornar um erro 400.

Preservação de raciocínio

O modelo mantém o raciocínio intermediário em conversas de vários turnos automaticamente. Quando presente no histórico da conversa, o contexto de raciocínio é transferido automaticamente, melhorando o desempenho em tarefas complexas de várias etapas, como depuração iterativa e refatoração de código. Não é necessário fazer mudanças na API.

Os pensamentos de turnos anteriores agora são preservados por padrão. O serviço não limpa mais o histórico de pensamentos do contexto da conversa antes de transmiti-lo ao modelo.

Ao enviar o histórico da conversa, seja consistente com as interações anteriores: inclua o contexto completo (pensamentos, chamadas de função, respostas) ou omita-o totalmente. O contexto parcial pode prejudicar o desempenho do modelo.

Observação: a preservação de raciocínio pode aumentar o uso de tokens e o tempo de resposta. Para consultas simples e independentes, limpar os pensamentos entre as interações pode ajudar.

Descontinuado: parâmetros de amostragem

Os seguintes parâmetros de amostragem não são mais recomendados para os modelos do Gemini 3:

• temperature
• top_p
• top_k

O modelo gerencia a própria amostragem para alcançar os melhores resultados. Remova esses parâmetros de todas as solicitações. Para garantir o determinismo, defina uma instrução do sistema com regras explícitas para seu caso de uso específico.

Descontinuado: thinking_budget

O parâmetro numérico bruto thinking_budget não é mais compatível com todos os modelos do Gemini 3. Use o tipo enumerado de string thinking_level.

# ⚠️ Before (not recommended)
config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(thinking_budget=7500)
)

# ✅ After
config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(thinking_level="MEDIUM")
)

Práticas recomendadas

Nesta seção, descrevemos as seguintes práticas recomendadas para usar o 3.5 Flash:

• Usar a correspondência de resposta estrita para chamadas de função
• Incluir conteúdo multimodal na resposta da função parts
• Usar instruções inline na resposta da função
• Reduzir chamadas de ferramentas desnecessárias

Usar correspondência de resposta estrita para chamadas de função

Respostas incompatíveis fazem com que o modelo retorne respostas vazias com finish_reason: STOP na maioria dos casos. Sempre siga estas convenções:

• Incluir id: cada FunctionResponse precisa incluir o id do FunctionCall correspondente.
• Correspondência de name: o name na resposta precisa corresponder ao name na chamada.
• Contagens de correspondência: retorna exatamente um FunctionResponse para cada FunctionCall recebido.

O código a seguir é um exemplo de chamada de função correta:

# ✅ Include matching id and name in the function response
final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={"result": result},
                id=tool_call.id,
            )
        ]),
    ],
)

Incluir conteúdo multimodal na resposta da função parts

Fornecer imagens fora da resposta da função pode levar a um comportamento inesperado do modelo, como vazamento de pensamento, e resultar em menor qualidade. Siga a recomendação incluída em Introdução à chamada de função e inclua conteúdo multimodal nas partes da resposta da função que você envia ao modelo. O modelo pode processar esse conteúdo multimodal na próxima vez para produzir uma resposta mais informada.

Exemplo:

# ✅ Include multimodal content in the function response
final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={
                    "result": "instrument.jpg",
                    "image": base64_image_data,
                },
                id=tool_call.id,
            )
        ]),
    ],
)

Usar instruções inline na resposta da função

Fornecer instruções de plataforma com respostas de função como parts subsequentes pode levar a um comportamento inesperado do modelo, como vazamento de pensamento, e resultar em menor qualidade. Em vez disso, adicione-o ao final do texto de resposta da função, separado por duas novas linhas.

Exemplo:

# ✅ Append inline instructions to the end of the function response separated by two newlines
result_text = f"{json.dumps(result)}\n\n<your inline instructions>"

final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={"result": result_text},
                id=tool_call.id,
            )
        ]),
    ],
)

Reduzir chamadas de ferramentas desnecessárias

Se você notar um uso excessivo de chamadas de ferramentas, duas técnicas podem ajudar a minimizá-las:

1. Reduza o nível de raciocínio: níveis de raciocínio mais altos incentivam o modelo a usar mais ferramentas para explorar e verificar. Portanto, reduzir o nível pode reduzir as chamadas de ferramentas.

2. Adicione uma instrução do sistema: se o uso excessivo persistir após o ajuste do nível de reflexão, considere um comando que restrinja o uso da ferramenta. Exemplo:

   You have a limited action budget of <n> tool calls. Use them efficiently.
   

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

Para migrar do 3.5 Flash ou do 3.1 Pro para o 3.6 Flash, 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 em toda a família Gemini 3:
   • Remover temperatura, top-K e top-P: remova esses parâmetros personalizados do payload. Embora não gerem um erro, o modelo vai ignorá-los completamente. Em vez disso, use o parâmetro thinking_level ou as saídas estruturadas json_schema para controlar o determinismo da saída.
   • Remover 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 preencher o modelo: revise as matrizes do histórico de mensagens para garantir que o payload da API não termine com uma vez de usuário ou de modelo vazia. 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 um erro de validação estrita.
   • Use thinking_level: remova instâncias do parâmetro thinking_budget descontinuado e use thinking_level.
   • Aplicar convenções estritas de chamada de função: o FunctionResponse precisa corresponder estritamente ao id, ao name e à contagem de execuções do FunctionCall anterior. Se você precisar anexar instruções inline, coloque-as diretamente no texto de resposta da função, separadas por duas linhas novas (\n\n).
3. Considere as mudanças no fluxo de trabalho:
   • Se o aplicativo depende de loops de conversação de vários turnos, teste seus fluxos de trabalho para garantir que a nova concisão de etapas do modelo não acione saídas prematuras.
   • Se estiver criando agentes de front-end ou de script básico, monitore chamadas execute_code exploratórias desnecessárias devido ao novo viés do modelo em relação à inspeção programática inicial.

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, ela poderá falhar com um erro Malformed_Function_Call. Para resolver esse problema, use uma das seguintes soluções alternativas:

• (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 ver 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: envolver as 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 antigo de <UPDATE> 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 vai fazer 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.5 Flash
• Notebook introdutório