Google Antigravity Agent API 入門：Interactions API、ツール呼び出し、状態の継続

米国の Google トレンドで「コーディング エージェント」に関する検索語が上昇しており、その中に反重力が含まれています。

Google は現在、Antigravity Agent の Interactions API へのプレビュー エントランスを提供しているため、「IDE で利用可能」と「プログラムで呼び出される」を分けて理解する必要があります。

この API はどのようなタスクに適していますか?

明確な目標があり、複数ステップの推論とツール操作が必要な開発タスクに適しています。

たとえば、リポジトリを読み取り、エラーを見つけ、コードを変更し、テストを実行します。

シングルパスのテキスト補完では、エージェント ランタイムを使用する必要はありません。

プレビュー バージョンは、分離せずに実稼働環境を直接操作するのにも適していません。

開始前に 4 つの情報を記録してください

• Google AI Studio プロジェクト。

• API キーはプロジェクトに属します。

• 選択されたモデルと地域での入手可能性。

• 無料層または有料層の割り当て。

キーには環境変数のみが設定されます。

1

$env:GEMINI_API_KEY = Read-Host "Gemini API key"

実際のキーをサンプル スクリプト、スクリーンショット、または Git 履歴に書き込まないでください。

まずツールを使わずに最小限のリクエストを作成します

現在公式ドキュメントに記載されている SDK とフィールド名を使用してください。

プレビュー API はすぐに変更されるため、古いブログ コードをコピーする前にバージョンを確認してください。

ターゲットに、「このエラーを説明し、仮説を 2 つ挙げてください」など、受け入れられるアクションを 1 つだけ書くように要求します。

応答ID、モデル名、所要時間、使用状況を保存します。

応答 ID は、その後の接続ステータスとトラブルシューティングのための重要な証拠となります。

読み取り専用ツールを追加する

最初のツールは、シェルを実行するのではなく、ファイルを読み取るものである必要があります。

許可されたディレクトリをテスト リポジトリに固定します。

1

C:\sandbox\antigravity-demo

ツールパラメータはパスを正規化する必要があります。

絶対パス、..、シンボリック リンク エスケープ、および非表示のネットワーク共有を拒否します。

リポジトリ全体がコンテキストに詰め込まれないように、返されるコンテンツにバイト制限を設定します。

ツール呼び出しサイクルを受け入れる方法

各通話はログに記録されます。

1. エージェントによって提案されたツール名。

2. オリジナルのパラメータ。

3. パラメータの検証結果。

4. ツールの終了コード。

5. 切り捨てられた出力。

6. エージェントの最終結論。

ツールの実行者は、自然言語に基づいて独自に権限を拡張しないでください。

エージェントがファイルの読み取りを要求した場合、書き込みを許可することはできません。

ステータスの継続のためにチャットテキストの結合に依存しないでください

API が再開可能なインタラクション ID を返す場合は、公式ステータス メカニズムが最初に使用されます。

すべての履歴メッセージを手動で繰り返し送信するとコストが増加し、ツールのステータスが失われる可能性もあります。

続行する前に、前回の実行が完了したか、ツールを待機したか、失敗したかを確認してください。

失敗ステータスを成功コンテキストとして直接継続しないでください。

書き込み操作では 2 フェーズの送信が採用されています

最初のステージでは diff のみが生成されます。

第 2 フェーズは、人間またはポリシー エンジンによる承認後に適用されます。

1
2

git diff --check
git diff --stat

適用後に最小限のテストを実行します。

テストが失敗した場合は、作業ツリーとログを保持し、エージェントに証拠を自動的にクリーンアップさせないでください。

コマンド ツールに明示的な許可リストを追加します

まず次のことを許可できます。

1
2
3
4

git status --short
git diff --check
npm test -- --runInBand
python -m pytest tests/unit

コマンドのスプライシング、リダイレクト、ダウンロードの実行、権限昇格を拒否します。

コマンドの先頭だけを一致させないでください。

パラメータも確認する必要があります。

コスト管理のための 3 つの境界線

エージェントのステップの最大数を設定します。

単一ツールの最大出力制限を設定します。

インタラクション全体の時間と予算の制限を設定します。

限界に達したら、「未完成」と既存の証拠に戻り、完了したふりをしないでください。

よくある位置決めの失敗

401 まずキーとプロジェクトを確認してください。

403 API が公開されているかどうか、アカウント資格、地域を確認します。

429 分単位のクォータ、日単位のクォータ、同時実行制限を区別します。

ツールが同じパラメーターを繰り返し呼び出す場合、通常、返される結果が十分に構造化されていないことを意味します。

最終的な答えは diff と矛盾しており、実際の作業ツリーに基づく必要があります。

信頼性の高いテストタスク

意図的に失敗する単体テストを準備します。

エージェントは原因を究明するよう求められますが、最初の段階ではファイルへの書き込みが禁止されています。

関連するソース ファイルを読み取って出力をテストすることを確認します。

2 番目のラウンドではパッチを生成できます。

パッチを手動で確認した後、テストを適用して実行します。

最後に、新しいインタラクションを開き、別の検査プロセスに差分をレビューさせます。

これにより、エージェントに実際のプロジェクトを変更させるよりも権限とステータスの問題が明らかになります。

オンラインにする前に確認してください

• プレビューの変更は明示的な SDK バージョンにロックされます。

• 鍵は倉庫や丸太には入りません。

• ファイル ツールはサンドボックスのルート ディレクトリに制限されています。

• コマンド引数は、文字列の接頭辞の一致ではなく解析されます。

• 書き込みは diff によって承認される必要があります。

• ステップ数、時間、出力、料金には制限があります。

• 障害ステータスは証拠を保持します。

Antigravity Agent の焦点は、「コードを自動的に作成する機能」ではなく、監視可能、停止可能、ロールバックの境界内でコード タスクを完了できるかどうかです。

エージェント API 正式入口

ツールの戻り値が安定した JSON になるように設計する

ツールは、区別できないステータスの端末テキストのブロック全体を返してはなりません。ファイル読み取り結果には、少なくとも path、encoding、truncated、および content が含まれます。コマンド結果には、少なくとも exit_code、stdout、stderr、および duration_ms が含まれます。 「コマンドの失敗」と「コマンドは成功したが出力がない」を区別できるのはエージェントだけです。

1
2
3
4
5
6
7
8

{
  "tool": "read_file",
  "ok": true,
  "path": "src/app.py",
  "encoding": "utf-8",
  "truncated": false,
  "content": "print('hello')"
}

コマンド実行プログラムの結果では、次の形式を使用できます。

1
2
3
4
5
6
7
8

{
  "tool": "run_test",
  "ok": false,
  "exit_code": 1,
  "stdout": "3 passed, 1 failed",
  "stderr": "",
  "duration_ms": 1842
}

ok` は終了コードに基づいてエグゼキュータによって生成され、モデル自体によって入力することはできません。出力が切り捨てられると、切り捨て位置も返され、エージェントがより狭い範囲のログを要求できるようになります。

ストリーミング応答中断後の処理

ネットワークの中断は、タスクが実行されないことを意味するものではありません。再試行する前に対話ステータスを問い合わせます。サーバーがツールの結果を受け入れた場合、送信を繰り返すと書き込み操作が 2 回実行される可能性があります。

各書き込みツールに冪等キーを追加します。キーはインタラクション ID、ツール呼び出し ID、ターゲット リソースで構成され、エグゼキュータは同じキーを見つけた場合に最初の結果を返します。

1

idempotency_key = interaction_id + tool_call_id + target

公式 SDK がステータス クエリ インターフェイスを公開していない場合は、書き込み操作を人間の確認段階に残し、不確実な状態で自動的に再試行しないでください。

プレビューバージョンアップグレード記録

SDK がアップグレードされるたびに、ロック ファイルの差分、リクエスト フィールドの変更、レスポンス フィールドの変更、および成功した記録が保存されます。まず修正されたテスト タスクを再生してから、実際のウェアハウスを開きます。

特に、ツール呼び出しパラメーターの名前が変更されているかどうか、ステータスの列挙が増加しているかどうか、古い対話を新しい SDK で継続できるかどうかを確認してください。タスクを継続できなくなった場合は、古いタスクを自然終了させ、運用中にバージョンを切り替えないでください。

フォールト挿入テスト

読み取りツールにタイムアウトを返させるようにして、エージェントがタイムアウトをファイルの存在しないものとして解釈しないことを確認します。テスト コマンドで終了コード 1 と空の stderr を返し、それでも失敗することを確認します。書き込みツールが「実行されましたが応答が失われました」を返して、冪等メカニズムが 2 回目の書き込みを防止できることを確認します。

最後に、テスト キーを取り消し、同じタスクを再実行します。システムは認証フェーズ中に停止し、それ以上ファイルのアクセス許可を要求しないようにする必要があります。

インタラクションのローカル監査レコードを作成する

監査レコードには完全なソース コードとプロンプトは保存されず、位置決め操作に必要なメタデータのみが保存されます。推奨される構造は次のとおりです。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "interaction_id": "int_example",
  "started_at": "2026-07-27T03:00:00Z",
  "model": "replace-with-current-model",
  "repository": "demo-api",
  "base_commit": "8c18d4a",
  "tool_policy": "readonly-v2",
  "tool_calls": 7,
  "write_approved": false,
  "result": "needs_review"
}

repository` 内部エイリアスを使用して、顧客名が集中ログに書き込まれることを回避します。ソース コード スニペットは、より厳格な権限を持つタスク添付ファイルにのみ保存され、独立した有効期限が設定されます。

パラメータは手動承認後も再検証する必要があります

承認インターフェイスに表示されるパラメータと実行者が受け取るパラメータの間には時間差が生じる場合があります。正規パス、コマンド引数、コンテンツ ハッシュは実行前に再計算されます。変更を行うと、元の承認が無効になります。

1

approval = hash(tool_name + normalized_arguments + target_revision)

承認を待っている間にターゲットのブランチが変更された場合、エージェントは差分を再生成する必要があります。新しいバージョンのコードに古いパッチを黙って適用しないでください。

終了時に継続可能な状態を残す

読み取られたファイル、まだ検証されていない仮説、最後に成功したツール呼び出し、および予算に達したとき、タイムアウト、または手動中止したときのワークツリーのステータスを出力します。

次回の実行はこれらの事実から開始されるため、ウェアハウス全体を再スキャンする必要はありません。作業ツリーにコミットされていない変更が含まれている場合、続行するか、パッチを保存するか、破棄するかは人間の判断に任されており、エージェントは自動的にそれをクリーンアップしません。

• Google：Antigravity Agent API

• Google：Antigravity 平台介绍