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 usando o Gemini 3.0 Pro. O agente será equipado com ferramentas de dois servidores MCP remotos (hospedados pelo Google) para acessar com segurança o BigQuery e obter dados demográficos, de preços e de vendas, além do Google Maps para análise e validação de locais 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 fictício da padaria.

O que você aprenderá

Configurar os dados:crie o conjunto de dados fundamental da padaria no BigQuery.
Desenvolver o agente:crie um agente inteligente usando o Kit de Desenvolvimento de Agente (ADK).
Integrar ferramentas:equipar o agente com funcionalidades do BigQuery e do Maps usando o servidor MCP.
Analise 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, inclusive iniciantes. Você vai usar a interface de linha de comando no Cloud Shell e o código Python para desenvolvimento do ADK. Você não precisa ser um especialista em Python, mas um entendimento básico de como ler código vai ajudar a entender os conceitos.

2. Antes de começar

Criar um projeto do Google Cloud

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

Verifique se o faturamento está ativado para seu projeto do Cloud. Saiba como verificar se o faturamento está ativado em um projeto.

Inicie o Cloud Shell

O Cloud Shell é um ambiente de linha de comando executado no Google Cloud que vem pré-carregado com as ferramentas necessárias.

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

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

gcloud auth list

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

gcloud config get project

Confirme se o projeto está como esperado e execute o comando abaixo para definir o ID do projeto:

export PROJECT_ID=$(gcloud config get project)

3. Buscar o código

Clonar o repositório

Clone o repositório no ambiente do Cloud Shell:

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

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

cd mcp/examples/launchmybakery

Autenticar

Execute o comando a seguir para fazer a autenticação 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.

4. Configurar o ambiente e o BigQuery

Executar scripts de configuração

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

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

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:

Informações demográficas: dados do censo e características da população por CEP.
bakery_prices: preços da concorrência e detalhes de produtos para vários itens de padaria.
sales_history_weekly: performance de vendas semanal (quantidade e receita) por loja e produto.
foot_traffic: estimativas de pontuações de visitas por CEP e hora do dia.

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

5. Instale o ADK

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

Crie um ambiente virtual:

python3 -m venv .venv

Ative o ambiente virtual:

source .venv/bin/activate

Instale o ADK:

pip install google-adk

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 ver 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 analisar 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évia do Gemini 3.0 Pro).
tools.py: contém definições de ferramentas personalizadas.
.env: contém a configuração do projeto e os segredos (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 do modelo (MCP, na sigla em inglês).

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 sua 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 de 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-pro-preview.

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

root_agent = LlmAgent(
    model='gemini-3-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 local).
Ferramentas:o maps_toolset e o bigquery_toolset são atribuídos ao agente, a ele acesso aos recursos dos dois serviços.

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

7. Converse com seu agente!

Volte ao terminal no Cloud Shell e execute este comando para acessar o diretório adk_agent:

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

Depois que o servidor for iniciado, você poderá conversar com seu agente clicando no URL fornecido para iniciar a interface da Web do ADK.

Interaja com o agente fazendo as seguintes perguntas. As ferramentas relevantes vão aparecer sendo chamadas.

Encontrar o bairro (macro): "Quero abrir uma padaria em Los Angeles. Encontre o CEP com a maior pontuação de fluxo de pedestres pela manhã."

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

Valide o local (micro): "Você pode pesquisar'Padarias' nesse CEP para ver se 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 do ADK em ação:

"Quero abrir minha quarta padaria em Los Angeles. Preciso de um bairro com atividade matinal. Encontre o CEP com a maior pontuação de tráfego a pé pela manhã".
"Você pode pesquisar'Padarias' nesse CEP para ver se ele está saturado? Se houver muitas, procure por lojas de "café especial" para que eu possa me posicionar perto delas e capturar o fluxo 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 área metropolitana de Los Angeles?"
"Agora quero uma projeção de receita para dezembro de 2025. Analise meu histórico de vendas e use os dados da minha loja de melhor desempenho para o "Pão de fermentação natural". Gere uma previsão para dezembro de 2025 e estime a quantidade que vou vender. Em seguida, calcule a receita total projetada usando um valor um pouco abaixo do preço premium que encontramos (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 viagem é inferior a 30 minutos para reabastecimento diário."

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 no Google Maps, você criou uma ferramenta poderosa capaz de fazer raciocínios comerciais complexos, tudo com tecnologia do Protocolo de contexto do modelo (MCP) e do Gemini.

O que você fez:

Infraestrutura como código:você provisionou uma pilha de dados usando 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.