Tutorial do Google ADK: construindo um agente de logística com servidor MCP

O maior obstáculo hoje para construir agentes de IA sofisticados não é o modelo, e sim a integração. Se você quer que um agente acesse dez ferramentas corporativas diferentes, normalmente precisa escrever dez wrappers de API. Pela minha experiência, isso gera "fadiga de wrapper" e um grande esforço de manutenção. Sempre que uma API muda, seu agente quebra.

A solução está na parceria entre o Google Agent Development Kit (ADK) e o Model Context Protocol (MCP). Se pensarmos na IA como um trabalhador, o ADK é o "cérebro" (orquestra lógica e memória), enquanto o MCP representa as "mãos" (uma forma padronizada de pegar e usar qualquer ferramenta).

Neste tutorial, vamos construir um agente real de recuperação logística usando o ADK. O agente vai:

1. Consultar o BigQuery por pedidos atrasados com alta prioridade. 
2. Calcular a distância real de direção do armazém até o cliente usando o servidor MCP do Google Maps. 
3. Recomendar uma ação de recuperação, como upgrade para frete aéreo em remessas de longa distância.

Tudo isso sem escrever uma única linha de código de API personalizado. O agente descobre e usa as ferramentas automaticamente.

Novo no Google Cloud? Recomendo começar com o curso gratuito Introduction to GCP para entender faturamento, projetos e serviços básicos.

O que é o Google ADK?

O Google Agent Development Kit (ADK) é o framework open source e code‑first do Google para construir, testar e implantar agentes de IA. Enquanto frameworks como o LangChain focam em cadeias, o ADK é feito para execução. Ele fornece uma estrutura padronizada de como os agentes pensam, usam toolsets e rodam em ambientes de produção.

Aqui estão os conceitos-chave:

• Agents: A entidade central definida por seu modelo (por exemplo, Gemini 2.0 Flash) e seu conjunto específico de instruções.
• Toolsets: Um conjunto de capacidades. Em vez de definir ferramentas manualmente, apontamos o ADK para um servidor MCP, e ele "aprende" as ferramentas automaticamente.
• Runners: O mecanismo de execução que gerencia o estado da conversa e o loop iterativo "pensamento-ação-observação".

Usar essa abordagem code‑first permite aplicar controle de versão, testes e CI/CD como fazemos com software tradicional. Ele também oferece integração profunda com o Google, o que significa que servidores MCP gerenciados exigem quase nenhuma implantação para BigQuery ou Maps.

Para uma comparação entre os "três grandes" provedores de nuvem e seus serviços, confira nosso guia AWS vs. Azure vs. Google Cloud.

Arquitetura de integração do Google ADK e fluxo lógico

Nosso agente de recuperação logística segue um caminho de raciocínio claro para resolver um problema de negócio. Entender o fluxo ajuda quando você for escrever as instruções do prompt depois.

O loop de raciocínio segue estas etapas:

1. O agente chama o MCP do BigQuery para encontrar linhas em que status='Delayed' e priority='High'. 

2. Para cada pedido retornado, o agente extrai os endereços do armazém e do cliente. 

3. O agente chama o MCP do Google Maps para cada pedido para calcular a distância de direção. 

4. O agente aplica a lógica de negócio (por exemplo, distância acima de 500 milhas significa frete aéreo) e apresenta uma tabela em Markdown com as recomendações.

Configurando os servidores MCP

Antes de começar a codar, precisamos preparar a infraestrutura de nuvem subjacente e deixar os servidores MCP prontos. Pela minha experiência, acertar as permissões de IAM é a parte mais importante desta fase.

Passo 1: inicializando o Google Cloud CLI 

Garanta que o Google Cloud CLI esteja instalado. Para começar, abra o terminal e execute o comando abaixo para vincular seu ambiente local à sua conta Google:

gcloud init

Ao rodar isso, uma janela do navegador abrirá automaticamente. Você será solicitado a fazer login com sua conta Google. Depois de entrar, clique em Allow para dar permissão ao CLI para gerenciar seus recursos. 

De volta ao terminal, o prompt pedirá que você selecione um projeto padrão. Se já tiver criado um, escolha o ID do projeto ou crie um novo projeto pelo terminal.

Passo 2: configurando o faturamento

Para usar os serviços de API, você precisa configurar o faturamento. Dito isso, o Google Cloud oferece US$ 300 de crédito gratuito por 90 dias para testar serviços como Compute, GKE e Maps — e esses créditos gratuitos são mais que suficientes para o exemplo deste tutorial. Você só será cobrado se ativar o pagamento conforme o uso ou a pré‑paga. Para configurar o faturamento:

1. Acesse a página de faturamento do Google Console e faça login com a conta que você usa no gcloud.

2. Crie uma conta de faturamento se ainda não tiver uma (adicionar um método de pagamento é obrigatório, mas o crédito grátis é aplicado primeiro).

3. Vincule a conta de faturamento ao seu projeto: Billing → Link a project → selecione seu projeto, ou rode:

gcloud billing projects link YOUR_PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

Passo 3: habilitando APIs centrais e serviços MCP

Em seguida, precisamos habilitar as principais APIs de produtos. Elas permitem que o agente acesse serviços de dados como BigQuery e Maps.

gcloud services enable bigquery.googleapis.com
gcloud services enable compute.googleapis.com
gcloud services enable container.googleapis.com
gcloud services enable mapstools.googleapis.com

Agora, precisamos habilitar os Managed MCP Endpoints. Ajuda pensar neles como interfaces tradutoras que ficam por cima das APIs regulares. 

Primeiro, vamos guardar o ID do seu projeto e o e-mail da conta em variáveis de ambiente. Isso evita ter que digitá-los manualmente em cada comando seguinte:

export PROJECT_ID=$(gcloud config get-value project)
export USER_EMAIL=$(gcloud config get-value account)

Com essas variáveis definidas, execute os comandos abaixo para ativar os recursos beta do MCP para seu projeto específico. Esses comandos dizem ao Google para preparar os endpoints MCP remotos que seu agente vai chamar:

gcloud beta services mcp enable bigquery.googleapis.com --project=$PROJECT_ID
gcloud beta services mcp enable mapstools.googleapis.com --project=$PROJECT_ID
gcloud beta services mcp enable container.googleapis.com --project=$PROJECT_ID
gcloud beta services mcp enable compute.googleapis.com --project=$PROJECT_ID

Passo 3: configurar IAM e chaves do Maps 

O MCP usa um modelo de segurança em "duas camadas". Você precisa de permissão para falar com o próprio servidor MCP e de uma permissão separada para acessar os dados reais (como linhas em uma tabela). Dá para fazer isso pelo gcloud CLI ou pela interface do Google Cloud Console.

Opção IAM A: usando o gcloud CLI 

Para conceder à sua conta permissão para usar o MCP e interagir com o BigQuery, execute estes três comandos:

# Permissão para falar com o MCP Translator
gcloud projects add-iam-policy-binding $PROJECT_ID --member="user:$USER_EMAIL" --role="roles/mcp.toolUser"

# Permissões para executar jobs do BigQuery e ver dados
gcloud projects add-iam-policy-binding $PROJECT_ID --member="user:$USER_EMAIL" --role="roles/bigquery.jobUser"
gcloud projects add-iam-policy-binding $PROJECT_ID --member="user:$USER_EMAIL" --role="roles/bigquery.dataViewer"

Opção IAM B: usando o Google Cloud Console (UI)

Se você prefere uma interface visual, siga estes passos no navegador:

1. Acesse a página IAM & Admin no seu Google Cloud Console.
2. Encontre seu e-mail na lista e clique no ícone Edit Member (lápis).
3. Clique em Add Another Role e pesquise por MCP Tool User.
4. Repita o processo para adicionar BigQuery Data Viewer e BigQuery Job User.
5. Clique em Save.

Criar uma chave da API do Maps

Por fim, crie uma chave da API do Maps. Diferente do BigQuery, que usa suas credenciais de login, o servidor MCP do Maps usa essa chave para faturamento e controle de cota: 

gcloud alpha services api-keys create --display-name="Maps-MCP-Key"

Passo 4: validando servidores localmente com o MCP Inspector

Antes de escrever nosso código em Python, vale fazer um sanity check usando o MCP Inspector. Vamos usar o comando npx, que vem com o Node.js. 

A ideia é permitir que você rode um pacote (como o inspector) imediatamente sem precisar instalá-lo permanentemente no computador. Execute no terminal:

npx @modelcontextprotocol/inspector

Isso vai abrir uma interface web no navegador (geralmente em http://localhost:3000). Fiz escolhas específicas na lista de configuração abaixo para garantir que estamos testando a versão Remote Managed dos servidores do Google, não um mock local:

1. Transport type: Streamable HTTP. Escolhemos porque é o protocolo padrão de produção que o Google usa para servidores gerenciados.

2. URL: Insira https://mapstools.googleapis.com/mcp. Esta é a porta de entrada direta para o Maps MCP do Google.

3. Connection Type: via Proxy. Essa escolha é crítica. Ao selecionar "Proxy", o inspector usará seu login local do gcloud para lidar automaticamente com todos os handshakes de segurança.

4. Custom Headers: Adicione X-Goog-Api-Key e cole sua chave do Passo 3.

5. Clique em Connect.

Agora você deve ver o status Connected em verde. Clique no botão List Tools para ver uma lista de todas as capacidades do servidor. Se você vir compute_routes nessa lista, sua infraestrutura está perfeitamente configurada.

Para entender melhor como usar BigQuery, Maps e outros serviços Google para seus agentes, confira este tutorial sobre Google MCP Servers.

Construindo um agente de servidor MCP com o Google ADK

Com a infraestrutura pronta, podemos ir para o ambiente de desenvolvimento local. Vamos começar organizando os arquivos do projeto.

Passo 1: configurando a estrutura do projeto e dependências

Para começar, crie uma pasta para o projeto e configure um ambiente virtual.

mkdir my-agents
cd my-agents
python -m venv .venv
source .venv/bin/activate

O último comando acima é para usuários de macOS ou Linux; se você usa Windows, use .venv\Scripts\activate.

Em seguida, instale o pacote google-adk com suas bibliotecas de suporte.

pip install google-adk google-generativeai python-dotenv httpx  google-auth

Você também precisa criar um arquivo .env na pasta raiz para guardar seu PROJECT_ID e o MAPS_API_KEY gerado no passo anterior.

Passo 2: configurando os toolsets MCP

Em um script chamado tools.py, não estamos escrevendo código para "buscar dados". Em vez disso, estamos escrevendo código para conectar a um servidor que sabe como buscar dados. 

Separar as ferramentas da lógica, na minha experiência, deixa o projeto bem mais fácil de depurar. Como estamos falando com endpoints remotos do Google Cloud, usamos StreamableHTTPConnectionParams para lidar com os headers de autenticação.

import os
import google.auth
import google.auth.transport.requests
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams 

# --- BigQuery Toolset ---
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())
        
    return MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url="https://bigquery.googleapis.com/mcp",
            headers={
                "Authorization": f"Bearer {credentials.token}",
                # 'x-goog-user-project' is vital for BigQuery billing
                "x-goog-user-project": project_id,
                "Content-Type": "application/json"
            }
        )
    )

# --- Maps Toolset ---
def get_maps_mcp_toolset():
    maps_api_key = os.getenv('MAPS_API_KEY')
    
    return MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url="https://mapstools.googleapis.com/mcp",
            headers={
                "X-Goog-Api-Key": maps_api_key,
                "Content-Type": "application/json"
            }
        )
    )

Passo 3: definindo a missão do agente

Agora vamos construir o "cérebro". Pela minha experiência, usar um dos modelos Gemini Flash é a melhor escolha aqui, pois eles são incrivelmente rápidos em chamadas de ferramenta. 

Fornecemos ao agente um procedimento operacional padrão por meio das instruções no arquivo agent.py. Note como usamos um pipeline claro, em quatro etapas, para evitar que o agente se confunda.

from .tools import get_maps_mcp_toolset, get_bigquery_mcp_toolset
from google.adk.agents import LlmAgent

# We're giving the agent a very structured 'Instruction' set. 
# Think of this as the SOP (Standard Operating Procedure) for your agent.
root_agent = LlmAgent(
    model='gemini-2.0-flash',
    name='logistics_recovery_agent',
    instruction="""
      You are an expert Retail Operations Recovery Agent. 
      Your job is to find high-priority problems and solve them using the tools provided.

      Step 1: Use 'execute_sql' to find orders where status is 'Delayed' and priority is 'High'.
      Step 2: For every result, pull the warehouse and customer addresses.
      Step 3: Call the Maps 'compute_routes' tool to find the exact drive distance.
      Step 4: Use this logic: If distance > 500 miles, recommend 'Air Shipping'. 
            Otherwise, recommend 'Regional Express Ground'.
    
      Output the final result as a clean Markdown table.
    """,
    # We simply drop our toolsets here. 
    # ADK handles the complexity of deciding which tool to call when.
    tools=[get_maps_mcp_toolset(), get_bigquery_mcp_toolset()]
)

Passo 4: rodando o loop do agente 

Para executar o agente, usamos o runner. Esse componente mantém o estado da conversa para que o agente saiba o que já fez e o que precisa fazer a seguir.

from google.adk.runners import Runner
from google.genai import types

async def main():
    # The Runner acts as the host for our agent.
    runner = Runner(app_name="logistics_app", agent=root_agent)

    # Wrap the user input in the standard GenAI Content format
    user_input = "Identify high-priority delayed orders and suggest recovery shipping methods."
    content = types.Content(role="user", parts=[types.Part(text=user_input)])

    print("--- Starting Smart Logistics Agent ---")
    
    # We use run_async to stream the 'events' (Thoughts and Tool Calls)
    async for event in runner.run_async(user_id="admin_user", new_message=content):
        # We only want to print the text part of the response to the console
        if hasattr(event, 'content') and event.content.parts:
            print(event.content.parts[0].text)

O que acontece por trás dos panos?

Quando você chama runner.run_async, o ADK inicia um loop iterativo:

1. O Gemini pensa: "Eu preciso ver primeiro os pedidos atrasados."

2. O ADK age: chama a ferramenta execute_sql do seu toolset MCP do BigQuery.

3. Observação: a ferramenta retorna os dados dos pedidos.

4. O Gemini pensa: "Agora preciso das distâncias para esses dois pedidos."

5. O ADK age: chama a ferramenta MCP do Maps duas vezes.

6. Resposta final: o Gemini vê todos os dados, aplica sua lógica das "500 milhas" e formata a tabela.

Testando nosso agente do Google ADK no console web

Embora o terminal seja ótimo para logs, o ADK inclui um console web integrado que visualiza o raciocínio interno do agente. Achei essa a ferramenta mais útil para depuração.

Abra a interface executando adk web. Quando o servidor iniciar, abra o navegador em http://127.0.0.1:8000. Você verá uma interface limpa, no estilo chat, onde pode enviar o comando: "Identify high-priority delayed orders and suggest recovery shipping methods."

Analisando o execution trace

O console do ADK oferece um "trace" transparente de como o agente está interagindo com sua infraestrutura em nuvem.

Vamos detalhar passo a passo:

1. Handshakes de ferramenta: Repare nos ícones marcados como execute_sql e compute_routes. No trace, o raio indica uma invocação de ferramenta. O agente não "chutou"; ele de fato contatou o servidor MCP do BigQuery para rodar uma consulta SQL específica na sua tabela de pedidos.

2. Lógica sequencial: O trace mostra uma ordem clara de operações. Primeiro, busca os dados via BigQuery (o primeiro check). Quando tem os endereços de armazém e cliente, você vê múltiplas chamadas compute_routes. O agente está "iterando" de forma inteligente pelos pedidos atrasados para obter dados de distância do mundo real do servidor MCP do Maps.

3. Síntese final: A parte inferior do trace mostra a resposta final.

Olhe os dados:

• ORD-101: distância de 380 milhas.
• ORD-103: distância de 352 milhas.

Como demos ao agente a lógica: "Se a distância > 500 milhas, recomende Air Shipping; caso contrário, Regional Express Ground", o agente aplicou corretamente essa regra de negócio a ambos os pedidos e formatou tudo em uma bela tabela Markdown.

Conclusão

Acabamos de construir um agente de logística funcional sem escrever uma única linha de código de API personalizado para BigQuery ou Google Maps. Usando ADK e MCP, criamos uma arquitetura modular, segura e developer‑first.

O futuro da IA não é só sobre chatbots que conversam, mas sobre agentes que agem. Com essas ferramentas, estamos finalmente caminhando nessa direção.

Este tutorial pode ser um ótimo ponto de partida para seus experimentos com o Google ADK e servidores MCP: 

• Troque o BigQuery por outro dataset (ou até por um servidor MCP local de SQLite) para ver como é fácil mudar fontes de dados.
• Substitua o Maps por outro servidor MCP (por exemplo, GKE para health checks de cluster) para comprovar o caráter plug‑and‑play.
• Adicione mais lógica de negócio no prompt (comparação de custos, rascunho de e‑mail) e teste ao vivo na interface web do ADK.

Se você quer aprender mais sobre orquestração de agentes, recomendo muito se inscrever na nossa trilha de carreira Associate AI Engineer for Developers.