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 Walkthrough de Antigravity
Requisitos
- Google Antigravity instalado
- Un proyecto de Google Cloud con facturación habilitada
- gcloud CLI 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 por definir la arquitectura de alto nivel y usar una de las funciones para ayudar a Antigravity a evaluar nuestra solicitud, hacernos preguntas adicionales y, luego, continuar con su planificación e implementación.
Suponiendo que ya iniciaste Antigravity, crearemos un proyecto nuevo para este codelab.
Haz clic en el ícono de proyecto nuevo junto al lab Projects y, luego, en New Project , como se muestra a continuación:
Aparecerá la opción Add Folder , como se muestra a continuación:
Haz clic en el botón Add Folder para agregar una carpeta a tu proyecto. En mi máquina, creé una carpeta google-cloud-serverless-app y la agregué a este proyecto.
Se abrirá una conversación en el proyecto google-cloud-serverless-app.
Haz clic en el ícono de configuración principal ⚙️ en la parte inferior izquierda de la pantalla y ve a Configuración específica del proyecto. Si no ves el proyecto google-cloud-serverless-app en la lista, solo ten una conversación y, luego, vuelve a la configuración del proyecto.
Configura Agent Settings / Security Preset en Default y Agent Behaviour / Artifact Review Policy en Always Ask, como se muestra a continuación:
Esto garantizará que, en cada paso, puedas revisar y aprobar el plan antes de que el agente lo ejecute.
Instrucción
Ahora, está todo listo para proporcionar nuestra primera instrucción a Antigravity. Usaremos un comando de barra diagonal /grill-me para evaluar nuestra solicitud.
Escribe /grill-me y, luego, ingresa la siguiente instrucción y haz clic en el botón Enviar:
/grill-me
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.
El comando /grill-me hace varias preguntas de seguimiento que puedes intentar responder de la mejor manera posible. También sugiere Recommended Answers , y puedes elegir esa opción si lo deseas.
A continuación, se muestra una ejecución de muestra de mi comando /grill-me:
How would you like the Cloud Run service to receive events from Cloud Storage and Pub/Sub?
(Recommended) Cloud Storage Pub/Sub Notification with a Pub/Sub Push Subscription (HTTP POST to Cloud Run)
How should access to the Cloud Run service endpoint be secured for Pub/Sub push requests?
Publicly accessible Cloud Run service without authentication (for prototyping/quick testing only)
How should the Python processor handle file inspection and the simulated OCR logic?
(Recommended) Download file from GCS: if plain text/utf-8, extract actual words and tags; if binary/image/PDF, simulate OCR processing (mock latency, generate synthetic text & tags, count words)
How should the processor write metadata to BigQuery and handle table/schema provisioning?
(Recommended) Use BigQuery Streaming Inserts (`insert_rows_json`) with auto-creation of the dataset and table if they do not exist
How should the Cloud Run service handle processing failures and retries from Pub/Sub?
(Recommended) Return HTTP 500 on transient errors for Pub/Sub automatic retry; return HTTP 200/204 on non-retryable errors (e.g., file not found, bad event format) to avoid poison pill loops
Which web framework would you prefer for the Python Cloud Run service?
Flask with Gunicorn: minimal, classic lightweight standard for GCP microservices
How would you like the cloud infrastructure (Bucket, Pub/Sub, Cloud Run, BigQuery) to be provisioned and deployed?
(Recommended) Provide both: automated `gcloud` CLI setup/deploy scripts for quick manual rollout AND Terraform manifests for reproducible IaC
How would you like to handle local testing and development before deploying to Google Cloud?
(Recommended) Include a local mock test suite and script (`test_local.py`) that can simulate Pub/Sub push envelopes and test processing with both mocked GCP clients and actual files
Ten en cuenta que le pedí a Antigravity que hiciera lo siguiente:
- Una secuencia de comandos simple de la CLI de gcloud para aprovisionar recursos
- Notificaciones nativas de Cloud Storage Pub/Sub + suscripción de envío de Pub/Sub a Cloud Run
- Usar Flask (con Gunicorn) para el framework
- Usar la simulación local con un archivo de texto para los datos en lugar de datos de OCR en vivo
- Usar BigQuery table.insert_rows() para insertar filas en BigQuery
- Implementación no autenticada de Cloud Run
y otras opciones recomendadas.
Plan de implementación y lista de tareas
Antigravity ahora comenzará a trabajar y generará un plan de implementación. Para que lo revises, te mostrará un mensaje similar al siguiente:
Puedes hacer clic en el botón de activación del panel auxiliar en la ventana superior derecha y ver los artefactos generados, que, en este punto, son solo el plan de implementación.
En este plan, se describe lo siguiente:
- Infraestructura: Bucket de GCS, tema de Pub/Sub, 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. A continuación, se muestra una lista parcial del plan de implementación en nuestra máquina:
Léelo con atención. Esta es tu oportunidad de 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 al agente el permiso 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.
Antigravity creará una carpeta y comenzará a crear los archivos necesarios para el proyecto. Si verificas los artefactos, notarás que se generan varios archivos (código fuente, archivos de secuencia de comandos, etcétera).
Una vez que complete su trabajo, lo mencionará y creará un documento Walkthrough que puedes consultar. A continuación, se muestra un resultado de muestra:
En el documento Walkthrough, se menciona lo que se implementó, las secuencias de comandos generadas y, lo que es más importante, la verificación y la validación que se realizaron. A continuación, se muestra un resultado parcial del documento Walkthrough que incluye la verificación y la validación:
3. Verification & Validation
Test Suite Execution
We ran the automated test suite using pytest:
bash
.venv/bin/pytest tests/ -v
tests/test_local.py::test_health_check PASSED [ 9%]
tests/test_local.py::test_invalid_pubsub_envelope PASSED [ 18%]
tests/test_local.py::test_ignore_delete_events PASSED [ 27%]
tests/test_local.py::test_gcs_file_not_found PASSED [ 36%]
tests/test_local.py::test_successful_contract_processing PASSED [ 45%]
tests/test_local.py::test_successful_pdf_ocr_processing PASSED [ 54%]
tests/test_local.py::test_transient_bq_error_triggers_500_retry PASSED [ 63%]
tests/test_processor.py::test_tag_extraction_filters_stopwords PASSED [ 72%]
tests/test_processor.py::test_process_plain_text_document PASSED [ 81%]
tests/test_processor.py::test_process_binary_pdf_simulated_ocr PASSED [ 90%]
tests/test_processor.py::test_process_empty_text_document PASSED [100%]
============================== 11 passed in 2.37s ==============================
Standalone End-to-End Simulation
We executed the standalone simulation script:
bash
.venv/bin/python tests/test_local.py
Sample Output:
=================================================================
Running Serverless Document Processing Local Simulation
=================================================================
[1] Health Check: Status=200, Payload={'service': 'document-processor', 'status': 'healthy'}
[2] Simulating GCS Event: Object Finalized 'sample_contract.txt' in 'finance-bucket'
Response: Status=200, Body={'file_name': 'sample_contract.txt', 'ocr_status': 'EXTRACTED_TEXT', 'status': 'success', 'tags': ['provider', 'cloud', 'client', 'agreement', 'shall'], 'word_count': 181}
[3] Simulating GCS Event: Object Finalized 'sample_invoice.pdf' in 'invoices-bucket'
Response: Status=200, Body={'file_name': 'sample_invoice.pdf', 'ocr_status': 'SIMULATED_OCR', 'status': 'success', 'tags': ['invoice', 'finance', 'billing', 'acme', 'pdf'], 'word_count': 62}
=================================================================
BigQuery Streamed Table Inspection (Mock Table)
=================================================================
Row #1:
File: sample_contract.txt (gs://finance-bucket)
Status: EXTRACTED_TEXT
Words: 181
Tags: ['provider', 'cloud', 'client', 'agreement', 'shall']
Processed: 2026-09-08T02:50:37.436225+00:00
Row #2:
File: sample_invoice.pdf (gs://invoices-bucket)
Status: SIMULATED_OCR
Words: 62
Tags: ['invoice', 'finance', 'billing', 'acme', 'pdf']
Processed: 2026-09-08T02:50:37.641931+00:00
¿Podemos preguntarle a Antigravity cómo implementar esta aplicación en Google Cloud? Devuelve detalles completos sobre lo mismo, como se indica a continuación. En resumen, nos pide que nos aseguremos de que el SDK de Google Cloud esté instalado junto con una configuración del proyecto de Google Cloud. Una vez que se complete ese paso,
Paso 1: Habilita las APIs de GCP necesarias
Ejecuta setup_gcp.sh para habilitar las APIs de Cloud Run, Pub/Sub, Cloud Storage, BigQuery y Cloud Build: ./scripts/setup_gcp.sh
Paso 2: Implementa toda la canalización
Ejecuta deploy.sh:
export GCP_PROJECT="<YOUR_PROJECT_ID>"
export GCP_REGION="us-central1" # or your region
./scripts/deploy.sh
¿Qué hace esta secuencia de comandos tras bambalinas?
- Compila la imagen de contenedor con Google Cloud Build y la envía a Container Registry o Artifact Registry.
- Implementa el servicio en Cloud Run con las variables de entorno adecuadas (
GCP_PROJECT,BQ_DATASET_ID,BQ_TABLE_ID). - Crea el bucket de transferencia de Cloud Storage (
gs://<PROJECT_ID>-document-ingest). - Crea el tema de Pub/Sub (
document-upload-events) y otorga permiso de GCS para publicar en él. - Configura una notificación de GCS (
OBJECT_FINALIZE) en el bucket. - Crea una suscripción de envío de Pub/Sub que apunte a la URL del servicio de Cloud Run con un retroceso de reintento automático.
También sugiere cómo probar la canalización.
Ejecuta test_pipeline.sh: ./scripts/test_pipeline.sh
Esto sube samples/sample_contract.txt y samples/sample_invoice.pdf a tu bucket, espera el procesamiento y ejecuta una consulta de SQL de BigQuery que muestra los metadatos extraídos, el recuento de palabras y las etiquetas.
5. Implemente la aplicación
Implementemos la aplicación como se mencionó. Podemos pedirle a Antigravity que lo ejecute por nosotros, pero, antes de hacerlo, asegúrate de que la gcloud CLI esté presente y configurada para el proyecto de Google Cloud.
Podemos darle una instrucción a Antigravity "Deploy the application for me". Esto te solicitará varios permisos y, luego, ejecutará los archivos de secuencia de comandos.
Inicia el proceso como una tarea en segundo plano, como se explica en el siguiente mensaje:
I have initiated the deployment of the document processing pipeline to Google Cloud project PROJECT_ID in REGION.The deployment process is currently executing in the background:
Building and publishing the container image via Cloud Build.
Configuring service account IAM permissions and deploying the Cloud Run service.
Provisioning the Cloud Storage bucket (gs://PROJECT_ID-document-ingest).
Setting up the Pub/Sub topic, GCS notification, and push subscription.
I will notify you as soon as the deployment finishes!
6. Verifica la aplicación
Una vez que se implementa la canalización, Antigravity continúa para verificar que la aplicación funcione. Nos pregunta si puede ejecutar el archivo test_pipeline.sh. Podemos otorgarle permiso.
Finalmente, nos dice lo siguiente:
🚀 Deployment Successful & Verified on Google Cloud!
The application has been deployed to Google Cloud project PROJECT_ID in REGION and end-to-end event-driven processing has been verified.
También actualizó el artefacto Walkthrough para ver los resultados (la lista parcial se muestra a continuación):
Resumen de la implementación
- Proyecto de GCP: PROJECT_ID
- Región: REGION
- Servicio de Cloud Run: document-processor
- Extremo de Cloud Run: SERVICE_URL
- Bucket de Cloud Storage: gs://PROJECT_ID-document-ingest
- Tema de Pub/Sub: document-upload-events
- Suscripción de envío de Pub/Sub: document-upload-events-push-sub
- Destino de BigQuery: PROJECT_ID.document_processing.document_metadata
Verificación de la canalización en vivo
Ejecutamos scripts/test_pipeline.sh en el entorno de Google Cloud en vivo:
- Se subieron sample_contract.txt y sample_invoice.pdf al bucket de Cloud Storage.
- GCS generó eventos OBJECT_FINALIZE en Pub/Sub.
- Pub/Sub envió los sobres al microservicio de Cloud Run.
- Cloud Run extrajo metadatos, procesó OCR simulado y transmitió registros a BigQuery.
Resultado de la consulta de BigQuery en vivo
+------------------------------+------------+----------------+---------------------------------------------------+---------------------+
| file_name | word_count | ocr_status | tags | processed_at |
+------------------------------+------------+----------------+---------------------------------------------------+---------------------+
| test_invoice_1788840194.pdf | 62 | SIMULATED_OCR | ["invoice","finance","billing","acme","pdf"] | 2026-09-08 04:03:27 |
| test_contract_1788840194.txt | 181 | EXTRACTED_TEXT | ["provider","cloud","client","agreement","shall"] | 2026-09-08 04:03:22 |
+------------------------------+------------+----------------+---------------------------------------------------+---------------------+
Todos los componentes de la canalización están activos, en buen estado y verificados en producción.
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.
- Navega a Cloud Storage > Buckets.
- Ubica el bucket llamado
PROJECT_ID-document-processing. - Haz clic en el nombre del bucket para explorar los archivos.
- Verifica lo que hiciste: Deberías ver los archivos subidos (p.ej.,
sample_contract.txt).
Pub/Sub
Objetivo: Confirma que el tema exista y tenga una suscripción de envío.
- Ve a Pub/Sub > Temas.
- Busca document-uploads-events.
- Haz clic en el ID del tema.
- Desplázate hacia abajo hasta la pestaña Suscripciones.
- Verifica lo que hiciste: Asegúrate de que doc-uploads-events-push-sub aparezca en la lista.
Cloud Run
Objetivo: Verifica el estado y los registros del servicio.
- Navega a Cloud Run.
- Haz clic en el servicio document-processor.
- Verifica lo que hiciste:
- Estado: Marca de verificación verde que indica que el servicio está activo
- Registros: Haz clic en la pestaña Registros. Busca entradas como "Processing document: gs://..." y "Successfully streamed metadata...".
BigQuery
Objetivo: Valida que los datos estén almacenados.
- Navega a BigQuery > SQL Workspace.
- En el panel Explorador, expande tu proyecto > document_processing conjunto de datos.
- Haz clic en la tabla document_metadata.
- Haz clic en la pestaña Consulta y recupera todas las filas de la tabla a través de la instrucción SELECT *.
- Verifica lo que hiciste: Deberías ver filas que contengan file_name, process_at, tags y word_count.
7. 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 ver los artefactos y debería mostrarte los archivos de código generados.
A continuación, se incluye un breve resumen de algunos archivos que podrías ver:
deploy.sh: Es la secuencia de comandos principal que aprovisiona todos los recursos de Google Cloud y habilita las APIs necesarias.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.Dockerfile: Define cómo empaquetar la app en una imagen de contenedor.requirements.txt: Enumera las dependencias de Python.
También es posible que veas otras secuencias de comandos y archivos de texto necesarios para las pruebas y la verificación.
8. Extiende la aplicación
Ahora que tienes una aplicación básica en funcionamiento, puedes seguir iterando y extendiendo la aplicación. Estas son 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 o AA reales
En lugar del procesamiento de OCR simulado, usa modelos de Gemini para extraer, clasificar y traducir.
- 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) o extraer entidades (fechas, nombres, ubicaciones).
- 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 el análisis
Puedes configurar reglas de ciclo de vida en el bucket para mover archivos antiguos al almacenamiento "Coldline" o "Archive" para ahorrar costos.
Robustez y seguridad
Puedes hacer que la app sea más sólida y segura, por ejemplo:
- 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 "Dead Letter" separado para la inspección humana.
- 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.
- 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.
9. Conclusión
Compilaste 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 Walkthroughs
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