Crea una cadena de suministro autónoma con Gemini 3 Flash y AlloyDB AI

1. Descripción general

La era de los "chatbots que leen" está llegando a su fin. Estamos entrando en la era de la Visión Agentic.

En este codelab, implementaremos la ingeniería de IA determinística, una práctica para crear sistemas de IA que no adivinen. Los modelos de IA estándar suelen "alucinar" (adivinar) cuando se les pide que cuenten elementos en una imagen compleja. En una cadena de suministro, una suposición es peligrosa. Si una IA adivina que tienes 12 artículos cuando en realidad tienes 15, se producen errores costosos.

Crearemos un agente de cadena de suministro autónoma con el nuevo bucle Pensar, actuar y observar en Gemini 3 Flash. No solo mira, sino que investiga.

La arquitectura determinística

Comenzaremos con un sistema "ciego" y "amnésico". Despertarás sus sentidos de forma manual uno por uno:

The Eyes (agente de visión): Habilitamos Gemini 3 Flash con Ejecución de código. En lugar de predecir tokens para adivinar un número, el modelo escribe código de Python (OpenCV) para contar píxeles de forma determinística.
La memoria (agente proveedor): Habilitamos AlloyDB AI con ScaNN (vecinos más cercanos escalables). Esto permite que el agente recuerde el proveedor exacto de una pieza entre millones de opciones en milisegundos.
El handshake (protocolo A2A): Habilitamos la comunicación Agent-to-Agent con un archivo agent_card.json estandarizado , lo que permite que el agente de Visión solicite stock de forma autónoma al agente de Proveedores.

Qué compilarás

Un agente de visión que realiza "cálculos visuales" en los feeds de la cámara.
Un agente de proveedores respaldado por ScaNN de AlloyDB para la búsqueda de vectores de alta velocidad.
Un frontend de Control Tower con actualizaciones de WebSocket en tiempo real para visualizar el bucle autónomo.

Qué aprenderás

Cómo configurar AlloyDB con embeddings de vectores e índices de ScaNN
Cómo habilitar Agentic Vision con gemini-3-flash-preview usando la API de Gemini
Cómo implementar la búsqueda de vectores con el operador <=> (distancia del coseno) en AlloyDB
Cómo conectar agentes a AlloyDB con el conector de Python de AlloyDB
Cómo usar el protocolo A2A para el descubrimiento dinámico de agentes

Requisitos

Un navegador, como Chrome o Firefox.
Un proyecto de Google Cloud con facturación habilitada.
Una clave de la API de Gemini (nivel gratuito disponible en Google AI Studio) para el agente de Vision.

2. Antes de comenzar

Crea 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.

Usarás Cloud Shell, un entorno de línea de comandos que se ejecuta en Google Cloud. Haz clic en Activar Cloud Shell en la parte superior de la consola de Google Cloud.

Imagen del botón Activar Cloud Shell

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

gcloud auth list

Configurar la base de datos [AlloyDB]

Antes de cualquier otra cosa, aprovisionemos la base de datos. Esto lleva alrededor de 15 minutos, así que lo haremos primero.

Haz clic en el siguiente botón para abrir la herramienta de configuración de AlloyDB en Cloud Shell:

Ejecuta la configuración:

Sh run.sh

Usa la vista previa web (ícono de ojo 👁️ → Vista previa en el puerto 8080) para abrir la IU de configuración.
Ingresa tu ID del proyecto, selecciona una región (p.ej., us-central1) y crea una contraseña de base de datos.

⚠️ GUARDA ESTA CONTRASEÑA, la necesitarás cuando la secuencia de comandos de configuración la solicite.

Haz clic en Start Deployment y espera unos 15 minutos para que se aprovisione el clúster.

Obtener el código

Mientras se aprovisiona AlloyDB (o una vez que se complete el proceso), abre el repo del codelab en Cloud Shell:

⚠️ IMPORTANTE: Cuando hagas clic en el botón, verás un diálogo de seguridad. Marca la casilla “Trust repo” y haz clic en “Confirm”.

También puedes clonar el repositorio de forma manual:

git clone https://github.com/MohitBhimrajka/visual-commerce-gemini-3-alloydb.git

cd visual-commerce-gemini-3-alloydb

Configura tu proyecto

En esta terminal de Cloud Shell, confirma que tu proyecto esté configurado:

gcloud config set project <YOUR_PROJECT_ID>

Habilita la IP pública en AlloyDB

Una vez que se complete el aprovisionamiento de AlloyDB, habilita la IP pública para que el conector de Python pueda conectarse desde Cloud Shell:

Ve a la consola de AlloyDB.
Haz clic en tu clúster → haz clic en tu instancia principal
Haga clic en Editar.
Desplázate hasta Conectividad de IP pública y marca Habilitar IP pública.
Haz clic en Actualizar instancia.

💡 Nota: El conector de Python de AlloyDB controla la autenticación y la encriptación, por lo que no es necesario que agregues ninguna red externa autorizada.

Otorga permisos de Vertex AI

La cuenta de servicio de AlloyDB necesita acceso a Vertex AI para generar incorporaciones. Ejecuta este comando en la misma ventana de Cloud Shell:

PROJECT_ID=$(gcloud config get-value project)


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

Ejecuta la secuencia de comandos de configuración

Ahora ejecuta la secuencia de comandos de configuración. Detectará automáticamente tu instancia de AlloyDB:

sh setup.sh

Qué hace la secuencia de comandos:

Valida la CLI de gcloud, la autenticación, el proyecto y Python 3
Verifica y habilita las APIs requeridas (AlloyDB, Vertex AI, Compute y Service Networking)
Solicitudes para tu clave de API de Gemini
Detecta automáticamente tu instancia de AlloyDB y extrae la región, el clúster y el nombre de la instancia
Te solicita la contraseña de la base de datos
Genera el archivo de configuración .env
Instala dependencias de Python

3. Configuración de la base de datos

AlloyDB para PostgreSQL es el núcleo de nuestra aplicación. Usaremos sus potentes capacidades de vectores y el índice de ScaNN para habilitar la búsqueda semántica casi en tiempo real, lo que permitirá que nuestros agentes encuentren coincidencias de inventario en miles de registros en milisegundos.

En esta sección, aprovisionarás el esquema, propagarás los datos y generarás embeddings, todo desde AlloyDB Studio.

Conéctate a AlloyDB Studio

Ve a tu instancia de AlloyDB en la consola de AlloyDB.
Haz clic en AlloyDB Studio en el panel de navegación izquierdo.
Autentica con:
Nombre de usuario: postgres
Base de datos: postgres
Contraseña: La contraseña que configuraste durante la creación del clúster

Habilitar extensiones

AlloyDB proporciona extensiones integradas para vectores y la IA. Ejecuta el siguiente código SQL en AlloyDB Studio:

CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS alloydb_scann CASCADE;

google_ml_integration: Habilita la función ai.embedding() para llamar a Vertex AI directamente desde SQL.
vector: Almacena y consulta embeddings de vectores de 768 dimensiones.
alloydb_scann: Habilita el índice ScaNN de Google para la búsqueda de vectores ultrarrápida.

Crea la tabla de inventario

DROP TABLE IF EXISTS inventory;

CREATE TABLE inventory (
    id SERIAL PRIMARY KEY,
    part_name TEXT NOT NULL,
    supplier_name TEXT NOT NULL,
    description TEXT,
    stock_level INT DEFAULT 0,
    part_embedding vector(768)
);

La columna part_embedding almacena vectores de 768 dimensiones de text-embedding-005. Esto es lo que impulsa la búsqueda semántica.

Inserta datos de muestra

Inserta 20 elementos del inventario de almacén:

INSERT INTO inventory (part_name, supplier_name, description, stock_level) VALUES
('Cardboard Shipping Box Large', 'Packaging Solutions Inc', 'Heavy-duty corrugated cardboard shipping container, 24x18x12 inches', 250),
('Warehouse Storage Container', 'Industrial Supply Co', 'Stackable plastic storage bin with snap-lock lid, blue', 180),
('Product Shipping Boxes', 'Acme Packaging', 'Medium corrugated boxes for warehouse storage, 18x14x10 inches', 320),
('Industrial Widget X-9', 'Acme Corp', 'Heavy-duty industrial coupling for pneumatic systems', 50),
('Precision Bolt M4', 'Global Fasteners Inc', 'Stainless steel M4 allen bolt, 20mm length, grade A2-70', 200),
('Hexagonal Nut M6', 'Metro Supply Co', 'Galvanized steel hex nut M6, DIN 934 standard', 150),
('Phillips Head Screw 3x20', 'Acme Corp', 'Zinc-plated Phillips head wood screw, 3mm x 20mm', 500),
('Wooden Dowel 10mm', 'Craft Materials Ltd', 'Hardwood birch dowel rod, 10mm diameter x 300mm length', 80),
('Rubber Gasket Small', 'SealTech Industries', 'Buna-N rubber gasket, 25mm OD x 15mm ID, oil resistant', 120),
('Spring Tension 5kg', 'Mechanical Parts Co', 'Stainless steel compression spring, 5kg load capacity', 60),
('Bearing 6204', 'Bearings Direct', 'Deep groove ball bearing 6204-2RS, 20x47x14mm sealed', 45),
('Warehouse Shelf Boxes', 'Storage Systems Ltd', 'Standardized warehouse inventory boxes, corrugated, bulk pack', 400),
('Inventory Container Units', 'Supply Chain Pros', 'Modular stackable storage units for warehouse racking', 95),
('Aluminum Extrusion Bar', 'MetalWorks International', 'T-slot aluminum extrusion 20x20mm profile, 1 meter length', 110),
('Cable Tie Pack 200mm', 'ElectroParts Depot', 'Nylon cable ties, 200mm x 4.8mm, UV resistant black, pack of 100', 600),
('Hydraulic Hose 1/2 inch', 'FluidPower Systems', 'High-pressure hydraulic hose, 1/2 inch ID, 3000 PSI rated', 35),
('Safety Goggles Clear', 'WorkSafe Equipment Co', 'ANSI Z87.1 rated clear safety goggles, anti-fog coating', 275),
('Packing Tape Industrial', 'Packaging Solutions Inc', 'Heavy-duty polypropylene packing tape, 48mm x 100m, clear', 450),
('Stainless Steel Sheet 1mm', 'MetalWorks International', '304 stainless steel sheet, 1mm thickness, 300x300mm', 70),
('Silicone Sealant Tube', 'SealTech Industries', 'Industrial-grade RTV silicone sealant, 300ml cartridge, grey', 190);

Cómo otorgar permisos de incorporación

GRANT EXECUTE ON FUNCTION embedding TO postgres;

Genera embeddings de vectores

Esto usa la función ai.embedding() integrada de AlloyDB para llamar al modelo text-embedding-005 de Vertex AI directamente desde SQL, sin necesidad de código de Python:

UPDATE inventory
SET part_embedding = ai.embedding(
    'text-embedding-005',
    part_name || '. ' || description
)::vector
WHERE part_embedding IS NULL;

Esto genera vectores de 768 dimensiones que capturan el significado semántico del nombre y la descripción de cada parte. El índice de ScaNN los usará para realizar búsquedas de similitud ultrarrápidas. [Completar este proceso tardará entre 3 y 5 minutos aproximadamente]

Crea el índice de ScaNN

SET scann.allow_blocked_operations = true;

CREATE INDEX IF NOT EXISTS idx_inventory_scann
ON inventory USING scann (part_embedding cosine)
WITH (num_leaves=5, quantizer='sq8');

Verifica que todo haya funcionado

SELECT part_name, supplier_name, stock_level,
       (part_embedding IS NOT NULL) as has_embedding
FROM inventory
ORDER BY id;

Deberías ver 20 filas, todas con has_embedding = true.

4. Información sobre la arquitectura

Antes de realizar cambios en el código, comprendamos cómo se compila el sistema. La arquitectura sigue un patrón de "activación" progresiva:

La pila del agente

Vision Agent (agents/vision-agent/)

agent.py: Lógica principal de Gemini 3 Flash. Envía imágenes al modelo con la Ejecución de código habilitada para que escriba código de Python (OpenCV) y cuente elementos de forma determinística.
agent_executor.py: Vincula las solicitudes del protocolo A2A a la lógica del agente.
main.py: Es un servidor A2A de Uvicorn que publica /.well-known/agent-card.json y controla solicitudes.

Agente de proveedor (agents/supplier-agent/)

inventory.py: Se conecta a AlloyDB a través del conector de Python de AlloyDB (no se necesita proxy de autenticación). Contiene la función find_supplier() que realiza la búsqueda de vectores de ScaNN.
agent_executor.py: Conecta el protocolo A2A a la lógica de búsqueda de inventario.
main.py: Servidor A2A de Uvicorn con tarjeta de agente y extremo de verificación de estado.

Control Tower (frontend/)

app.py: Servidor de FastAPI y WebSocket que descubre agentes a través de A2A, coordina la canalización de visión → búsqueda → pedido y transmite actualizaciones en tiempo real al navegador.

El flujo de A2A

Control Tower lee /.well-known/agent-card.json de cada agente
Descubre capacidades (habilidades, extremos) sin URLs codificadas
Envía la imagen al agente de Vision → obtiene el recuento de elementos y la descripción
Envía la descripción como una consulta de incorporación al agente de proveedores → obtiene una coincidencia parcial
Realiza pedidos de forma autónoma

La conexión de AlloyDB

El agente de proveedores usa el conector de Python de AlloyDB en lugar del proxy de autenticación tradicional:

from google.cloud.alloydbconnector import Connector

connector = Connector()
conn = connector.connect(
    inst_uri,       # Full instance URI
    "pg8000",       # Driver
    user="postgres",
    password=DB_PASS,
    ip_type="PUBLIC",  # Cloud Shell uses Public IP
)

Esto controla la autenticación de IAM, SSL/TLS y el enrutamiento de conexiones de forma automática. Cuando realices la implementación en Cloud Run más adelante, simplemente cambia ip_type a "PRIVATE" para el acceso a la VPC.

5. Paso 1: La memoria (agente de proveedores)

El agente de proveedores recuerda millones de piezas con AlloyDB ScaNN. Por el momento, se incluye con una consulta de marcador de posición, un amnésico que devuelve la primera fila que encuentra, independientemente de lo que busques.

La auditoría: El amnésico

Si consultas al agente de proveedores ahora, este devolverá un resultado aleatorio. No tiene concepto de similitud. Sin embargo, podemos solucionarlo.

Inicia el agente de proveedores

El servidor A2A (main.py) delega en agent_executor.py, que une el protocolo a la lógica de negocios en inventory.py.

pkill -f uvicorn #Kill all uvicorn processes

Paso 1: Navega al directorio del agente

cd agents/supplier-agent

Paso 2: Instala las dependencias

pip install -r requirements.txt

Paso 3: Inicia el servidor del agente

uvicorn main:app --host 0.0.0.0 --port 8082 > /dev/null 2>&1 &

El comando > /dev/null 2>&1 & ejecuta el servidor en segundo plano y suprime la salida para que no interrumpa la terminal.

Paso 4: Verifica que el agente esté en ejecución (espera de 2 a 3 segundos después de iniciarlo)

curl http://localhost:8082/.well-known/agent-card.json

Resultado esperado: JSON con la configuración del agente (debe devolverse sin errores)

La solución: Implementa el operador <=>

Abre agents/supplier-agent/inventory.py y busca la función find_supplier() alrededor de las líneas 60 a 70. Verás el marcador de posición:

# TODO: Replace this placeholder query with ScaNN vector search

sql = "SELECT part_name, supplier_name FROM inventory LIMIT 1;"
cursor.execute(sql)

Reemplaza esas dos líneas por lo siguiente:

sql = """
SELECT part_name, supplier_name,
       part_embedding <=> %s::vector as distance
FROM inventory
ORDER BY part_embedding <=> %s::vector
LIMIT 1;
"""
cursor.execute(sql, (embedding_str, embedding_str))

Qué hace:

<=> es el operador de distancia del coseno en PostgreSQL.
ORDER BY part_embedding <=> %s::vector encuentra la coincidencia más cercana (la distancia más baja = el significado semántico más cercano).
%s::vector convierte tu array de incorporación al tipo de vector de PostgreSQL.
El índice ScaNN acelera automáticamente esta consulta.

Paso 4: Guarda el archivo (Ctrl + S o Cmd + S)

Ahora, el agente usará la búsqueda semántica en lugar de mostrar resultados aleatorios.

Verificación

Prueba el descubrimiento de A2A y el inventario:

curl http://localhost:8082/.well-known/agent-card.json

python3 -c "
from inventory import find_supplier
import json
vec = [0.1]*768
r = find_supplier(vec)
if r:
    result = {'part': r[0], 'supplier': r[1]}
    if len(r) > 2:
        result['distance'] = float(r[2]) if r[2] else None
    print(json.dumps(result))
else:
    print('No result found')
"

Resultado esperado: agent-card.json devuelve la tarjeta del agente. El fragmento de Python devuelve una pieza y un proveedor de los datos iniciales.

6. Paso 2: Los ojos (agente de visión)

Mientras la base de datos está accesible, despertemos los ojos con Gemini 3 Flash. El agente de Vision realiza "cálculos visuales" a través de la ejecución de código.

La auditoría: La alucinación

Si le preguntas a un modelo multimodal estándar "¿Cuántas cajas hay en esta imagen desordenada?", procesará la imagen como una instantánea estática y hará una suposición.

El modelo dice: "Veo alrededor de 12 cajas".
Realidad: Hay 15 cajas.
Resultado: Falla en la cadena de suministro.

La solución: Despertar el bucle de pensar-actuar-observar

Habilitamos Code Execution y ThinkingConfig para que el modelo escriba Python (OpenCV) y realice el recuento de forma determinística.

Abre agents/vision-agent/agent.py .
Busca la sección GenerateContentConfig (alrededor de las líneas 68 a 78).
Quita la marca de comentario del bloque thinking_config=types.ThinkingConfig(...) y de tools=[types.Tool(code_execution=...)].
El cliente ya está configurado para usar tu GEMINI_API_KEY del entorno.

Archivo: agents/vision-agent/agent.py

config = types.GenerateContentConfig(
    temperature=0,
    # CODELAB STEP 1: Uncomment to enable reasoning
    thinking_config=types.ThinkingConfig(
        thinking_level="MINIMAL",  # Valid: "MINIMAL", "LOW", "MEDIUM", "HIGH"
        include_thoughts=False    # Set to True for debugging
    ),
    # CODELAB STEP 2: Uncomment to enable code execution
    tools=[types.Tool(code_execution=types.ToolCodeExecution)]
)

¿Por qué thinking_level="MINIMAL"?

Para esta tarea (contar elementos a través de la ejecución de código), "MINIMAL" proporciona un razonamiento suficiente para planificar la secuencia de comandos y verificar el recuento. Usar "ALTA" agregaría una latencia de 2 a 3 veces mayor sin mejorar la precisión para las tareas determinísticas. Optimización del costo y el rendimiento: Adapta la profundidad del razonamiento a la complejidad de la tarea.

La optimización del costo-rendimiento es una habilidad clave para la ingeniería de IA de producción: adapta la profundidad del razonamiento a la complejidad de la tarea.

Inicia el agente de Vision

🔄 Verificación de ruta de acceso: Si aún estás en agents/supplier-agent/, primero regresa a la raíz del repo con cd ../..

Paso 1: Navega al directorio del agente de visión

cd agents/vision-agent

Paso 2: Instala las dependencias

pip install -r requirements.txt

Paso 3: Inicia el servidor del agente de visión

uvicorn main:app --host 0.0.0.0 --port 8081 > /dev/null 2>&1 &

El comando > /dev/null 2>&1 & ejecuta el servidor en segundo plano y suprime la salida para que no interrumpa la terminal.

Verificación

Prueba el descubrimiento de A2A:

curl http://localhost:8081/.well-known/agent-card.json

Resultado esperado: JSON con el nombre y las habilidades del agente. Probarás el recuento de visión real con la IU de Control Tower en el paso 8.

7. Paso 3: El saludo (tarjeta del agente de A2A)

Nuestro agente ve el problema (Visión) y conoce al proveedor (Memoria). El protocolo A2A permite el descubrimiento dinámico: El frontend aprende a comunicarse con cada agente leyendo su tarjeta.

APIs de REST tradicionales vs. APIs de A2A

Aspecto	REST tradicional	Protocolo A2A
Detección de extremos	URLs codificadas de forma rígida en la configuración	Dinámicos a través de /.well-known/agent-card.json
Descripción de la capacidad	Documentos de la API (para humanos)	Habilidades (aptas para la lectura automática)
Integración	Código manual por servicio	Concordancia semántica: "Necesito buscar inventario" → descubre la skill
Se agregó un agente nuevo	Actualiza la configuración de todos los clientes	Sin configuración, se detecta automáticamente

Beneficio en el mundo real: En un microservicio tradicional, si agregas un tercer "agente de logística", deberás actualizar el código de la torre de control con su URL y contrato de API. Con A2A, la Torre de control la descubre automáticamente y comprende sus capacidades a través de descripciones de habilidades en lenguaje natural.

Por eso, la A2A permite la composición de agentes Plug-and-Play, el patrón arquitectónico para sistemas autónomos.

Crea la tarjeta del agente

🔄 Verificación de ruta de acceso: Si aún estás en agents/vision-agent/, primero regresa a la raíz del repo con cd ../..

La tarjeta de agente ya está incluida en agents/supplier-agent/agent_card.json. Ábrelo y revisa lo siguiente:

{
  "name": "Acme Supplier Agent",
  "description": "Autonomous fulfillment for industrial parts via AlloyDB ScaNN.",
  "version": "1.0.0",
  "skills": [{
    "id": "search_inventory",
    "name": "Search Inventory",
    "description": "Searches the warehouse database for semantic matches using AlloyDB ScaNN vector search.",
    "tags": ["inventory", "search", "alloydb"],
    "examples": ["Find stock for Industrial Widget X-9", "Who supplies ball bearings?"]
  }]
}

Puedes personalizar el nombre, la descripción o los ejemplos para que coincidan con tu caso de uso.

Reinicia el agente de proveedores para cargar la tarjeta:

Paso 1: Detén el agente en ejecución

pkill -f "uvicorn main:app.*8082"

Paso 2: Navega al directorio del agente

cd agents/supplier-agent

Paso 3: Vuelve a iniciar el agente

uvicorn main:app --host 0.0.0.0 --port 8082 > /dev/null 2>&1 &

El comando > /dev/null 2>&1 & ejecuta el servidor en segundo plano y suprime la salida para que no interrumpa la terminal.

Paso 4: Verifica la nueva tarjeta del agente (espera de 2 a 3 segundos después de iniciar)

curl http://localhost:8082/.well-known/agent-card.json

Resultado esperado: JSON con tu nombre, descripción y habilidades completados.

8. Paso 4: La Torre de Control

Ejecuta el frontend de Control Tower con FastAPI y WebSockets. Descubre agentes a través de A2A y coordina el ciclo completo con actualizaciones en tiempo real.

Iniciar todos los servicios

La forma más fácil de iniciar todos los servicios:

Verifica que estás en la raíz del repo

pwd  # Should end with: visual-commerce-gemini-3-alloydb

Luego, haz lo siguiente:

sh run.sh

Este único comando inicia lo siguiente:

Agente de Vision en el puerto 8081
Agente de proveedores en el puerto 8082
Control Tower en el puerto 8080

Espera alrededor de 10 segundos para que se inicialicen todos los servicios.

Prueba el sistema

Accede a Control Tower:

Haz clic en el botón Vista previa en la Web (ícono de ojo 👁️) en la barra de herramientas de Cloud Shell.
Selecciona “Vista previa en el puerto 8080”.
El panel de Control Tower se abrirá en una pestaña nueva.

Ejecuta la demostración:

Esquina superior derecha: Estado de la conexión (punto verde “En vivo”), botón de activación del modo DEMO/AUTO y controles de audio
Centro: Lienzo principal del flujo de trabajo con visualización de carga y análisis de imágenes
Paneles laterales (aparecen durante el análisis): Cronograma del flujo de trabajo (izquierda), seguimiento del progreso y visor de código (derecha)

Opción 1: Inicio rápido (recomendado)

En la página principal, verás una sección de "Inicio rápido" con imágenes de muestra.
Haz clic en cualquier imagen de muestra para iniciar el análisis automáticamente.
Mira el flujo de trabajo autónomo (entre 30 y 45 segundos)

Opción 2: Sube tu propio video

Arrastra y suelta una imagen de un almacén o estante (PNG, JPG, hasta 10 MB) o haz clic para examinarla.
Haz clic en "Iniciar flujo de trabajo autónomo".
Observa la canalización de 4 etapas

Qué sucede:

Descubrimiento de agentes: Los modales del protocolo A2A muestran las tarjetas del agente de Vision y del agente de Supplier con sus habilidades y extremos.
Análisis de visión: Gemini 3 Flash genera y ejecuta código de Python (OpenCV) para contar elementos. La barra de progreso muestra los pasos secundarios. Se superponen cuadros de límite en los elementos detectados. El distintivo de resultado muestra "✓ Verificado con código" o "~ Estimado".
Supplier Match: Animación de la búsqueda de vectores ScaNN de AlloyDB. Se muestran las búsquedas (p.ej., "cajas metálicas industriales"). La tarjeta de resultado muestra la pieza, el proveedor y la puntuación de confianza coincidentes
Pedido realizado: Tarjeta de recibo con el ID del pedido, la cantidad y los detalles

Sugerencia: Mantén activado el modo DEMO (en la esquina superior derecha) para pausar en cada etapa de las presentaciones. En el modo AUTO, el flujo de trabajo se ejecuta de forma continua.

¿Qué pasó?

La Torre de control usó el protocolo A2A para descubrir ambos agentes a través de /.well-known/agent-card.json, coordinó el análisis de visión (Gemini 3 Flash con ejecución de código), realizó la búsqueda de vectores (AlloyDB ScaNN) y realizó un pedido autónomo, todo con actualizaciones de WebSocket en tiempo real. Cada agente expone sus capacidades a través del estándar A2A, lo que permite la composición plug-and-play sin SDKs personalizados. Más información: Protocolo A2A

Solución de problemas

Errores relacionados con la ruta de acceso:

“No existe el archivo o el directorio” cuando ejecutas comandos: No estás en la raíz del repo.

# Check where you are
pwd

# If you're lost, navigate to home and back to repo
cd
cd visual-commerce-gemini-3-alloydb

Errores de servicio:

"Address already in use": Los procesos de ejecuciones anteriores aún están activos.

# Kill all services and restart
pkill -f uvicorn
sh run.sh  # Or manually restart individual agents

Los servicios no se inician: Verifica si los puertos están ocupados:

# Check which processes are using the ports
lsof -i :8080  # Control Tower
lsof -i :8081  # Vision Agent
lsof -i :8082  # Supplier Agent

"Connection refused" a AlloyDB: Verifica que la IP pública esté habilitada en tu instancia de AlloyDB

9. 🎁 Bonus: Implementa en Cloud Run

Opcional: Todo funciona de forma local. Sin embargo, si quieres compartir tu creación con una URL pública, sigue estos pasos:

# From repo root
sh deploy/deploy.sh

Qué sucede:

Lee tu configuración de .env
Te pide tu nombre (se muestra en la app implementada)
Implementa los 3 servicios como un solo contenedor de Cloud Run
Otorga roles de IAM para el acceso a AlloyDB
Genera una URL para compartir

Los visitantes que abran tu URL verán una ventana emergente:

10. Limpieza

Para evitar cargos, destruye todos los recursos con la secuencia de comandos de limpieza automatizada:

# From repo root
sh deploy/cleanup.sh

Se quitan de forma segura los siguientes elementos:

Clúster de AlloyDB (el principal factor de costo)
Servicios de Cloud Run (si se implementaron)
Cuentas de servicio asociadas

La secuencia de comandos solicitará confirmación antes de borrar cualquier elemento.

11. Referencias y lecturas adicionales

Todas las afirmaciones técnicas de este codelab se verifican a partir de la documentación oficial de Google Cloud y de la IA de Google.

Documentación oficial

Gemini 3 Flash:

API de Code Execution: https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/code-execution-api
Guía para desarrolladores: https://ai.google.dev/gemini-api/docs/gemini-3
Documentación del modelo: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-flash
Tarjeta de modelo: https://deepmind.google/models/gemini/flash/

IA de AlloyDB y ScaNN:

Comparativas de rendimiento de ScaNN: https://cloud.google.com/blog/products/databases/how-scann-for-alloydb-vector-search-compares-to-pgvector-hnsw
Información sobre el índice de ScaNN: https://cloud.google.com/blog/products/databases/understanding-the-scann-index-in-alloydb
Análisis detallado de la IA de AlloyDB: https://cloud.google.com/blog/products/databases/alloydb-ais-scann-index-improves-search-on-all-kinds-of-data
Prácticas recomendadas para el ajuste: https://docs.cloud.google.com/alloydb/docs/ai/best-practices-tuning-scann
Documentación de AlloyDB: https://cloud.google.com/alloydb/docs

MCP Toolbox para bases de datos (enfoque alternativo):

Caja de herramientas de MCP: https://googleapis.github.io/genai-toolbox/getting-started/introduction/

Información sobre los precios:

Precios de la API de Gemini: https://ai.google.dev/gemini-api/docs/pricing
Precios de AlloyDB: https://cloud.google.com/alloydb/pricing
Precios de Vertex AI: https://cloud.google.com/vertex-ai/pricing

Afirmaciones de rendimiento verificadas

Función	Canjear	Origen
Comparación entre ScaNN y HNSW (filtrado)	10 veces más rápido	Blog de Google Cloud (verificado)
Comparación entre ScaNN y HNSW (estándar)	4 veces más rápido	Blog de Google Cloud (verificado)
Huella de memoria de ScaNN	Entre 3 y 4 veces más pequeño	Blog de Google Cloud (verificado)
Tiempo de compilación del índice de ScaNN	8 veces más rápido	Blog de Google Cloud (verificado)
Tiempo de espera de ejecución de código	Máximo de 30 segundos	Documentos de Google Cloud (verificados)
E/S de archivos de ejecución de código	No compatible	Documentos de Google Cloud (verificados)
Comportamiento de Temperature=0	Resultado determinístico	Verificado por la comunidad

Recursos adicionales

Protocolo Agent-to-Agent (A2A):

A2A estandariza el descubrimiento y la comunicación de agentes
Tarjetas de agente que se muestran en /.well-known/agent-card.json
Estándar emergente para la colaboración de agentes autónomos

Investigación de ScaNN:

Basado en 12 años de investigación de Google
Potencia la Búsqueda de Google y YouTube a gran escala
Lanzamiento para la disponibilidad general: octubre de 2024
Primer índice de vector de PostgreSQL adecuado para millones o miles de millones de vectores

12. Modo de desafío: Mejora tus habilidades de agente

Creaste una cadena de suministro autónoma que funciona. ¿Todo listo para seguir? En estos desafíos, se aplican los patrones que aprendiste a problemas nuevos.

Desafío 1: Búsqueda basada en imágenes (incorporaciones multimodales)

Flujo actual: El agente de Vision cuenta los elementos → genera una búsqueda de texto → El agente de Supplier incorpora el texto → busca en AlloyDB

Desafío: Omitir el texto por completo: Envía la imagen recortada directamente al agente del proveedor.

Notas:

La ejecución de código del agente de Vision puede recortar elementos individuales de la imagen de la biblioteca.
El modelo multimodalembedding@001 de Vertex AI puede incorporar imágenes directamente
Modifica inventory.py para que acepte bytes de imágenes en lugar de texto
Actualiza la descripción de la habilidad de A2A para indicar "Acepta: image/jpeg o texto".

Por qué es importante: La búsqueda visual es más precisa para las piezas con apariencias complejas (variaciones de color, daños, diferencias de empaque).

Desafío 2: Observabilidad: Confianza a través de la transparencia

Estado actual: El sistema funciona, pero no puedes ver "lo que sucede internamente".

Desafío: Inspecciona los registros de consultas de AlloyDB para demostrar que se está ejecutando la búsqueda de vectores.

Pasos:

Las estadísticas de consultas están habilitadas de forma predeterminada en AlloyDB. Para verificarlo, ejecute el siguiente comando:

gcloud alloydb instances describe INSTANCE_NAME \
  --cluster=CLUSTER_NAME \
  --region=us-central1 \
  --format="value(queryInsightsConfig.queryPlansPerMinute)"

Ejecuta una búsqueda de proveedores a través de la IU
Para ver el código SQL real que se ejecutó, haz lo siguiente:

gcloud logging read \
  'resource.type="alloydb.googleapis.com/Instance" AND textPayload:"ORDER BY part_embedding"' \
  --limit 5 \
  --format=json

Resultado esperado: Verás la consulta exacta ORDER BY part_embedding <=> $1::vector LIMIT 1 con el tiempo de ejecución.

Por qué es importante: La observabilidad genera confianza. Cuando los interesados pregunten "¿Cómo toma decisiones este agente?", puedes mostrarles el plan de consulta, no solo el resultado.

Desafío 3: Composición de múltiples agentes

Desafío: Agrega un tercer agente (agente de logística) que calcule los costos de envío según la ubicación del almacén y el peso del artículo.

Arquitectura:

Resultados del agente de Vision: recuento de elementos
Salidas del agente de proveedores: ubicación del proveedor
Entradas del agente de logística (NUEVO): destino, peso → salidas: costo de envío y ETA

Sugerencia: El protocolo A2A hace que esto sea trivial: crea una nueva tarjeta de agente con una habilidad de calculate_shipping. La Torre de control lo detectará automáticamente.

Patrón que aprenderás: Este es el núcleo de la arquitectura orientada a agentes: sistemas complejos creados a partir de especialistas pequeños y componibles.

13. Conclusión

Realizaste la transición de IA generativa a IA de agentes correctamente.

Lo que creamos:

Visión: Reemplazamos la "adivinación" por la ejecución de código (Gemini 3 Flash a través de la clave de API).
Memoria: Reemplazamos la "búsqueda lenta" por AlloyDB ScaNN (a través de GCP).
Acción: Reemplazamos "Integración de API" por el protocolo A2A.

Beneficios de la arquitectura híbrida:

En este codelab, se demostró un enfoque híbrido:

Agente de Vision: Usa la API de Gemini (clave de API). Es simple, tiene un nivel gratuito disponible y no requiere facturación de GCP.
Agente de proveedores: Usa GCP (Vertex AI + AlloyDB), apto para el cumplimiento y de nivel empresarial

Esta es la arquitectura de la economía autónoma. El código es tuyo.

Próximos pasos

Obtén tu clave de API de Gemini (nivel gratuito disponible)
Explora la documentación de la API de Gemini
Consulta la documentación de AlloyDB AI
Explora la ejecución de código de Gemini