🧩 Google Antigravity SDKの実行監視と状態保存

Google Antigravity SDK は、Antigravity の本番ハーネスと Gemini を前提に、自律エージェントを Python プロセスへ埋め込む SDK です。自前のエージェントハブで、実行監視・介入・状態保存を組み立てる面として使います。確認時点（2026-09-10）の PyPI 現行は google-antigravity 0.1.16（Alpha、Apache-2.0、Python >=3.10）です。import は google.antigravity です。

2026-09-09、Google Cloud Blog は Power agent hubs or custom harnesses with the Antigravity SDK で、この構成を公開しました。著者は Wei Yih Yap と Paul Datta です。ページ本文の日付は September 9, 2026 です。

この記事では、Python SDK の公開 API と公式ドキュメントを突き合わせ、次を再現できる形で整理します。

• ホストプロセスへハーネスを埋め込む三層の境界
• Lifecycle Hooks と宣言的ポリシーで止める／見る／直す分担
• save_dir と conversation_id によるセッション再開

この記事の全体像。以下、順に解説します。

Google Antigravity SDKとは

Google Antigravity SDK は、共有ハーネスをホストの Python プロセスへ持ち込むプログラマブル API です。

公式ドキュメントは、ツール実行・コンテキスト管理・安全ポリシー・サブエージェント委譲を含む、セキュアでステートフルなランタイムハーネスと位置づけます。ブログの主題は、自前のエージェントハブ（マルチエージェント制御プレーン）を組むときの実行監視・介入・状態保存です。

Antigravity 2.0（デスクトップ）、Antigravity CLI（バイナリ名 agy）、本 SDK は同じ共有ハーネスを使います。配送経路はサーフェスごとに分かれます。SDK は PyPI wheel 同梱バイナリ、2.0 / CLI は各製品のインストーラ、Managed Agents はクラウド面です。

認証の名前は次の 3 系統です。

実行に必要なコンパイル済み runtime binary は、PyPI のプラットフォーム別 wheel（0.1.16 時点で約 35〜41 MiB。PyPI の MB 表示では約 36〜43 MB）に同梱されます。公開 wheel の対象例は macosx_11_0_arm64、manylinux_2_17_x86_64.musllinux_1_1_x86_64、manylinux_2_17_aarch64.musllinux_1_1_aarch64、win_amd64、win_arm64 です。

起点ブログが示す制御プレーンは、エージェントの思考・ツール呼び出し・状態保存を単一面で監視する構成です。

特徴

• 共有ハーネスの埋め込み。Antigravity 2.0 / CLI と同じ計画・ツール実行・検証ループを Python から使います。
• batteries-included な Agent。バイナリ発見・ツール配線・hook / ポリシー既定を async コンテキストマネージャでまとめます。
• 三層アーキテクチャ。Layer1 Agent、Layer2 Conversation / ChatResponse / HookRunner、Layer3 Connection / LocalConnection（Go localharness へ WebSocket）。
• 並行ストリーム。1 応答から可視テキスト・thinking・型付き ToolCall を独立 cursor で並行イテレートします。
• Lifecycle Hooks。Decide / Inspect / Transform の 3 分類。ツール実行前の許可、実行後レシート、エラー整形、セッション境界の観測を行います。
• 宣言的ポリシー。deny / allow / ask_user、優先度モデル、when 述語。fail-closed です。
• ワークスペース制限。workspaces 設定時、ファイル系ツールへ policy.workspace_only が自動適用されます。
• Skills。ファイルシステムの SKILL.md バンドルを skills_paths から解決します。外部レジストリは不要です。
• カスタム Python ツールと MCP。ホスト側関数と stdio / HTTP の MCP サーバを同一パイプラインへ載せます。
• セッション永続。save_dir と conversation_id で軌跡をディスクへ残し、プロセス再起動後に再開します。
• サブエージェント。動的セルフクローン（enable_subagents、types.py 既定 True）と静的 SubagentConfig。親ポリシーは子のツール呼び出しにも適用されます。
• トリガー。定期 / 外部イベントでエージェントへメッセージを投入します。
• トークン監査。ChatResponse.usage_metadata と BudgetConfig。

起点ブログが制御プレーン向けに強調する 4 ブロックは次です。

1. Skills による能力拡張
2. サンドボックス化された組み込みツールと workspace スコープ
3. save_dir / conversation_id によるセッション隔離と軌跡永続
4. Lifecycle Hooks によるリアルタイム・テレメトリと介入

関連技術との関係

ユースケース別の推奨

構造

ホストアプリケーションが SDK を組み込み、Go 同梱ランタイムがモデル API・MCP・ファイルシステムへ出ます。観測と介入の接点は Lifecycle Hooks と ChatResponse ストリームです。

システムコンテキスト図

アクター

調査対象

外部システム

コンテナ図

ホストプロセス境界

同梱ランタイムと外部

コンポーネント図

Layer1 Simplified

Layer2 Session

Layer3 Adapter

Go harness プロセス

Lifecycle hook 分類と順序

ツール呼び出しの標準順序は次です。

1. Decide（PreToolCallDecideHook）
2. Execute（harness 組み込み、またはホスト ToolRunner / MCP）
3. Post（PostToolCallHook）

エラー経路では OnToolErrorHook が Post より先に走ります。回復結果がある場合、通常の Post 監査経路は短絡します。

起点ブログの「SDK agent core」は Go harness を含む実行核を指します。「observability middleware」は Lifecycle Hooks をホスト側で観測中継に使う構成例です。

データ

設定境界は LocalAgentConfig、実行時状態は Conversation と ChatResponse、介入の戻り値は HookResult です。フック用コンテキストとツール用 ToolContext は独立した状態空間です。フックが書いた値をツールが直接読む経路はありません。Python 公開 API に Trajectory クラスはありません。概念上の軌跡は Step.trajectory_id と Conversation.history の束です。

概念モデル

情報モデル

公開型の主要フィールドです。Zenn の Mermaid 上限に合わせ、設定系と実行時系を分けて示します。図中の Trajectory は概念上の束であり、Python 公開クラスではありません。ChatResponse.thoughts / tool_calls は非同期イテレータ、text() は非同期メソッドです。BuiltinTools は文字列 Enum（識別子は value）、Hook は Decide / Inspect / Transform の Union で kind 属性はありません。run_command_config は RunCommandConfig | None です。

BuiltinTools 正式 identifier

BuiltinTools.file_tools() は view_file / create_file / edit_file のみです。policy.workspace_only の対象はこの 3 つです。

conversation_id と保存先

公式 lifecycle の手入力例は session-12345678901234567890123456789012 です。

HookResult

run_command の引数キーはポリシー例で CommandLine です。

CapabilitiesConfig 既定（types.py）

enabled_tools と disabled_tools は相互排他です。

導入

前提条件

• Python 3.10 以上（PyPI requires_python: >=3.10）
• Gemini API キー、または Gemini Enterprise Agent Platform 向け認証
• 実行には PyPI wheel 同梱の runtime binary が必要
• 既定モデルは gemini-3.8-flash、既定画像生成モデルは gemini-3.1-flash-lite-image（skills agent_configuration.md）

インストール

推奨は PyPI です。リポジトリ clone はソース参照用で、runtime binary は wheel 側に含まれるため、clone のみでは実行環境は揃いません。

pip install google-antigravity

バージョン固定です。

pip install google-antigravity==0.1.16

ソース参照を併用する場合です。

git clone https://github.com/google-antigravity/antigravity-sdk-python.git
pip install google-antigravity

バージョン確認

curl -sS https://pypi.org/pypi/google-antigravity/json
python3 -c "import importlib.metadata as m; print(m.version('google-antigravity'))"
pip show google-antigravity

確認時点の registry info.version は 0.1.16（アップロード 2026-09-02）です。

認証の初期セットアップ

Gemini API です。

export GEMINI_API_KEY="your_api_key_here"
python ./examples/getting_started/hello_world.py

Vertex Express Mode です。

from google.antigravity import Agent, LocalAgentConfig

config = LocalAgentConfig(
    vertex=True,
    api_key="your_api_key_here",
)

async with Agent(config) as agent:
    response = await agent.chat("Hello!")
    print(await response.text())

Vertex Standard Mode です。

from google.antigravity import Agent, LocalAgentConfig

config = LocalAgentConfig(
    vertex=True,
    project="your-gcp-project",
    location="us-central1",
)

async with Agent(config) as agent:
    response = await agent.chat("Hello!")
    print(await response.text())

環境変数でも Standard Mode を有効化できます。明示 kwargs が env より優先します。GOOGLE_GENAI_USE_ENTERPRISE も Vertex 有効化に使えます。

export GOOGLE_GENAI_USE_VERTEXAI=True
export GOOGLE_CLOUD_PROJECT="your-gcp-project"
export GOOGLE_CLOUD_LOCATION="us-central1"
gcloud auth application-default login

利用方法

必須パラメータ

最小 chat

import asyncio
from google.antigravity import Agent, LocalAgentConfig

async def main() -> None:
    config = LocalAgentConfig()
    async with Agent(config) as my_agent:
        response = await my_agent.chat("Say 'Hello World!'")
        print(await response.text())

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

同一 async with 内で chat を複数回呼ぶと、同一会話上にターンが積み上がります。コンテキストマネージャ終了でセッションが閉じます。

ChatResponse ストリーム

await agent.chat(...) は即時に ChatResponse を返します。本文は async for token in response、思考は response.thoughts、ツール呼び出しは response.tool_calls です。各 iterator は共有バッファ上の独立 cursor です。asyncio.gather で並行消費できます。ターン完了後のトークン合計は response.usage_metadata.total_token_count です。

response = await my_agent.chat(prompt)

async for thought in response.thoughts:
    print(thought, end="", flush=True)

async for token in response:
    print(token, end="", flush=True)

async for call in response.tool_calls:
    print(call.name)

Skills

skills_paths は個別 skill ディレクトリ（中に SKILL.md）と、複数 skill サブディレクトリを持つ親ディレクトリの双方を受け付けます。解決単位は SKILL.md を含むディレクトリです。親ディレクトリを渡すと、直下の各サブディレクトリが skill として解決されます。外部レジストリは使いません。runtime がファイルシステムから読み、システムプロンプトへ注入します。同名衝突時の優先順位は公式 tools ページに機械可読な表が無いため、パス指定を一意に保ちます。

skills/code-review/
  SKILL.md
  references/
  scripts/

from google.antigravity import Agent, LocalAgentConfig

config = LocalAgentConfig(
    skills_paths=["./skills/research", "./skills/code_review"],
)
async with Agent(config) as agent:
    response = await agent.chat("Analyze the deployment logs.")
    print(await response.text())

ワークスペースと組み込みツール露出

from google.antigravity import Agent, LocalAgentConfig, types

config = LocalAgentConfig(
    model="gemini-3.8-flash",
    capabilities=types.CapabilitiesConfig(
        enabled_tools=[
            types.BuiltinTools.LIST_DIR,
            types.BuiltinTools.FIND_FILE,
            types.BuiltinTools.SEARCH_DIR,
            types.BuiltinTools.VIEW_FILE,
            types.BuiltinTools.CREATE_FILE,
            types.BuiltinTools.EDIT_FILE,
        ],
    ),
    workspaces=["./workspace"],
)

workspaces を設定すると、ファイル系 3 ツールへ policy.workspace_only が自動適用されます。run_command / MCP / search_web は別ポリシーで制御します。

read-only 露出の明示です。

from google.antigravity import LocalAgentConfig, CapabilitiesConfig
from google.antigravity.types import BuiltinTools

config = LocalAgentConfig(
    capabilities=CapabilitiesConfig(
        enabled_tools=BuiltinTools.read_only()
    )
)

README は「既定は read-only。capabilities=CapabilitiesConfig() で全ツールを有効化」と書きます。LocalAgentConfig 実装の default_factory は既に CapabilitiesConfig() で、ポリシー既定が confirm_run_command()（run_command 拒否、他許可）です。層の違いの詳細は後述の注意点です。

セッション再開

import tempfile
from google.antigravity import Agent, LocalAgentConfig

save_dir = tempfile.mkdtemp(prefix="agent_session_")

config1 = LocalAgentConfig(save_dir=save_dir)
async with Agent(config1) as agent:
    response = await agent.chat("Remember this: my favorite color is blue.")
    await response.text()
    conversation_id = agent.conversation_id

config2 = LocalAgentConfig(
    conversation_id=conversation_id,
    save_dir=save_dir,
)
async with Agent(config2) as agent:
    response = await agent.chat("What is my favorite color?")
    print(await response.text())

手入力 ID の公式例です。

conversation_id = "session-12345678901234567890123456789012"
config = LocalAgentConfig(
    save_dir="./sessions",
    conversation_id=conversation_id,
    app_data_dir="/path/to/custom/storage",
)

Lifecycle Hooks

デコレータは from google.antigravity.hooks import hooks です。登録は LocalAgentConfig(hooks=[...]) です。

from google.antigravity import Agent, LocalAgentConfig, types
from google.antigravity.hooks import hooks

@hooks.on_session_start
async def on_start() -> None:
    print("Session started")

@hooks.on_session_end
async def on_end() -> None:
    print("Session ended")

@hooks.pre_tool_call_decide
async def pre_tool(data: types.ToolCall) -> types.HookResult:
    print(f"Approving tool -> {data.name}")
    return types.HookResult(allow=True)

@hooks.post_tool_call
async def post_tool(data) -> None:
    print(f"Result -> {data!r}")

config = LocalAgentConfig(
    hooks=[on_start, on_end, pre_tool, post_tool],
)

公式 lifecycle ページは pre_turn と on_tool_error も示します。双方が併存します。pre_turn は SDK 側 send() 起点ターン向けです。trigger 起点ターンの完全ガードは Decide 側へ寄せます。

from google.antigravity import Agent, LocalAgentConfig, hooks, types

@hooks.pre_turn
async def log_turn(prompt: str) -> types.HookResult:
    print(f"User prompt: {prompt}")
    return types.HookResult(allow=True)

@hooks.on_tool_error
async def handle_error(err: Exception) -> None:
    print(f"Tool execution failed: {err}")

config = LocalAgentConfig(hooks=[log_turn, handle_error])

主要フックのシグネチャ

監視と介入の分担です。

ポリシー

import の正本は次です。

• from google.antigravity.hooks import policy
• from google.antigravity.hooks.policy import deny, allow, ask_user, enforce
• 互換 re-export: google.antigravity.policy

from google.antigravity import LocalAgentConfig
from google.antigravity.hooks.policy import deny, allow, ask_user

async def my_handler(tool_call):
    print(f"Tool approval requested for: {tool_call.name}")
    return True

policies = [
    deny("*"),
    allow("view_file"),
    ask_user("run_command", handler=my_handler),
]

config = LocalAgentConfig(policies=policies)

優先度は Specific DENY → Specific ASK_USER → Specific APPROVE → Wildcard DENY → Wildcard ASK_USER → Wildcard APPROVE です。同一レベルは first match wins です。

LocalAgentConfig.policies の静的ルール（ツール名と decision だけ）は Go harness 側で評価します。when 述語と ask_user handler は Python へ問い合わせます。policy.enforce() は Python の Decide hook を直接登録する別経路です。

when 述語や承認ハンドラの評価で例外が発生すると、fail-closed として呼び出しを拒否します。ask_user は handler 必須で、欠けると構築時に ValueError です。handler は ToolCall を受け取り True（承認）または False（拒否）を返します。

対話 preset は policy.safe_defaults(handler=interactive.ask_user_handler) です。既定ポリシーは policy.confirm_run_command() です。全許可は policies=[policy.allow_all()] です。

when 述語と MCP / Web ツールの閉じ方です。

from google.antigravity import types
from google.antigravity.hooks import policy

stdio_server = types.McpStdioServer(
    name="pirate_math",
    command="python3",
    args=["mcp_server.py"],
)

async def my_handler(tool_call):
    return True

policies = [
    policy.deny_all(),
    policy.allow("view_file"),
    policy.deny(
        "run_command",
        when=lambda args: "rm" in args.get("CommandLine", ""),
    ),
    policy.ask_user("run_command", handler=my_handler),
    policy.deny("search_web"),
    policy.allow("read_url_content"),
    policy.allow(stdio_server, ["pirate_multiply"]),
    policy.deny(stdio_server, ["pirate_divide"]),
]

カスタムツールと MCP

from google.antigravity import Agent, LocalAgentConfig

def get_weather(city: str) -> str:
    """Returns the current weather for a city."""
    return f"It's sunny in {city}."

config = LocalAgentConfig(tools=[get_weather])

from google.antigravity import Agent, LocalAgentConfig
from google.antigravity.types import McpStdioServer

config = LocalAgentConfig(
    mcp_servers=[
        McpStdioServer(
            name="my_server",
            command="npx",
            args=["my-mcp-server"],
        )
    ],
)

MCP サーバ名は ^[a-zA-Z0-9_-]+$ です。HTTP 接続は McpStreamableHttpServer です。

サブエージェント

from google.antigravity import Agent, LocalAgentConfig, types

config = LocalAgentConfig(
    capabilities=types.CapabilitiesConfig(enable_subagents=True)
)

静的サブエージェントに渡す callable は SubagentConfig.tools に載せます。Agent は親と子の callable を ToolRunner へ収集しますが、親セッションへ公開するツール集合は別に構築します。親の tools へ同じ関数を足すのは、親自身にもその関数を公開したい場合に限ります。公式ドキュメントが一律登録と書く場合でも、実行関数の登録と親へのツール公開は別です。

運用

起動と停止

• async with Agent(config) がセッション境界です。
• 長期監視は triggers=[every(seconds, handler)] を載せ、プロセスを生存させたまま、コールバック内の ctx.send() でエージェントへ定期ターンを投入します。
• 対話運用は run_interactive_loop(config) です。終了入力は exit / quit です。

import asyncio
from google.antigravity import Agent, LocalAgentConfig
from google.antigravity.triggers import every

async def check_status(ctx):
    await ctx.send("Check the deployment status.")

config = LocalAgentConfig(triggers=[every(60, check_status)])

async def main():
    async with Agent(config) as agent:
        await asyncio.sleep(120)

asyncio.run(main())

状態確認

状態保存の契約です。

ログと監査

• Inspect 系は観測専用です。
• Decide 系はゲートです。allow=False で中断します。
• Transform 系はエラー文言を差し替えます。
• 実行順は Decide → Execute → Post です。
• 軌跡は runtime が残します。ダッシュボード向け構造化監査はアプリの hooks が所有者です。

from google.antigravity.hooks import hooks
from google.antigravity import types

class AuditLogHook(hooks.PostToolCallHook):
    def __init__(self):
        self.log = []

    async def run(self, context, data: types.ToolResult):
        self.log.append({"tool": data.name, "result": str(data.result)})

更新とスケール

• runtime binary は PyPI wheel に同梱されます。パッケージ更新が runtime 更新の配送経路です。
• 起点ブログは「core runtime 更新が SDK agents に自動継承される」と述べます。運用ではパッケージ更新後に承認条件の回帰を実施します。
• 動的サブエージェントの enable_subagents 既定は True です。
• 親の Decide / Post はサブエージェント内のツール呼び出しにも発火します。
• OS サンドボックスは RunCommandConfig(enable_sandbox=True) です。既定は False です。ポリシー（実行可否）とサンドボックス（実行後の到達範囲）は役割が分かれます。
• レート制限は PreToolCallDecideHook で実装します（examples/deep_dives/agent_middleware.py）。

回帰観点の最小セットです。

• 同一 policies リストで ask_user が発火すること
• workspace 外への create_file / edit_file が拒否されること
• 32 文字制約を満たす conversation_id で再開できること
• 親 policies が子エージェントの run_command でも発火すること
• OnToolError 回復後の呼び出しが Post 監査に載らないことをテストが明示記録すること
• パッケージ bump 前後で同一 policies スナップショットを比較すること
• enable_sandbox=True を使う環境では、非対応 OS で sandbox が黙って無効にならないかを別観点で確認すること

ベストプラクティス

CI/CD

• SDK バージョンを lock し、wheel 更新ごとに承認回帰を走らせます。
• 本番と同一の policies リストを固定入力にします。
• OnToolErrorHook はメッセージ文字列ベースでフォールバックを返します。isinstance サブクラス判定は LocalConnection 境界で効きません。

マルチ環境

• save_dir と app_data_dir は環境ごとに分離します。
• conversation_id は環境接頭辞付きの 32 文字以上 ID をアプリが採番するか、runtime mint 値を外部ストアへ保存します。

リソース制限

• ターン単位のコストは usage_metadata で監査します。
• ツール呼び出し頻度は Decide hook のレート制限で抑えます。
• BudgetConfig / CompactionConfig でモデル呼び出し上限とコンテキスト要約間隔を寄せます。
• enable_sandbox=True は run_command 許可時の到達範囲を狭めます。

セキュリティ

disable と deny を使い分けます。

• fail-closed です。Decide の deny は即中断です。
• workspace_only の対象は view_file / create_file / edit_file です。
• write ツールや MCP を有効化した状態で policies も Decide hook も空の場合、Agent 起動時に ValueError になります。明示の allow_all か選択的 allow を載せます。
• 既定ポリシー confirm_run_command() は run_command を拒否し、他ツールを許可します。

from google.antigravity import LocalAgentConfig, types
from google.antigravity.hooks import policy

async def approve(tool_call) -> bool:
    return True

policies = [
    policy.deny_all(),
    policy.allow("view_file"),
    policy.ask_user("run_command", handler=approve),
]

config = LocalAgentConfig(
    capabilities=types.CapabilitiesConfig(),
    workspaces=["/srv/agent/ws"],
    policies=policies,
)

設定管理

• 正本は LocalAgentConfig の宣言値です。
• secrets は環境変数（GEMINI_API_KEY / Vertex 系）に分離します。
• policies・hooks・skills_paths・workspaces・save_dir を環境別定数としてバージョン管理します。

注意点

ドキュメントと実装の乖離

資料間の食い違い

確認時点の未確認事項

トラブルシューティング

セッションが再開されない

Agent 起動時に ValueError

run_command が常に拒否される

workspace 外ファイルは拒否されるが shell は通る

承認 UI が出る前にツールが動く

サブエージェント経由の危険ツール

trigger 定期実行が pre_turn ログに出ない

OnToolErrorHook の型判定が効かない

エラー回復後の呼び出しが監査ログに無い

SDK 更新後に承認挙動が変わった

まとめ

Google Antigravity SDK は、Antigravity 2.0 / CLI と同じハーネスを Python プロセスへ持ち込み、自前のエージェントハブで実行監視・介入・状態保存を組み立てる面です。止められるのは Decide（PreToolCallDecideHook / policy.enforce）だけで、思考ストリームと PostToolCallHook は観測です。セッション再開は同一 save_dir と 32 文字以上の conversation_id の組が契約です。ブログ例の短い ID や google.antigravity.policies import は、現行 0.1.16 の validator / パッケージ配置と一致しません。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク

概要

• Power agent hubs or custom harnesses with the Antigravity SDK
• Choosing your surface: Antigravity 2.0, CLI, IDE, or SDK
• Antigravity SDK 製品ページ
• google-antigravity · PyPI
• PyPI JSON 0.1.16
• Antigravity agent（Gemini API Managed Agents）

構造

• SDK Overview
• GitHub README Architecture
• hooks/README.md
• connections/README.md
• conversation/README.md
• examples/deep_dives/agent_middleware.py

データ

• types.py
• LocalAgentConfig
• AgentConfig / conversation_id validator
• Lifecycle hooks, triggers, and session persistence

構築方法 / 利用方法

• Custom tools and agent skills
• Safety policies and permissions
• MCP
• Subagents
• persistence.py
• hooks.py
• policies.py

運用 / ベストプラクティス / 注意点 / トラブルシューティング

• safety_policies.md
• policy.py
• tools/README.md
• triggers/README.md