Guia para desenvolvedores do Gemini 3.5 Flash

O Gemini 3.5 Flash é um modelo de alta velocidade e econômico 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 você deve usá-lo, como migrar para o 3.5 Flash e fornece um início rápido para usar o 3.5 Flash.

Como ele se encaixa na família Gemini?

A tabela a seguir compara algumas das especificações entre 3.5 Flash, 3.1 Pro e 3.1 Flash-Lite:

Consulte a página do modelo Flash 3.5 para conferir 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 níveis para otimizar qualidade, velocidade e 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 "cavalo de batalha" para tarefas de execução, chamadas de função e etapas de raciocínio intermediárias, oferecendo o melhor equilíbrio entre desempenho e eficiência.
• Gemini Flash-Lite: implante para pré-processamento e tarefas estruturais 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, inclusão de tags 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 família de modelos Gemini:

• Desempenho de ponta sustentado: nosso modelo Flash mais inteligente, otimizado para tarefas agênticas e de programação em grande escala.
• Execução com agentes: implantação de subagentes, resolução de problemas e loops rápidos com agentes em grande escala.
• Melhoria na programação: ciclos de programação iterativos, exploração rápida e prototipagem para testar caminhos alternativos e explorar soluções de forma dinâmica.
• Longo prazo: fluxos de trabalho de várias etapas e uso de ferramentas em grande escala.
• Preservação de ideias: o modelo mantém o raciocínio intermediário em conversas de várias etapas 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 LOW raciocínio: o nível de raciocínio baixo agora está significativamente melhorado para tarefas de código e agênticas que exigem menos etapas, oferecendo qualidade alta com latência e custo menores.

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

Guia de início rápido

Antes de começar, autentique-se na Agent Platform usando Application Default Credentials (ADC) ou uma chave de API. Consulte Começar a usar a plataforma de agentes do Gemini Enterprise 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 do 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.5-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.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 pensamento 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 dos modelos do Gemini 3 agora é MEDIUM, que mudou de HIGH na versão de pré-lançamento do Gemini 3 Flash. O nível de raciocínio MEDIUM gera resultados sólidos em uma ampla variedade de tarefas, além de ser mais rápido e econômico.

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

• MINIMAL: corresponde à configuração "sem pensar" 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 simples para a maioria das tarefas com alta velocidade e custo menor.
• MEDIUM: (padrão) configuração equilibrada para a maioria das tarefas que exigem raciocínio.
• HIGH: maximiza o raciocínio para otimizar a performance 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 Flash 3.5 vai usar a configuração padrão (MEDIUM).

Preservação de raciocínio

O modelo mantém o raciocínio intermediário em conversas de várias rodadas automaticamente. Quando presente no histórico de conversas, 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.

As ideias de turnos anteriores agora são preservadas por padrão. O serviço não limpa mais o histórico de ideias 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 tudo. O contexto parcial pode prejudicar o desempenho do modelo.

Descontinuado: parâmetros de amostragem

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

• temperature
• top_p
• top_k

O modelo gerencia a própria amostragem para ter resultados ideais. 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. Em vez disso, use o enum 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 correspondência estrita de respostas para chamadas de função
• Incluir conteúdo multimodal na resposta da função parts
• Usar instruções in-line na resposta da função
• Reduzir chamadas de ferramentas desnecessárias

Usar correspondência rigorosa de respostas para chamadas de função

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

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

O código a seguir é um exemplo de uma 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 qualidade inferior. Siga a recomendação incluída em Introdução à chamada de funções e inclua conteúdo multimodal nas partes de 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 embasada.

Por 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 in-line na resposta da função

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

Por 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 função, duas técnicas podem ajudar a minimizar isso:

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

2. Adicione uma instrução do sistema: se o uso excessivo persistir depois de ajustar o nível de raciocínio, considere um comando que restrinja o uso da ferramenta. Por exemplo:

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

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

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 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 os ignora completamente. Em vez disso, use o parâmetro thinking_level ou saídas estruturadas json_schema para controlar o determinismo da 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 de chat não tenta fazer o pré-enchimento do modelo: analise as matrizes de histórico de mensagens para garantir que a carga útil da API não termine com uma rodada vazia do usuário ou do modelo. Se o último objeto na matriz de histórico for uma função "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 thinking_budget descontinuado e use thinking_level.
   • Impor convenções estritas de chamada de função: o FunctionResponse precisa corresponder estritamente ao id, name e à contagem de execução do FunctionCall anterior. Se você precisar adicionar instruções inline, coloque-as diretamente no texto da resposta da função, separadas por duas quebras de linha (\n\n).
3. Considerar mudanças no fluxo de trabalho:
   • Se o aplicativo depender de loops de conversa de várias rodadas, 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 inicial.

Soluções alternativas para requisitos de texto antes do uso da 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 ocasionalmente com um erro Malformed_Function_Call. Use uma das seguintes soluções alternativas para resolver esse problema:

• (Recomendado) Instrua o modelo a colocar as observações 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 observações 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 função.

Solução recomendada: encapsular 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 <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.5 Flash
• Notebook introdutório