1. Descripción general
En este codelab, aprenderás a implementar la app de Pet Passport, un agente de IA que usa el Protocolo de contexto del modelo (MCP) para combinar el análisis de datos y los servicios de ubicación.
La app ayuda a los usuarios a planificar un día perfecto con su perro en función de la popularidad de la raza en la ciudad de Nueva York. El agente usa una cadena de razonamiento "Macro a Micro":
- Descubrimiento estratégico (BigQuery): Identifica el código postal de la ciudad de Nueva York con la mayor población para una raza específica.
- Ejecución local (Maps): Usa ese código postal como una desviación de ubicación para encontrar "cafeterías que admiten mascotas" y "parques para perros".
- Generación de itinerarios: Combina los datos para crear un itinerario de "Pet Passport" con vínculos e imágenes en los que se puede hacer clic.
El agente se compila con el framework google-adk y funciona con Gemini.
Nota: El código completo del proyecto, incluida la IU de frontend, está disponible en GitHub. En este codelab, nos enfocaremos en la lógica principal del agente y la configuración de la infraestructura.
2. Configuración y requisitos
En primer lugar, asegúrate de que tu entorno de desarrollo esté configurado correctamente.
1. Autentica con Google Cloud
Configura tu proyecto activo de Google Cloud y autentica. Esto es necesario para que el agente acceda a BigQuery y a otros servicios.
gcloud config set project [YOUR-PROJECT-ID] gcloud auth application-default login --project [YOUR-PROJECT-ID]
Nota: Si encuentras errores sobre un proyecto diferente durante la autenticación, puedes omitirlos inhabilitando el proyecto de cuota y configurándolo de forma manual:
gcloud auth application-default login --disable-quota-project gcloud auth application-default set-quota-project [YOUR-PROJECT-ID]
2. Requisitos de software
Debes tener instalado el siguiente software en tu máquina local:
- Python (se requiere la versión 3.13 o posterior)
- Git (para descargar el repositorio)
Descarga el repositorio
El código de este proyecto está disponible en el repositorio de Google MCP. Clona el repositorio y navega a la carpeta del proyecto:
git clone https://github.com/google/mcp.git cd examples/petpassport
3. Instalación
Ahora que tienes los archivos, configuremos el entorno de Python.
- Crea un entorno virtual: Esto mantiene tus dependencias aisladas.
python3 -m venv .venv
- Activa el entorno virtual:
- En Linux/macOS:
source .venv/bin/activate
- En Windows:
.venv\Scripts\activate
- En Linux/macOS:
- Instala las dependencias:
pip install google-adk==1.28.0 python-dotenv google-genai pillow uvicorn
Habilita las APIs de Cloud
Habilita las siguientes APIs en tu proyecto:
gcloud services enable \ bigquery.googleapis.com \ aiplatform.googleapis.com \ artifactregistry.googleapis.com \ cloudbuild.googleapis.com \ run.googleapis.com \ storage.googleapis.com
Choose a region
Establece la región como una variable de entorno en tu shell:
export REGION=us-central1
4. Adquiere claves de API
Para usar los servicios de Maps y Gemini, debes adquirir claves de API y almacenarlas en un archivo .env en la raíz del proyecto.
1. Clave de API de Google Maps
- Ve a la consola de Google Cloud.
- Navega hasta APIs y servicios > Credenciales.
- Haz clic en Crear credenciales > Clave de API.
- Copia la clave generada y agrégala a tu archivo
.envcomoMAPS_API_KEY=[YOUR_KEY]. - (Recomendado) Restringe la clave para permitir solo las APIs de Maps que usa el servidor de MCP.
2. Clave de API de Gemini (AI Studio)
- Ve a Google AI Studio.
- Haz clic en Obtener clave de API o navega a la sección Claves de API.
- Haz clic en Crear clave de API.
- Copia la clave y agrégala a tu archivo
.envcomoGEMINI_API_KEY=[YOUR_KEY].
5. Instala las dependencias
Crea un archivo requirements.txt en la carpeta petpassport/:
google-adk==1.28.0
python-dotenv
google-genai
pillow
6. Autentica servidores de MCP
Esta aplicación se basa en servidores del Protocolo de contexto del modelo (MCP) para interactuar con Google Maps y BigQuery. Para autenticar estos servidores, debes configurar las variables de entorno y los encabezados adecuados.
- MCP de Google Maps: Requiere una clave de API de Google Maps válida que se pase en el encabezado
X-Goog-Api-Key. - MCP de BigQuery: Requiere credenciales de OAuth con acceso al servicio de BigQuery. El agente usa la cuenta de servicio de Compute predeterminada cuando se ejecuta en Cloud Run o tus credenciales locales cuando se ejecuta de forma local.
Proporcionamos una secuencia de comandos de configuración setup/setup_env.sh en el repositorio que ayuda a configurar estas variables en tu archivo .env.
7. Crea la tabla de BigQuery
Antes de que el agente pueda consultar los datos de la licencia de perro, debemos crear el conjunto de datos y la tabla en BigQuery, y cargar los datos.
Proporcionamos una secuencia de comandos de configuración setup/setup_bigquery.sh que realiza los siguientes pasos:
- Crea un bucket de Cloud Storage llamado
pet-passport-data-[PROJECT_ID]para almacenar los datos sin procesar. - Descarga el conjunto de datos públicos de licencias de perros de la ciudad de Nueva York (CSV).
- Sube el archivo CSV al bucket.
- Crea un conjunto de datos de BigQuery llamado
nyc_dogs. - Carga los datos del bucket en una tabla llamada
licensesen el conjunto de datos.
Para ejecutar la secuencia de comandos de configuración, ejecuta el siguiente comando en tu terminal:
bash setup/setup_bigquery.sh
8. Conéctate a servidores de MCP
Una parte clave de esta app es usar MCP para conectarse a datos y servicios. En esta sección, configurarás los conjuntos de herramientas de MCP para BigQuery y Google Maps en un archivo llamado petpassport/tools.py.
Código tools.py completo
Esta es la implementación completa de tools.py, incluidos los conjuntos de herramientas de MCP y las herramientas personalizadas para la persistencia de imágenes y datos. Optimizamos este código para reducir las redundancias moviendo la resolución del bucket al nivel del módulo:
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
Explicación del código: tools.py
get_maps_mcp_toolsetyget_bigquery_mcp_toolsetconfiguran los clientes de MCP con extremos y encabezados de autenticación correctos.generate_pet_passport_photousa Gemini para crear una escena y sube el resultado a Google Cloud Storage, y muestra una URL firmada al frontend para que sobreviva a los reinicios del servidor.
9. Crea el agente
Ahora que tus herramientas están configuradas, es hora de crear el "cerebro" del agente. Usarás el Kit de desarrollo de agentes (ADK) para crear un agente en un archivo llamado petpassport/agent.py.
Código agent.py completo
Esta es la implementación completa de agent.py, en la que definimos el agente y sus instrucciones:
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]
)
Explicación del código: agent.py
- Importamos
toolsdirectamente (estructura aplanada) para admitir el entorno de contenedor. - El agente se inicializa con
gemini-2.5-pro. - Las instrucciones definen una cadena de pensamiento estricta de varios pasos (primero BigQuery y, luego, Maps) y prohíben estrictamente la alucinación o la renderización de rutas a pie que conducen a desorden.
10. Ejecuta la aplicación de manera local
Antes de implementar en Cloud Run, es una buena idea probar la aplicación de forma local.
- Asegúrate de estar en el directorio del proyecto:
cd examples/petpassport
- Inicia el servidor de FastAPI: Usamos
uvicornpara ejecutar la app. El punto de entrada esmain.pydentro de la carpetapetpassport.uvicorn petpassport.main:app --reload
- Abre la IU: Navega a
http://127.0.0.1:8000/ui/en tu navegador para interactuar con la interfaz de Pet Passport.
11. Implementa en Cloud Run
Ahora que tu agente está listo, es hora de implementarlo en Cloud Run. Usamos el comando gcloud estándar directamente para mantener un control estricto sobre el entorno de contenedor.
Desde el directorio del proyecto, ejecuta el siguiente comando:
gcloud run deploy petpassport \ --source petpassport \ --region $REGION \ --allow-unauthenticated \ --labels dev-tutorial=google-mcp
Configura las variables de entorno
Después de la implementación, navega al servicio de Cloud Run en la consola de Google Cloud y establece las siguientes variables de entorno en la pestaña Variables y secretos:
MAPS_API_KEY: Es tu clave de API de Google Maps.GOOGLE_CLOUD_PROJECT: Es el ID del proyecto.PROJECT_ID: Es el ID del proyecto (se admite la redundancia para los módulos heredados).
12. Ejemplos de instrucciones
Intenta interactuar con el agente implementado usando estas instrucciones:
- Estándar: "Quiero ir a caminar con mi Golden Retriever en Nueva York cerca de 10021. Encuentra una ruta para nosotros que tenga una cafetería".
- Raza diferente: "Tengo un bulldog francés y estamos en Upper West Side (cerca de 10024). Sugiere una caminata corta que se detenga en un parque para perros popular".
- Con imagen: (Sube una foto de tu perro) "Aquí hay una foto de mi corgi. Estamos cerca de 10013. Planifica un día perfecto para nosotros".
13. Limpia
Para evitar que se generen cargos por los recursos que usaste en este instructivo, haz lo siguiente:
- Borra el servicio de Cloud Run:
gcloud run services delete petpassport --region=$REGION - Borra el bucket de GCS:
gcloud storage rm -r gs://pet-passport-data-$PROJECT_ID