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.0 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 della panetteria fittizia.

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 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 di come leggere il 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 della demo:

cd mcp/examples/launchmybakery

Autenticare

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 Google Maps e crea un file .env con l'ID progetto e la chiave API 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 del traffico pedonale 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

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.0 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 set di strumenti 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

Strumenti di Maps:configura la connessione al server Maps MCP utilizzando la chiave API.
BigQuery Toolset:questa funzione configura la connessione al server MCP BigQuery. 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-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]
)

Istruzioni di sistema:all'agente vengono fornite istruzioni specifiche per combinare le informazioni ricavate da BigQuery (per i dati) e 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. Sentiti libero di 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:

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

Una volta avviato il server, puoi chattare con l'agente facendo clic sull'URL fornito per avviare l'interfaccia web dell'ADK.

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

Trova il quartiere (macro): "Voglio aprire una panetteria a Los Angeles. Trova il codice postale con il punteggio più alto di traffico pedonale mattutino."

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 l'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 traffico a piedi "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 il traffico pedonale".
"Ok, voglio posizionarlo 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 percorrenza sia inferiore a 30 minuti per il rifornimento giornaliero."

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 Location Intelligence utilizzando 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 su Gemini.

Cosa hai fatto:

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.