Antigravity を使用して Google Cloud にビルドしてデプロイする

1. はじめに

この Codelab では、 Google Antigravity を使用して、サーバーレス アプリケーションを設計、構築し、Google Cloud にデプロイする方法について説明します。Google Cloud Storage（GCS）からファイルを取り込み、Cloud Run と Gemini を使用して処理し、そのメタデータを BigQuery にストリーミングする、サーバーレスでイベント ドリブンなドキュメント パイプラインを構築します。

学習内容

• Antigravity を使用してアーキテクチャの計画と設計を行う方法。
• AI エージェントを使用して、Infrastructure as Code（シェル スクリプト）を生成する。
• Python ベースの Cloud Run サービスを構築してデプロイする。
• Vertex AI で Gemini を統合して、マルチモーダル ドキュメント分析を行う。
• Antigravity の Walkthrough アーティファクトを使用して、エンドツーエンドのパイプラインを確認する。

必要なもの

• Google Antigravity がインストールされていること。
• 課金が有効な Google Cloud プロジェクトが用意されていること。
• gcloud CLI がインストールされ、認証されていること。

2. アプリの概要

Antigravity を使用してアプリケーションのアーキテクチャを設計して実装する前に、構築するアプリケーションの概要を説明します。

Google Cloud Storage（GCS）からファイルを取り込み、Cloud Run と Gemini を使用して処理し、そのメタデータを BigQuery にストリーミングする、サーバーレスでイベント ドリブンなドキュメント パイプラインを構築します。

このアプリケーションのアーキテクチャ図の概要は次のようになります。

正確である必要はありません。Antigravity を使用すると、アーキテクチャの詳細を把握できます。ただし、構築する内容を把握しておくと便利です。詳細な情報を提供すればするほど、アーキテクチャとコードに関して Antigravity からより良い結果が得られます。

3. アーキテクチャを計画する

Antigravity を使用してアーキテクチャの詳細を計画する準備ができました。

Antigravity は複雑なシステムの計画に優れています。コードをすぐに記述するのではなく、まずアーキテクチャの概要を定義し、Antigravity がリクエストを評価し、もっと聞くように促し、計画と実装を進めるのに役立つ機能を使用します。

Antigravity を起動したら、この Codelab の新しいプロジェクトを作成します。

[Projects] ラボの横にある新しいプロジェクト アイコンをクリックし、次に下の図に示すように [New Project] をクリックします。

下の図に示すように、[Add Folder] オプションが表示されます。

[Add Folder] ボタンをクリックして、プロジェクトにフォルダを追加します。自分のマシンで google-cloud-serverless-app フォルダを作成し、このプロジェクトに追加しました。

これにより、[google-cloud-serverless-app] プロジェクトで会話が開きます。

画面左下のメイン設定アイコン ⚙️ をクリックして、プロジェクト固有の設定に移動します。[google-cloud-serverless-app] プロジェクトが表示されない場合は、1 回の会話を行い、[Project Settings] に戻ります。

下の図に示すように、[Agent Settings / Security Preset] を [Default] に、[Agent Behaviour / Artifact Review Policy] を [Always Ask] に設定します。

これにより、エージェントが実行する前に、すべてのステップで計画を確認して承認できます。

プロンプト

Antigravity に最初のプロンプトを指定する準備ができました。スラッシュ コマンド /grill-me を使用してリクエストを評価します。

/grill-me と入力し、次のプロンプトを入力して [送信] ボタンをクリックします。

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

/grill-me コマンドは、できるだけ詳しく回答できるもっと聞く質問をいくつか行います。また、推奨される回答 も表示されます。必要に応じて、この回答を使用できます。

/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

Antigravity に次のことを行うように依頼しました。

• リソースをプロビジョニングする簡単な gcloud CLI スクリプト
• ネイティブ Cloud Storage Pub/Sub 通知 + Pub/Sub push サブスクリプションから Cloud Run
• フレームワークに Flask（Gunicorn を使用）を使用する
• ライブ OCR データの代わりに、テキスト ファイルを使用したローカル シミュレーションを使用する
• BigQuery テーブルに挿入する BigQuery table.insert_rows() を使用する
• 未認証の Cloud Run デプロイ

その他の推奨オプション。

実装計画とタスクリスト

Antigravity が動作して実装計画 を生成します。次のようなメッセージが表示され、確認を求められます。

右上のウィンドウで [補助ペイン] 切り替えをクリックすると、生成されたアーティファクト（現時点では実装計画 のみ）を表示できます。

この計画では、次のことが概要を示されています。

• インフラストラクチャ: GCS バケット、Pub/Sub トピック、BigQuery データセット。
• プロセッサ: Python/Flask アプリ、Dockerfile、要件。
• 統合: GCS 通知 → Pub/Sub → Cloud Run。

次のようなものが表示されます。マシンでの実装計画の一部を次に示します。

よくお読みください。実装に関するフィードバックを送信する機会です。実装計画の任意の部分をクリックして、コメントを追加できます。コメントを追加したら、特に命名、Google Cloud プロジェクト ID、リージョンなどについて、変更を確認して送信してください。

問題がなければ、[Proceed] ボタンをクリックして、エージェントに実装計画を進める権限を付与します。

注: [Proceed] ボタンが表示されない場合があり、Antigravity が入力を待たずに続行することがあります。

4. アプリケーションを生成する

計画が承認されると、Antigravity は、プロビジョニング スクリプトからアプリケーション コードまで、アプリケーションに必要なファイルの生成を開始します。

注: エージェントが環境を理解し、それに応じてスクリプトを生成するために使用する必要があるターミナル コマンド（gcloud、シェル スクリプトなど）がいくつか表示されます。Submit ボタンをクリックして、エージェントを進めます。このラボでは、生成された特定のファイル名について説明しますが、Antigravity では異なるファイル名が生成されることがあります。ただし、ファイルの目的と内容は同様です。

Antigravity はフォルダを作成し、プロジェクトに必要なファイルの作成を開始します。アーティファクトを確認すると、いくつかのファイル（ソースコード、スクリプト ファイルなど）が生成されていることがわかります。

作業が完了すると、その旨が通知され、確認できるWalkthrough ドキュメントが作成されます。出力例を以下に示します。

Walkthrough ドキュメントには、実装された内容、生成されたスクリプト、最も重要な検証と検証について記載されています。検証と検証を含む Walkthrough ドキュメントの一部を次に示します。

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

このアプリケーションを Google Cloud にデプロイする方法について Antigravity に問い合わせることができます。以下に示すように、詳細が返されます。まとめると、Google Cloud プロジェクトの設定とともに Google Cloud SDK がインストールされていることを確認するよう求められます。完了したら、

ステップ 1: 必要な GCP API を有効にする

setup_gcp.sh を実行して、Cloud Run、Pub/Sub、Cloud Storage、BigQuery、Cloud Build API を有効にします。./scripts/setup_gcp.sh

ステップ 2: パイプライン全体をデプロイする

deploy.sh を実行します。

export GCP_PROJECT="<YOUR_PROJECT_ID>"
export GCP_REGION="us-central1"               # or your region
./scripts/deploy.sh

このスクリプトの処理内容:

1. Google Cloud Build を使用してコンテナ イメージをビルドし、Container Registry/Artifact Registry に push します。
2. 適切な環境変数（GCP_PROJECT、BQ_DATASET_ID、BQ_TABLE_ID）を使用して、サービスを Cloud Run にデプロイします。
3. Cloud Storage 取り込みバケット（gs://<PROJECT_ID>-document-ingest）を作成します。
4. Pub/Sub トピック（document-upload-events）を作成し、GCS にパブリッシュ権限を付与します。
5. バケットに GCS 通知（OBJECT_FINALIZE）を構成します。
6. 自動再試行バックオフを使用して、Cloud Run サービス URL をターゲットとする Pub/Sub push サブスクリプションを作成します。

パイプラインをテストする方法も提案します。

test_pipeline.sh を実行します。 ./scripts/test_pipeline.sh

これにより、samples/sample_contract.txt と samples/sample_invoice.pdf がバケットにアップロードされ、処理が完了するまで待機し、抽出されたメタデータ、単語数、タグを表示する BigQuery SQL クエリが実行されます。

5. アプリケーションをデプロイする

前述のようにアプリケーションをデプロイしましょう。Antigravity に実行を依頼できますが、その前に、gcloud CLI が存在し、Google Cloud プロジェクト用に構成されていることを確認してください。

Antigravity に「アプリケーションをデプロイする」というプロンプトを指定できます。さまざまな権限を求めるプロンプトが表示され、スクリプト ファイルが実行されます。

次のメッセージで説明されているように、バックグラウンド タスクとしてプロセスが開始されます。

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. アプリケーションを確認する

パイプラインがデプロイされると、Antigravity はアプリケーションが実際に動作することを確認します。test_pipeline.sh ファイルを実行できるかどうかを尋ねられます。権限を付与できます。

最終的に、次のようになります。

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

また、Walkthrough アーティファクトが更新され、結果が表示されます（一部を以下に示します）。

デプロイの概要

• GCP プロジェクト: PROJECT_ID
• 地域: REGION
• Cloud Run サービス: document-processor
• Cloud Run エンドポイント: SERVICE_URL
• Cloud Storage バケット: gs://PROJECT_ID-document-ingest
• Pub/Sub トピック: document-upload-events
• Pub/Sub push サブスクリプション: document-upload-events-push-sub
• BigQuery ターゲット: PROJECT_ID.document_processing.document_metadata

ライブ パイプラインの検証

ライブ Google Cloud 環境に対して scripts/test_pipeline.sh を実行しました。

1. sample_contract.txt と sample_invoice.pdf を Cloud Storage バケットにアップロードしました。
2. GCS は OBJECT_FINALIZE イベントを Pub/Sub に生成しました。
3. Pub/Sub はエンベロープを Cloud Run マイクロサービスに push しました。
4. Cloud Run はメタデータを抽出し、シミュレートされた OCR を処理し、レコードを BigQuery にストリーミングしました。

ライブ BigQuery クエリの出力

+------------------------------+------------+----------------+---------------------------------------------------+---------------------+
|          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 |
+------------------------------+------------+----------------+---------------------------------------------------+---------------------+

すべてのパイプライン コンポーネントがアクティブで正常であり、本番環境で検証されています。

省略可: 手動検証

Antigravity がすでにアプリケーションを検証していても、必要に応じて、次の手順に沿って Google Cloud コンソールでリソースがすべて作成されていることを手動で確認できます。

Cloud Storage

目標: バケットが存在することを確認し、アップロードされたファイルを確認します。

1. Cloud Storage > バケット に移動します。
2. PROJECT_ID-document-processing という名前のバケットを見つけます。
3. バケット名をクリックしてファイルを参照します。
4. 確認: アップロードしたファイル（sample_contract.txt など）が表示されます。

Pub/Sub

目標: トピックが存在し、push サブスクリプションがあることを確認します。

1. Pub/Sub > トピック に移動します。
2. document-uploads-events を見つけます。
3. トピック ID をクリックします。
4. [サブスクリプション] タブまでスクロールします。
5. 確認: doc-uploads-events-push-sub が表示されていることを確認します。

Cloud Run

目標: サービスのステータスとログを確認します。

1. Cloud Run に移動します。
2. サービス document-processor をクリックします。
3. 確認:
4. ヘルス: 緑色のチェックマークは、サービスがアクティブであることを示します。
5. ログ: [ログ] タブをクリックします。「Processing document: gs://...」や「Successfully streamed metadata...」などのエントリを探します。

BigQuery

目標: データが実際に保存されていることを検証します。

1. BigQuery > SQL ワークスペース に移動します。
2. [エクスプローラ] ペインで、プロジェクト > document_processing データセットを開きます。
3. [document_metadata] テーブルをクリックします。
4. [クエリ] タブをクリックし、SELECT * ステートメントを使用してテーブルからすべての行を取得します。
5. 確認: file_name 、process_at 、tags 、word_count を含む行が表示されます。

7. アプリケーションを確認する

この時点で、基本的なアプリがプロビジョニングされ、実行されています。このアプリケーションをさらに拡張する前に、コードを確認してください。アーティファクトを表示すると、生成されたコードファイルが表示されます。

表示される可能性のあるファイルの概要を次に示します。

1. deploy.sh: すべての Google Cloud リソースをプロビジョニングし、必要な API を有効にするマスター スクリプト。
2. main.py: パイプラインのメイン エントリ ポイント。この Python アプリは、Pub/Sub push メッセージを受信するウェブサーバーを作成し、GCS からファイルをダウンロードして「処理」（OCR をシミュレート）し、メタデータを BigQuery にストリーミングします。
3. Dockerfile: アプリをコンテナ イメージにパッケージ化する方法を定義します。
4. requirements.txt: Python の依存関係を一覧表示します。

テストと検証に必要な他のスクリプトやテキスト ファイルが表示されることもあります。

8. アプリケーションを拡張する

基本的なアプリケーションが完成したので、アプリケーションの反復と拡張を続けることができます。たとえば、次のことを試してみます。

フロントエンドを追加する

処理済みのドキュメントを表示するシンプルなウェブ インターフェースを構築します。

次のプロンプトを試します。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

実際の AI/ML と統合する

シミュレートされた OCR 処理の代わりに、Gemini モデルを使用して抽出、分類、翻訳を行います。

1. ダミーの OCR ロジックを置き換えます。画像/PDF を Gemini に送信して、実際のテキストとデータを抽出します。抽出したテキストを分析して、ドキュメント タイプ（請求書、契約書、履歴書）を分類するか、エンティティ（日付、名前、場所）を抽出します。
2. ドキュメントの言語を自動的に検出し、保存する前に英語に翻訳します。他の言語も使用できます。

ストレージと分析を強化する

バケットにライフサイクル ルールを構成して、古いファイルを「Coldline」または「Archive」ストレージに移動し、費用を節約できます。

堅牢性とセキュリティ

次のように、アプリの堅牢性とセキュリティを強化できます。

1. デッドレター キュー（DLQ）: 失敗を処理するように Pub/Sub サブスクリプションを更新します。Cloud Run サービスがファイルの処理に 5 回失敗した場合は、メッセージを別の「デッドレター」トピック/バケットに送信して、人が検査できるようにします。
2. Secret Manager: アプリで API キーや機密性の高い構成が必要な場合は、Secret Manager に保存し、文字列をハードコードするのではなく、Cloud Run から安全にアクセスします。
3. Eventarc: より柔軟なイベント ルーティングを実現するために、直接 Pub/Sub から Eventarc にアップグレードします。これにより、複雑な監査ログや他の GCP サービス イベントに基づいてトリガーできます。

もちろん、独自のアイデアを思いつき、Antigravity を使用して実装することもできます。

9. まとめ

Google Antigravity を使用して、スケーラブルでサーバーレスの AI 搭載ドキュメント パイプラインを数分で構築できました。具体的には、以下の方法について学習しました。

• AI を使用してアーキテクチャを計画する。
• コード生成からデプロイと検証まで、アプリケーションの生成を行う Antigravity を指示して管理する。
• Walkthrough を使用してデプロイと検証を確認する。

リファレンス ドキュメント

• 公式サイト : https://antigravity.google/
• ドキュメント: https://antigravity.google/docs
• ユースケース : https://antigravity.google/use-cases
• ダウンロード : https://antigravity.google/download