Nesta página, explicamos como embasar as respostas do Gemini usando resultados do mecanismo de pesquisa do Google, que usa dados da Web disponíveis publicamente. Além disso, as sugestões de pesquisa, que estão incluídas nas suas respostas, são explicadas.
Embasamento com a Pesquisa Google
Se quiser conectar seu modelo ao conhecimento mundial, a uma ampla variedade de tópicos ou a informações atualizadas na Internet, use o embasamento com a Pesquisa Google.
Para saber mais sobre o embasamento de modelo na Gemini Enterprise Agent Platform, consulte a Visão geral do embasamento.
Modelos compatíveis
Esta seção lista os modelos que oferecem suporte ao embasamento com a Pesquisa.
Clique para abrir os modelos compatíveis
- Gemini 3 Pro Image
- Criação de imagens do Gemini 3.1 Flash
- Gemini 3.5 Flash
- Gemini 3.1 Flash-Lite
- Criação de imagens do Gemini 3.1 Flash
- Gemini 3.1 Pro
- Gemini 3 Flash
- Gemini 3 Pro Image
- Gemini 2.5 Pro
- Gemini 2.5 Flash
- Gemini 2.5 Flash-Lite
- Gemini 2.5 Flash
- Gemini 2.5 Flash-Lite
- Gemini 2.5 Flash com áudio nativo da API Gemini Live
- Gemini 2.0 Flash com a API Gemini Live
Idiomas compatíveis
Para uma lista de idiomas disponíveis, consulte Idiomas.
Usar o embasamento com a Pesquisa Google
Use as instruções a seguir para embasar um modelo com dados da Web disponíveis publicamente.
Considerações
Para usar o embasamento com a Pesquisa Google, ative as Sugestões da Pesquisa Google. Para mais informações, consulte Usar as sugestões da Pesquisa Google.
Para resultados ideais, use uma temperatura de
1.0. Para saber mais sobre como definir essa configuração, consulte o Corpo da solicitação de API Gemini na referência do modelo.O embasamento na Pesquisa Google tem um limite de um milhão de consultas por dia. Se precisar de mais consultas, entre em contato com o suporte doGoogle Cloud para receber ajuda.
Os resultados da pesquisa podem ser personalizados para uma localização geográfica específica do usuário final usando as coordenadas de latitude e longitude. Para mais informações, consulte a API Grounding.
Console
Para usar o Embasamento com a Pesquisa Google no Agent Studio na Gemini Enterprise Agent Platform, siga estas etapas:
- No console Google Cloud , acesse a página Agent Studio.
- Clique na guia Formato livre.
- No painel lateral, clique no botão Embasar respostas do modelo.
- Clique em Personalizar e defina o embasamento com a Pesquisa Google como a origem.
- Insira o comando na caixa de texto e clique em Enviar.
Agora, suas respostas aos comandos usam o embasamento com a Pesquisa Google.
Python
Instalar
pip install --upgrade google-genai
Para saber mais, consulte a documentação de referência do SDK.
Defina variáveis de ambiente para usar o SDK de IA generativa com a Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Go
Saiba como instalar ou atualizar o Go.
Para saber mais, consulte a documentação de referência do SDK.
Defina variáveis de ambiente para usar o SDK de IA generativa com a Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Java
Saiba como instalar ou atualizar o Java.
Para saber mais, consulte a documentação de referência do SDK.
Defina variáveis de ambiente para usar o SDK de IA generativa com a Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Node.js
Instalar
npm install @google/genai
Para saber mais, consulte a documentação de referência do SDK.
Defina variáveis de ambiente para usar o SDK de IA generativa com a Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
REST
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- LOCATION: a região para processar a solicitação. Para usar o endpoint global, exclua o local do nome do endpoint e configure o local do recurso como global.
- PROJECT_ID: Seu [ID do projeto](/resource-manager/docs/creating-managing-projects#identifiers). .
- MODEL_ID: o ID do modelo multimodal.
- TEXT: as instruções de texto a serem incluídas no comando.
- EXCLUDE_DOMAINS: opcional. Lista de domínios que não podem ser usados para embasamento.
- LATITUDE: opcional: a latitude do local do usuário final. Por exemplo, uma latitude de
37.7749representa São Francisco. Você pode usar serviços como o Google Maps ou outras ferramentas de geocodificação para obter coordenadas de latitude e longitude. - LONGITUDE: opcional: a longitude do local do usuário final. Por exemplo, uma longitude de
-122.4194representa São Francisco.
Método HTTP e URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent
Corpo JSON da solicitação:
{
"contents": [{
"role": "user",
"parts": [{
"text": "TEXT"
}]
}],
"tools": [{
"googleSearch": {
"exclude_domains": [ "domain.com", "domain2.com" ]
}
}],
"toolConfig": {
"retrievalConfig": {
"latLng": {
"latitude": LATITUDE,
"longitude": LONGITUDE
}
}
},
"model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID"
}
Para enviar a solicitação, expanda uma destas opções:
Você receberá uma resposta JSON semelhante a esta:
{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{
"text": "The weather in Chicago this weekend, will be partly cloudy. The temperature will be between 49°F (9°C) and 55°F (13°C) on Saturday and between 51°F (11°C) and 56°F (13°C) on Sunday. There is a slight chance of rain on both days.\n"
}
]
},
"finishReason": "STOP",
"groundingMetadata": {
"webSearchQueries": [
"weather in Chicago this weekend"
],
"searchEntryPoint": {
"renderedContent": "..."
},
"groundingChunks": [
{
"web": {
"uri": "https://www.google.com/search?q=weather+in+Chicago,+IL",
"title": "Weather information for locality: Chicago, administrative_area: IL",
"domain": "google.com"
}
},
{
"web": {
"uri": "...",
"title": "weatherbug.com",
"domain": "weatherbug.com"
}
}
],
"groundingSupports": [
{
"segment": {
"startIndex": 85,
"endIndex": 214,
"text": "The temperature will be between 49°F (9°C) and 55°F (13°C) on Saturday and between 51°F (11°C) and 56°F (13°C) on Sunday."
},
"groundingChunkIndices": [
0
],
"confidenceScores": [
0.8662828
]
},
{
"segment": {
"startIndex": 215,
"endIndex": 261,
"text": "There is a slight chance of rain on both days."
},
"groundingChunkIndices": [
1,
0
],
"confidenceScores": [
0.62836814,
0.6488607
]
}
],
"retrievalMetadata": {}
}
}
],
"usageMetadata": {
"promptTokenCount": 10,
"candidatesTokenCount": 98,
"totalTokenCount": 108,
"trafficType": "ON_DEMAND",
"promptTokensDetails": [
{
"modality": "TEXT",
"tokenCount": 10
}
],
"candidatesTokensDetails": [
{
"modality": "TEXT",
"tokenCount": 98
}
]
},
"modelVersion": "gemini-2.0-flash",
"createTime": "2025-05-19T14:42:55.000643Z",
"responseId": "b0MraIMFoqnf-Q-D66G4BQ"
}
Embasamento com a Pesquisa de imagens do Google
Com o embasamento na pesquisa por imagens do Google, os modelos podem usar imagens da Web recuperadas da pesquisa por imagens do Google como contexto visual ao gerar imagens. A Pesquisa de imagens do Google é um novo tipo de pesquisa na ferramenta de embasamento com a Pesquisa Google e existe ao lado da Pesquisa Google na web padrão. O embasamento com a Pesquisa de imagens do Google está disponível em pré-lançamento apenas para o modelo de imagem do Gemini 3.1 Flash.
Configuração de solicitação de API
Para ativar a Pesquisa de imagens do Google, configure a ferramenta googleSearch na sua solicitação de API e especifique imageSearch no objeto searchTypes. Você pode usar a Pesquisa de imagens do Google de forma independente ou com a Pesquisa Google na web.
REST
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- LOCATION: a região para processar a solicitação. Para usar o endpoint global, exclua o local do nome do endpoint e configure o local do recurso como global.
- PROJECT_ID: .
- MODEL_ID: o ID do modelo multimodal.
- SEARCH_TERM: um termo de pesquisa para uma imagem.
Método HTTP e URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent
Corpo JSON da solicitação:
{
"contents": [
{
"role": "user",
"parts": [
{
"text": "SEARCH_TERM"
}
]
}
],
"tools": [
{
"googleSearch": {
"searchTypes": {
"imageSearch": {},
"webSearch": {}
}
}
}
],
"model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID"
}
Para enviar a solicitação, escolha uma destas opções:
curl
Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent"
PowerShell
Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent" | Select-Object -Expand Content
Você receberá um código de status bem-sucedido (2xx) e uma resposta vazia.
Requisitos de exibição
Ao usar a Pesquisa de imagens do Google com o embasamento com a Pesquisa Google, você precisa obedecer às seguintes condições:
Atribuição de fonte: você precisa fornecer um link para a página da Web que contém a imagem de origem (a "página que contém", não o arquivo de imagem em si) de maneira que o usuário reconheça como um link.
Navegação direta: se você também optar por mostrar as imagens de origem, será necessário fornecer um caminho direto de um único clique das imagens de origem para a página da Web de origem que as contém. Qualquer outra implementação que atrase ou abstraia o acesso dos usuários finais às páginas da Web de origem, incluindo, entre outros, qualquer caminho de vários cliques ou o uso de um visualizador de imagens intermediário, não é permitida.
Resposta
Para respostas embasadas usando a pesquisa por imagens, a API fornece atribuição e metadados claros para vincular a saída a fontes verificadas. O objeto groundingMetadata inclui os seguintes campos:
imageSearchQueries: a consulta específica usada pelo modelo para contexto visual (também conhecida como "pesquisa por imagens").groundingChunks: contém as informações de origem dos resultados recuperados. Para fontes de imagens, eles são retornados como URLs de redirecionamento usando um novo tipo de fragmento de imagem. O bloco inclui o seguinte:url: o URL da página da Web para atribuição (também conhecido como "página de destino").image_url: o URL direto da imagem.
groundingSupports: fornece mapeamentos específicos que vinculam o conteúdo gerado à fonte de citação relevante nos trechos.searchEntryPoint: inclui o ícone da Pesquisa Google que contém HTML e CSS compatíveis para renderizar as sugestões da Pesquisa Google.
Entender a resposta
Se o comando do modelo usar o embasamento com a Pesquisa Google pelo Agent Studio ou pela API, as respostas vão incluir metadados com links de origem (URLs da Web). No entanto, há vários motivos para esses metadados não serem fornecidos e a resposta ao comando não ser embasada. Esses motivos incluem baixa relevância de fonte ou informações incompletas na resposta do modelo.
Citações inline
As citações inline usam o grounding_metadata estruturado retornado pela API para
vincular segmentos específicos de texto gerado a fontes verificáveis.
Esse recurso é compatível com todos os métodos de embasamento, incluindo a Pesquisa, o Google Maps e a Pesquisa do agente, fornecendo os detalhes precisos da fonte necessários para mostrar citações interativas e precisas no seu aplicativo.
response = client.models.generate_content(
model="gemini-3.5-flash",
contents="Where will the next FIFA World Cup be held?",
config=types.GenerateContentConfig(
tools=[types.Tool(google_search=types.GoogleSearch())],
),
)
display(Markdown(response.text))
print(response.candidates[0].grounding_metadata.grounding_chunks)
display(HTML(response.candidates[0].grounding_metadata.search_entry_point.rendered_content))
Exemplo de saída:
…
Citations:
Wikipedia. "2026 FIFA World Cup." Retrieved February 11, 2026. (https://en.wikipedia.org/wiki/2026_FIFA_World_Cup)
US Soccer Players. "2026 FIFA World Cup FAQ — Dates, Hosts, Tickets, Teams & More." (https://ussoccerplayers.com/2026-fifa-world-cup-faq)
Holafly. "2026 World Cup host cities and countries: Full list of stadiums." (https://travel.holafly.com/esims/2026-world-cup-host-cities/)
…
Suporte de embasamento
É necessário mostrar o suporte de embasamento porque ele ajuda a validar as respostas dos editores e oferece caminhos para mais aprendizado.
O suporte de embasamento para respostas de fontes da Web precisa ser mostrado inline e de forma agregada. Confira a imagem abaixo como uma sugestão de como fazer isso.

Uso de opções alternativas de mecanismo de pesquisa
Ao usar o Embasamento com a Pesquisa Google, um Aplicativo do Cliente pode:
- Ofereça opções alternativas de mecanismos de pesquisa.
- Definir outros mecanismos de pesquisa como padrão
- Mostrar sugestões ou resultados de pesquisa próprios ou de terceiros, desde que: todos os resultados que não sejam do Google sejam exibidos separadamente dos resultados embasados e das sugestões de pesquisa do Google, e mostrados de uma forma que não confunda os usuários nem sugira que são do Google.
Vantagens
As seguintes solicitações e fluxos de trabalho complexos que exigem planejamento, raciocínio e pensamento podem ser feitos ao usar o embasamento com a Pesquisa Google como uma ferramenta:
- Você pode usar o embasamento para garantir que as respostas sejam baseadas nas informações mais recentes e precisas.
- Você pode recuperar artefatos da Web para fazer análises.
- Você pode encontrar imagens, vídeos ou outras mídias relevantes para ajudar no raciocínio multimodal ou na geração de tarefas.
- Você pode programar, resolver problemas técnicos e realizar outras tarefas especializadas.
- Você pode encontrar informações específicas da região ou ajudar a traduzir conteúdo com precisão.
- Você pode encontrar sites relevantes para navegar.
Usar as Sugestões da Pesquisa Google
Ao usar o embasamento com a Pesquisa Google e receber sugestões de pesquisa na sua resposta, você precisa mostrar as sugestões de pesquisa na produção e nos seus aplicativos.
Especificamente, você precisa mostrar as consultas de pesquisa incluídas nos metadados da resposta embasada. A resposta inclui:
"content": resposta gerada por LLM."webSearchQueries": as consultas a serem usadas para sugestões de pesquisa.
Por exemplo, no snippet de código a seguir, o Gemini responde a um comando baseado na Pesquisa que pergunta sobre um tipo de planta tropical.
"predictions": [
{
"content": "Monstera is a type of vine that thrives in bright indirect light…",
"groundingMetadata": {
"webSearchQueries": ["What's a monstera?"],
}
}
]
Use as sugestões da Pesquisa para mostrar essa saída.
Requisitos para sugestões de pesquisa
Os seguintes requisitos são necessários para as sugestões de pesquisa:
| Requisito | Descrição |
|---|---|
| O que fazer |
|
| O que não fazer |
|
Requisitos de exibição
Confira os requisitos de exibição:
- Mostre a sugestão de pesquisa exatamente como ela foi fornecida e não faça modificações nas cores, fontes ou aparência. Confira se a sugestão de pesquisa é renderizada conforme especificado nas seguintes simulações, como os modos claro e escuro:

- Sempre que uma resposta fundamentada for exibida, a sugestão de pesquisa correspondente deverá permanecer visível.
- Para branding, siga rigorosamente as diretrizes do Google para uso de características da marca por terceiros na Central de recursos da marca.
- Quando você usa o embasamento com a Pesquisa, os ícones de sugestão de pesquisa são mostrados. O campo que contém os chips de sugestões de pesquisa precisa ter a mesma largura da resposta embasada do LLM.
Comportamento ao tocar
Quando um usuário toca no ícone, ele é direcionado para uma página de resultados da Pesquisa (SRP) com o termo de pesquisa exibido no ícone. O SRP pode ser aberto no navegador do aplicativo ou em um aplicativo de navegador separado. É importante não minimizar, remover ou obstruir a exibição do SRP de maneira alguma. O modelo animado a seguir ilustra a interação do toque para o SRP.
Comportamento ao tocar

Código para implementar uma sugestão de pesquisa
Quando você usa a API para fundamentar uma resposta para a pesquisa, a resposta do modelo fornece estilo HTML e CSS compatível no campo renderedContent, que você implementa para exibir sugestões de pesquisa no seu aplicativo.
Além disso, as Sugestões de pesquisa eram chamadas de Pontos de entrada de pesquisa. Embora você possa encontrar referências a pontos de entrada da pesquisa em alguns campos da API, os dois termos se referem às sugestões de pesquisa atuais que você recebe na resposta da API.
Confira a seguir um exemplo de uso do curl para embasar uma resposta na pesquisa:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/PROJEC_ID/locations/global/publishers/google/models/gemini-3.5-flash:generateContent -d '{
"contents": {
"role": "user",
"parts": {
"text": "Why is the sky blue?"
}
},
"tools": [
{
"googleSearch": {}
}
]
}'
Mudanças no faturamento com o Gemini 3
Ao usar o embasamento com a Pesquisa Google nos modelos do Gemini 3, o faturamento ocorre para cada consulta de pesquisa gerada pelo Gemini e enviada à Pesquisa. Um único comando pode gerar uma ou mais consultas de pesquisa.
Exemplo
Este exemplo mostra um comando do usuário e consultas de pesquisa que podem ser cobradas.
- Comando do usuário: Conte sobre a vida de Albert Einstein.
- O Gemini pode gerar estas consultas de pesquisa:
- Nascimento e educação de Albert Einstein
- Teoria da relatividade de Albert Einstein
- A vida de Albert Einstein nos EUA
Neste exemplo, essas três consultas de pesquisa são cobradas.
A seguir
- Para saber mais sobre o embasamento, consulte Visão geral do embasamento.
- Saiba como enviar solicitações de comandos de chat.
- Saiba mais sobre as práticas recomendadas de IA responsável e os filtros de segurança da plataforma de agentes do Gemini Enterprise.