Compila e implementa en Google Cloud con Antigravity

1. Introducción

En este codelab, aprenderás a usar Google Antigravity para diseñar, compilar e implementar una aplicación sin servidores en Google Cloud. Compilaremos una canalización de documentos sin servidores y basada en eventos que transfiera archivos de Google Cloud Storage (GCS), los procese con Cloud Run y Gemini, y transmita sus metadatos a BigQuery.

Qué aprenderás

• Cómo usar Antigravity para la planificación y el diseño de la arquitectura
• Generar infraestructura como código (secuencias de comandos de shell) con un agente de IA
• Compilar e implementar un servicio de Cloud Run basado en Python
• Integrar Gemini en Vertex AI para el análisis multimodal de documentos
• Verificar la canalización de extremo a extremo con el artefacto de explicación de Antigravity

Requisitos

• Google Antigravity instalado (si necesitas ayuda para instalar Antigravity y comprender los conceptos básicos, te recomendamos que completes el codelab: Primeros pasos con Google Antigravity)
• Un proyecto de Google Cloud con facturación habilitada
• La CLI de gcloud instalada y autenticada.

2. Descripción general de la app

Antes de comenzar a diseñar e implementar la aplicación con Antigravity, primero describamos la aplicación que queremos compilar.

Queremos compilar una canalización de documentos sin servidores y basada en eventos que transfiera archivos de Google Cloud Storage (GCS), los procese con Cloud Run y Gemini, y transmita sus metadatos a BigQuery.

Un diagrama de arquitectura de alto nivel para esta aplicación podría verse de la siguiente manera:

No es necesario que sea preciso. Antigravity puede ayudarnos a determinar los detalles de la arquitectura a medida que avanzamos. Sin embargo, es útil tener una idea de lo que quieres compilar. Cuanto más detalles puedas proporcionar, mejores resultados obtendrás de Antigravity en términos de arquitectura y código.

3. Planifica la arquitectura

Ya estamos listos para comenzar a planificar los detalles de la arquitectura con Antigravity.

Antigravity se destaca en la planificación de sistemas complejos. En lugar de escribir código de inmediato, podemos comenzar definiendo la arquitectura de alto nivel.

Primero, asegúrate de estar en el Administrador de agentes. Si acabas de abrir Antigravity, puedes hacer clic en el botón Open Agent Manager en el medio o también deberías ver el mismo Open Agent Manager en la esquina superior derecha.

Primero, crea una carpeta para la aplicación, por ejemplo, document-pipeline, y agrégala como un espacio de trabajo en el Administrador de agentes:

En el Administrador de agentes, inicia una conversación en el espacio de trabajo document-pipeline. Asegúrate de que el modo Plan también esté habilitado:

En la esquina superior derecha, haz clic en el ícono de configuración ⚙️ y establece Review Policy en Artifact a Asks for Review y Terminal Command Auto Execution en Terminal a Request Review. Esto garantizará que, en cada paso, puedas revisar y aprobar el plan antes de que el agente lo ejecute.

Instrucción

Ahora, ya podemos proporcionar nuestra primera instrucción a Antigravity.

Primero, verifica que Antigravity esté en modo Plan y, para el modelo, usemos el modelo Gemini Pro (High) (pero no dudes en experimentar con otros modelos).

Ingresa la siguiente instrucción y haz clic en el botón Enviar:

I want to build a serverless event-driven document processing pipeline on Google Cloud.
Architecture:
- Ingestion: Users upload files to a Cloud Storage bucket.
- Trigger: File uploads trigger a Pub/Sub message.
- Processor: A Python-based Cloud Run service receives the message, processes the file (simulated OCR), and extracts metadata.
- Storage: Stream the metadata (filename, date, tags, word_count) into a BigQuery dataset. 

Lista de tareas y plan de implementación

Antigravity analizará tu solicitud y generará una lista de tareas y un plan de implementación.

Este plan describe lo siguiente:

• Infraestructura: Bucket de GCS, tema de Pub/Sub y conjunto de datos de BigQuery
• Procesador: App de Python/Flask, Dockerfile y requisitos
• Integración: Notificaciones de GCS → Pub/Sub → Cloud Run.

Deberías ver un resultado similar al siguiente:

Haz clic en el botón Open junto a la fila Task. Esto debería mostrarte un conjunto de tareas que creó Antigravity. El agente las revisará una por una:

El siguiente paso es revisar el plan de implementación y otorgarle permiso al agente para continuar.

Haz clic en el plan de implementación para ver sus detalles. Léelo con atención. Esta es tu oportunidad para proporcionar comentarios sobre la implementación. Puedes hacer clic en cualquier parte del plan de implementación y agregar comentarios. Una vez que agregues algunos comentarios, asegúrate de enviar para su revisión los cambios que te gustaría ver, en especial en lo que respecta a la asignación de nombres, el ID del proyecto de Google Cloud, la región, etcétera.

Una vez que todo se vea bien, haz clic en el botón Proceed para otorgarle permiso al agente para continuar con el plan de implementación.

4. Genera la aplicación

Una vez que se aprueba el plan, Antigravity comienza a generar los archivos necesarios para la aplicación, desde secuencias de comandos de aprovisionamiento hasta código de la aplicación.

Nota: Se te solicitarán varios comandos de la terminal (gcloud, secuencias de comandos de shell, etcétera) que el agente deberá usar para comprender el entorno y, luego, generar las secuencias de comandos en consecuencia. Haz clic en el botón Accept para que el agente avance. Si bien este lab abarca los nombres de archivo específicos que se generaron, es posible que Antigravity genere nombres de archivo diferentes, aunque el propósito y el contenido de los archivos deberían ser similares.

Antigravity creará una carpeta y comenzará a crear los archivos necesarios para el proyecto. En nuestra ejecución de muestra, vimos lo siguiente:

Se genera un archivo setup.sh o un archivo de secuencia de comandos de shell con un nombre similar, que automatiza la creación de recursos. Se encarga de lo siguiente:

1. Habilitar las APIs (run, pubsub, bigquery, storage)
2. Crear el bucket de Cloud Storage (doc-ingestion-{project-id})
3. Crear el conjunto de datos y la tabla de BigQuery (pipeline_data.processed_docs)
4. Configurar temas y notificaciones de Pub/Sub

El agente debería generar una aplicación de Python (main.py) que detecte los mensajes de envío de Pub/Sub. Usa una lógica de OCR simulada, genera recuentos y etiquetas de palabras aleatorios, y los conserva en BigQuery.

Una vez que se genere esta secuencia de comandos de configuración, Antigravity debería solicitarte que la ejecutes en tu nombre. A continuación, se muestra una pantalla de ejemplo:

Haz clic en Accept según sea necesario.

La secuencia de comandos de aprovisionamiento creará los recursos y validará que se hayan creado. Si la verificación se realiza correctamente, se pasará a compilar el contenedor y a implementarlo como un servicio (en main.py) en Cloud Run. A continuación, se muestra un resultado de ejemplo:

Como parte de la implementación del servicio, también se configurarán las suscripciones a Pub/Sub y otros elementos necesarios para que funcione esta canalización. Todo esto debería tardar unos minutos.

Mientras tanto, puedes cambiar a Inbox (desde la esquina superior izquierda), verificar las tareas Pending que esperan tu entrada:

Esta es una buena manera de asegurarte de aprobar las tareas a medida que el agente busca tus comentarios.

5. Verifica la aplicación

Una vez que se implementa la canalización, Antigravity verifica que la aplicación funcione. Antigravity automatiza esto con pasos de verificación en la lista de tareas. A continuación, se muestra una pantalla de ejemplo:

Crea un artefacto de prueba (test.txt) y quiere subirlo al bucket de Cloud Storage. Haz clic en Accept para continuar.

Si deseas ejecutar más pruebas por tu cuenta, puedes intentar subir un archivo de muestra al bucket de Cloud Storage:

gcloud storage cp <some-test-doc>.txt gs://doc-ingestion-{project-id}/

Verifica los resultados en BigQuery

Como parte del proceso de verificación, también se verificará que los datos se hayan conservado en BigQuery.

Ten en cuenta la consulta en SQL que usó para verificar los documentos.

Una vez que se complete la verificación, deberías ver que la lista de tareas está lista:

Opcional: Verificación manual

Aunque Antigravity ya verificó la aplicación, también puedes verificar manualmente en la consola de Google Cloud que se hayan creado todos los recursos. Para ello, sigue estos pasos.

Cloud Storage

Objetivo: Verifica que exista el bucket y comprueba si hay archivos subidos.

1. Navega a Cloud Storage > Buckets.
2. Busca el bucket llamado [PROJECT_ID]-doc-uploads.
3. Haz clic en el nombre del bucket para explorar los archivos.
4. Verifica lo que hiciste: Deberías ver los archivos que subiste (por ejemplo, test.txt).

Pub/Sub

Objetivo: Confirma que el tema existe y tiene una suscripción de envío.

1. Navega a Pub/Sub > Temas.
2. Busca doc-processing-topic.
3. Haz clic en el ID del tema.
4. Desplázate hacia abajo hasta la pestaña Suscripciones.
5. Verifica lo que hiciste: Asegúrate de que doc-processing-sub aparezca en la lista con el tipo de entrega "Enviar".

Cloud Run

Objetivo: Verifica el estado y los registros del servicio.

1. Navega a Cloud Run.
2. Haz clic en el servicio doc-processor.
3. Verifica lo que hiciste:
4. Estado: Marca de verificación verde que indica que el servicio está activo
5. Registros: Haz clic en la pestaña Registros. Busca entradas como "Processing file: gs://..." y "Successfully processed...".

BigQuery

Objetivo: Valida que los datos estén almacenados.

1. Navega a BigQuery > SQL Workspace.
2. En el panel Explorador, expande tu proyecto > conjunto de datos pipeline_data.
3. Haz clic en la tabla processed_docs.
4. Haz clic en la pestaña Vista previa.
5. Verifica lo que hiciste: Deberías ver filas que contengan filename, upload_date, tags y word_count.

Explicación

Como paso final, Antigravity genera un artefacto de explicación. Este artefacto resume lo siguiente:

• Cambios realizados
• Comandos de verificación ejecutados
• Resultados reales (resultado de la consulta que muestra los metadatos extraídos de Gemini)

Puedes hacer clic en Open para verlo. A continuación, se muestra un resultado de ejemplo:

6. Explora la aplicación

En este punto, ya tienes la app básica aprovisionada y en ejecución. Antes de profundizar en la extensión de esta aplicación, tómate un momento para explorar el código. Puedes cambiar al editor con el botón Open Editor en la esquina superior derecha.

A continuación, se incluye un resumen rápido de los archivos que puedes ver:

1. setup.sh: Es la secuencia de comandos principal que aprovisiona todos los recursos de Google Cloud y habilita las APIs requeridas.
2. main.py: Es el punto de entrada principal de la canalización. Esta app de Python crea un servidor web que recibe mensajes de envío de Pub/Sub, descarga el archivo de GCS, lo "procesa" (simula OCR) y transmite los metadatos a BigQuery.
3. Dockerfile: Define cómo empaquetar la app en una imagen de contenedor.
4. requirements.txt: Muestra las dependencias de Python.

También puedes ver otras secuencias de comandos y archivos de texto necesarios para las pruebas y la verificación.

7. Extiende la aplicación

Ahora que tienes una aplicación básica en funcionamiento, puedes seguir iterando y extendiendo la aplicación. Aquí tienes algunas ideas.

Agrega un frontend

Compila una interfaz web simple para ver los documentos procesados.

Prueba la siguiente instrucción: Create a simple Streamlit or Flask web application that connects to BigQuery. It should display a table of the processed documents (filename, upload_date, tags, word_count) and allow me to filter the results by tag

Integra con IA y AA reales

En lugar del procesamiento de OCR simulado, usa modelos de Gemini para extraer, clasificar y traducir.

1. Reemplaza la lógica de OCR ficticia. Envía la imagen o el PDF a Gemini para extraer texto y datos reales. Analiza el texto extraído para clasificar el tipo de documento (factura, contrato, CV) o extraer entidades (fechas, nombres, ubicaciones).
2. Detecta automáticamente el idioma del documento y tradúcelo al inglés antes de almacenarlo. También puedes usar cualquier otro idioma.

Mejora el almacenamiento y las estadísticas

Puedes configurar reglas de ciclo de vida en el bucket para mover archivos antiguos al almacenamiento "Coldline" o "Archive" para ahorrar costos.

Solidez y seguridad

Puedes hacer que la app sea más sólida y segura, por ejemplo:

1. Colas de mensajes no entregados (DLQ): Actualiza la suscripción a Pub/Sub para controlar las fallas. Si el servicio de Cloud Run no puede procesar un archivo 5 veces, envía el mensaje a un tema o bucket de "Dead Letter" separado para que lo inspeccione un humano.
2. Secret Manager: Si tu app necesita claves de API o configuración sensible, almacénalas en Secret Manager y accede a ellas de forma segura desde Cloud Run en lugar de codificar cadenas.
3. Eventarc: Actualiza de Pub/Sub directo a Eventarc para obtener un enrutamiento de eventos más flexible, lo que te permite activar según registros de auditoría complejos o eventos de otros servicios de GCP.

Por supuesto, puedes generar tus propias ideas y usar Antigravity para ayudarte a implementarlas.

8. Conclusión

Creaste correctamente una canalización de documentos escalable, sin servidores y potenciada por IA en minutos con Google Antigravity. Aprendiste todo esto:

• Planificar arquitecturas con IA
• Dar instrucciones a Antigravity y administrarlo mientras genera la aplicación desde la generación de código hasta la implementación y la validación
• Verificar las implementaciones y la validación con explicaciones

Documentos de referencia

• Sitio oficial : https://antigravity.google/
• Documentación: https://antigravity.google/docs
• Casos de uso : https://antigravity.google/use-cases
• Descarga : https://antigravity.google/download
• Codelab : Primeros pasos con Google Antigravity