1. Panoramica
In questo lab di programmazione imparerai a eseguire il deployment dell'app Pet Passport, un agente AI che utilizza Model Context Protocol (MCP) per combinare l'analisi dei dati e i servizi di localizzazione.
L'app aiuta gli utenti a pianificare una giornata perfetta con il proprio cane in base alla popolarità della razza a New York City. L'agente utilizza una catena di ragionamento "dal macro al micro":
- Strategic Discovery (BigQuery): identifica il codice postale di New York City con la popolazione più numerosa per una razza specifica.
- Esecuzione locale (Maps): utilizza il codice postale come bias di località per trovare "caffetterie che accettano animali" e "parchi per cani".
- Generazione dell'itinerario:combina i dati per creare un itinerario "Passaporto per animali domestici" con link e immagini cliccabili.
L'agente è creato utilizzando il framework google-adk e basato su Gemini.
Nota: il codice completo del progetto, inclusa la UI frontend, è disponibile su GitHub. In questo codelab, ci concentreremo sulla logica principale dell'agente e sulla configurazione dell'infrastruttura.
2. Configurazione e requisiti
Innanzitutto, assicurati che l'ambiente di sviluppo sia configurato correttamente.
1. Autenticazione con Google Cloud
Imposta il progetto Google Cloud attivo e autenticati. È necessario per consentire all'agente di accedere a BigQuery e ad altri servizi.
gcloud config set project [YOUR-PROJECT-ID] gcloud auth application-default login --project [YOUR-PROJECT-ID]
Nota: se riscontri errori relativi a un altro progetto durante l'autenticazione, puoi aggirarli disattivando il progetto di quota e impostandolo manualmente:
gcloud auth application-default login --disable-quota-project gcloud auth application-default set-quota-project [YOUR-PROJECT-ID]
2. Requisiti software
Devi avere installato i seguenti software sulla tua macchina locale:
- Python (è richiesta la versione 3.13 o successive)
- Git (per scaricare il repository)
Scaricare il repository
Il codice per questo progetto è disponibile nel repository Google MCP. Clona il repository e vai alla cartella del progetto:
git clone https://github.com/google/mcp.git cd examples/petpassport
3. Installazione
Ora che hai i file, configuriamo l'ambiente Python.
- Crea un ambiente virtuale:in questo modo le dipendenze rimangono isolate.
python3 -m venv .venv
- Attiva l'ambiente virtuale:
- Su Linux/macOS:
source .venv/bin/activate
- In Windows:
.venv\Scripts\activate
- Su Linux/macOS:
- Installa le dipendenze:
pip install google-adk==1.28.0 python-dotenv google-genai pillow uvicorn
Abilita le API Cloud
Abilita le seguenti API nel tuo progetto:
gcloud services enable \ bigquery.googleapis.com \ aiplatform.googleapis.com \ artifactregistry.googleapis.com \ cloudbuild.googleapis.com \ run.googleapis.com \ storage.googleapis.com
Scegli una regione
Imposta la regione come variabile di ambiente nella shell:
export REGION=us-central1
4. Acquisire chiavi API
Per utilizzare i servizi Maps e Gemini, devi acquisire le chiavi API e memorizzarle in un file .env nella radice del progetto.
1. Chiave API di Google Maps
- Vai alla console Google Cloud.
- Vai ad API e servizi > Credenziali.
- Fai clic su Crea credenziali > Chiave API.
- Copia la chiave generata e aggiungila al file
.envcomeMAPS_API_KEY=[YOUR_KEY]. - (Consigliato) Limita la chiave in modo da consentire solo le API di Maps utilizzate dal server MCP.
2. Chiave API Gemini (AI Studio)
- Vai a Google AI Studio.
- Fai clic su Ottieni chiave API o vai alla sezione Chiavi API.
- Fai clic su Crea chiave API.
- Copia la chiave e aggiungila al file
.envcomeGEMINI_API_KEY=[YOUR_KEY].
5. Installa le dipendenze
Crea un file requirements.txt nella cartella petpassport/:
google-adk==1.28.0
python-dotenv
google-genai
pillow
6. Autenticare i server MCP
Questa applicazione si basa sui server Model Context Protocol (MCP) per interagire con Google Maps e BigQuery. Per autenticare questi server, devi configurare le variabili di ambiente e le intestazioni appropriate.
- Google Maps MCP: richiede una chiave API di Google Maps valida passata nell'intestazione
X-Goog-Api-Key. - BigQuery MCP:richiede credenziali OAuth con accesso al servizio BigQuery. L'agente utilizza il service account Compute predefinito quando viene eseguito su Cloud Run o le tue credenziali locali quando viene eseguito localmente.
Nel repository forniamo uno script di configurazione setup/setup_env.sh che consente di configurare queste variabili nel file .env.
7. Creazione della tabella BigQuery
Prima che l'agente possa eseguire query sui dati delle licenze per cani, dobbiamo creare il set di dati e la tabella in BigQuery e caricare i dati.
Forniamo uno script di configurazione setup/setup_bigquery.sh che esegue i seguenti passaggi:
- Crea un bucket Cloud Storage denominato
pet-passport-data-[PROJECT_ID]per archiviare i dati non elaborati. - Scarica il set di dati pubblico NYC Dog Licensing (CSV).
- Carica il file CSV nel bucket.
- Crea un set di dati BigQuery denominato
nyc_dogs. - Carica i dati dal bucket in una tabella denominata
licensesnel set di dati.
Per eseguire lo script di configurazione, esegui questo comando nel terminale:
bash setup/setup_bigquery.sh
8. Connettiti ai server MCP
Una parte fondamentale di questa app è l'utilizzo di MCP per connettersi a dati e servizi. In questa sezione configurerai i toolset MCP per BigQuery e Google Maps in un file denominato petpassport/tools.py.
Codice tools.py completo
Ecco l'implementazione completa per tools.py, inclusi i toolset MCP e gli strumenti personalizzati per la persistenza di immagini e dati. Abbiamo ottimizzato questo codice per ridurre le ridondanze spostando la risoluzione del bucket a livello di modulo:
import os
import dotenv
import google.auth
import time
import datetime
from google.cloud import storage
from PIL import Image
from google import genai
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
MAPS_MCP_URL = "https://mapstools.googleapis.com/mcp"
BIGQUERY_MCP_URL = "https://bigquery.googleapis.com/mcp"
PROJECT_ID = os.getenv('GOOGLE_CLOUD_PROJECT', 'project_not_set')
BUCKET_NAME = f"pet-passport-data-{PROJECT_ID}"
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
},
timeout=30.0,
sse_read_timeout=300.0
)
)
print("Maps MCP Toolset configured.")
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,
timeout=30.0,
sse_read_timeout=300.0
)
)
print("BigQuery MCP Toolset configured.")
return tools
def generate_pet_passport_photo(prompt: str, image_path: str = None) -> str:
"""Generates an image using gemini-3.1-flash-image-preview based on a prompt and a reference image."""
client = genai.Client()
output_path = f"/tmp/pet_passport_{int(time.time())}.png"
try:
image = Image.open(image_path)
response = client.models.generate_content(
model="gemini-3.1-flash-image-preview",
contents=[prompt, image],
)
for part in response.parts:
if part.inline_data is not None:
generated_image = part.as_image()
generated_image.save(output_path)
# Upload to GCS and generate signed URL
try:
storage_client = storage.Client()
bucket = storage_client.bucket(BUCKET_NAME)
blob_name = os.path.basename(output_path)
blob = bucket.blob(blob_name)
blob.upload_from_filename(output_path)
url = blob.generate_signed_url(
version="v4",
expiration=datetime.timedelta(hours=24),
method="GET",
)
return url
except Exception as e:
print(f"Error uploading image to GCS: {e}")
return output_path
raise ValueError("No image was returned by the model.")
except Exception as e:
print(f"Error generating image: {e}")
raise
def save_pet_passport(user_id: str, breed: str, postal_code: str, route_details: str, image_paths: list[str] = None) -> str:
"""Appends the generated itinerary to the user's history in GCS."""
try:
storage_client = storage.Client()
bucket = storage_client.bucket(BUCKET_NAME)
blob = bucket.blob(f"user-{user_id}.json")
# Download existing or start fresh
# ... (Implementation details hidden for brevity) ...
return "Success"
except Exception as e:
print(f"Error saving path: {e}")
raise
Spiegazione del codice: tools.py
get_maps_mcp_toolseteget_bigquery_mcp_toolsetconfigurano i client MCP con endpoint e intestazioni di autenticazione corretti.generate_pet_passport_photoutilizza Gemini per creare una scena e carica il risultato su Google Cloud Storage, restituendo un URL firmato al frontend per sopravvivere ai riavvii del server.
9. Creazione dell'agente
Ora che gli strumenti sono configurati, è il momento di creare il "cervello" dell'agente. Utilizzerai l'Agent Development Kit (ADK) per creare un agente in un file denominato petpassport/agent.py.
Codice agent.py completo
Ecco l'implementazione completa per agent.py, in cui definiamo l'agente e le relative istruzioni:
import os
import dotenv
import tools
from google.adk.agents import LlmAgent
dotenv.load_dotenv()
PROJECT_ID = os.getenv('GOOGLE_CLOUD_PROJECT', 'project_not_set')
maps_toolset = tools.get_maps_mcp_toolset()
bigquery_toolset = tools.get_bigquery_mcp_toolset()
root_agent = LlmAgent(
model='gemini-2.5-pro',
name='root_agent',
instruction=f"""
You are the Pet Passport Agent. Your goal is to help users find a fun walking route for their dog in NYC.
When given a breed and a postal code, follow this flow:
1. **Strategic Discovery:** Use BigQuery to find the most popular neighborhood for that breed in NYC.
2. **Local Execution:** Use Maps to build a walking route with specific places (parks, cafes) in that area.
**NO DIRECTIONS LINKS:** You must NOT include a Google Maps directions link (e.g., `https://www.google.com/maps/dir/...`) in your final response. Only provide links to individual places.
After generating the itinerary, you MUST call the `save_pet_passport` tool to save this path to the user's profile. Pass a clean summary of the itinerary as `route_details`. The summary should include details (like rating, description from maps).
""",
tools=[maps_toolset, bigquery_toolset, tools.generate_pet_passport_photo, tools.save_pet_passport]
)
Spiegazione del codice: agent.py
- Importiamo
toolsdirettamente (struttura piatta) per supportare l'ambiente container. - L'agente è inizializzato con
gemini-2.5-pro. - Le istruzioni definiscono una rigorosa catena di pensiero in più passaggi (prima BigQuery, poi Maps) e vietano rigorosamente l'allucinazione o il rendering di itinerari a piedi che portano a un'eccessiva confusione.
10. Esecuzione dell'applicazione in locale
Prima di eseguire il deployment in Cloud Run, è consigliabile testare l'applicazione localmente.
- Assicurati di trovarti nella directory del progetto:
cd examples/petpassport
- Avvia il server FastAPI:utilizziamo
uvicornper eseguire l'app. L'entry point èmain.pyall'interno della cartellapetpassport.uvicorn petpassport.main:app --reload
- Apri la UI:vai a
http://127.0.0.1:8000/ui/nel browser per interagire con l'interfaccia del passaporto per animali domestici.
11. Deployment in Cloud Run
Ora che l'agente è pronto, è il momento di eseguirne il deployment in Cloud Run. Utilizziamo direttamente il comando standard gcloud per mantenere un controllo rigoroso sull'ambiente del container.
Dalla directory del progetto, esegui questo comando:
gcloud run deploy petpassport \ --source petpassport \ --region $REGION \ --allow-unauthenticated \ --labels dev-tutorial=google-mcp
Configura le variabili di ambiente
Dopo il deployment, vai al servizio Cloud Run nella console Google Cloud e imposta le seguenti variabili di ambiente nella scheda Variabili e secret:
MAPS_API_KEY: la tua chiave API di Google Maps.GOOGLE_CLOUD_PROJECT: il tuo ID progetto.PROJECT_ID: Il tuo ID progetto (la ridondanza è supportata per i moduli legacy).
12. Prompt di esempio
Prova a interagire con l'agente di cui è stato eseguito il deployment utilizzando questi prompt:
- Standard: "Voglio fare una passeggiata con il mio golden retriever a New York vicino al codice postale 10021. Trova un percorso per noi che includa un bar".
- Razza diversa: "Ho un bulldog francese e mi trovo nell'Upper West Side (vicino al codice postale 10024). Suggerisci una breve passeggiata che si fermi in un parco per cani molto frequentato.
- Con immagine: (carica una foto del tuo cane) "Ecco una foto del mio Corgi! Ci troviamo vicino a 10013. Organizzami una giornata perfetta."
13. Esegui la pulizia
Per evitare che ti vengano addebitati costi per le risorse utilizzate in questo tutorial:
- Elimina il servizio Cloud Run:
gcloud run services delete petpassport --region=$REGION - Elimina il bucket GCS:
gcloud storage rm -r gs://pet-passport-data-$PROJECT_ID