O Gemini está pensando…

Os modelos da série Gemini 3 e 2.5 usam um "processo de pensamento" que melhora significativamente as habilidades de raciocínio e planejamento de várias etapas, tornando-os altamente eficazes para tarefas complexas, como programação, matemática avançada e análise de dados.

Quando você usa um modelo de pensamento, o Gemini raciocina internamente antes de responder. A API Interactions mostra esse raciocínio usando etapas thought, que aparecem em ordem cronológica junto com chamadas de função, entradas do usuário ou saídas do modelo na matriz steps.

Cada etapa de pensamento contém dois campos:

Campo Obrigatório Descrição
signature ✅ Sim Uma representação criptografada do estado de raciocínio interno do modelo. Sempre presente, mesmo quando o modelo faz um raciocínio mínimo.
summary ❌ Não Uma matriz de conteúdo (texto e/ou imagens) que resume o raciocínio. Pode estar vazio dependendo da configuração thinking_summaries, se o modelo fez raciocínio suficiente ou do tipo de conteúdo. Por exemplo, latentes de imagem podem não ter resumos de texto.

Interações com o pensamento

Iniciar uma interação com um modelo de pensamento é semelhante a qualquer outra solicitação de interação. Especifique um dos modelos com suporte para raciocínio no campo model:

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Explain the concept of Occam's Razor and provide a simple, everyday example."
)
print(interaction.steps[-1].content[0].text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Explain the concept of Occam's Razor and provide a simple, everyday example."
});
console.log(interaction.steps.at(-1).content[0].text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Explain the concept of Occam'\''s Razor and provide a simple example."
  }'

Resumos de raciocínio

Os resumos de pensamento fornecem insights sobre o processo de raciocínio interno do modelo. Por padrão, apenas a saída final é retornada. Você pode ativar os resumos de ideias com o thinking_summaries:

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="What is the sum of the first 50 prime numbers?",
    generation_config={
        "thinking_summaries": "auto"
    }
)

for step in interaction.steps:
    if step.type == "thought":
        print("Thought summary:")
        for content_block in step.summary:
            if content_block.type == "text":
                print(content_block.text)
        print()
    elif step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print("Answer:")
                print(content_block.text)
                print()

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "What is the sum of the first 50 prime numbers?",
    generation_config: {
        thinking_summaries: "auto"
    }
});

for (const step of interaction.steps) {
    if (step.type === "thought") {
        console.log("Thought summary:");
        for (const contentBlock of step.summary) {
            if (contentBlock.type === "text") console.log(contentBlock.text);
        }
    } else if (step.type === "model_output") {
        for (const contentBlock of step.content) {
            if (contentBlock.type === "text") {
                console.log("Answer:");
                console.log(contentBlock.text);
            }
        }
    }
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "What is the sum of the first 50 prime numbers?",
    "generation_config": {
      "thinking_summaries": "auto"
    }
  }'

Um bloco de pensamento pode conter apenas uma assinatura sem resumo nestes casos:

  • Solicitações simples, em que o modelo não raciocinou o suficiente para gerar um resumo
  • thinking_summaries: "none", em que os resumos estão explicitamente desativados
  • Alguns tipos de conteúdo de pensamento, como imagens, podem não ter resumos de texto.

Seu código precisa sempre processar blocos de pensamento em que summary está vazio ou ausente.

Streaming com raciocínio

Use o streaming para receber resumos incrementais de ideias durante a geração. Os blocos de pensamento são entregues usando eventos enviados pelo servidor (SSE) com dois tipos de delta distintos:

Tipo de delta Contém Quando enviado
thought_summary Conteúdo de resumo de texto ou imagem Um ou mais deltas com resumo incremental
thought_signature A assinatura criptográfica o último delta antes de step.stop

Python

from google import genai

client = genai.Client()

prompt = """
Alice, Bob, and Carol each live in a different house on the same street: red, green, and blue.
Alice does not live in the red house.
Bob does not live in the green house.
Carol does not live in the red or green house.
Which house does each person live in?
"""

thoughts = ""
answer = ""

stream = client.interactions.create(
    model="gemini-3-flash-preview",
    input=prompt,
    generation_config={
        "thinking_summaries": "auto"
    },
    stream=True
)

for event in stream:
    if event.event_type == "step.delta":
        if event.delta.type == "thought_summary":
            if not thoughts:
                print("Thinking...")
            summary_text = event.delta.content.get('text', '') if hasattr(event.delta, 'content') else getattr(event.delta, 'text', '')
            print(f"[Thought] {summary_text}", end="")
            thoughts += summary_text
        elif event.delta.type == "text" and event.delta.text:
            if not answer:
                print("\nAnswer:")
            print(event.delta.text, end="")
            answer += event.delta.text

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const prompt = `Alice, Bob, and Carol each live in a different house on the same
street: red, green, and blue. Alice does not live in the red house.
Bob does not live in the green house.
Carol does not live in the red or green house.
Which house does each person live in?`;

let thoughts = "";
let answer = "";

const stream = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: prompt,
    generation_config: {
        thinking_summaries: "auto"
    },
    stream: true
});

for await (const event of stream) {
    if (event.event_type === "step.delta") {
        if (event.delta.type === "thought_summary") {
            if (!thoughts) console.log("Thinking...");
            const text = event.delta.content?.text || "";
            process.stdout.write(`[Thought] ${text}`);
            thoughts += text;
        } else if (event.delta.type === "text" && event.delta.text) {
            if (!answer) console.log("\nAnswer:");
            process.stdout.write(event.delta.text);
            answer += event.delta.text;
        }
    }
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H 'Content-Type: application/json' \
  --no-buffer \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Alice, Bob, and Carol each live in a different house on the same street: red, green, and blue. Alice does not live in the red house. Bob does not live in the green house. Carol does not live in the red or green house. Which house does each person live in?",
    "generation_config": {
      "thinking_summaries": "auto"
    },
    "stream": true
  }'

A resposta de streaming usa eventos enviados pelo servidor (SSE) e é composta de etapas e eventos. Confira um exemplo abaixo.

event: interaction.created
data: {"interaction":{"id":"v1_xxx","status":"in_progress","object":"interaction","model":"gemini-3-flash-preview"},"event_type":"interaction.created"}

event: step.start
data: {"index":0,"step":{"signature":"","summary":[{"text":"**Evaluating the clues**\n\nI'm considering...","type":"text"}],"type":"thought"},"event_type":"step.start"}

event: step.delta
data: {"index":0,"delta":{"signature":"EpoGCpcGAXLI2nx/...","type":"thought_signature"},"event_type":"step.delta"}

event: step.stop
data: {"index":0,"event_type":"step.stop"}

event: step.start
data: {"index":1,"step":{"content":[{"text":"Based on the clues provided, here","type":"text"}],"type":"model_output"},"event_type":"step.start"}

event: step.delta
data: {"index":1,"delta":{"text":" is the answer to your question...","type":"text"},"event_type":"step.delta"}

event: step.stop
data: {"index":1,"event_type":"step.stop"}

event: interaction.completed
data: {"interaction":{"id":"v1_xxx","status":"completed","usage":{"total_tokens":530,"total_input_tokens":62,"total_output_tokens":171,"total_thought_tokens":297}},"event_type":"interaction.completed"}

event: done
data: [DONE]

Pensamento controlador

Os modelos do Gemini usam o pensamento dinâmico por padrão, ajustando automaticamente a quantidade de esforço de raciocínio com base na complexidade da solicitação. Você pode controlar esse comportamento usando o parâmetro thinking_level.

Modelo Raciocínio padrão Níveis compatíveis
gemini-3.1-pro-preview Ativado (alto) baixo, médio, alto
gemini-3-flash-preview Ativado (alto) mínima, baixa, média, alta
gemini-3-pro-preview Ativado (alto) baixo, alto
gemini-2.5-pro Ativado baixo, médio, alto
gemini-2.5-flash Ativado baixo, médio, alto
gemini-2.5-flash-lite Desativado baixo, médio, alto

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Provide a list of 3 famous physicists and their key contributions",
    generation_config={
        "thinking_level": "low"
    }
)
print(interaction.steps[-1].content[0].text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Provide a list of 3 famous physicists and their key contributions",
    generation_config: {
        thinking_level: "low"
    }
});
console.log(interaction.steps.at(-1).content[0].text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Provide a list of 3 famous physicists and their key contributions",
    "generation_config": {
      "thinking_level": "low"
    }
  }'

Assinaturas de raciocínio

As assinaturas de pensamento são representações criptografadas do raciocínio interno do modelo. Elas precisam manter a continuidade do raciocínio em interações de várias etapas.

A API Interactions simplifica muito mais o processamento de assinaturas de pensamento do que a API generateContent.

Por padrão, quando você usa a API Interactions no modo com estado (definindo store: true e transmitindo previous_interaction_id em turnos subsequentes), o servidor gerencia automaticamente o estado da conversa, incluindo todos os blocos de pensamento e assinaturas. Nesse modo, você não precisa fazer nada em relação às assinaturas. Eles são processados totalmente no lado do servidor.

Modo sem estado

Se você estiver gerenciando o estado da conversa (modo sem estado) e transmitindo o histórico completo de entradas e saídas em cada solicitação:

  • Você PRECISA sempre reenviar todos os blocos thought exatamente como foram recebidos do modelo.
  • NÃO remova nem modifique os blocos de pensamento do histórico, porque eles contêm as assinaturas necessárias para que o modelo continue raciocinando.
  • Ao trocar de modelo em uma sessão, ainda é necessário reenviar os blocos de pensamento do modelo anterior. O back-end gerencia a compatibilidade.

Preços

Quando o raciocínio está ativado, o preço da resposta é a soma dos tokens de saída e de raciocínio. É possível conferir o número total de tokens de pensamento gerados no campo total_thought_tokens.

Python

# ...
print("Thoughts tokens:", interaction.usage.total_thought_tokens)
print("Output tokens:", interaction.usage.total_output_tokens)

JavaScript

// ...
console.log(`Thoughts tokens: ${interaction.usage.total_thought_tokens}`);
console.log(`Output tokens: ${interaction.usage.total_output_tokens}`);

Os modelos de pensamento geram ideias completas para melhorar a qualidade da resposta final e, em seguida, produzem resumos para fornecer insights sobre o processo de pensamento. O preço é baseado no total de tokens de pensamento que o modelo precisa gerar, mesmo que apenas o resumo seja gerado pela API.

Saiba mais sobre tokens no guia Contagem de tokens.

Práticas recomendadas

Siga estas diretrizes para usar modelos de pensamento de maneira eficiente.

  • Revisar o raciocínio: analise os resumos de pensamento para entender as falhas e melhorar os comandos.
  • Controle o orçamento de pensamento: peça ao modelo para pensar menos em saídas longas e economizar tokens.
  • Tarefas simples: use o mínimo de raciocínio para recuperação de fatos ou classificação (por exemplo, "Onde a DeepMind foi fundada?").
  • Tarefas moderadas: use o pensamento padrão para comparar conceitos ou raciocínio criativo (por exemplo, "Compare carros elétricos e híbridos").
  • Tarefas complexas: use o pensamento máximo para programação avançada, matemática ou planejamento em várias etapas (por exemplo, resolver problemas de matemática da AIME).

A seguir