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 você a criar aplicativos que podem:
- Aumentar a acurácia factual:reduza as alucinações do modelo embasando as respostas em informações do mundo real.
- Acessar informações em tempo real:responda a perguntas sobre eventos e temas recentes.
Forneça citações:conquiste a confiança do usuário mostrando as fontes das declarações do modelo.
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3.8-flash",
input="Who won the euro 2024?",
tools=[{"type": "google_search"}]
)
print(interaction.output_text)
JavaScript
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: "gemini-3.8-flash",
input: "Who won the euro 2024?",
tools: [{ type: "google_search" }]
});
console.log(interaction.output_text);
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
Client client = new Client();
CreateModelInteraction params =
CreateModelInteraction.builder()
.model(Model.of("gemini-3.8-flash"))
.input(InteractionsInput.of("Who won the euro 2024?"))
.tools(Arrays.asList(GoogleSearch.builder().build()))
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
Go
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(
interactions.CreateModelInteraction{
Model: interactions.Model("gemini-3.8-flash"),
Input: interactions.NewInteractionsInput("Who won the euro 2024?"),
Tools: []interactions.Tool{
interactions.NewTool(interactions.GoogleSearch{}),
},
},
),
})
if err != nil {
log.Fatal(err)
}
fmt.Println(resp.Interaction.GetOutputText())
}
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3.8-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, tratamento e citação de informações automaticamente.
- Comando do usuário:seu aplicativo envia um comando do usuário à API Gemini
com a ferramenta
google_searchativada. - Análise de comandos:o modelo analisa o comando e determina se uma Pesquisa Google pode melhorar a resposta.
- Pesquisa Google:se necessário, o modelo gera e executa automaticamente uma ou várias consultas de pesquisa.
- Processamento dos resultados da pesquisa:o modelo processa os resultados da pesquisa, sintetiza as informações e formula uma resposta.
- Resposta embasada:a API retorna uma resposta final e fácil de usar que se baseia nos resultados da pesquisa. Essa resposta inclui a resposta de texto do modelo com
annotationsinline contendo as citações, bem como as etapasgoogle_search_callegoogle_search_resultcom as consultas e sugestões de pesquisa.
Entender a resposta de embasamento
Quando uma resposta é fundamentada, 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 campos principais na resposta:
google_search_call: contém a pesquisaqueriesexecutada pelo modelo.google_search_result: contémsearch_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.textcomannotations: a resposta sintetizada do modelo com citações inline. Cada anotaçãourl_citationvincula um segmento de texto (definido porstart_indexeend_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 públicos da Web 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,
a você controle total sobre como exibir as fontes na interface do usuário.
Cada anotação inclui start_index e end_index para identificar qual parte do texto ela cita. Veja como extrair e mostrar esses dados.
Python
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}\"")
JavaScript
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}"`);
}
}
}
}
}
}
}
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Annotation;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.URLCitation;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
Client client = new Client();
CreateModelInteraction params =
CreateModelInteraction.builder()
.model(Model.of("gemini-3.8-flash"))
.input(InteractionsInput.of("Who won the euro 2024?"))
.tools(Arrays.asList(GoogleSearch.builder().build()))
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
if (interaction.steps().isPresent()) {
for (Step step : interaction.steps().get()) {
if (step instanceof ModelOutputStep) {
ModelOutputStep outputStep = (ModelOutputStep) step;
if (outputStep.content().isPresent()) {
for (Content contentBlock : outputStep.content().get()) {
if (contentBlock instanceof TextContent) {
TextContent textContent = (TextContent) contentBlock;
String text = textContent.text().orElse("");
System.out.println(text);
if (textContent.annotations().isPresent()
&& !textContent.annotations().get().isEmpty()) {
System.out.println("\nCitations:");
for (Annotation annotation : textContent.annotations().get()) {
if (annotation instanceof URLCitation) {
URLCitation citation = (URLCitation) annotation;
int start = citation.startIndex().orElse(0);
int end = citation.endIndex().orElse(0);
String citedText =
(start >= 0 && end <= text.length() && start <= end)
? text.substring(start, end)
: "";
System.out.printf(
" [%s](%s)%n", citation.title().orElse(""), citation.url().orElse(""));
System.out.printf(" Cited text: \"%s\"%n", citedText);
}
}
}
}
}
}
}
}
}
Go
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(
interactions.CreateModelInteraction{
Model: interactions.Model("gemini-3.8-flash"),
Input: interactions.NewInteractionsInput("Who won the euro 2024?"),
Tools: []interactions.Tool{
interactions.NewTool(interactions.GoogleSearch{}),
},
},
),
})
if err != nil {
log.Fatal(err)
}
for _, step := range resp.Interaction.Steps {
if step.ModelOutputStep != nil {
for _, content := range step.ModelOutputStep.Content {
if content.TextContent != nil {
text := content.TextContent.Text
fmt.Println(text)
if len(content.TextContent.Annotations) > 0 {
fmt.Println("\nCitations:")
for _, annotation := range content.TextContent.Annotations {
if annotation.URLCitation != nil {
c := annotation.URLCitation
start := 0
if c.StartIndex != nil {
start = *c.StartIndex
}
end := 0
if c.EndIndex != nil {
end = *c.EndIndex
}
citedText := ""
if start >= 0 && end <= len(text) && start <= end {
citedText = text[start:end]
}
title := ""
if c.Title != nil {
title = *c.Title
}
url := ""
if c.URL != nil {
url = *c.URL
}
fmt.Printf(" [%s](%s)\n", title, url)
fmt.Printf(" Cited text: %q\n", 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 se aplica apenas aos modelos do Gemini 3. Ao usar o embasamento da pesquisa com o Gemini 2.5 ou modelos mais antigos, seu projeto é faturado por comando.
Para informações detalhadas sobre preços, consulte a página de preços da API Gemini.
Modelos compatíveis
Confira todos os recursos na página Visão geral do modelo.
| Modelo | Embasamento com a Pesquisa Google |
|---|---|
| Gemini 3.8 Flash | ✔️ |
| Gemini 3.7 Flash | ✔️ |
| Gemini 3.6 Flash | ✔️ |
| Gemini 3.5 Flash Lite | ✔️ |
| Gemini 3.5 Flash | ✔️ |
| Pré-lançamento da imagem do Gemini 3.1 Flash | ✔️ |
| Pré-lançamento do Gemini 3.1 Pro | ✔️ |
| Pré-lançamento do Gemini 3 Pro Image | ✔️ |
| Pré-lançamento do Gemini 3 Flash | ✔️ |
| Gemini 2.5 Pro | ✔️ |
| Gemini 2.5 Flash | ✔️ |
| Gemini 2.5 Flash Lite | ✔️ |
| Gemini 2.0 Flash | ✔️ |
Combinações de ferramentas compatíveis
Você pode usar o embasamento com a Pesquisa Google e outras ferramentas, como execução de código, contexto de URL e embasamento com o Google Maps (disponível no Gemini 3.5 Flash e modelos mais recentes) para casos de uso mais complexos. Os modelos do Gemini 3 também permitem combinar essas ferramentas integradas com ferramentas personalizadas (chamada de função). Saiba mais na página Combinações de ferramentas.
A seguir
- Saiba mais sobre outras ferramentas disponíveis, como a chamada de função.
- Aprenda a aumentar os comandos com URLs específicos usando a ferramenta de contexto de URL.