Embasamento com a Pesquisa Google

O embasamento com a Pesquisa Google conecta o modelo do Gemini ao conteúdo da Web em tempo real e funciona com todos os idiomas disponíveis. Isso permite que o Gemini forneça respostas mais precisas e cite fontes verificáveis além do limite de conhecimento.

O embasamento ajuda a criar aplicativos que podem:

• Aumentar a precisão factual:reduza as alucinações do modelo com base em informações do mundo real.
• Acessar informações em tempo real:responda a perguntas sobre eventos e tópicos recentes.

• Fornecer citações:crie confiança do usuário mostrando as fontes das declarações do modelo.

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="Who won the euro 2024?",
    tools=[{"type": "google_search"}]
)

print(interaction.output_text)

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3.5-flash",
    input: "Who won the euro 2024?",
    tools: [{ type: "google_search" }]
});

console.log(interaction.output_text);

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.5-flash",
    "input": "Who won the euro 2024?",
    "tools": [{"type": "google_search"}]
  }'

Como funciona o embasamento com a Pesquisa Google

Quando você ativa a ferramenta google_search, o modelo processa todo o fluxo de trabalho de pesquisa, processamento e citação de informações automaticamente.

1. Comando do usuário:seu aplicativo envia um comando do usuário para a API Gemini com a ferramenta google_search ativada.
2. Análise de comandos:o modelo analisa o comando e determina se uma Pesquisa Google pode melhorar a resposta.
3. Pesquisa Google:se necessário, o modelo gera automaticamente uma ou várias consultas de pesquisa e as executa.
4. Processamento de resultados da pesquisa:o modelo processa os resultados da pesquisa, sintetiza as informações e formula uma resposta.
5. Resposta embasada:a API retorna uma resposta final e fácil de usar que é baseada nos resultados da pesquisa. Essa resposta inclui a resposta de texto do modelo com annotations inline que contêm as citações, bem como as etapas google_search_call e google_search_result com as consultas e sugestões de pesquisa.

Entender a resposta de embasamento

Quando uma resposta é embasada, a saída de texto do modelo inclui annotations inline diretamente no bloco de conteúdo de texto. Essas anotações fornecem informações de citação que vinculam partes da resposta às fontes.

{
  "steps": [
    {
      "type": "thought",
      "summary": [
        {
          "type": "text",
          "text": "The user is asking for the winner of Euro 2024. I need to search for the result of the Euro 2024 final."
        }
      ],
      "signature": "CoMDAXLI2nynRYojJIy6B1Jh9os2crpWLfB0..."
    },
    {
      "type": "google_search_call",
      "arguments": {
        "queries": ["UEFA Euro 2024 winner"]
      }
    },
    {
      "type": "google_search_result",
      "call_id": "search_001",
      "result": [
        {
          "search_suggestions": "<!-- HTML and CSS for the search widget -->"
        }
      ]
    },
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Spain won Euro 2024, defeating England 2-1 in the final. This victory marks Spain's record fourth European Championship title.",
          "annotations": [
            {
              "type": "url_citation",
              "url": "https://www.aljazeera.com/sports/euro-2024-final",
              "title": "aljazeera.com",
              "start_index": 0,
              "end_index": 56
            },
            {
              "type": "url_citation",
              "url": "https://www.uefa.com/euro2024/news/spain-wins-euro-2024",
              "title": "uefa.com",
              "start_index": 57,
              "end_index": 124
            }
          ]
        }
      ]
    }
  ]
}

Os principais campos na resposta:

• google_search_call : contém as queries de pesquisa que o modelo executou.
• google_search_result : contém search_suggestions, um snippet HTML para renderizar sugestões de pesquisa na sua interface. Os requisitos de uso completos estão detalhados nos Termos de Serviço.
• text com annotations : a resposta sintetizada do modelo com citações inline. Cada anotação url_citation vincula um segmento de texto (definido por start_index e end_index) a um URL de origem. Essa é a chave para criar citações inline.

O embasamento com a Pesquisa Google também pode ser usado em combinação com a ferramenta de contexto de URL para embasar respostas em dados da Web públicos e nos URLs específicos que você fornece.

Atribuir fontes com citações inline

A API retorna anotações url_citation inline no bloco de conteúdo de texto, oferecendo controle total sobre como você mostra as fontes na interface do usuário. Cada anotação inclui start_index e end_index para identificar a parte do texto que ela cita. Saiba como extrair e mostrar essas informações.

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nCitations:")
                    for annotation in content_block.annotations:
                        if annotation.type == "url_citation":
                            cited_text = content_block.text[annotation.start_index:annotation.end_index]
                            print(f"  [{annotation.title}]({annotation.url})")
                            print(f"    Cited text: \"{cited_text}\"")

for (const step of interaction.steps) {
  if (step.type === 'model_output') {
    for (const contentBlock of step.content) {
      if (contentBlock.type === 'text') {
        console.log(contentBlock.text);
        if (contentBlock.annotations) {
          console.log("\nCitations:");
          for (const annotation of contentBlock.annotations) {
            if (annotation.type === 'url_citation') {
              const citedText = contentBlock.text.slice(annotation.startIndex, annotation.endIndex);
              console.log(`  [${annotation.title}](${annotation.url})`);
              console.log(`    Cited text: "${citedText}"`);
            }
          }
        }
      }
    }
  }
}

A saída vai mostrar o texto seguido das citações:

Spain won Euro 2024, defeating England 2-1 in the final. This victory marks Spain's record fourth European Championship title.

Citations:
  [aljazeera.com](https://www.aljazeera.com/sports/euro-2024-final)
    Cited text: "Spain won Euro 2024, defeating England 2-1 in the final."
  [uefa.com](https://www.uefa.com/euro2024/news/spain-wins-euro-2024)
    Cited text: "This victory marks Spain's record fourth European Championship title."

Preços

Quando você usa o embasamento com a Pesquisa Google com o Gemini 3, seu projeto é cobrado por cada consulta de pesquisa que o modelo decide executar. Se o modelo decidir executar várias consultas de pesquisa para responder a um único comando (por exemplo, pesquisar "UEFA Euro 2024 winner" e "Spain vs England Euro 2024 final score" na mesma chamada de API), isso será contabilizado como dois usos faturáveis da ferramenta para essa solicitação. Para fins de faturamento, ignoramos as consultas de pesquisa na Web vazias ao contar consultas exclusivas. Esse modelo de faturamento só se aplica aos modelos do Gemini 3. Ao usar o embasamento de pesquisa com o Gemini 2.5 ou modelos mais antigos, seu projeto é cobrado por comando.

Para informações detalhadas sobre preços, consulte a página de preços da API Gemini.

Modelos compatíveis

Você pode encontrar todos os recursos na página de visão geral do modelo.

Combinações de ferramentas compatíveis

Você pode usar o embasamento com a Pesquisa Google com outras ferramentas, como execução de código e contexto de URL para oferecer suporte a casos de uso mais complexos.

Os modelos do Gemini 3 oferecem suporte à combinação de ferramentas integradas (como o embasamento com a Pesquisa Google) com ferramentas personalizadas (chamada de função). Saiba mais na página de combinações de ferramentas.

A seguir

• Saiba mais sobre outras ferramentas disponíveis, como a chamada de função.
• Saiba como aumentar os comandos com URLs específicos usando a ferramenta de contexto de URL.