Criar um agente ADK de inteligência de localização com servidores MCP para o BigQuery e o Google Maps

1. Introdução

Neste codelab, você vai criar um agente com o ADK com tecnologia do Gemini 3.1 Pro. O agente será equipado com ferramentas de dois servidores MCP remotos (hospedados pelo Google) para acessar com segurança o BigQuery para dados demográficos, de preços e de vendas, e o Google Maps para análise e validação de localização no mundo real.

O agente organiza solicitações entre o usuário e os serviços do Google Cloud para resolver problemas de negócios relacionados ao conjunto de dados de uma padaria fictícia.

O que você vai fazer

• Configurar os dados:crie o conjunto de dados básico da padaria no BigQuery.
• Desenvolver o agente:crie um agente inteligente usando o Kit de Desenvolvimento de Agente (ADK).
• Integrar ferramentas:equipe o agente com funcionalidades do BigQuery e do Maps pelo servidor MCP.
• Analisar o mercado:interaja com o agente para avaliar as tendências e a saturação do mercado.

O que é necessário

• Um navegador da Web, como o Chrome
• Um projeto do Google Cloud com o faturamento ativado ou uma conta do Gmail.

Este codelab é destinado a desenvolvedores de todos os níveis, incluindo iniciantes. Você vai usar a interface de linha de comando no Google Cloud Shell e o código Python para o desenvolvimento do ADK. Não é necessário ser um especialista em Python, mas um conhecimento básico de como ler o código vai ajudar você a entender os conceitos.

2. Antes de começar

Criar um projeto do Google Cloud

1. No console do Google Cloud, na página de seletor de projetos, selecione ou crie um projeto na nuvem.

2. Verifique se o faturamento está ativado para seu projeto na nuvem. Saiba como verificar se o faturamento está ativado em um projeto.

Iniciar Cloud Shell

O Cloud Shell é um ambiente de linha de comando em execução no Google Cloud que vem pré-carregado com as ferramentas necessárias.

1. Clique em Ativar o Cloud Shell na parte de cima do console do Google Cloud:

2. Depois de se conectar ao Cloud Shell, execute este comando para verificar sua autenticação no Cloud Shell:

gcloud auth list

3. Execute o comando a seguir para confirmar se o projeto está configurado para uso com o gcloud:

gcloud config get project

4. Confirme se o projeto é o esperado e execute o comando abaixo para definir o ID do projeto:

export PROJECT_ID=$(gcloud config get project)

3. Buscar o código

Clone o repositório

1. Clone o repositório para o ambiente do Cloud Shell:

git clone https://github.com/google/mcp.git

2. Navegue até o diretório de demonstração:

cd mcp/examples/launchmybakery

Autenticar

Execute o comando a seguir para autenticar com sua conta do Google Cloud. Isso é necessário para que o ADK acesse o BigQuery.

gcloud auth application-default login

Siga as instruções para concluir o processo de autenticação.

Observação:o ADK não atualiza automaticamente o token OAuth 2.0. Se a sessão de chat durar mais de 60 minutos, talvez seja necessário autenticar novamente usando o comando acima.

4. Configurar o ambiente e o BigQuery

Executar scripts de configuração

1. Execute o script de configuração do ambiente. Esse script ativa as APIs BigQuery e Google Maps e cria um arquivo .env com o ID do projeto e a chave da API Maps.

chmod +x setup/setup_env.sh
./setup/setup_env.sh

2. Execute o script de configuração do BigQuery. Esse script automatiza a criação do bucket do Cloud Storage, o upload de dados e o provisionamento do conjunto de dados e das tabelas do BigQuery.

chmod +x ./setup/setup_bigquery.sh
./setup/setup_bigquery.sh

Quando o script for concluído, o conjunto de dados mcp_bakery será criado e preenchido com as seguintes tabelas:

• demographics : dados do censo e características da população por CEP.
• bakery_prices : preços da concorrência e detalhes do produto para vários produtos assados.
• sales_history_weekly : desempenho de vendas semanais (quantidade e receita) por loja e produto.
• foot_traffic : pontuações estimadas de tráfego de pedestres por CEP e horário do dia.

3. Para verificar se o conjunto de dados e as tabelas foram criados, acesse o console do BigQuery no projeto do Google Cloud:

5. Instale o ADK

Agora que a infraestrutura está pronta, vamos criar um ambiente Python virtual e instalar os pacotes necessários para o ADK.

1. Crie um ambiente virtual:

python3 -m venv .venv

2. Ative o ambiente virtual:

source .venv/bin/activate

3. Instale o ADK:

pip install google-adk==1.28.0

4. Navegue até o diretório do agente:

cd adk_agent/

6. Inspecionar o aplicativo ADK

Clique no botão Abrir editor no Cloud Shell para abrir o editor do Cloud Shell e visualizar o repositório clonado no diretório mcp/examples/launchmybakery.

O código do agente já está disponível no diretório adk_agent/. Vamos explorar a estrutura da solução:

launchmybakery/
├── data/                        # Pre-generated CSV files for BigQuery
├── adk_agent/                   # AI Agent Application (ADK)
│   └── mcp_bakery_app/          # App directory
│       ├── agent.py             # Agent definition
│       ├── tools.py             # Custom tools for the agent
│       └── .env                 # Project configuration (created by setup script)
├── setup/                       # Infrastructure setup scripts
└── cleanup/                     # Infrastructure cleanup scripts

Arquivos principais em mcp_bakery_app:

• agent.py: a lógica principal que define o agente, as ferramentas e o modelo (pré-lançamento do Gemini 3.1 Pro).
• tools.py: contém todas as definições de ferramentas personalizadas.
• .env: contém a configuração do projeto e os secrets (como chaves de API) criados pelo script de configuração.

1. Inicialização do conjunto de ferramentas do MCP:

Agora, abra adk_agent/mcp_bakery_app/tools.py no editor para entender como os conjuntos de ferramentas do MCP são inicializados.

Para permitir que nosso agente se comunique com o BigQuery e o Google Maps, precisamos configurar os clientes do Protocolo de Contexto de Modelo (MCP).

O código estabelece conexões seguras com os servidores MCP remotos do Google usando StreamableHTTPConnectionParams.

def get_maps_mcp_toolset():
    dotenv.load_dotenv()
    maps_api_key = os.getenv('MAPS_API_KEY', 'no_api_found')
    
    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=MAPS_MCP_URL,
            headers={    
                "X-Goog-Api-Key": maps_api_key
            }
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    return tools


def get_bigquery_mcp_toolset():   
        
    credentials, project_id = google.auth.default(
            scopes=["https://www.googleapis.com/auth/bigquery"]
    )

    credentials.refresh(google.auth.transport.requests.Request())
    oauth_token = credentials.token
        
    HEADERS_WITH_OAUTH = {
        "Authorization": f"Bearer {oauth_token}",
        "x-goog-user-project": project_id
    }

    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=BIGQUERY_MCP_URL,
            headers=HEADERS_WITH_OAUTH
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    return tools

• Conjunto de ferramentas do Maps:configura a conexão com o servidor MCP do Maps usando a chave de API.
• Conjunto de ferramentas do BigQuery: essa função configura a conexão com o servidor MCP do BigQuery. Ele usa google.auth para recuperar automaticamente suas credenciais do Cloud, gera um token de portador OAuth e o injeta no cabeçalho de autorização.

2. Definição do agente:

Agora, abra adk_agent/mcp_bakery_app/agent.py no editor para ver como o agente é definido.

O LlmAgent é inicializado com o modelo gemini-3.1-pro-preview.

maps_toolset = tools.get_maps_mcp_toolset()
bigquery_toolset = tools.get_bigquery_mcp_toolset()

root_agent = LlmAgent(
    model='gemini-3.1-pro-preview',
    name='root_agent',
    instruction=f"""
                Help the user answer questions by strategically combining insights from two sources:
                
                1.  **BigQuery toolset:** Access demographic (inc. foot traffic index), product pricing, and historical sales data in the  mcp_bakery dataset. Do not use any other dataset.
                Run all query jobs from project id: {project_id}. 

                2.  **Maps Toolset:** Use this for real-world location analysis, finding competition/places and calculating necessary travel routes.
                    Include a hyperlink to an interactive map in your response where appropriate.
            """,
    tools=[maps_toolset, bigquery_toolset]
)

• Instruções do sistema:o agente recebe instruções específicas para combinar insights do BigQuery (para dados) e do Maps (para análise de localização).
• Ferramentas:os maps_toolset e bigquery_toolset são atribuídos ao agente, acesso aos recursos dos dois serviços.

O agente segue as instruções e ferramentas definidas no repositório. Faça alterações nas instruções para ver como isso afeta o comportamento do agente.

7. Converse com o agente!

Volte ao terminal no Cloud Shell e execute este comando para navegar até o diretório adk_agent (se ainda não tiver feito isso):

cd adk_agent/

Execute o comando a seguir para iniciar a interface da Web do ADK. Esse comando inicia um servidor da Web leve para hospedar o aplicativo de chat:

adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'

Quando o servidor for iniciado, você verá o seguinte no Cloud Shell:

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://127.0.0.1:8000.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Você tem duas opções para acessar a interface do ADK:

Opção 1: clique no link local Clique no link http://127.0.0.1:8000 que aparece no terminal do Cloud Shell.

Opção 2: usar a visualização da Web

1. Clique no botão Visualização da Web no canto superior direito do Cloud Shell.
2. Selecione Alterar porta.
3. Insira 8000 como o número da porta e clique em Alterar e visualizar.

Interaja com o agente fazendo as seguintes perguntas na interface da Web. As ferramentas relevantes serão chamadas.

1. Encontre a vizinhança (macro) : "Quero abrir uma padaria em Los Angeles. Encontre o CEP com a maior pontuação de visitas pela manhã.

O agente precisa usar ferramentas como get_table_info e execute_sql para consultar a tabela foot_traffic no BigQuery.

2. Validar o local (micro) : "Você pode pesquisar por "Padarias" nesse CEP para ver se ele está saturado?"

O agente precisa usar as ferramentas search places no conjunto de ferramentas do Maps para responder a essa pergunta.

Chegou sua vez! Confira estas perguntas de exemplo para ver seu agente ADK em ação:

• "Quero abrir minha quarta padaria em Los Angeles. Preciso de um bairro com atividade inicial. Encontre o CEP com a maior pontuação de visitas pela manhã.
• "Você pode pesquisar por "Padarias" nesse CEP para ver se ele está saturado? Se houver muitas, procure lojas de "Café especial" para que eu possa me posicionar perto delas e capturar o tráfego de pedestres."
• "Ok, e quero posicionar isso como uma marca premium. Qual é o preço máximo cobrado por um "Pão de fermentação natural" na região metropolitana de Los Angeles?"
• "Agora quero uma projeção de receita para dezembro de 2025. Consulte meu histórico de vendas e extraia dados da minha loja de melhor desempenho para o "Pão de fermentação natural". Execute uma previsão para dezembro de 2025 para estimar a quantidade que vou vender. Em seguida, calcule a receita total projetada usando um preço premium um pouco menor do que o encontrado (vamos usar US $18).
• "Isso vai cobrir meu aluguel. Por fim, vamos verificar a logística. Encontre o "Restaurant Depot" mais próximo da área proposta e verifique se o tempo de percurso é inferior a 30 minutos para o reabastecimento diário.

Quando terminar de testar o agente, encerre a interface da Web do ADK pressionando Ctrl+C no terminal do Cloud Shell.

8. Limpeza

Para evitar cobranças contínuas na sua conta do Google Cloud, exclua os recursos criados durante este codelab.

Execute o script de limpeza. Esse script vai excluir o conjunto de dados do BigQuery, o bucket do Cloud Storage e as chaves de API criadas durante a configuração.

chmod +x ../cleanup/cleanup_env.sh
./../cleanup/cleanup_env.sh

9. Parabéns

Missão concluída! Você criou um agente de inteligência de localização usando o Kit de Desenvolvimento de Agente (ADK).

Ao preencher a lacuna entre os dados da sua empresa no BigQuery e o contexto de localização do mundo real do Google Maps, você criou uma ferramenta poderosa capaz de raciocínio comercial complexo, tudo com tecnologia do Protocolo de Contexto de Modelo (MCP) e do Gemini.

O que você realizou:

• Infraestrutura como código:você provisionou uma pilha de dados usando as ferramentas da CLI do Google Cloud.
• Integração do MCP:você conectou um agente de IA a dois servidores MCP remotos distintos (BigQuery e Maps) sem escrever wrappers de API complexos.
• Raciocínio unificado:você criou um único agente capaz de combinar estrategicamente insights de dois domínios diferentes para resolver um problema de negócios.

Documentos de referência

• Usar o servidor MCP do BigQuery
• Usar o servidor MCP do Maps Groundling Lite
• Autenticar o MCP