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 supone que tienes 12 artículos cuando en realidad tienes 15, se producen errores costosos.

Crearemos un agente autónomo de la cadena de suministro que utilizará 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". Deberás "despertar" sus sentidos de forma manual uno por uno:

1. 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.
2. 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.
3. El protocolo de enlace (protocolo A2A): Habilitamos la comunicación Agente a agente 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 Proveedor.

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 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 Cloud Shell a AlloyDB con el proxy de autenticación

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

1. En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
2. 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.

Para probar este codelab, puedes usar el vínculo de crédito de facturación de prueba de GCP: https://bit.ly/cvs14-ghj

¿Cómo canjeo créditos con este vínculo? Referir.

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

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

gcloud auth list

Eso es todo.

Ya puedes realizar la configuración con un solo clic. En la siguiente sección, se hará lo siguiente:

• Abre Cloud Shell automáticamente
• Clona el repositorio
• Guiarte a través de toda la configuración en un instructivo interactivo

3. Configuración con un clic en Cloud Shell

Simplificamos la configuración en un instructivo guiado de Cloud Shell. Todo está automatizado: el aprovisionamiento de la infraestructura, la configuración de AlloyDB, la configuración del proxy de autenticación y la propagación de la base de datos.

Inicia el instructivo de Cloud Shell

⚠️ IMPORTANTE:Antes de hacer clic, cuando hagas clic en el botón que se encuentra a continuación, verás un diálogo de seguridad que te preguntará si quieres "Abrir en Cloud Shell". Esto aparece ANTES de que se clone el repositorio.

Obligaciones:

1. ✅ Marca la casilla: “Trust repo”.
2. ✅ Haz clic en "Confirmar".

Sin esto, el repositorio no se clonará.

¿Tienes todo listo? Haz clic para abrir el proyecto con un instructivo paso a paso:

One Click & Run

Qué sucederá después:

1. Cloud Shell se abre con el repositorio preclonado
2. Aparecerá un panel de explicación a la derecha con instrucciones paso a paso.
3. Te guiaremos por los siguientes pasos:

• Cómo obtener tu clave de API de Gemini (nivel gratuito disponible)
• Cómo configurar tu proyecto de GCP en la terminal
• Ejecución de la configuración (verifica las APIs, las habilita si es necesario y aprovisiona AlloyDB: ~15 minutos)
• Realizar 2 cambios clave en el código (habilitar la visión y la memoria)
• Cómo crear la tarjeta del agente (protocolo A2A)
• Cómo iniciar todos los servicios

El instructivo es interactivo: cada paso está numerado y hace un seguimiento de tu progreso.

📌 Automatizada: La secuencia de comandos de configuración verifica la autenticación, las APIs y la configuración del proyecto. Te avisa si algo requiere atención.

💡 Es seguro reiniciar: Si la configuración se atasca o falla, puedes volver a ejecutar sh setup.sh de forma segura. La secuencia de comandos detecta las instancias de AlloyDB existentes y omite el aprovisionamiento, retomando el proceso donde lo dejaste.

Alternativa: Configuración manual

Si prefieres el control manual, haz lo siguiente:

1. Abre Cloud Shell y verifica que tu proyecto esté configurado

gcloud config get-value project

2. Si es necesario, configura tu proyecto.

gcloud config set project YOUR_PROJECT_ID

3. Clona el repositorio

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

4. Ejecuta la configuración

sh setup.sh

Sigue las instrucciones en pantalla del script de configuración.

Próximos pasos: El instructivo te guía por los pasos restantes. Cuando termines, continúa con la sección 4 para comprender qué sucedió en segundo plano.

4. Detrás de escena: Proxy de autenticación y propagación de bases de datos

Nota: Si usaste el instructivo completo de Cloud Shell, todo esto se automatizó. En esta sección, se explica lo que sucedió en segundo plano.

El problema: AlloyDB reside dentro de una VPC privada. Cloud Shell está fuera de él. La conexión directa es imposible.

La solución: El proxy de autenticación de AlloyDB crea un túnel seguro y autenticado por IAM desde 127.0.0.1:5432 en Cloud Shell hasta tu instancia de AlloyDB. Si tu instancia tiene habilitada la IP pública, el proxy la usa. De lo contrario, se conecta a través de la IP privada de la VPC.

Qué hizo setup.sh

1. Se detectó automáticamente tu instancia de AlloyDB (clúster, región y proyecto).
2. Se creó .env con todas las credenciales (GEMINI_API_KEY, DB_PASS, detalles de AlloyDB).
3. Descargaste y, luego, iniciaste el proxy de autenticación (con –public-ip si corresponde).
4. Se completó la base de datos con 8 piezas de inventario de muestra y el índice de ScaNN.

Tu archivo .env está listo. Todas las ejecuciones futuras cargarán las credenciales automáticamente.

Verifica que funcionó

Asegúrate de que aún estás en la raíz del repo.

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

Verifica que el proxy de autenticación esté en ejecución

ps aux | grep alloydb-auth-proxy

Qué se creó

• Tabla de inventario con 8 partes y embeddings de 768 dimensiones
• Índice ScaNN (idx_inventory_scann) para la búsqueda de vectores rápida

Errores comunes:

• "DB_PASS not set": Vuelve a ejecutar sh setup.sh para volver a crear .env.
• "Connection refused": Es posible que el proxy de autenticación necesite más tiempo. Espera 30 segundos y vuelve a intentarlo.
• "No instance found": Verifica la implementación: gcloud alloydb instances list
• "Error de bus" (el proxy de autenticación falla): Corrupción binaria. Corrección: rm alloydb-auth-proxy && sh setup.sh

5. Paso 1: La memoria (agente del proveedor)

Nota: Si usaste el instructivo de Cloud Shell, ya realizaste este cambio de código. En esta sección, se explica por qué es importante y cómo funciona.

El agente de proveedores recuerda millones de piezas con AlloyDB ScaNN. Lo iniciamos como un servidor A2A y, luego, corregimos la consulta de vectores.

La auditoría: El amnésico

Si consultas al agente de proveedores ahora (con el SQL de marcador de posición), este devolverá la primera fila que encuentre, no la coincidencia más cercana. No tiene concepto de similitud. Es amnésico.

Inicia el agente de proveedores

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

💡 Sugerencia para solucionar problemas: Si recibes errores de "dirección ya en uso", finaliza los procesos existentes y vuelve a intentarlo:

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

Salida esperada: JSON con la configuración del agente (debe devolverse sin errores)

Embeddings semánticos reales

Durante la configuración, la base de datos se completó con embeddings semánticos reales generados a través del modelo text-embedding-005 del SDK de IA generativa de Google. Esto garantiza una correlación de similitud precisa, no vectores aleatorios. El proceso de inicialización tarda alrededor de 10 segundos para 13 elementos de muestra, ya que usa la generación de incorporaciones paralelas para crear vectores significativos de 768 dimensiones que capturan el significado semántico de cada parte.

Desvío de AlloyDB: ¿Por qué ScaNN?

Nota: La búsqueda de vectores estándar (HNSW) requiere mucha memoria. A medida que tu inventario crece a 100 millones de piezas, el índice se vuelve demasiado grande para la RAM. ScaNN (vecinos más cercanos escalables) usa la cuantización vectorial. Comprime los vectores para que el índice quepa en la caché L2 de la CPU. Esto lo hace hasta 10 veces más rápido que el HNSW estándar.

La solución: Implementa el operador <=>

El agente se entrega con una consulta de marcador de posición. Tenemos que habilitar la búsqueda de vectores de ScaNN.

Paso 1: Abre el archivo de inventario

cd agents/supplier-agent

Paso 2: Busca el TODO en inventory.py

Busca la función find_supplier() alrededor de las líneas 47 a 60. En esta página verá lo siguiente:

# ============================================================
# CODELAB STEP 1: Implement ScaNN Vector Search
# ============================================================
# TODO: Replace this placeholder query with ScaNN vector search

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

Paso 3: Reemplaza el SQL de marcador de posición por la búsqueda de vectores de ScaNN

Borra estas dos líneas:

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

Y reemplázalas por lo siguiente:

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

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 significa el significado semántico más cercano).
• %s::vector convierte tu array de incorporación al tipo de vector de PostgreSQL
• LIMIT 1 devuelve solo la coincidencia más cercana.
• 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.

Errores comunes:

• "No such file or directory": No estás en la raíz del repo. Ejecuta cd para ir a la carpeta principal y, luego, cd visual-commerce-gemini-3-alloydb, o bien usa pwd para saber dónde estás.
• Port 8082 in use: Kill existing process: lsof -ti:8082 | xargs kill -9
• ModuleNotFoundError: Instala las dependencias: pip install -r requirements.txt
• Database connection failed: Asegúrate de que el proxy de Auth siga en ejecución
• La secuencia de comandos de verificación falla: Comprueba que la inicialización se haya completado correctamente en el paso 4.

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

Nota: Si usaste el instructivo de Cloud Shell, ya habilitaste la ejecución de código. En esta sección, se explica la arquitectura y por qué este enfoque elimina las alucinaciones.

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. El servidor A2A (main.py) delega en agent_executor.py, que llama a agent.py para el análisis de Gemini.

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.

1. Abre agents/vision-agent/agent.py .
2. Busca la sección GenerateContentConfig.
3. Quita la marca de comentario del bloque thinking_config=types.ThinkingConfig(...) y de tools=[types.Tool(code_execution=...)] .
4. El cliente ya está configurado para usar tu GEMINI_API_KEY del entorno.

Nota: thinking_level="LOW" equilibra la velocidad y la precisión. Los valores válidos son "MINIMAL", "LOW", "MEDIUM" y "HIGH". Requiere google-genai>=1.56.0.

Nota sobre la arquitectura: El agente de Vision usa la API de Gemini (clave de API), mientras que el agente de Supplier usa las incorporaciones de Vertex AI (credenciales de GCP). Este enfoque híbrido mantiene la simplicidad del componente de visión y, al mismo tiempo, conserva las funciones de base de datos de nivel empresarial.

Archivo: agents/vision-agent/agent.py

config = types.GenerateContentConfig(
    temperature=0,
    # CODELAB STEP 1: Uncomment to enable reasoning
    thinking_config=types.ThinkingConfig(
        thinking_level="LOW",  # 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="LOW"?

Para esta tarea específica (contar elementos a través de la ejecución de código), "LOW" proporciona un presupuesto de razonamiento suficiente para lo siguiente:

• Planifica la estructura de la secuencia de comandos de Python
• Decide qué enfoque de procesamiento de imágenes usar
• Verifica que el recuento coincida con la cantidad de cuadros de límite.

Usar "ALTA" agregaría una latencia y un costo de 2 a 3 veces mayores sin mejorar la precisión para las tareas determinísticas. Reserva "ALTA" para el razonamiento complejo de varios pasos (p.ej., "Analiza esta interrupción de la cadena de suministro y recomienda 3 proveedores alternativos con justificación").

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.

Errores comunes:

• "No such file or directory": No estás en la raíz del repo. Usa cd ../.. para volver a la raíz del repo o verifica tu ubicación con pwd.
• Port 8081 in use: Kill existing process: lsof -ti:8081 | xargs kill -9
• GEMINI_API_KEY no está configurada: Verifica que el archivo .env exista en la raíz del repositorio con cat .env | grep GEMINI_API_KEY
• La clave de API no es válida: Verifica que la clave sea correcta y que no haya vencido.
• No se encontró google-genai: Instala las dependencias: pip install -r requirements.txt

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

Nota: Si usaste el instructivo de Cloud Shell, ya creaste esta tarjeta de agente. En esta sección, se explica el protocolo A2A y por qué permite la composición de agentes plug-and-play.

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, A2A habilita la composición de agentes Plug-and-Play, el patrón arquitectónico para sistemas autónomos.

La solución: Crea la tarjeta de agente

Tenemos que definir lo que puede hacer el agente de proveedores.

1. Copia agents/supplier-agent/agent_card_skeleton.json en agents/supplier-agent/agent_card.json.
2. Edita el archivo para reemplazar los marcadores de posición:

Antes (esqueleto):

{
  "name": "___FILL: agent-name ___",
  "description": "___FILL: what-this-agent-does ___"
}

Después (tus ediciones):

{
  "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?"]
  }]
}

3. Reinicia el agente de proveedores para que cargue la tarjeta nueva:

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

Nota: Si usaste el instructivo de Cloud Shell, tus servicios ya se están ejecutando. Ve a la sección "Prueba el sistema" que se encuentra más abajo para acceder a la Torre de control y ver el flujo de trabajo autónomo en acción.

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:

• Proxy de autenticación de AlloyDB (si no se está ejecutando)
• 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.

💡 Sugerencia para solucionar problemas: Si run.sh falla con errores de "dirección ya en uso", haz lo siguiente:

Cierra todos los servicios y vuelve a intentarlo

pkill -f uvicorn

sh run.sh

Esto sucede si los servicios aún se están ejecutando desde un intento anterior.

Prueba el sistema

Accede a Control Tower:

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

Nota: El frontend usa WebSockets en tiempo real para las actualizaciones de agentes en vivo. Verás cómo se actualizan las tarjetas de los agentes a medida que piensan, analizan y actúan, sin necesidad de actualizar la página.

Ejecuta la demostración:

1. 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
2. Centro: Lienzo principal del flujo de trabajo con visualización de carga y análisis de imágenes
3. 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)

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

Opción 2: Sube tu propio video

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

Qué sucede:

1. 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.
2. 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. La insignia de resultado muestra "✓ Verificado con código" o "~ Estimado".
3. Supplier Match: Animación de la búsqueda de vectores ScaNN de AlloyDB. Visualizaciones de búsquedas (p.ej., "cajas metálicas industriales"). La tarjeta de resultado muestra la pieza, el proveedor y la puntuación de confianza coincidentes
4. 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, orquestó el análisis de visión (Gemini 3 Flash con ejecución de código), realizó la búsqueda vectorial (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

• Se rechazó la conexión a AlloyDB: Verifica que el proxy de autenticación esté en ejecución:

ps aux | grep alloydb-auth-proxy

Problemas de conexión de AlloyDB:

Si ves el mensaje Connection to server at 127.0.0.1, port 5432 failed, haz lo siguiente:

Si ves el mensaje "Connection to server at 127.0.0.1, port 5432 failed", haz lo siguiente:

1. Comprueba el proxy de autenticación: ps aux | grep alloydb-auth-proxy
2. Verifica que la IP pública esté habilitada: gcloud alloydb instances describe INSTANCE_NAME –cluster=CLUSTER_NAME –region=us-central1 –format="value(ipAddress)"
3. Para el desarrollo local (no Cloud Shell):
4. Problema: Cloud Shell funciona automáticamente, pero las máquinas locales necesitan redes autorizadas
5. Solución: Vuelve a ejecutar sh setup.sh y elige la opción 1 (autorizar 0.0.0.0/0) cuando se te solicite.
6. Nota de seguridad: Incluso con 0.0.0.0/0, la conexión requiere lo siguiente:
7. Credenciales de GCP válidas (credenciales predeterminadas de la aplicación)
8. Contraseña de la base de datos
9. Encriptación de mTLS (el proxy de autenticación se encarga de esto)

9. Limpieza

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

# From repo root
sh 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.

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

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 Agent2Agent (A2A):

• El estándar 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 vectores de PostgreSQL adecuado para millones o miles de millones de vectores

11. 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, aplicarás 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.

Sugerencias:

1. La ejecución de código del agente de Vision puede recortar elementos individuales de la imagen de la biblioteca.
2. El modelo multimodalembedding@001 de Vertex AI puede incorporar imágenes directamente
3. Modifica inventory.py para aceptar bytes de imagen en lugar de texto
4. 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 descubrirá automáticamente.

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

12. Conclusión

Migraste correctamente de la IA generativa a la IA basada en agentes.

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 ScaNN de AlloyDB (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