Compila e implementa en Google Cloud con Antigravity

1. Introducción

En este codelab, aprenderás a usar Google Antigravity (en el resto del documento, se hará referencia a Antigravity) para diseñar, compilar e implementar una aplicación sin servidores en Google Cloud. Crearemos 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.

Para obtener créditos de Google Cloud: Para ayudarte a usar Antigravity con proyectos de Google Cloud, canjea tus créditos gratuitos de Google Cloud con este vínculo. Puedes seguir las instrucciones aquí para activar el crédito y crear un proyecto nuevo.

Qué aprenderás

• Cómo usar Antigravity para la planificación y el diseño arquitectónico
• Genera infraestructura como código (secuencias de comandos de shell) con un agente de IA.
• Compila e implementa un servicio de Cloud Run basado en Python.
• Integra Gemini en Vertex AI para el análisis multimodal de documentos.
• Verifica la canalización de extremo a extremo con el artefacto de Walkthrough de Antigravity.

Requisitos

• Google Antigravity instalado Si necesitas ayuda para instalar Antigravity y comprender los conceptos básicos, te recomendamos que completes el siguiente codelab: Primeros pasos con Google Antigravity.
• Un proyecto de Google Cloud con facturación habilitada
• La CLI de gcloud debe estar 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 crear.

Queremos crear 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 precisa. Antigravity puede ayudarnos a definir los detalles de la arquitectura a medida que avanzamos. Sin embargo, es útil tener una idea de lo que quieres crear. Cuantos más detalles proporciones, mejores resultados obtendrás de Antigravity en términos de arquitectura y código.

3. Planifica la arquitectura

Ya podemos 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 por definir 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 del centro o también deberías ver el mismo Open Agent Manager en la esquina superior derecha.

En el Administrador de agentes, tienes la opción de abrir un espacio de trabajo o simplemente usar Playground, un espacio de trabajo independiente para prototipos y experimentación rápidos. Comencemos con Playground.

Haz clic en el botón + para iniciar una conversación nueva en Playground:

Aparecerá una interfaz en la que podrás proporcionar la instrucción, como se muestra a continuación:

En la esquina superior derecha, haz clic en el ícono de configuración ⚙️ y establece Review Policy en Artifact y Terminal Command Auto Execution en Terminal como 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, asegúrate de que el modo Antigravity esté activado Planning y, para el modelo, usemos el modelo Gemini Pro (High) (pero puedes experimentar con otros modelos).

Ingresa la siguiente instrucción y haz clic en el botón de envío:

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.

En este plan, se describe lo siguiente:

• Infraestructura: Es el bucket de GCS, el tema de Pub/Sub y el conjunto de datos de BigQuery.
• Procesador: App de Python/Flask, Dockerfile, 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. Deberías ver un conjunto de tareas creadas por Antigravity. El agente los revisará uno por uno:

El siguiente paso es revisar el plan de implementación y otorgarle permiso al agente para que continúe.

Haz clic en el plan de implementación para ver sus detalles. Léelo con atención. Esta es tu oportunidad para brindar 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 quieras ver, especialmente los relacionados con la nomenclatura, el ID del proyecto de Google Cloud, la región, etcétera.

Cuando todo esté bien, haz clic en el botón Proceed para darle permiso al agente para que continúe 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 las secuencias de comandos de aprovisionamiento hasta el código de la aplicación.

Nota: Se te solicitarán varios comandos de 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 según corresponda. Haz clic en el botón Accept para que el agente avance. Si bien este lab abarca los nombres de archivos específicos que se generaron, es posible que Antigravity genere nombres de archivos diferentes, aunque la intención 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 de secuencia de comandos de shell setup.sh o con un nombre similar, que automatiza la creación de recursos. Se encarga de lo siguiente:

1. Habilitación de APIs (run, pubsub, bigquery, storage)
2. Crear el bucket de Google 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 debe generar una aplicación de Python (main.py) que detecte los mensajes push de Pub/Sub. Utiliza una lógica de OCR simulada, genera recuentos y etiquetas de palabras aleatorios, y los persiste en BigQuery.

Una vez que se genere este script de configuración, Antigravity debería solicitarte que lo 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 procederá a compilar el contenedor y a implementarlo como un servicio (en main.py) en Cloud Run. A continuación, se muestra un ejemplo del resultado:

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

Mientras tanto, puedes cambiar a Inbox (en la esquina superior izquierda) y consultar las tareas de Pending que esperan tu entrada:

Esta es una buena manera de asegurarte de que apruebas 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 realmente funcione. Antigravity automatiza este proceso 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 Google Cloud Storage. Haz clic en Accept para continuar.

Si deseas realizar más pruebas por tu cuenta, puedes tomar una sugerencia del paso de validación de Antigravity, en el que se usa la utilidad gsutil para subir un archivo de muestra al bucket de Cloud Storage. A continuación, se muestra el comando de ejemplo:

gsutil cp <some-test-doc>.txt gs://<bucket-name>/

Verifica los resultados en BigQuery

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

Observa la consulta SQL que se usó para verificar los documentos.

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

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, si lo deseas, siguiendo estos pasos.

Cloud Storage

Objetivo: Verificar que el bucket exista y buscar archivos subidos

1. Navega a Cloud Storage > Buckets.
2. Ubica el bucket llamado [PROJECT_ID]-doc-uploads.
3. Haz clic en el nombre del bucket para explorar los archivos.
4. Verifica que veas los archivos que subiste (p.ej., test.txt).

Pub/Sub

Objetivo: Confirma que el tema exista y tenga una suscripción push.

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 que doc-processing-sub aparezca con el tipo de entrega "Push".

Cloud Run

Objetivo: Comprobar el estado y los registros del servicio

1. Navega a Cloud Run.
2. Haz clic en el servicio doc-processor.
3. Verificación:
4. Estado: La marca de verificación verde 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: Validar que los datos se almacenen correctamente.

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 que veas filas que contengan filename, upload_date, tags y word_count.

Explicación

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

• Se realizaron los cambios.
• Se ejecutan los comandos de verificación.
• Resultados reales (resultado de la búsqueda que muestra los metadatos extraídos por Gemini).

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

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 que se encuentra en la esquina superior derecha.

A continuación, se incluye un breve resumen 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 push de Pub/Sub, descarga el archivo de GCS, lo "procesa" (simula el OCR) y transmite los metadatos a BigQuery.
3. Dockerfile: Define cómo empaquetar la app en una imagen de contenedor.
4. requirements.txt: Enumera las dependencias de Python.

También es posible que veas otros archivos de texto y secuencias de comandos necesarios para las pruebas y la verificación.

En este punto, también puedes pasar de Playground a un espacio de trabajo o una carpeta dedicados. Para ello, haz clic en el botón correspondiente en la esquina superior derecha:

Una vez que elijas una carpeta, todo el código se trasladará a ella y se creará un nuevo espacio de trabajo con la carpeta y el historial de conversaciones.

7. Extiende la aplicación

Ahora que tienes una aplicación básica funcional, puedes seguir iterando y extendiendo la aplicación. Estas son algunas ideas.

Agrega un frontend

Crea 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

Integración con IA/AA reales

En lugar de usar el procesamiento de OCR simulado, usa los 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, currículum vitae) o extraer entidades (fechas, nombres, ubicaciones).
2. Detectar automáticamente el idioma del documento y traducirlo 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 trasladar archivos antiguos al almacenamiento "Coldline" o "Archive" y ahorrar costos.

Robustez y seguridad

Puedes hacer que la app sea más sólida y segura de las siguientes maneras:

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 "mensajes no entregados" independiente para su inspección manual.
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 de forma rígida.
3. Eventarc: Actualiza de Pub/Sub directo a Eventarc para obtener un enrutamiento de eventos más flexible, lo que te permite activar eventos basados en registros de auditoría complejos o en otros eventos de servicios de GCP.

Por supuesto, puedes generar tus propias ideas y usar Antigravity para 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:

• Planifica arquitecturas con IA.
• Instruye y administra Antigravity mientras genera la aplicación, desde la generación de código hasta la implementación y la validación.
• Verifica las implementaciones y la validación con los tutoriales.

Documentos de referencia

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