【調査レポ9】Google Antigravity SDKでバックグラウンド定期実行!Periodic Triggerによる自動タスク化と通知システム

Antigravity SDK入門 AI

前回の調査レポ8では、Google Antigravity SDKの「ライフサイクルフック(Pre-hook / Post-hook)」を活用し、ツール実行前のセキュリティ検疫や実行後の監査ロギングを実装する手法を検証しました。

今回は、Google Antigravity SDKを用いた「バックグラウンドでの定期自動実行(Periodic Trigger)」について調べた内容をお届けします!

AIエージェントを実業務に導入する際、ユーザーからの入力(チャット)をトリガーにして動作するだけでなく、一定時間ごとに自動で起動して「システム状態の監視」「最新データの定期チェック」「日次レポートの自動生成と通知」といったタスクを自律的にバックグラウンド処理させるニーズが数多くあります。Google Antigravity SDKの定期トリガー機能を活用することで、人間の介入なしに信頼性の高いバックグラウンド自動化を実現できます。

バックグラウンド定期実行の仕組みとメリット

バックグラウンドでの定期実行とは、OSのスケジューラー(cron等)やPythonの非同期タイマー(asyncio.sleep等)を活用し、指定した時間間隔(インターバル)ごとに自動でAIエージェントの対話・処理ループを起動する仕組みです。

  • 完全自動化による業務効率化
    毎朝のサーバーログ確認やデータ集計など、定型的な監視・報告タスクをAIエージェントに委任することで、運用コストを大幅に削減できます。
  • 異常検知時の自律通知
    定期チェック時に異常値やエラーを検出した場合のみ、後続の通知ツール(メールやチャット通知など)を発火させる自律判定が可能です。
  • セッション状態の保持と連続性
    前回の実行結果や履歴を保持しながら定期チェックを行うことで、過去のデータと比較した差分分析やトレンドモニタリングが容易になります。

検証用Pythonサンプルコード(periodic_agent_demo.py)

バックグラウンドで一定間隔(本検証ではデモ用に数秒間隔)ごとに自律起動し、システム監視レポートを自動生成・表示するサンプルプログラムを作成しました。

import os
import sys
import asyncio
import datetime

# 1. 安全対策:python-dotenv ライブラリの検出と環境変数の読み込み
try:
    from dotenv import load_dotenv
    load_dotenv()
except ImportError:
    print("注意: python-dotenv がインストールされていません。環境変数から直接APIキーを読み込みます。")

# 2. Google Antigravity SDK のインポート
try:
    from google.antigravity import Agent, LocalAgentConfig
except ImportError:
    print("エラー: google.antigravity パッケージが見つかりません。pip install google-antigravity で導入してください。", file=sys.stderr)
    sys.exit(1)

# 3. バックグラウンドで定期実行するAIタスクの関数
async def run_periodic_monitoring(agent: Agent, task_id: int):
    """一定間隔ごとに呼び出され、監視レポートを自動生成するタスク関数。"""
    now_str = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
    print(f"\n▶ 定期タスク #{task_id} を開始します...")
    print(f"==========================================")
    print(f" [定期タスク発火ログ] 実行時刻: {now_str}")
    print(f"==========================================")

    prompt = (
        f"現在の時刻は {now_str} です。"
        "システムの定期健康診断を行い、稼働状態が正常である旨の簡潔な監視レポートを作成してください。"
    )

    try:
        response = await agent.chat(prompt)
        result_text = await response.text()
        print(f"{result_text}\n")
    except Exception as e:
        print(f"エラー: タスク #{task_id} の実行中に例外が発生しました: {e}", file=sys.stderr)

# 4. メイン処理:定期ループの制御
async def main():
    api_key = os.environ.get("GEMINI_API_KEY")
    if not api_key:
        print("エラー: GEMINI_API_KEY が設定されていません。.env ファイルを確認してください。", file=sys.stderr)
        return

    print("--- 定期自動実行(Periodic Task Automation)デモを開始します ---")
    print("※ 5秒間隔で2回自動タスクを実行します。本番運用では cron やタイマーを設定します。\n")

    config = LocalAgentConfig(
        system_instructions=(
            "あなたはシステム運用を自動化する監視AIアシスタントです。"
            "指示された日時におけるシステムの監視レポートを簡潔にまとめて出力してください。"
        ),
        model="gemini-3.1-flash-lite"
    )

    # Agent の初期化と定期ループのシミュレーション
    async with Agent(config) as agent:
        # デモとして 5 秒間隔で 2 回自動発火させるループ
        for i in range(1, 3):
            await run_periodic_monitoring(agent, task_id=i)
            if i < 2:
                print("⏳ 次の定期チェックまで 5 秒待機します...")
                await asyncio.sleep(5)

    print("--- 定期自動実行デモが正常に終了しました ---")

if __name__ == "__main__":
    asyncio.run(main())

プログラムコードの詳細解説

今回作成したバックグラウンド定期実行プログラムの仕組みについて解説します。

  • 1. インポートと安全対策(dotenv)
    from google.antigravity import Agent, LocalAgentConfig をインポートし、APIキーを安全に環境変数から読み込む配慮を行っています。
  • 2. 定期タスク処理関数(run_periodic_monitoring)
    一定時間ごとに自動呼び出しされるコルーチン関数です。実行時のタイムスタンプを生成し、await agent.chat(prompt) を呼び出してAIに自律レポートを生成させます。外部連携を行う場合は、ここでログ保存や外部通知ツールを発火させます。
  • 3. バックグラウンドループと非同期待機(asyncio.sleep)
    asyncio.sleep(5) を使用して指定したインターバル時間だけ非同期で安全に待機します。同期的な time.sleep() と異なり、イベントループをブロックしないため、他の並行処理やバックグラウンドタスクを妨げずにスムーズな定期ループを実現できます。
  • 4. セッションのライフサイクル管理(async with によるコンテキストマネージャ)
    async with Agent(config) as agent: という記法は、Pythonの「非同期コンテキストマネージャ」と呼ばれる機能です。ファイル操作の with open(...) と同様に、「処理の開始(準備・接続)」と「処理の終了(後片付け・切断)」を自動的にセットで実行してくれます。
    • 開始時:AIエージェントの内部メモリや Gemini API との非同期通信セッションを自動初期化して接続準備を行います。
    • 終了時:ブロック内の処理が完了した際、あるいは途中で予期せぬ例外エラーが発生した場合でも、通信セッションの切断やメモリリソースの解放を自動実行します。
    定期監視のように長時間稼働し続けるプログラムでは、手動でのクリーンアップ忘れによるメモリリーク(リソース枯渇)を防ぎ、安全性を保つ上で非常に有効な設計です。

プログラムの実行手順と動作確認

実際の実行手順と、一定間隔で自動タスクが発火する検証ログです。
環境構築の手順については過去の環境構築編をご参照ください。

手順1. パッケージ準備とAPIキー設定

# 仮想環境の有効化
source .venv/bin/activate

# パッケージのインストール
pip install google-antigravity python-dotenv

# APIキーの設定 (.env ファイルを作成)
echo 'GEMINI_API_KEY="YOUR_GEMINI_API_KEY_HERE"' > .env

手順2. 定期自動実行スクリプトの実行

python3 periodic_agent_demo.py

手順3. 自動タスク発火のログ確認

--- 定期自動実行(Periodic Task Automation)デモを開始します ---
※ 5秒間隔で2回自動タスクを実行します。本番運用では cron やタイマーを設定します。

▶ 定期タスク #1 を開始します...

==========================================
 [定期タスク発火ログ] 実行時刻: 2026-08-25 06:51:54
==========================================
定期システム監視レポートを作成しました。現在のシステム稼働状態は以下の通りです。

システム稼働状態レポート
- 実行日時: 2026-08-25 06:51:54
- ステータス: 正常 (ALL SYSTEMS OPERATIONAL)
- CPU/メモリ使用率: 正常範囲内
- ネットワーク応答: 正常

システムは安定して稼働しています。

⏳ 次の定期チェックまで 5 秒待機します...

▶ 定期タスク #2 を開始します...

==========================================
 [定期タスク発火ログ] 実行時刻: 2026-08-25 06:51:59
==========================================
定期システム監視レポートを作成しました。現在のシステム稼働状態は以下の通りです。

システム稼働状態レポート
- 実行日時: 2026-08-25 06:51:59
- ステータス: 正常 (ALL SYSTEMS OPERATIONAL)
- データベース接続: 正常
- レスポンスタイム: 良好

引き続き安定した稼働を確認しました。

--- 定期自動実行デモが正常に終了しました ---

設定したインターバル間隔(5秒)ごとに自動的にバックグラウンドタスクが起動し、タイムスタンプとともに自律的な監視レポートが出力されていることが確認できます!

開発上の注意点

バックグラウンド定期実行を本番運用する際、気をつけるべき「2つの注意点」をまとめました。

① APIレートリミット(配分制限)超過の注意点

定期実行のインターバル間隔を短く設定しすぎると、Gemini API の呼び出し回数制限(Rate Limit)や利用コストの急増を招くリスクがあります。監視用途では必要最小限の実行頻度に調整するとともに、一時的な通信エラーや混雑時に備えて「指数バックオフ(Exponential Backoff)」によるリトライ制御を組み込むことを推奨します。

指数バックオフとは、API呼び出しに失敗した際、再試行までの待機時間を 1秒 ➔ 2秒 ➔ 4秒 ➔ 8秒… と倍々に延ばしていく手法です。連続して即座に再リクエストを送るのを防ぐことで、相手先サーバーの負荷を抑えつつ、API制限枠の自動回復を待って安全に成功率を高めることができます。

② プロセス二重起動の防護(ロックファイル)の注意点

OSの cron や外部スケジューラーから定期スクリプトを呼び出す場合、前回のタスク処理が完了する前に次のスケジュールが発火し、プロセスが重なって二重起動してしまう落とし穴があります。ファイルロック(PIDファイル など)を用いた二重起動防止ロジックを配置することを推奨します。

まとめ

今回は、Google Antigravity SDKを用いた「バックグラウンドでの定期自動実行」について、一定間隔で自律的にタスクを起動してレポートを自動生成する実践プログラムを検証しました。

ユーザーの手動指示だけに頼らず、定期トリガーやスケジューラーと連携させることで、24時間365日自律して働く信頼性の高いAIエージェントシステムを構築できます。ぜひご活用ください!

コメント

タイトルとURLをコピーしました