Tutorial Google ADK: creare un agente logistico con server MCP

L’ostacolo più grande nella creazione di agenti AI sofisticati oggi non è il modello, ma l’integrazione. Se vuoi che un agente acceda a dieci diversi strumenti aziendali, di solito devi scrivere dieci diversi wrapper per le API. Per esperienza, questo porta a “stanchezza da wrapper” e a un enorme onere di manutenzione. Ogni volta che un’API cambia, il tuo agente si rompe.

La soluzione sta nella partnership tra il Google Agent Development Kit (ADK) e il Model Context Protocol (MCP). Se pensiamo all’AI come a un lavoratore, l’ADK è il "cervello" (che orchestra logica e memoria), mentre MCP rappresenta le "mani" (un modo standardizzato per prendere e usare qualsiasi strumento).

In questo tutorial, costruiremo un vero agente di recupero logistico usando ADK. L’agente:

1. Interrogherà BigQuery per ordini in ritardo ad alta priorità. 
2. Calcolerà la distanza di guida reale dal magazzino al cliente usando il server MCP di Google Maps. 
3. Consiglierà un’azione di recupero, ad esempio l’upgrade alla spedizione aerea per spedizioni a lunga distanza.

Tutto questo avviene senza scrivere una sola riga di codice API personalizzato. L’agente scopre e usa gli strumenti in automatico.

Nuovo su Google Cloud? Ti consiglio di iniziare con il corso gratuito Introduction to GCP per coprire billing, progetti e servizi di base.

Che cos’è Google ADK?

Il Google Agent Development Kit (ADK) è il framework open-source e code‑first di Google per creare, testare e distribuire agenti AI. Mentre framework come LangChain si concentrano sulle chain, ADK è pensato per l’esecuzione. Fornisce una struttura standardizzata su come gli agenti pensano, usano i toolset e girano in ambienti di produzione.

Ecco i concetti chiave:

• Agent: l’entità principale definita dal suo modello (ad es. Gemini 2.0 Flash) e dal suo set specifico di istruzioni.
• Toolset: una collezione di capacità. Invece di definire gli strumenti manualmente, puntiamo l’ADK a un server MCP, e lui "impara" automaticamente gli strumenti.
• Runner: il motore di esecuzione che gestisce lo stato della conversazione e il loop iterativo "pensiero‑azione‑osservazione".

Questo approccio code‑first ci consente di usare il version control, il testing e la CI/CD come nel software tradizionale. Offre anche un’integrazione profonda con Google, per cui i server MCP gestiti richiedono quasi zero deploy per BigQuery o Maps.

Per un confronto tra i tre grandi provider cloud e i loro servizi, dai un’occhiata alla nostra guida su AWS vs. Azure vs. Google Cloud.

Architettura di integrazione e flusso logico di Google ADK

Il nostro agente di recupero logistico segue un percorso di ragionamento chiaro per risolvere un problema di business. Capire il flusso aiuta quando inizierai a scrivere le istruzioni del prompt.

Il loop di ragionamento segue questi passaggi:

1. L’agente chiama il server MCP di BigQuery per trovare le righe in cui status='Delayed' e priority='High'. 

2. Per ogni ordine restituito, l’agente estrae gli indirizzi del magazzino e del cliente. 

3. L’agente chiama il server MCP di Google Maps per ogni ordine per calcolare la distanza di guida. 

4. L’agente applica la logica di business (ad es., una distanza superiore a 500 miglia implica spedizione aerea) e presenta una tabella in markdown con le raccomandazioni.

Configurazione dei server MCP

Prima di iniziare a scrivere codice, dobbiamo preparare l’infrastruttura cloud sottostante e rendere pronti i server MCP. Per esperienza, ottenere i permessi IAM corretti è la parte più importante di questa fase.

Passaggio 1: inizializzare la Google Cloud CLI 

Assicurati di avere installata la Google Cloud CLI. Per iniziare, apri il terminale ed esegui il seguente comando per collegare l’ambiente locale al tuo account Google:

gcloud init

Una volta eseguito, si aprirà automaticamente una finestra del browser. Ti verrà chiesto di accedere con il tuo account Google. Dopo l’accesso, fai clic su Allow per concedere alla CLI il permesso di gestire le tue risorse. 

Tornando al terminale, il prompt ti chiederà di selezionare un progetto predefinito. Se ne hai già creato uno, scegli l’ID del progetto, oppure crea un nuovo progetto nel terminale.

Passaggio 2: impostare il billing

Per usare i servizi API, devi impostare il billing. Detto questo, Google Cloud ti offre 300 $ di credito gratuito per 90 giorni per provare servizi come Compute, GKE e Maps, e quei crediti gratuiti sono più che sufficienti per l’esempio in questo tutorial. Paghi solo se attivi il pay‑as‑you‑go o la ricarica anticipata. Per configurare il billing:

1. Vai alla pagina billing della Google Console ed effettua l’accesso con l’account che usi per gcloud.

2. Crea un account di fatturazione se non ne hai uno (è necessario aggiungere un metodo di pagamento, ma il credito gratuito viene applicato per primo).

3. Collega l’account di fatturazione al tuo progetto: Billing → Link a project → seleziona il tuo progetto, oppure esegui:

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

Passaggio 3: abilitare le API core e i servizi MCP

Successivamente, dobbiamo abilitare le API principali del prodotto. Queste consentono all’agente di raggiungere i servizi dati grezzi come 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

Ora dobbiamo abilitare i Managed MCP Endpoints. Trovo utile pensarli come interfacce di traduzione che si appoggiano alle normali API. 

Per prima cosa, salviamo l’ID del tuo progetto e l’email dell’account in variabili d’ambiente. Questo evita di doverle digitare manualmente per ogni comando successivo:

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

Con queste variabili impostate, esegui i seguenti comandi per attivare le funzionalità beta MCP per il tuo progetto specifico. Questi comandi dicono a Google di preparare gli endpoint MCP remoti che il tuo agente chiamerà:

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

Passaggio 3: configurare IAM e chiavi Maps 

MCP utilizza un modello di sicurezza a "doppio livello". Ti serve il permesso per parlare con il server MCP stesso e un permesso separato per accedere ai dati effettivi (come le righe di una tabella). Puoi farlo usando la gcloud CLI o la UI della Google Cloud Console.

Opzione IAM A: usare la gcloud CLI 

Per concedere al tuo account il permesso di usare MCP e interagire con BigQuery, esegui questi tre comandi:

# Permission to talk to the MCP Translator
gcloud projects add-iam-policy-binding $PROJECT_ID --member="user:$USER_EMAIL" --role="roles/mcp.toolUser"

# Permissions to run BigQuery jobs and view data
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"

Opzione IAM B: usare la Google Cloud Console (UI)

Se preferisci un’interfaccia visiva, puoi seguire questi passaggi nel browser:

1. Vai alla pagina IAM & Admin nella tua Google Cloud Console.
2. Trova il tuo indirizzo email nell’elenco e fai clic sull’icona Edit Member (matita).
3. Fai clic su Add Another Role e cerca MCP Tool User.
4. Ripeti il processo per aggiungere BigQuery Data Viewer e BigQuery Job User.
5. Fai clic su Save.

Crea una chiave API di Maps

Infine, crea una chiave API di Maps. A differenza di BigQuery, che usa le tue credenziali di accesso, il server MCP di Maps utilizza questa chiave per il billing e il tracciamento delle quote: 

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

Passaggio 4: validare i server in locale con MCP Inspector

Prima di scrivere il nostro codice Python, facciamo un sanity check usando MCP Inspector. Useremo il comando npx, uno strumento che viene con Node.js. 

Serve per eseguire immediatamente un pacchetto (come l’inspector) senza doverlo installare in modo permanente sul computer. Esegui questo nel terminale:

npx @modelcontextprotocol/inspector

Questo avvierà un’interfaccia web nel browser (di solito su http://localhost:3000). Ho fatto scelte specifiche nell’elenco di setup qui sotto per assicurarci di testare la versione Remote Managed dei server Google, non un mock locale:

1. Transport type: Streamable HTTP. Lo scegliamo perché è il protocollo standard di produzione che Google usa per i server cloud gestiti.

2. URL: Inserisci https://mapstools.googleapis.com/mcp. È la porta d’ingresso diretta al MCP di Maps di Google.

3. Connection Type: via Proxy. Scelta fondamentale. Selezionando "Proxy", l’inspector userà il tuo login locale gcloud per gestire automaticamente tutti i complessi handshake di sicurezza.

4. Custom Headers: Aggiungi X-Goog-Api-Key e incolla la tua chiave dal Passaggio 3.

5. Fai clic su Connect.

Dovresti ora vedere lo stato Connected in verde. Fai clic sul pulsante List Tools per vedere l’elenco di tutte le funzionalità offerte dal server. Se vedi compute_routes in quell’elenco, la tua infrastruttura è configurata alla perfezione.

Per capire più a fondo come usare BigQuery, Maps e altri servizi Google per i tuoi agenti, dai un’occhiata a questo tutorial sui server MCP di Google.

Creare un agente con server MCP tramite Google ADK

Con l’infrastruttura pronta, possiamo passare all’ambiente di sviluppo locale. Inizieremo organizzando i file del progetto.

Passaggio 1: struttura del progetto e dipendenze

Per iniziare, crea una cartella per il progetto e imposta un ambiente virtuale.

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

Il comando finale sopra è per utenti macOS o Linux; se usi Windows, usa invece .venv\Scripts\activate.

Poi, puoi installare il pacchetto google-adk insieme alle sue librerie di supporto.

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

Un’ultima cosa da fare è creare un file .env nella cartella root per archiviare il tuo PROJECT_ID e la MAPS_API_KEY generata nel passaggio precedente.

Passaggio 2: configurare i toolset MCP

In uno script chiamato tools.py, non stiamo scrivendo codice per "ottenere dati". Stiamo invece scrivendo codice per connetterci a un server che sa come ottenere i dati. 

Separare gli strumenti dalla logica rende il progetto molto più semplice da debuggare. Poiché stiamo parlando con endpoint remoti di Google Cloud, usiamo StreamableHTTPConnectionParams per gestire gli header di autenticazione.

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"
            }
        )
    )

Passaggio 3: definire la missione dell’agente

Ora costruiamo il "cervello". Per esperienza, usare uno dei modelli Gemini Flash è la scelta migliore qui, perché sono incredibilmente veloci nel chiamare gli strumenti. 

Forniamo all’agente una procedura operativa standard tramite le istruzioni nel file agent.py. Nota come usiamo una pipeline chiara in quattro passaggi per evitare che l’agente si confonda.

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()]
)

Passaggio 4: eseguire il loop dell’agente 

Per eseguire l’agente, usiamo il runner. Questo componente tiene traccia dello stato della conversazione così che l’agente sappia cosa ha già fatto e cosa deve fare dopo.

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)

Cosa succede dietro le quinte?

Quando chiami runner.run_async, l’ADK avvia un loop iterativo:

1. Gemini pensa: "Prima devo vedere gli ordini in ritardo".

2. ADK agisce: chiama lo strumento execute_sql dal tuo toolset MCP di BigQuery.

3. Osservazione: lo strumento restituisce i dati degli ordini.

4. Gemini pensa: "Ora mi servono le distanze per questi due ordini".

5. ADK agisce: chiama due volte lo strumento MCP di Maps.

6. Risposta finale: Gemini vede tutti i dati, applica la tua logica delle "500 miglia" e formatta la tabella.

Testare il nostro agente Google ADK nella web console

Sebbene il terminale sia ottimo per i log, ADK include una web console integrata che visualizza il ragionamento interno dell’agente. L’ho trovata lo strumento più utile per il debug.

Avvia l’interfaccia eseguendo adk web. Una volta avviato il server, apri il browser su http://127.0.0.1:8000. Vedrai un’interfaccia pulita, in stile chat, dove puoi inviare il comando: "Identify high-priority delayed orders and suggest recovery shipping methods."

Analizzare la execution trace

La console ADK fornisce una "trace" trasparente di come esattamente l’agente interagisce con la tua infrastruttura cloud.

Vediamola passo dopo passo:

1. Handshake degli strumenti: nota le icone etichettate execute_sql e compute_routes. Nella trace, il fulmine indica un’invocazione di strumento. L’agente non ha indovinato: ha contattato fisicamente il server MCP di BigQuery per eseguire una specifica query SQL sulla tua tabella ordini.

2. Logica sequenziale: la trace mostra un ordine di operazioni chiaro. Prima recupera i dati via BigQuery (il primo segno di spunta). Una volta ottenuti gli indirizzi di magazzino e cliente, vedi più chiamate compute_routes. L’agente sta "ciclando" in modo intelligente tra gli ordini in ritardo per ottenere dati di distanza reali dal server MCP di Maps.

3. Sintesi finale: in fondo alla trace vedi la risposta finale.

Guarda i dati:

• ORD-101: distanza 380 miglia.
• ORD-103: distanza 352 miglia.

Poiché abbiamo dato all’agente la logica: "Se distanza > 500 miglia, consiglia Air Shipping, altrimenti Regional Express Ground", l’agente ha applicato correttamente questa regola di business a entrambi gli ordini e li ha formattati in una bella tabella Markdown.

Conclusione

Abbiamo appena creato un agente logistico funzionale senza scrivere una sola riga di codice API personalizzato per BigQuery o Google Maps. Usando ADK e MCP, abbiamo creato un’architettura modulare, sicura e developer‑first.

Il futuro dell’AI non è solo chatbot che parlano, ma agenti che agiscono. Con questi strumenti, stiamo finalmente andando in quella direzione.

Questo tutorial può essere un ottimo punto di partenza per i tuoi esperimenti con Google ADK e i server MCP: 

• Sostituisci BigQuery con un dataset diverso (o anche un server MCP SQLite locale) per vedere quanto è facile cambiare fonte dati.
• Sostituisci Maps con un altro server MCP (ad es., GKE per i controlli di salute del cluster) per dimostrare la natura plug‑and‑play.
• Aggiungi più logica di business nel prompt (confronto costi, bozza email) e testala live nella web UI di ADK.

Se vuoi approfondire l’orchestrazione degli agenti, ti consiglio vivamente di iscriverti al nostro percorso di carriera Associate AI Engineer for Developers.