Se usó la API de Cloud Translation para traducir esta página.

Crea un asistente de IA de agente de tienda deportiva con ADK, MCP Toolbox y AlloyDB

1. Introducción

Qué compilarás

En este codelab, aprenderás a compilar un asistente de IA de agente de tienda de deportes. Esta aplicación de IA para agentes de nueva generación, potenciada por ADK, MCP Toolbox y AlloyDB, ayudará a los usuarios con diversas tareas, como las siguientes:

Buscar productos con lenguaje natural
Encontrar tiendas cercanas para comprar productos recomendados
Realizar pedidos nuevos
Verificar los estados de los pedidos existentes
Actualizar pedidos con métodos de entrega preferidos

Qué aprenderás

Aprovisionamiento y propagación de una base de datos de AlloyDB para PostgreSQL
Configura MCP Toolbox for Databases con tu instancia de AlloyDB para PostgreSQL.
Diseñar y desarrollar un agente de IA con el Kit de desarrollo de agentes (ADK) para ayudar con las consultas de la tienda de deportes
Probar tu agente y el kit de herramientas de MCP para bases de datos en un entorno de nube
Aprovechar las capacidades avanzadas de consultas de AlloyDB para obtener respuestas de agentes inteligentes

Requisitos

Para completar este codelab, necesitarás lo siguiente:

Un navegador web Chrome
Una cuenta de Gmail
Un proyecto de Google Cloud con facturación habilitada

Este codelab está diseñado para desarrolladores de todos los niveles, incluidos los principiantes.

2. Antes de comenzar

En esta sección, se te guía a través de la configuración inicial requerida en tu proyecto de Google Cloud antes de que puedas comenzar a compilar el asistente de IA de Sports Shop Agent.

Cómo crear un proyecto

En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Obtén información para verificar si la facturación está habilitada en un proyecto .
Haz clic en este vínculo para activar Cloud Shell. Puedes alternar entre la terminal de Cloud Shell (para ejecutar comandos de Cloud) y el editor (para compilar proyectos) haciendo clic en el botón correspondiente de Cloud Shell.

Una vez que te conectes a Cloud Shell, verifica que ya te autenticaste y que el proyecto se configuró con el ID de tu proyecto con el siguiente comando:

gcloud auth list

En Cloud Shell, ejecuta el siguiente comando para confirmar que el comando gcloud conoce tu proyecto.

gcloud config list project

Configura la variable PROJECT_ID con el siguiente comando:

export PROJECT_ID=[YOUR_PROJECT_ID]

gcloud config set project $PROJECT_ID

Ejecuta los siguientes comandos para habilitar las APIs:

gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       vpcaccess.googleapis.com \
                       aiplatform.googleapis.com

3. Crea la instancia de AlloyDB

En esta sección, configurarás tu clúster y tu instancia de base de datos de AlloyDB, y configurarás los permisos y la red necesarios para tu agente de IA.

Primero, ejecuta el siguiente comando en tu terminal de Cloud Shell para crear el clúster de AlloyDB:

gcloud alloydb clusters create alloydb-cluster \
    --password=alloydb\
    --network=default \
    --region=us-central1 \
    --database-version=POSTGRES_16

AlloyDB depende de la conectividad de IP privada para brindar acceso seguro y de alto rendimiento. Debes asignar un rango de IP privada dentro de tu VPC para que Google lo use en la conexión de intercambio de tráfico de servicio a la infraestructura de redes administrada por Google. Ejecuta el siguiente comando:

gcloud compute addresses create peering-range-for-alloydb \
    --global \
    --purpose=VPC_PEERING \
    --prefix-length=16 \
    --description="Automatically allocated IP range for service networking" \
    --network=default

A continuación, crea la conexión de intercambio de tráfico de servicios de VPC. Esto permite que tu red de nube privada virtual (VPC) de Google Cloud se comunique de forma segura y privada con los servicios administrados de Google, incluido AlloyDB. Ejecuta el siguiente comando:

gcloud services vpc-peerings connect \
--service=servicenetworking.googleapis.com \
--ranges=peering-range-for-alloydb \
--network=default

Ahora, crea la instancia principal dentro de tu clúster de AlloyDB. Este es el extremo de la base de datos real al que se conectarán tus aplicaciones. Ejecuta el siguiente comando para crear una instancia de AlloyDB:

gcloud alloydb instances create alloydb-inst \
     --instance-type=PRIMARY \
     --cpu-count=2 \
     --region=us-central1 \
     --cluster=alloydb-cluster \
     --availability-type=ZONAL \
     --ssl-mode=ALLOW_UNENCRYPTED_AND_ENCRYPTED

Nota: La creación de la instancia puede tardar aproximadamente 10 minutos en completarse. Espera a que finalice esta operación antes de continuar.

Habilitar la integración en Vertex AI

Para permitir que tu instancia de AlloyDB realice consultas de búsqueda de vectores (que son esenciales para las funciones basadas en IA, como la búsqueda semántica) y llame a los modelos implementados en Vertex AI, debes otorgar permisos de Vertex AI al agente de servicio de AlloyDB.

Primero, recupera el número de tu proyecto de Google Cloud, ya que es necesario para la vinculación de IAM.

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
gcloud projects describe $PROJECT_ID --format="value(projectNumber)"

Luego, otorga permiso a Vertex AI para el agente de servicio de AlloyDB:

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:service-$PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"

Habilitar IP pública

Como preparación para los siguientes pasos, habilitaremos la conectividad de IP pública en nuestra instancia de AlloyDB.

En la consola, ve al campo de búsqueda que se encuentra en la parte superior central de la pantalla, ingresa "alloydb" y, luego, edita y ve a la sección de conectividad de IP pública. Marca la casilla de verificación "Habilitar IP pública" y, luego, ingresa la dirección IP de tu máquina de Cloud Shell.

Para obtener la IP de tu máquina de Cloud Shell, ve a la terminal de Cloud Shell y, luego, ingresa el comando "ifconfig | grep -A 1 eth0". En el resultado, reemplaza los últimos 2 dígitos por 0.0 con un tamaño de máscara "/16". Por ejemplo, se vería como "XX.XX.0.0/16", donde XX son números.

Pega esta IP en el cuadro de texto "Redes" de las redes externas autorizadas en la página de edición de la instancia.

Nota: La operación de actualización puede tardar hasta 3 minutos.

4. Carga la base de datos

Crea la base de datos de la tienda

Ahora es el momento de crear tu base de datos y cargar los datos iniciales de tu tienda de deportes.

Para permitir que psql se conecte a tu instancia privada de AlloyDB desde Cloud Shell, usarás el proxy de autenticación de AlloyDB. Esta utilidad crea un túnel seguro para tu conexión a la base de datos. (Consulta Proxy de autenticación de AlloyDB).

Descarga el proxy de autenticación de AlloyDB con el siguiente comando:

wget https://storage.googleapis.com/alloydb-auth-proxy/v1.13.3/alloydb-auth-proxy.linux.amd64 -O alloydb-auth-proxy

Haz que sea ejecutable:

chmod +x alloydb-auth-proxy

Ejecuta este comando en la primera ventana de la terminal de Cloud Shell. El proxy se ejecutará en segundo plano y reenviará las conexiones.

./alloydb-auth-proxy "projects/$PROJECT_ID/locations/us-central1/clusters/alloydb-cluster/instances/alloydb-inst" --public-ip

Importante: Deja esta ventana de la terminal abierta y ejecutando el proxy. No la cierres.

Abre una ventana de terminal nueva en Cloud Shell (haz clic en el ícono + junto a la pestaña "Terminal de Cloud Shell" en la parte superior).

Conéctate a la instancia de AlloyDB con psql:

psql -h 127.0.0.1 -U postgres

Nota: Cuando se te solicite, ingresa la contraseña que configuraste para el usuario postgres durante la creación del clúster (si sigues la documentación directamente, la contraseña es alloydb).

Luego, crea la base de datos de la tienda para nuestra aplicación (ejecuta los comandos uno por uno):

CREATE DATABASE store;
\c store
exit

Código fuente

Ahora, clona el repositorio de código fuente del codelab. Asegúrate de estar en tu directorio principal o en una ubicación adecuada antes de clonar y ejecutar el siguiente comando:

git clone https://github.com/mtoscano84/sports-agent-adk-mcp-alloydb.git

Completa la base de datos

Navega a la carpeta data del proyecto clonado para acceder al archivo de volcado de la base de datos.

cd sports-agent-adk-mcp-alloydb/data

Luego, importa el conjunto de datos de muestra a tu base de datos store con el archivo store_backup.sql del repositorio.

psql -h 127.0.0.1 -U postgres -d store -f store_backup.sql

Nota: Es posible que veas algunos mensajes de ADVERTENCIA y ERROR durante esta importación, que se pueden ignorar de forma segura para este codelab. A menudo, se relacionan con permisos o con objetos que ya existen si el volcado contiene el esquema completo. Encontrarás algunos mensajes de WARNING y ERROR que se pueden ignorar.

5. Configuración del servicio de autorización

En esta sección, configurarás el servicio de autorización para tu aplicación. Este servicio es fundamental para proteger el acceso y brindar protección contra las vulnerabilidades de inyección de instrucciones en tu agente de IA.

Primero, agregarás un usuario de muestra a la tabla users en tu base de datos store. Este usuario se usará para la autenticación en tu aplicación.

Ve a la consola y navega a AlloyDB, selecciona la instancia principal y, luego, AlloyDB Studio:

Cuando se te solicite, accede a AlloyDB Studio con las credenciales que creaste cuando configuraste el clúster:

Nombre de usuario: "postgres"
Base de datos: "store"
Contraseña: "alloydb"

En el editor de SQL, ejecuta una instrucción INSERT para agregar tu usuario a la base de datos. Cambia el nombre, el apellido y la dirección de correo electrónico.

Importante:

Mantén la ubicación como se muestra en el ejemplo.
Usa la misma dirección de correo electrónico que usas para registrarte en la consola de Google Cloud.

INSERT INTO users (user_id, first_name, last_name, Address, city, postal_code, location, email)
VALUES (10,'John', 'Doe', 'Carrer Muntaner 39', 'Barcelona', '08019', '0101000020E61000008AAE0B3F38B144401FBB0B9414780140', 'john.doe@example.com');

A continuación, debes configurar la pantalla de consentimiento de OAuth para tu proyecto. Esta pantalla se muestra a los usuarios cuando tu aplicación solicita acceso a su Cuenta de Google y define la marca de tu aplicación.

En la consola, navega a "APIs y servicios", "Consentimiento de OAuth de Google":

Proporciona la siguiente información para crear la marca de tu aplicación:

Nombre de la app: "Sports Shopping Agent AI"
Correo electrónico de asistencia del usuario: "YOUR_EMAIL"
Público: "Externo"
Información de contacto: "TU_CORREO_ELECTRÓNICO"

Ahora, crearás el ID de cliente de OAuth que usará tu aplicación de frontend para validar la identidad del usuario con Google.

Primero, asegúrate de tener tu número de proyecto de Google Cloud. Esto es necesario para configurar correctamente los URIs de redireccionamiento. Ejecuta el siguiente comando en una terminal de Cloud Shell:

En caso de que la variable PROJECT_ID no esté configurada en esta ventana de la terminal de Cloud Shell, ejecuta el siguiente comando:

export PROJECT_ID=[YOUR_PROJECT_ID]

Luego, obtén el PROJECT_NUMBER con el siguiente comando:

gcloud projects describe $PROJECT_ID --format="value(projectNumber)"

Luego, navega a "APIs and Services" -> "Credentials" -> "Create Credentials" -> "OAuth Client ID".

Usa la siguiente información para crear la credencial:

Tipo de aplicación: “Aplicación web”
Nombre: "App de IA del agente de compras de deportes"

Orígenes autorizados de JavaScript:

URL1: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

URIs de redireccionamiento autorizados:

URL1: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

Nota: La URL https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app es la URL de implementación esperada para tu aplicación de frontend, que se configurará más adelante en este codelab. Asegúrate de reemplazar [YOUR_PROJECT_NUMBER] por el número real que copiaste.

Importante: Después de la creación, aparecerá una ventana emergente con tu ID de cliente de OAuth y, a veces, un secreto de cliente. Almacena tu ID de cliente de OAuth en un lugar seguro, ya que lo necesitarás en un paso posterior cuando configures tu frontend.

6. Configuración de MCP Toolbox for Databases

Toolbox se encuentra entre el framework de orquestación de tu aplicación y tu base de datos, y proporciona un plano de control que se usa para modificar, distribuir o invocar herramientas. Simplifica la administración de tus herramientas, ya que te proporciona una ubicación centralizada para almacenarlas y actualizarlas, lo que te permite compartirlas entre agentes y aplicaciones, y actualizarlas sin necesidad de volver a implementar tu aplicación.

Dado que AlloyDB es una de las bases de datos compatibles con MCP Toolbox for Databases y ya la aprovisionamos en la sección anterior, configuremos Toolbox.

Primero, configurarás el servidor de MCP Toolbox de forma local en tu entorno de Cloud Shell para verificar su funcionalidad.

En la terminal de Cloud Shell, navega a la carpeta toolbox que se encuentra dentro del repositorio del proyecto clonado:

cd sports-agent-adk-mcp-alloydb/src/toolbox

Ejecuta los siguientes comandos para descargar el objeto binario de Toolbox y otorgarle permisos de ejecución:

# see releases page for other versions
export VERSION=0.7.0

curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox

chmod +x toolbox

Nota: Aquí se especifica la versión 0.7.0. Para los entornos de producción, siempre verifica y usa la versión estable más reciente de la página de versiones de la caja de herramientas.

Navega al Editor de Cloud Shell (puedes alternar desde la terminal haciendo clic en el ícono del editor).

En el mismo directorio sports-agent-adk-mcp-alloydb/src/toolbox, encontrarás un archivo llamado tools.yaml. Abre este archivo y actualiza los marcadores de posición con tu ID de cliente de OAuth y el ID del proyecto de Google Cloud de los pasos anteriores.

Comprendamos tools.yaml

Las fuentes representan las diferentes fuentes de datos con las que una herramienta puede interactuar. Una fuente representa una fuente de datos con la que puede interactuar una herramienta. Puedes definir fuentes como un mapa en la sección sources de tu archivo tools.yaml. Por lo general, una configuración de origen contendrá toda la información necesaria para conectarse con la base de datos y para interactuar con ella.

Las herramientas definen las acciones que puede realizar un agente, como leer y escribir en una fuente. Una herramienta representa una acción que puede realizar tu agente, como ejecutar una instrucción SQL. Puedes definir herramientas como un mapa en la sección tools de tu archivo tools.yaml. Por lo general, una herramienta requerirá una fuente para actuar.

Para obtener más detalles sobre cómo configurar tu archivo tools.yaml, consulta esta documentación.

Ejecutemos el servidor de MCP Toolbox para bases de datos

Ejecuta el siguiente comando (desde la carpeta mcp-toolbox) para iniciar el servidor:

./toolbox --tools-file "tools.yaml"

Ahora, si abres el servidor en un modo de vista previa web en la nube, deberías poder ver el servidor de Toolbox en funcionamiento con todas las herramientas de nuestra aplicación.

El servidor de MCP Toolbox se ejecuta de forma predeterminada en el puerto 5000. Usemos Cloud Shell para probarlo.

Haz clic en Vista previa en la Web en Cloud Shell, como se muestra a continuación:

Haz clic en Cambiar puerto y establece el puerto en 5000, como se muestra a continuación. Luego, haz clic en Cambiar y obtener vista previa.

Esto debería generar el siguiente resultado:

El MCP Toolkit for Databases describe un SDK de Python para que valides y pruebes las herramientas, que se documenta aquí. Omitiremos ese paso y pasaremos directamente al Kit de desarrollo de agentes (ADK) en la siguiente sección, en la que se utilizarán estas herramientas.

Implementemos nuestra caja de herramientas en Cloud Run

Para que tu servidor de Toolbox sea accesible como un extremo público que se pueda integrar con otras aplicaciones y tu agente de IA, lo implementarás en Cloud Run. Encontrarás instrucciones detalladas para alojar la caja de herramientas en Cloud Run aquí.

Regresa a la terminal de Cloud Shell y navega a la carpeta de la caja de herramientas:

cd sports-agent-adk-mcp-alloydb/src/toolbox

Asegúrate de que la variable de entorno PROJECT_ID esté configurada en el ID de tu proyecto de Google Cloud.

export PROJECT_ID=$PROJECT_ID

A continuación, verifica que los siguientes servicios de Google Cloud estén habilitados en el proyecto.

gcloud services enable run.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       iam.googleapis.com \
                       secretmanager.googleapis.com

Creemos una cuenta de servicio independiente que actuará como la identidad del servicio de Toolbox que implementaremos en Google Cloud Run. También nos aseguramos de que esta cuenta de servicio tenga los roles correctos, es decir, la capacidad de acceder a Secret Manager y comunicarse con AlloyDB.

gcloud iam service-accounts create toolbox-identity

gcloud projects add-iam-policy-binding $PROJECT_ID \
   --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
   --role roles/secretmanager.secretAccessor


gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member='serviceAccount:toolbox-identity@'$PROJECT_ID'.iam.gserviceaccount.com' \
    --role='roles/alloydb.client'


gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member='serviceAccount:toolbox-identity@'$PROJECT_ID'.iam.gserviceaccount.com' \
    --role='roles/serviceusage.serviceUsageConsumer'

Luego, subirás el archivo tools.yaml como secreto y, como tenemos que instalar Toolbox en Cloud Run, usaremos la imagen de contenedor más reciente para Toolbox y la estableceremos en la variable IMAGE.

gcloud secrets create tools --data-file=tools.yaml

export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest

Por último, implementa tu servidor de Toolbox en Cloud Run con el siguiente comando. Este comando creará un contenedor para tu aplicación, configurará la cuenta de servicio, insertará el secreto y lo expondrá de forma pública:

gcloud run deploy toolbox \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools:latest" \
--args="--tools_file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--allow-unauthenticated

Esto debería iniciar el proceso de implementación del servidor de Toolbox con nuestro archivo tools.yaml configurado en Cloud Run. Si la implementación se realiza correctamente, deberías ver un mensaje similar al siguiente:

Deploying container to Cloud Run service [toolbox] in project [sports-store-agent-ai] region [us-central1]
OK Deploying... Done.
  OK Creating Revision...
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [toolbox] revision [toolbox-00002-dn2] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-[YOUR_PROJECT_NUMBER].us-central1.run.app

Ahora puedes visitar la URL de servicio que se indicó anteriormente en el navegador. Debería mostrar el mensaje "Hello World" que vimos antes. Además, también puedes visitar la siguiente URL para ver las herramientas disponibles:

https://toolbox-[YOUR_PROJECT_NUMBER].us-central1.run.app/api/toolset

También puedes visitar Cloud Run desde la consola de Google Cloud y verás el servicio de Toolbox disponible en la lista de servicios de Cloud Run.

7. Agente compilado en el ADK

En esta sección, implementarás en Cloud Run tu agente de IA, que se creó con el kit de desarrollo de agentes (ADK).

Primero, habilita las APIs necesarias en tu proyecto para compilar e implementar tu agente en Cloud Run, y para interactuar con Artifact Registry y Cloud Storage. Ejecuta el siguiente comando en tu terminal de Cloud Shell:

gcloud services enable artifactregistry.googleapis.com \
                       cloudbuild.googleapis.com \
                       run.googleapis.com \
                       storage.googleapis.com

Luego, asignaremos los permisos necesarios a la cuenta de servicio predeterminada de Compute en nuestro proyecto. Primero, ejecuta el siguiente comando en tu terminal de Cloud Shell para obtener PROJECT_NUMBER:

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")

Asigna permisos a la cuenta de servicio predeterminada de Compute:

# Grant Cloud Run service account access to GCS
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/storage.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/run.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/artifactregistry.writer"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER@cloudbuild.gserviceaccount.com" \
--role="roles/artifactregistry.repoAdmin"

# Grant Vertex AI User role to the service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.user"

# Grant Vertex AI Model User role to the service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.modelUser"

Conecta nuestro agente a las herramientas

Conectaremos nuestro agente a las herramientas. En el contexto del ADK, una herramienta representa una capacidad específica que se proporciona a un agente de IA, lo que le permite realizar acciones e interactuar con el mundo más allá de sus capacidades principales de generación de texto y razonamiento.

En nuestro caso, equiparemos nuestro agente con las herramientas que configuramos en el MCP Toolbox for Databases.

Con el editor de Cloud Shell, navega a sports-agent-adk-mcp-alloydb/src/backend/ y edita el archivo "finn_agent.py" con el siguiente código. Ten en cuenta que usamos la URL del servicio de Cloud Run del servidor de MCP ToolBox implementado en el paso anterior:

Implementa nuestro agente en Cloud Run

Por último, implementarás el agente de IA configurado en Cloud Run, lo que lo hará accesible a través de un extremo HTTP.

Primero, crea un repositorio de Docker en Artifact Registry para almacenar las imágenes de contenedor de tu agente. Ejecuta el siguiente comando en Cloud Shell:

gcloud artifacts repositories create finn-agent-images \
    --repository-format=docker \
    --location=us-central1 \
    --project=$PROJECT_ID \
    --description="Repository for finn-agent images"

A continuación, compila la imagen de Docker para tu agente con Cloud Build. Ejecuta este comando desde el directorio raíz de tu proyecto clonado (sports-agent-adk-mcp-alloydb/):

gcloud builds submit src/backend/ --tag us-central1-docker.pkg.dev/$PROJECT_ID/finn-agent-images/finn-agent

Ahora, implementa el servicio del agente. Este comando creará un servicio de Cloud Run, extraerá la imagen de Artifact Registry y configurará las variables de entorno.

gcloud run deploy finn-agent \
    --image us-central1-docker.pkg.dev/$PROJECT_ID/finn-agent-images/finn-agent \
    --platform managed \
    --allow-unauthenticated \
    --region us-central1 \
    --project $PROJECT_ID --set-env-vars="GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=us-central1,GOOGLE_GENAI_USE_VERTEXAI=TRUE"

Nota: Establecemos dinámicamente variables de entorno, incluida GOOGLE_CLOUD_PROJECT (con la variable de shell $PROJECT_ID).

Deberías obtener un resultado similar a este, que indica que se implementó correctamente tu agente:

Deploying container to Cloud Run service [finn-agent] in project [sports-store-agent-ai] region [us-central1]
OK Deploying... Done.
  OK Creating Revision...
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [finn-agent] revision [finn-agent-00005-476] has been deployed and is serving 100 percent of traffic.
Service URL: https://finn-agent-359225437509.us-central1.run.app

Por último, prueba tu agente ejecutando este comando curl desde tu terminal de Cloud Shell:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello"}' \
  https://finn-agent-[YOUR_PROJECT_NUMBER].us-central1.run.app/chat

Obtendrás un resultado similar al siguiente:

"¡Hola! Soy Finn, tu asistente de compras deportivo con IA. Puedo ayudarte a encontrar productos, equipos y accesorios deportivos. ¿En qué puedo ayudarte?"

En este punto, validaste correctamente la implementación de AlloyDB, el kit de herramientas de MCP y tu agente compilado con el ADK.

8. Implementa el frontend

En esta sección, implementarás la interfaz de usuario conversacional para tu asistente de IA en Cloud Run. Este frontend se compila con React y JavaScript.

Antes de implementar, debes actualizar el código fuente del frontend con las URLs de tu agente implementado y tu ID de cliente de OAuth.

Con el Editor de Cloud Shell, navega a sports-agent-adk-mcp-alloydb/src/frontend/src/pages/ y abre el archivo Home.jsx. Deberás actualizar el marcador de posición de la URL del servicio de Cloud Run de tu agente. Luego, reemplázala por la URL del servicio de Cloud Run de tu agente del paso anterior (p.ej., https://finn-agent-[YOUR_PROJECT_NUMBER].us-central1.run.app).

Ahora, navega a sports-agent-adk-mcp-alloydb/src/frontend/src/components/ y abre el archivo GoogleSignInButton.jsx. Actualizarás este archivo con el ID de cliente de OAuth que obtuviste en la sección "Configuración del servicio de autorización":

Implementa el frontend en Cloud Run

Ahora que configuraste tu aplicación de frontend, puedes implementarla en Cloud Run.

Ejecuta el siguiente comando en una terminal de Cloud Shell desde el directorio raíz (sports-agent-adk-mcp-alloydb/) para crear un repositorio de Docker en Artifact Registry para tus imágenes de frontend.

gcloud artifacts repositories create finn-frontend-images \
    --repository-format=docker \
    --location=us-central1 \
    --project=$PROJECT_ID \
    --description="Repository for finn-frontend images"

A continuación, compila la imagen de Docker para tu aplicación de frontend con Cloud Build. Ejecuta este comando desde el directorio raíz de tu proyecto:

gcloud builds submit src/frontend/ --tag us-central1-docker.pkg.dev/$PROJECT_ID/finn-frontend-images/finn-frontend

Por último, implementaremos el frontend en Cloud Run con el siguiente comando:

gcloud run deploy finn-frontend \
    --image us-central1-docker.pkg.dev/$PROJECT_ID/finn-frontend-images/finn-frontend \
    --platform managed \
    --allow-unauthenticated \
    --region us-central1 \
    --project $PROJECT_ID

Deberías obtener un resultado similar a este, que indica que la implementación de tu frontend se realizó correctamente:

Deploying container to Cloud Run service [finn-frontend] in project [sport-store-agent-ai] region [us-central1]
OK Deploying... Done.
  OK Creating Revision...
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [finn-frontend] revision [finn-frontend-00002-mwc] has been deployed and is serving 100 percent of traffic.
Service URL: https://finn-frontend-535807247199.us-central1.run.app

Abre tu navegador web y usa la URL del servicio del paso anterior para abrir la aplicación que acabas de implementar, con la tecnología de tu agente de IA.

9. Ejecuta nuestro agente

Tu asistente de IA de Sports Store Agent, Finn, ya está completamente implementado y listo para ayudarte con las compras.

Abre tu navegador web y navega a la URL del servicio de tu aplicación de frontend desde el paso anterior. La URL sigue este formato: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

Una vez que se cargue el frontend, haz clic en el botón de la esquina superior derecha (por lo general, etiquetado como "Acceder" o un mensaje similar) para autenticarte con tus credenciales de Google. Esta acción aprovechará la configuración de OAuth que estableciste anteriormente.

Después de una autenticación exitosa, podrás interactuar con Finn. Haz clic en el botón “Comprar ahora” para comenzar tu experiencia de compra conversacional.

Usa la siguiente secuencia de comandos para probar las diversas funcionalidades de tu agente de IA. Copia y pega estas instrucciones en la interfaz de chat una por una:

¡Hola, Finn!
Busco zapatillas para correr en un ultra trail.
Cuéntame más detalles sobre Ultra Glide
Agrega Ultra Glide, talla 40, color rojo y gris a mi lista de compras.
Mostrar mi lista de compras
Buscar tiendas cercanas
Haz un pedido con mi lista de compras para la tienda Sports Diagonal Mar.
Cómo consultar el estado de mis pedidos
Enumera los métodos de entrega de la tienda Sports Diagonal Mar
Actualiza el método de entrega a Entrega exprés para mi pedido [TU_NÚMERO_DE_PEDIDO]
Cómo consultar el estado de mis pedidos
¡Gracias, Finn!

Para ver una demostración visual del agente de Finn implementado y sus capacidades, mira el siguiente video:

Demostración de un asistente de IA de agente deportivo potenciado por AlloyDB

10. Resultados

Después de ejecutar la secuencia de comandos anterior, validaste correctamente la integración completa de tu agente del ADK, su conexión a AlloyDB y su uso de la MCP Toolbox. En esta sección, se destacan las capacidades principales que implementaste.

Servicio de autorización

La caja de herramientas de MCP para bases de datos proporciona la capacidad de federar un servicio de autorización (específicamente, Acceso con Google en este codelab) para autenticar a los usuarios dentro de tu aplicación. Con MCP Toolbox, tu ID de cliente de OAuth se usa para validar la identidad del usuario cuando se invoca una herramienta.

Este sólido mecanismo de autenticación ofrece una excelente solución para proteger tu aplicación basada en agentes contra la inyección de instrucciones, un tipo de ataque en el que la entrada maliciosa intenta eludir o manipular el comportamiento previsto del agente. Para obtener más detalles, puedes consultar el artículo de Wikipedia sobre inyección de instrucciones .

En esta aplicación, se utiliza esta técnica cuando un usuario pide "consultar el estado de nuestros pedidos" o "mostrar mi lista de compras". El agente está diseñado para mostrar solo los pedidos que pertenecen al usuario autenticado, lo que evita el acceso no autorizado a la información de los pedidos.

Búsqueda de vectores

Tu aplicación basada en agentes aprovecha AlloyDB para PostgreSQL para proporcionar capacidades de consulta avanzadas, en particular a través de la búsqueda vectorial. AlloyDB admite la generación de embeddings en línea directamente dentro de la base de datos con funciones de SQL.

Esta potente función permite que el agente traduzca la entrada de lenguaje natural de un usuario en una representación numérica de la incorporación. Posteriormente, puede ejecutar una búsqueda de similitud en tu catálogo de productos (o en otros datos relevantes) en función de estos embeddings, lo que permite obtener resultados de búsqueda muy pertinentes.

En tu aplicación, experimentas esta técnica cuando le preguntas a Finn: "Estoy buscando zapatillas para correr en un ultra trail".

Capacidades geoespaciales (PostGIS)

AlloyDB para PostgreSQL mantiene el 100% de compatibilidad con las funciones estándar de PostgreSQL. En esta aplicación, utilizamos la popular extensión de PostgreSQL PostGIS para proporcionar capacidades de ubicación geoespacial al agente.

Cuando le pides al agente: "Encuentra tiendas cerca de mí", el agente ejecuta una herramienta que aprovecha los índices de PostGIS dentro de la base de datos para ubicar de manera eficiente las tiendas más cercanas a la ubicación especificada o inferida del usuario.

11. (Opcional) Prueba la función de lenguaje natural a SQL de AlloyDB AI

En esta sección, se presenta una función avanzada en versión previa a la DG de AlloyDB para PostgreSQL: Lenguaje natural a SQL. Esta función te permite generar consultas en SQL directamente a partir de instrucciones en lenguaje natural, lo que aprovecha el poder de la IA dentro de tu base de datos.

Importante: Como esta es una función previa a la GA, debes registrarte y habilitar el acceso para tu proyecto de Google Cloud, clúster de AlloyDB y base de datos.

Regístrate para obtener acceso: Completa este formulario para solicitar acceso a tu proyecto.
Documentación: Puedes obtener más información para aprovechar AlloyDB AI Natural Language to SQL en la documentación oficial.

Después de registrarte y confirmar el acceso a tu proyecto, sigue estos pasos en AlloyDB Studio.

Accede a AlloyDB con las credenciales que creaste cuando creaste el clúster:

Nombre de usuario: "postgres"
Base de datos: "store"
Contraseña: "alloydb"

1. Crea la extensión alloydb_ai_nl. Esta extensión proporciona las funciones necesarias para las capacidades de lenguaje natural de AlloyDB AI.

CREATE EXTENSION alloydb_ai_nl cascade;

2: Crea una configuración para tu aplicación. Una configuración define el contexto del esquema que usará el modelo de IA para comprender tu base de datos.

SELECT
 alloydb_ai_nl.g_create_configuration(
   'finn_app_config'        -- configuration_id
 );

3: Registra el esquema o las tablas con la configuración. Agrega a la configuración las tablas y los esquemas específicos con los que interactuará el agente de tu aplicación.

SELECT alloydb_ai_nl.g_manage_configuration(
   operation => 'register_table_view',
   configuration_id_in => 'finn_app_config',
   table_views_in=>'{public.products, public.products_variants, public.orders, public.orders_items, public.users, public.inventory, public.stores}'
);

4: Genera el contexto para el esquema o las tablas. En este paso, se procesan las tablas registradas para generar el contexto necesario para el modelo de IA. Este proceso puede tardar aproximadamente entre 2 y 3 minutos.

SELECT alloydb_ai_nl.generate_schema_context(
 'finn_app_config',
 TRUE
);

5: Verifica el contexto generado automáticamente para tablas y columnas específicas (opcional). Puedes inspeccionar el contexto generado para comprender cómo interpreta tu esquema el modelo de IA.

SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'public.inventory';


SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'public.products.name';


SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'public.products.popularity_score';

Encontrarás una herramienta llamada "check-inventory-by-store-brand-category" en el archivo "tools.yaml" de nuestro agente. Esta herramienta usa AlloyDB Natural Language to SQL:

Abre un navegador web y usa la URL del servicio para abrir la aplicación: "https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app".

Luego, usa la siguiente secuencia de comandos en la interfaz de chat para probar esta nueva capacidad:

¡Hola, Finn!
¿Cuál es la cantidad total de productos de la categoría Running de Salomon que hay en stock en la tienda "Sports Diagonal Mar"?

Para ver la consulta en SQL real que generó AlloyDB AI a partir de tu entrada en lenguaje natural, vuelve a AlloyDB Studio y ejecuta la siguiente consulta:

SELECT
   alloydb_ai_nl.get_sql(
       'finn_app_config',
       'What is the total quantity of category Running products of Salomon in stock at the "Sports Diagonal Mar" store?'
   ) ->> 'sql';

Se mostrará la instrucción SQL que generó AlloyDB AI.

12. Limpieza

Sigue estos pasos para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usaste en este lab:

En la consola de Google Cloud, ve a la página Administrar recursos.
En la lista de proyectos, elige el proyecto que quieres borrar y haz clic en Borrar.
En el diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrarlo.

13. Felicitaciones

¡Felicitaciones! Creaste correctamente una aplicación de IA basada en datos y con agentes usando el ADK, el kit de herramientas de MCP para bases de datos y AlloyDB para PostgreSQL.

Para obtener más información, consulta la documentación del producto: Kit de desarrollo de agentes, Caja de herramientas de MCP para bases de datos y AlloyDB para PostgreSQL