Creare un agente ADK di Location Intelligence con server MCP per BigQuery e Google Maps

1. Introduzione

In questo codelab, creerai un agente con ADK basato su Gemini 3.1 Pro. L'agente sarà dotato di strumenti di due server MCP remoti (ospitati da Google) per accedere in modo sicuro a BigQuery per i dati demografici, sui prezzi e sulle vendite e a Google Maps per l'analisi e la convalida della posizione nel mondo reale.

L'agente coordina le richieste tra l'utente e i servizi Google Cloud per risolvere i problemi aziendali relativi al set di dati fittizio della panetteria.

Attività previste

Configura i dati:crea il set di dati di base della panetteria in BigQuery.
Sviluppa l'agente:crea un agente intelligente utilizzando Agent Development Kit (ADK).
Integra strumenti:dota l'agente delle funzionalità BigQuery e Maps tramite il server MCP.
Analizza il mercato: interagisci con l'agente per valutare le tendenze e la saturazione del mercato.

Che cosa ti serve

Un browser web come Chrome
Un progetto cloud Google Cloud con la fatturazione abilitata o un account Gmail.

Questo Codelab è rivolto a sviluppatori di tutti i livelli, inclusi i principianti. Utilizzerai l'interfaccia a riga di comando in Google Cloud Shell e il codice Python per lo sviluppo dell'ADK. Non è necessario essere esperti di Python, ma una conoscenza di base della lettura del codice ti aiuterà a comprendere i concetti.

2. Prima di iniziare

Crea un progetto Google Cloud

Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.

Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata per un progetto.

Avvia Cloud Shell

Cloud Shell è un ambiente a riga di comando in esecuzione in Google Cloud che viene precaricato con gli strumenti necessari.

Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud:

Una volta connesso a Cloud Shell, esegui questo comando per verificare l'autenticazione in Cloud Shell:

gcloud auth list

Esegui questo comando per verificare che il progetto sia configurato per l'utilizzo con gcloud:

gcloud config get project

Verifica che il progetto sia quello previsto, quindi esegui il comando riportato di seguito per impostare l'ID progetto:

export PROJECT_ID=$(gcloud config get project)

3. Richiedi il codice

Clona il repository

Clona il repository nel tuo ambiente Cloud Shell:

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

Vai alla directory demo:

cd mcp/examples/launchmybakery

Autenticazione

Esegui questo comando per autenticarti con il tuo account Google Cloud. Questo è necessario per consentire all'ADK di accedere a BigQuery.

gcloud auth application-default login

Segui le istruzioni per completare la procedura di autenticazione.

4. Configura l'ambiente e BigQuery

Esegui gli script di configurazione

Esegui lo script di configurazione dell'ambiente. Questo script abilita le API BigQuery e API di Google Maps e crea un file .env con l'ID progetto e la chiave API di Google Maps.

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

Esegui lo script di configurazione di BigQuery. Questo script automatizza la creazione del bucket Cloud Storage, il caricamento dei dati e il provisioning del set di dati e delle tabelle BigQuery.

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

Al termine dello script, il set di dati mcp_bakery deve essere creato e compilato con le seguenti tabelle:

Dati demografici: dati del censimento e caratteristiche della popolazione per codice postale.
bakery_prices: prezzi della concorrenza e dettagli dei prodotti per vari prodotti da forno.
sales_history_weekly: rendimento settimanale delle vendite (quantità ed entrate) per negozio e prodotto.
foot_traffic: punteggi stimati delle visite nei punti vendita per codice postale e ora del giorno.

Verifica che il set di dati e le tabelle siano stati creati visitando la console BigQuery nel tuo progetto Google Cloud:

5. Installa ADK

Ora che l'infrastruttura è pronta, creiamo un ambiente Python virtuale e installiamo i pacchetti richiesti per l'ADK.

Crea un ambiente virtuale:

python3 -m venv .venv

Attiva l'ambiente virtuale:

source .venv/bin/activate

Installa l'ADK:

pip install google-adk==1.28.0

Vai alla directory dell'agente:

cd adk_agent/

6. Ispeziona l'applicazione ADK

Fai clic sul pulsante Apri editor in Cloud Shell per aprire l'editor di Cloud Shell e visualizzare il repository clonato nella directory mcp/examples/launchmybakery.

Il codice agente è già fornito nella directory adk_agent/. Esaminiamo la struttura della soluzione:

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

File chiave in mcp_bakery_app:

agent.py: la logica di base che definisce l'agente, i suoi strumenti e il modello (anteprima di Gemini 3.1 Pro).
tools.py: contiene eventuali definizioni di strumenti personalizzati.
.env: contiene la configurazione del progetto e i secret (come le chiavi API) creati dallo script di configurazione.

1. Inizializzazione del set di strumenti MCP:

Ora apri adk_agent/mcp_bakery_app/tools.py nell'editor per capire come vengono inizializzati i toolset MCP.

Per consentire al nostro agente di comunicare con BigQuery e Google Maps, dobbiamo configurare i client Model Context Protocol (MCP).

Il codice stabilisce connessioni sicure ai server MCP remoti di Google utilizzando 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

Maps Toolset:configura la connessione al server Maps MCP utilizzando la chiave API.
BigQuery Toolset:questa funzione configura la connessione al server BigQuery MCP. Utilizza google.auth per recuperare automaticamente le tue credenziali Cloud, genera un token OAuth Bearer e lo inserisce nell'intestazione Authorization.

2. Definizione di agente:

Ora apri adk_agent/mcp_bakery_app/agent.py nell'editor per vedere come è definito l'agente.

LlmAgent viene inizializzato con il modello 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]
)

Istruzioni di sistema:all'agente vengono fornite istruzioni specifiche per combinare le informazioni sia di BigQuery (per i dati) sia di Maps (per l'analisi della posizione).
Strumenti:sia maps_toolset che bigquery_toolset sono assegnati all'agente, che ha accesso alle funzionalità di entrambi i servizi.

L'agente rispetta le istruzioni e gli strumenti definiti nel repository. Puoi apportare modifiche alle istruzioni per vedere come influiscono sul comportamento dell'agente.

7. Chatta con il tuo agente.

Torna al terminale in Cloud Shell ed esegui questo comando per passare alla directory adk_agent (se non l'hai già fatto):

cd adk_agent/

Esegui questo comando per avviare l'interfaccia web dell'ADK. Questo comando avvia un server web leggero per ospitare l'applicazione di chat:

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

Una volta avviato il server, in Cloud Shell verrà visualizzato quanto segue:

+-----------------------------------------------------------------------------+
| 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)

Hai due opzioni per accedere alla UI dell'ADK:

Opzione 1: fai clic sul link locale. Fai clic sul link http://127.0.0.1:8000 visualizzato nel terminale Cloud Shell.

Opzione 2: utilizza l'anteprima web

Fai clic sul pulsante Anteprima web nell'angolo in alto a destra di Cloud Shell.
Seleziona Cambia porta.
Inserisci 8000 come numero di porta e fai clic su Cambia e visualizza anteprima.

Screenshot di come aprire l'interfaccia utente dell'ADK

Interagisci con l'agente ponendo le seguenti domande nell'interfaccia utente web. Dovresti vedere gli strumenti pertinenti chiamati.

Trova il quartiere (macro): "Voglio aprire una panetteria a Los Angeles. Trova il codice postale con il punteggio di visite nei punti vendita mattutine più alto.

L'agente deve utilizzare gli strumenti get_table_info e execute_sql per eseguire query sulla tabella foot_traffic in BigQuery.

Convalida della località (micro): "Puoi cercare "Panifici" in quel codice postale per vedere se è saturo?"

L'agente deve utilizzare gli strumenti search places nel set di strumenti di Maps per rispondere a questa domanda.

Prova! Dai un'occhiata a queste domande di esempio per vedere il tuo agente ADK in azione:

"Voglio aprire la mia quarta panetteria a Los Angeles. Mi serve un quartiere con attività mattutine. Trova il codice postale con il punteggio di visite nei punti vendita "mattina" più alto.
"Puoi cercare "Panifici" in quel codice postale per vedere se è saturo? Se ce ne sono troppi, cerca negozi di "caffè speciali", così posso posizionarmi vicino a loro per intercettare le visite nei punti vendita".
"Ok, voglio posizionare questo brand come brand premium. Qual è il prezzo massimo addebitato per una "pagnotta di pasta madre" nell'area metropolitana di Los Angeles?"
"Ora voglio una proiezione delle entrate per dicembre 2025. Analizza la mia cronologia delle vendite e prendi i dati del mio negozio con il rendimento migliore per il "Pane a lievitazione naturale". Esegui una previsione per dicembre 2025 per stimare la quantità che venderò. Poi, calcola le entrate totali previste utilizzando un prezzo leggermente inferiore a quello premium che abbiamo trovato (utilizziamo 18 $)."
"Così potrò pagare l'affitto. Infine, verifichiamo la logistica. Trova il "Restaurant Depot" più vicino alla zona proposta e assicurati che il tempo di guida sia inferiore a 30 minuti per il rifornimento giornaliero."

Al termine del test dell'agente, puoi terminare l'interfaccia web dell'ADK premendo Ctrl+C nel terminale Cloud Shell.

8. Esegui la pulizia

Per evitare addebiti continui al tuo account Google Cloud, elimina le risorse create durante questo Codelab.

Esegui lo script di pulizia. Questo script eliminerà il set di dati BigQuery, il bucket Cloud Storage e le chiavi API create durante la configurazione.

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

9. Complimenti

Missione completata. Hai creato correttamente un agente di intelligence sulla posizione utilizzando l'Agent Development Kit (ADK).

Colmando il divario tra i dati "aziendali" in BigQuery e il contesto della posizione nel mondo reale di Google Maps, hai creato un potente strumento in grado di eseguire ragionamenti aziendali complessi, il tutto basato sul Model Context Protocol (MCP) e Gemini.

Cosa hai ottenuto:

Infrastructure as Code:hai eseguito il provisioning di uno stack di dati utilizzando gli strumenti Google Cloud CLI.
Integrazione MCP:hai connesso un agente AI a due server MCP remoti distinti (BigQuery e Maps) senza scrivere wrapper API complessi.
Ragionamento unificato:hai creato un singolo agente in grado di combinare strategicamente approfondimenti provenienti da due domini diversi per risolvere un problema aziendale.