Criar e implantar no Google Cloud com o Antigravity

1. Introdução

Neste codelab, você vai aprender a usar o Google Antigravity para projetar, criar e implantar um aplicativo sem servidor no Google Cloud. Vamos criar um pipeline de documentos sem servidor e orientado a eventos que ingere arquivos do Google Cloud Storage (GCS), os processa usando o Cloud Run e o Gemini e transmite os metadados para o BigQuery.

O que você vai aprender

• Como usar o Antigravity para planejamento e design de arquitetura.
• Gerar infraestrutura como código (scripts shell) com um agente de IA.
• Crie e implante um serviço do Cloud Run baseado em Python.
• Integrar o Gemini na Vertex AI para análise de documentos multimodais.
• Verifique o pipeline de ponta a ponta usando o artefato de tutorial do Antigravity.

O que é necessário

• O Google Antigravity instalado.
• um projeto do Google Cloud com faturamento ativado
• A CLI gcloud instalada e autenticada.

2. Visão geral do app

Antes de começar a arquitetar e implementar o aplicativo usando o Antigravity, vamos descrever o aplicativo que queremos criar.

Queremos criar um pipeline de documentos sem servidor e orientado a eventos que ingere arquivos do Google Cloud Storage (GCS), os processe usando o Cloud Run e o Gemini e transmita os metadados para o BigQuery.

Um diagrama de arquitetura de alto nível para esse aplicativo pode ser assim:

Não precisa ser preciso. O Antigravity pode nos ajudar a descobrir os detalhes da arquitetura ao longo do caminho. No entanto, é útil ter uma ideia do que você quer criar. Quanto mais detalhes você fornecer, melhores serão os resultados da Antigravity em termos de arquitetura e código.

3. Planejar a arquitetura

Agora podemos começar a planejar os detalhes da arquitetura com o Antigravity.

O Antigravity é excelente para planejar sistemas complexos. Em vez de escrever código imediatamente, podemos começar definindo a arquitetura de alto nível e usar um dos recursos para ajudar o Antigravity a avaliar nossa solicitação, fazer perguntas complementares e prosseguir com o planejamento e a implementação.

Supondo que você tenha iniciado o Antigravity, vamos criar um novo projeto para este codelab.

Clique no ícone de novo projeto ao lado do laboratório Projects e em New Project, conforme mostrado abaixo:

Isso vai abrir a opção Add Folder, como mostrado abaixo:

Clique no botão Adicionar pasta para adicionar uma pasta ao projeto. Na minha máquina, criei uma pasta google-cloud-serverless-app e a adicionei a este projeto.

Isso abre uma conversa no espaço de trabalho google-cloud-serverless-app.

Clique no ícone de configurações principal ⚙️ na parte inferior esquerda da tela e acesse "Configurações específicas do projeto". Defina Agent Settings / Security Preset como Default e Agent Behaviour / Artifact Review Policy como Always Ask, conforme mostrado abaixo:

Isso garante que, em cada etapa, você possa revisar e aprovar o plano antes da execução pelo agente.

Comando

Agora, estamos prontos para dar nosso primeiro comando ao Antigravity. Vamos usar um comando de barra /grill-me para avaliar nossa solicitação.

Digite /grill-me e insira o seguinte comando. Depois, clique no botão "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. 

O comando /grill-me faz várias perguntas complementares que você pode tentar responder da melhor forma possível. Ela também sugere Respostas recomendadas, que você pode usar se quiser.

Confira abaixo um exemplo de execução do meu comando /grill-me:

How would you provision and manage the Google Cloud infrastructure resources (Cloud Storage buckets, Pub/Sub topics, BigQuery datasets, Cloud Run service)?
gcloud CLI Setup Script - Shell scripts running gcloud CLI commands to create resources step-by-step

How should the Cloud Storage upload events trigger and reach your Python Cloud Run service?
(Recommended) Native Cloud Storage Pub/Sub Notifications + Pub/Sub Push subscription to Cloud Run (direct, lightweight, standard event-driven approach)

Which Python web framework would you prefer for the Cloud Run processing service?
Flask (with Gunicorn) - Standard, lightweight, and very common for simple Cloud Run services

How should the OCR and metadata extraction logic be implemented in the Cloud Run service?
(Recommended) Full local simulation - If it's a .txt file, read the contents, count words, and extract tags. For other files, generate mock OCR metadata and simulated word count. No external API calls.

Which BigQuery insertion method should the Cloud Run service use to store metadata?
(Recommended) BigQuery table.insert_rows() (Legacy Streaming API) - Extremely simple to code, clean error handling, perfect for simulation and low-to-medium volumes.

How should security/authentication be configured for the Cloud Run service?
Unauthenticated Cloud Run - Allow public requests to the Cloud Run service URL (simpler setup, but insecure for production).


What schema would you like to define for the BigQuery metadata table?
(Recommended) Extended Schema - Include filename, bucket, size, content_type, word_count, tags (as a REPEATED STRING array), ocr_text_preview, and process_timestamp.

How should the Cloud Run service handle processing failures (e.g., file not found, BigQuery write error)?
(Recommended) Fail-Fast with Retry - Log error to standard output (Cloud Logging) and return HTTP 500 to Pub/Sub, so that Pub/Sub automatically retries the message delivery.

What testing tools should we generate to verify the pipeline's functionality?
(Recommended) Both - Include a local test script (sending mock Pub/Sub POST requests to the local Flask server) and a Cloud-integrated test script (uploading a real file to GCS and verifying BigQuery).

Perceba que pedi ao Antigravity para usar:

• Um script simples da CLI gcloud para provisionar recursos
• Notificações nativas do Cloud Storage Pub/Sub + assinatura por push do Pub/Sub para o Cloud Run
• Usar o Flask (com Gunicorn) para o framework
• Basta usar a simulação local com um arquivo de texto para os dados em vez de dados de OCR em tempo real.
• Usar "table.insert_rows()" do BigQuery para inserir linhas no BigQuery
• Implantação não autenticada do Cloud Run

e outras opções recomendadas.

Plano de implementação e lista de tarefas

O Antigravity vai começar a trabalhar e gerar um plano de implementação. Ele coloca o conteúdo para sua revisão com uma mensagem semelhante a esta:

Clique na alternância do painel auxiliar na janela do canto superior direito e confira os artefatos gerados, que, neste momento, são apenas o Plano de implementação.

Este plano descreve:

• Infraestrutura: bucket do GCS, tópico do Pub/Sub, conjunto de dados do BigQuery.
• Processador: app Python/Flask, Dockerfile, requisitos.
• Integração: notificações do GCS → Pub/Sub → Cloud Run.

Você vai ver algo parecido com o seguinte. Abaixo, mostramos uma lista parcial do plano de implementação na nossa máquina:

Event-Driven Document Processing Pipeline Implementation Plan
This implementation plan describes the components and setup scripts required to build a serverless event-driven document processing pipeline on Google Cloud.

User Review Required

Please review the proposed architecture, components, and default configuration. If you agree, please approve the plan so we can proceed with creating the files and implementation.

IMPORTANT

Security Notice: As requested, the Cloud Run service is configured to allow unauthenticated invocations (--allow-unauthenticated) for simpler testing and development.

Error Handling: The service returns an HTTP 500 error code for failures to trigger Pub/Sub retries.

GCP Configuration: The provisioning scripts will use standard environment variables (e.g., GCP_PROJECT, GCP_REGION) that default to the active configuration of your local gcloud CLI.

Proposed Components and Files

The project will be organized as follows:

google-cloud-serverless-app/
├── src/
│   ├── __init__.py
│   ├── app.py              # Flask app entrypoint and routes
│   ├── processor.py        # Simulated OCR and metadata extraction engine
│   ├── gcs_helper.py       # Helper functions to read files from Cloud Storage
│   └── bq_helper.py        # Helper functions to write metadata to BigQuery
├── requirements.txt         # Python dependencies
├── Dockerfile              # Docker configuration for Cloud Run
├── deploy.sh               # gcloud CLI provisioning and deployment script
├── test_local.sh           # Script to test the Flask app locally with mock Pub/Sub events
├── test_cloud.sh           # Script to upload a real file to GCS and query BigQuery
└── README.md               # Setup and execution guide

Leia com atenção. Esta é sua chance de enviar feedback sobre a implementação. Clique em qualquer parte do plano de implementação e adicione comentários. Depois de adicionar alguns comentários, envie para revisão as mudanças que você quer ver, principalmente em relação a nomes, ID do projeto do Google Cloud, região etc.

Quando tudo estiver certo, clique no botão Proceed para dar permissão ao agente de continuar com o plano de implementação.

Agora, ele cria outro artefato, o Plano de tarefas, que contém um conjunto de tarefas criadas pelo Antigravity. O agente vai analisar e executar cada uma delas. Confira abaixo uma lista de tarefas de exemplo:

4. Gerar o aplicativo

Depois que o plano é aprovado, o Antigravity começa a gerar os arquivos necessários para o aplicativo, desde scripts de provisionamento até código do aplicativo.

O Antigravity vai criar uma pasta e começar a criar os arquivos necessários para o projeto. Se você verificar os artefatos, vai notar que vários arquivos (código-fonte, arquivos de script etc.) estão sendo gerados.

Quando terminar, ele vai mencionar isso e criar um documento de Tutorial para você consultar. Ele menciona a próxima etapa para o usuário. Confira um exemplo abaixo:

• Implante o pipeline:verifique se você fez login na CLI do GCP e definiu o projeto de destino. Em seguida, execute: ./ deploy.sh
• Executar o teste de ponta a ponta: execute o script de teste de integração na nuvem para verificar se o upload de um arquivo aciona o processamento do Cloud Run e transmite metadados para o BigQuery:./test_cloud.sh
• Limpeza:depois de concluir o teste, consulte os comandos de limpeza README.md para remover os recursos criados e evitar cobranças.

Um arquivo de script de shell deploy.sh ou com um nome semelhante será gerado, o que automatiza a criação de recursos. Ela trabalha com:

1. Ativação de APIs (run, pubsub, bigquery, storage).
2. Criar o bucket do Google Cloud Storage (document-processing-ingest-{project-id}).
3. Criar o conjunto de dados e a tabela do BigQuery (document_processing.processed_metadata).
4. Configurar tópicos e notificações do Pub/Sub.

5. Implantar o aplicativo

Vamos implantar o aplicativo conforme mencionado usando o comando ./ deploy.sh. Podemos pedir para o Antigravity fazer isso, mas antes, verifique se a CLI gcloud está presente e configurada para o projeto do Google Cloud.

Podemos dar um comando ao Antigravity: "Execute o deploy.sh para mim". Isso vai pedir sua permissão. Faça isso.

Ele inicia o processo como uma tarefa em segundo plano, conforme explicado na mensagem abaixo:

Iniciei o processo de implantação executando ./deploy.sh em segundo plano. Vou monitorar os registros de execução e avisar assim que a implantação terminar.

6. Verificar o aplicativo

Depois que o pipeline é implantado, o Antigravity verifica se o aplicativo realmente funciona. Ele pergunta se pode executar o arquivo test_cloud.sh. Podemos conceder a permissão.

Por fim, ele nos informa o seguinte:

I have successfully run both ./deploy.sh and ./test_cloud.sh.
The pipeline is fully deployed to your GCP project PROJECT_ID and working end-to-end. 

Please refer to the walkthrough.md for full verification details and the query output from BigQuery showing the successfully processed document metadata.

Podemos abrir o artefato de tutorial para conferir os resultados:

Cloud Verification Results

The deployment and end-to-end cloud integration test (./test_cloud.sh) succeeded perfectly!

Resources Created:

GCS Bucket: gs://document-processing-ingest-gcp-experiments-349209

Pub/Sub Topic: document-uploads-topic

Pub/Sub Subscription: document-uploads-sub (pushing to Cloud Run)

Cloud Run Service: document-processor (URL: https://document-processor-ido3ocn3pq-uc.a.run.app)

BigQuery Dataset: document_processing

BigQuery Table: processed_metadata

Integration Test Run: A test file cloud_test_sample.txt was uploaded to the bucket. The pipeline processed the file and streamed the metadata record into BigQuery:

🔍 Querying BigQuery to verify metadata insertion...
<BIQUERY DATA HERE>

The pipeline successfully detected the hashtags #gcp and #serverless as tags, correctly counted the 47 words, generated the OCR preview, and wrote the entry to BigQuery under the schema.

Opcional: verificação manual

Mesmo que a Antigravity já tenha verificado o aplicativo, você também pode conferir manualmente no console do Google Cloud se todos os recursos foram criados. Para isso, siga estas etapas.

Cloud Storage

Objetivo: verificar se o bucket existe e se há arquivos enviados.

1. Acesse Cloud Storage > Buckets.
2. Localize o bucket chamado document-processing-ingest-{project-id}.
3. Clique no nome do bucket para procurar arquivos.
4. Verifique se os arquivos enviados aparecem (por exemplo,cloud_test_sample.txt).

Pub/Sub

Objetivo: confirmar se o tópico existe e tem uma assinatura por push.

1. Acesse Pub/Sub > Tópicos.
2. Encontre document-uploads-topic.
3. Clique no ID do tópico.
4. Role a tela para baixo até a guia Inscrições.
5. Verifique se doc-uploads-sub está listado com o tipo de entrega "Push".

Cloud Run

Objetivo: verificar o status e os registros do serviço.

1. Navegue até Cloud Run.
2. Clique no serviço document-processor.
3. Verificar:
4. Integridade: marca de seleção verde indicando que o serviço está ativo.
5. Registros: clique na guia "Registros". Procure entradas como "Processing file: gs://..." e "Successfully inserted...".

BigQuery

Objetivo: validar se os dados estão realmente armazenados.

1. Acesse BigQuery > Espaço de trabalho SQL.
2. No painel "Explorador", expanda projeto > conjunto de dados document_processing.
3. Clique na tabela processed_metadata.
4. Clique na guia Consulta e recupere todas as linhas da tabela com a instrução SELECT *.
5. Verifique: você vai encontrar linhas com filename, process_timestamp, tags e word_count.

7. Conheça o aplicativo

Neste ponto, você tem o app básico provisionado e em execução. Antes de se aprofundar na extensão desse aplicativo, reserve um momento para explorar o código. É possível ver os artefatos, que mostram os arquivos de código gerados.

Confira um breve resumo dos arquivos que podem aparecer:

1. deploy.sh: o script principal que provisiona todos os recursos do Google Cloud e ativa as APIs necessárias.
2. appy.py: o principal ponto de entrada do pipeline. Esse app Python cria um servidor da Web que recebe mensagens push do Pub/Sub, baixa o arquivo do GCS, o "processa" (simula OCR) e transmite os metadados para o BigQuery.
3. Dockerfile: define como empacotar o app em uma imagem do contêiner.
4. requirements.txt: lista as dependências do Python.

Você também pode encontrar outros scripts e arquivos de texto necessários para testes e verificação.

8. Estender o aplicativo

Agora que você tem um aplicativo básico funcionando, pode continuar iterando e estendendo o aplicativo. Confira algumas ideias.

Adicionar um front-end

Crie uma interface da Web simples para visualizar os documentos processados.

Tente o seguinte comando: 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ção com IA/ML real

Em vez de processamento de OCR simulado, use modelos do Gemini para extrair, classificar e traduzir.

1. Substitua a lógica de OCR fictícia. Envie a imagem/PDF para o Gemini extrair texto e dados reais. Analise o texto extraído para classificar o tipo de documento (fatura, contrato, currículo) ou extrair entidades (datas, nomes, locais).
2. Detectar automaticamente o idioma do documento e traduzir para inglês antes de armazenar. Você também pode usar qualquer outro idioma.

Melhorar o armazenamento e a análise

É possível configurar regras de ciclo de vida no bucket para mover arquivos antigos para o armazenamento "Coldline" ou "Archive" e economizar custos.

Robustez e segurança

Você pode tornar o app mais robusto e seguro das seguintes maneiras:

1. Filas de mensagens inativas (DLQ): atualize a assinatura do Pub/Sub para lidar com falhas. Se o serviço do Cloud Run não processar um arquivo cinco vezes, envie a mensagem para um tópico/bucket separado de "Dead Letter" para inspeção humana.
2. Secret Manager: se o app precisar de chaves de API ou configurações sensíveis, armazene-as no Secret Manager e acesse-as com segurança no Cloud Run em vez de codificar strings.
3. Eventarc: faça upgrade do Pub/Sub direto para o Eventarc e tenha um roteamento de eventos mais flexível, permitindo acionar com base em registros de auditoria complexos ou outros eventos de serviço do GCP.

É claro que você pode criar suas próprias ideias e usar o Antigravity para ajudar a implementá-las.

9. Conclusão

Você criou um pipeline de documentos escalonável, sem servidor e com tecnologia de IA em minutos usando o Google Antigravity. Você aprendeu a:

• Planejar arquiteturas com IA.
• Instrua e gerencie o Antigravity enquanto ele gera o aplicativo, desde a geração de código até a implantação e validação.
• Verificar implantações e validação com tutoriais.

Documentos de referência

• Site oficial : https://antigravity.google/
• Documentação: https://antigravity.google/docs
• Casos de uso : https://antigravity.google/use-cases
• Download : https://antigravity.google/download