O Google Search Grounding transforma agentes de IA de repositórios estáticos de conhecimento em assistentes dinâmicos e conectados à web, capazes de fornecer informações precisas e em tempo real. Ao integrar esse recurso aos seus agentes do ADK, você permite que eles:
- Acesse informações atuais além dos dados de treinamento
- Forneça atribuição de fonte para transparência e confiança
- Forneça respostas abrangentes com fatos verificáveis
Melhore a experiência do usuário com sugestões de pesquisa relevantes
O processo de aterramento conecta perfeitamente as consultas dos usuários ao vasto índice de busca do Google, enriquecendo as respostas com contexto atualizado e mantendo o fluxo da conversa. Com a implementação e exibição adequadas de respostas aterradas, seus agentes se tornam ferramentas poderosas para descoberta de informações e tomada de decisões.
A ferramenta Google Search Grounding é um recurso poderoso do Kit de Desenvolvimento de Agentes (ADK - Agent Development Kit) que permite que agentes de IA acessem informações confiáveis e em tempo real da web. Ao conectar seus agentes à Pesquisa Google, você pode fornecer aos usuários respostas atualizadas e respaldadas por fontes confiáveis.
Esse recurso é particularmente útil para consultas que exigem informações atuais, como atualizações meteorológicas, notícias sobre eventos, preços de ações ou quaisquer fatos que possam ter mudado desde o corte dos dados de treinamento do modelo. Quando o seu agente determina que informações externas são necessárias, ele realiza automaticamente pesquisas na web e incorpora os resultados em sua resposta com a devida atribuição.
Início rápido do Google Search Grounding
Este guia de início rápido orienta você na criação de um agente ADK com o recurso de Google Search Grounding. Este guia de início rápido pressupõe um IDE local (VS Code ou PyCharm, etc.) com Python 3.9+ e acesso ao terminal.
1. Configurar ambiente e instalar o ADK
Criar e ativar ambiente virtual:
# Create
python -m venv .venv
# Activate (each new terminal)
# macOS/Linux: source .venv/bin/activate
# Windows CMD: .venv\Scripts\activate.bat
# Windows PowerShell: .venv\Scripts\Activate.ps1
Instalar o ADK:
pip install google-adk==1.4.2
2. Criar projeto de agente
Em um diretório de projeto, execute os seguintes comandos:
OS X e Linux
# Step 1: Create a new directory for your agent
mkdir google_search_agent
# Step 2: Create __init__.py for the agent
echo "from . import agent" > google_search_agent/__init__.py
# Step 3: Create an agent.py (the agent definition) and .env (Gemini authentication config)
touch google_search_agent/agent.py .env
Windows
# Step 1: Create a new directory for your agent
mkdir google_search_agent
# Step 2: Create __init__.py for the agent
echo "from . import agent" > google_search_agent/__init__.py
# Step 3: Create an agent.py (the agent definition) and .env (Gemini authentication config)
type nul > google_search_agent\agent.py
type nul > google_search_agent\.env
Editar agent.py
Copie e cole o seguinte código em agent.py:
google_search_agent/agent.py
from google.adk.agents import Agent
from google.adk.tools import google_search
root_agent = Agent(
name="google_search_agent",
model="gemini-2.5-flash",
instruction="Answer questions using Google Search when needed. Always cite sources.",
description="Professional search assistant with Google Search capabilities",
tools=[google_search]
)
Agora você teria a seguinte estrutura de diretório:
my_project/
google_search_agent/
__init__.py
agent.py
.env
3. Escolha uma plataforma
Para executar o agente, você precisa selecionar uma plataforma que o agente usará para chamar o modelo Gemini. Escolha entre Google AI Studio ou Vertex AI:
Gemini - Estúdio de IA do Google
Obtenha uma chave de API do Google AI Studio.
Ao usar Python, abra o arquivo .env, copie e cole o código a seguir.
.env
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=PASTE_YOUR_ACTUAL_API_KEY_HERE
Substitua PASTE_YOUR_ACTUAL_API_KEY_HEREpelo seu API KEY.
Gemini - Google Cloud Vertex IA
Você precisa de uma conta existente do Google Cloud e de um projeto.
Configurar um projeto do Google Cloud
Configurar a CLI do gcloud
Autentique-se no Google Cloud a partir do terminal executando gcloud auth login.
Habilite a API do Vertex AI.
Ao usar Python, abra o .env arquivo, copie e cole o código a seguir e atualize o ID e o local do projeto.
.env
GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=LOCATION
4. Execute seu agente
Existem várias maneiras de interagir com seu agente:
Interface de usuário de desenvolvimento (adk web)
Execute o seguinte comando para iniciar a interface de desenvolvimento .
adk web
Nota para usuários do Windows: Ao clicar em _make_subprocess_transport NotImplementedError, considere usar adk web --no-reload em vez disso.
Etapa 1: Abra a URL fornecida (geralmente http://localhost:8000ou http://127.0.0.1:8000) diretamente no seu navegador.
Etapa 2: No canto superior esquerdo da interface, você pode selecionar seu agente no menu suspenso. Selecione "google_search_agent".
Solução de problemas: Se você não vir "google_search_agent" no menu suspenso, certifique-se de que está executando adk web na pasta pai da pasta do seu agente (ou seja, a pasta pai do google_search_agent).
Etapa 3: Agora você pode conversar com seu agente usando a caixa de texto.
Terminal (execução adk)
Execute o seguinte comando para conversar com seu agente do Weather.
adk run google_search_agent
Para sair, use Cmd/Ctrl+C.
📝 Exemplos de prompts para tentar
Com essas perguntas, você pode confirmar se o agente está realmente acessando o Google Search para obter as últimas informações sobre o clima e a hora.
- Como é o clima em Nova York?
- Que horas são em Nova York?
- Como é o clima em Paris?
- Que horas são em Paris?
Como funciona o Google Search Grounding
O Google Search Grounding é o processo que conecta seu agente a informações em tempo real da web, permitindo que ele gere respostas mais precisas e atualizadas. Quando o prompt de um usuário solicita informações com as quais o modelo não foi treinado, ou que são sensíveis ao tempo, o Large Language Model subjacente do agente decide, de forma inteligente, invocar a ferramenta google_search para encontrar os fatos relevantes.
Diagrama de fluxo de dados
O diagrama abaixo ilustra o processo passo a passo de como uma consulta do usuário resulta em uma resposta fundamentada.
Descrição detalhada
O agente de Grounding usa o fluxo de dados descrito no diagrama para recuperar, processar e incorporar informações externas na resposta final apresentada ao usuário.
Consulta do usuário: um usuário final interage com seu agente fazendo uma pergunta ou dando um comando.
Orquestração do ADK: O Agent Development Kit orquestra o comportamento do agente e passa a mensagem do usuário para o núcleo do seu agente.
Análise de LLM e Chamada de Ferramentas: O LLM do agente (por exemplo, um modelo Gemini) analisa o prompt. Se determinar que informações externas atualizadas são necessárias, ele aciona o mecanismo de aterramento chamando a ferramenta google_search. Isso é ideal para responder a consultas sobre notícias recentes, previsão do tempo ou fatos não presentes nos dados de treinamento do modelo.
Interação do serviço de aterramento: a ferramenta google_search interage com um serviço de aterramento interno que formula e envia uma ou mais consultas ao Índice de Pesquisa do Google.
Injeção de Contexto: O serviço de Grounding recupera as páginas da web e os snippets relevantes. Em seguida, ele integra esses resultados de pesquisa ao contexto do modelo antes que a resposta final seja gerada. Essa etapa crucial permite que o modelo "raciocine" sobre dados factuais e em tempo real.
Geração de Resposta Fundamentada: O LLM, agora informado pelos novos resultados da pesquisa, gera uma resposta que incorpora as informações recuperadas.
Apresentação da Resposta com Fontes: O ADK recebe a resposta final fundamentada, que inclui os URLs de origem e os groundingMetadata necessários, e a apresenta ao usuário com atribuição. Isso permite que os usuários finais verifiquem as informações e gera confiança nas respostas do agente.
Compreendendo o aterramento com a resposta da Pesquisa Google
Quando o agente usa a Pesquisa Google para fundamentar uma resposta, ele retorna um conjunto detalhado de informações que inclui não apenas a resposta final em texto, mas também as fontes utilizadas para gerá-la. Esses metadados são cruciais para verificar a resposta e atribuir a atribuição às fontes originais.
Exemplo de uma resposta fundamentada
A seguir está um exemplo do objeto de conteúdo retornado pelo modelo após uma consulta fundamentada.
Texto da resposta final:
"Yes, Inter Miami won their last game in the FIFA Club World Cup. They defeated FC Porto 2-1 in their second group stage match. Their first game in the tournament was a 0-0 draw against Al Ahly FC. Inter Miami is scheduled to play their third group stage match against Palmeiras on Monday, June 23, 2025."
Trecho de metadados de aterramento:
"groundingMetadata": {
"groundingChunks": [
{ "web": { "title": "mlssoccer.com", "uri": "..." } },
{ "web": { "title": "intermiamicf.com", "uri": "..." } },
{ "web": { "title": "mlssoccer.com", "uri": "..." } }
],
"groundingSupports": [
{
"groundingChunkIndices": [0, 1],
"segment": {
"startIndex": 65,
"endIndex": 126,
"text": "They defeated FC Porto 2-1 in their second group stage match."
}
},
{
"groundingChunkIndices": [1],
"segment": {
"startIndex": 127,
"endIndex": 196,
"text": "Their first game in the tournament was a 0-0 draw against Al Ahly FC."
}
},
{
"groundingChunkIndices": [0, 2],
"segment": {
"startIndex": 197,
"endIndex": 303,
"text": "Inter Miami is scheduled to play their third group stage match against Palmeiras on Monday, June 23, 2025."
}
}
],
"searchEntryPoint": { ... }
}
Como interpretar a resposta
Os metadados fornecem um link entre o texto gerado pelo modelo e as fontes que o suportam. Aqui está uma análise passo a passo:
groundingChunks: Esta é uma lista das páginas da web consultadas pelo modelo. Cada pedaço contém o título da página e um URI que leva à fonte.
groundingSupports: Esta lista conecta frases específicas na resposta final de volta aos groundingChunks.
segmento: Este objeto identifica uma parte específica da resposta do texto final, definida por seu startIndex, endIndex e o próprio texto.
groundingChunkIndices: Esta matriz contém os números de índice que correspondem às fontes listadas em groundingChunks. Por exemplo, a frase "Eles derrotaram o FC Porto por 2 a 1..." é corroborada por informações de groundingChunks nos índices 0 e 1 (ambos de mlssoccer.com e intermiamicf.com).
Como exibir respostas de aterramento com a Pesquisa Google
Uma parte essencial do uso do grounding é exibir corretamente as informações, incluindo citações e sugestões de pesquisa, ao usuário final. Isso gera confiança e permite que os usuários verifiquem as informações.
Exibindo sugestões de pesquisa
O searchEntryPointobjeto em groundingMetadata contém HTML pré-formatado para exibir sugestões de consultas de pesquisa. Como visto na imagem de exemplo, elas geralmente são renderizadas como ícones clicáveis que permitem ao usuário explorar tópicos relacionados.
HTML renderizado de searchEntryPoint: Os metadados fornecem o HTML e o CSS necessários para renderizar a barra de sugestões de pesquisa, que inclui o logotipo do Google e ícones para consultas relacionadas, como "Quando será a próxima Copa do Mundo de Clubes da FIFA" e "Histórico da Copa do Mundo de Clubes da FIFA do Inter Miami". Integrar esse HTML diretamente no front-end do seu aplicativo exibirá as sugestões conforme o esperado.
👉 Siga André Bernardes no Linkedin. Clique aqui e contate-me via What's App.
