Google Antigravity Agent API 入門：Interactions API、工具調用與狀態續接

美國區 Google Trends 的 “coding agent” 上升查詢中出現 Antigravity。

Google 現在又提供了 Antigravity Agent 的 Interactions API 預覽入口，因此“IDE 裏能用”與“程序裏調用”需要分開理解。

這個 API 適合什麼任務

它適合有明確目標、需要多步推理與工具操作的開發任務。

例如讀倉庫、定位錯誤、修改代碼並運行測試。

單輪補全文本不必使用 Agent 運行時。

預覽版也不適合未經隔離直接操作生產環境。

開始前記錄四項信息

• Google AI Studio 項目。

• API key 所屬項目。

• 選擇的模型和區域可用性。

• 免費層或付費層的配額。

密鑰只放環境變量：

1

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

不要把真實密鑰寫進示例腳本、截圖或 Git 歷史。

先做不帶工具的最小請求

使用官方文檔當前展示的 SDK 與字段名。

預覽 API 變化較快，複製舊博客代碼前先覈對版本。

請求目標只寫一個可驗收動作，例如“解釋這段錯誤並給出兩種假設”。

保存響應 ID、模型名、耗時和用量。

響應 ID 是後續續接狀態與排錯的重要證據。

再增加只讀工具

第一種工具應是讀取文件，而不是執行 shell。

把允許目錄固定到測試倉庫：

1

C:\sandbox\antigravity-demo

工具參數需要做路徑規範化。

拒絕絕對路徑、..、符號鏈接逃逸和隱藏的網絡共享。

返回內容設置字節上限，避免把整個倉庫塞進上下文。

工具調用循環怎麼驗收

每次調用都記錄：

1. Agent 提出的工具名。

2. 原始參數。

3. 參數校驗結果。

4. 工具退出碼。

5. 截斷後的輸出。

6. Agent 最終結論。

工具執行器不應根據自然語言自行擴大權限。

Agent 請求讀取文件，就不能順便允許寫入。

狀態續接不要依賴聊天文本拼接

如果 API 返回可續接的 interaction 標識，優先使用官方狀態機制。

手工把所有歷史消息重複發送，會增加成本，也可能丟失工具狀態。

續接前確認上一次運行是完成、等待工具還是失敗。

失敗狀態不要直接當成功上下文繼續。

寫操作採用兩階段提交

第一階段只生成 diff。

第二階段由人或策略引擎批准後才應用。

1
2

git diff --check
git diff --stat

應用後運行最小測試集。

測試失敗時保留工作樹與日誌，不要讓 Agent 自動清理證據。

給命令工具加明確的允許列表

可以先允許：

1
2
3
4

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

拒絕命令拼接、重定向、下載執行和提權。

不要只按命令開頭匹配。

參數同樣需要校驗。

控制成本的三個邊界

設置最大 Agent 步數。

設置單次工具輸出上限。

設置整個 interaction 的時間與預算上限。

達到上限後返回“未完成”和已有證據，不要僞裝成完成。

常見失敗定位

401 先檢查密鑰與項目。

403 檢查 API 是否開放、賬號資格和區域。

429 區分每分鐘配額、每日配額與併發限制。

工具反覆調用同一參數，通常說明返回結果不夠結構化。

最終答案與 diff 不一致，應以真實工作樹爲準。

一個可靠的測試任務

準備一個故意失敗的單元測試。

要求 Agent 找出原因，但第一輪禁止寫文件。

確認它讀取了相關源文件和測試輸出。

第二輪允許生成補丁。

人工審覈補丁後應用並運行測試。

最後開啓新 interaction，讓另一個檢查流程複覈 diff。

這比讓 Agent 修改真實項目更能暴露權限與狀態問題。

上線前檢查

• 預覽版變更被鎖定到明確 SDK 版本。

• 密鑰不進入倉庫和日誌。

• 文件工具限制在沙箱根目錄。

• 命令參數經過解析而非字符串前綴匹配。

• 寫入必須經過 diff 審批。

• 步數、時間、輸出和費用均有限額。

• 失敗狀態保留證據。

Antigravity Agent 的重點不是“能自動寫代碼”，而是能否在可觀測、可停止、可回滾的邊界內完成代碼任務。

Agent API 官方入口

把工具返回值設計成穩定 JSON

工具不要返回一整段無法區分狀態的終端文本。文件讀取結果至少包含 path、encoding、truncated 和 content；命令結果至少包含 exit_code、stdout、stderr 與 duration_ms。Agent 才能區分“命令失敗”和“命令成功但沒有輸出”。

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 由執行器根據退出碼產生，不能讓模型自己填寫。輸出發生截斷時還要返回截斷位置，並允許 Agent 請求更小範圍的日誌。

流式響應中斷後的處理

網絡中斷不代表任務沒有執行。重試前先查詢 interaction 狀態；如果服務端已經接受工具結果，重複提交可能讓寫操作執行兩次。

爲每個寫工具增加冪等鍵。鍵由 interaction ID、工具調用 ID 和目標資源組成，執行器發現相同鍵時返回第一次結果。

1

idempotency_key = interaction_id + tool_call_id + target

如果官方 SDK 沒有暴露狀態查詢接口，就把寫操作留在人類確認階段，不要在不確定狀態下自動重試。

預覽版升級記錄

每次升級 SDK 都保存鎖文件 diff、請求字段變化、響應字段變化和一條成功錄製。先在固定測試任務上重放，再開放真實倉庫。

特別檢查工具調用參數是否更名、狀態枚舉是否增加，以及舊 interaction 能否由新 SDK 續接。無法續接時讓舊任務自然結束，不在運行中切換版本。

一次故障注入測試

讓讀取工具返回一次超時，確認 Agent 不會把超時解釋成文件不存在。讓測試命令返回退出碼 1 和空 stderr，確認它仍判斷爲失敗。再讓寫工具返回“已執行但響應丟失”，確認冪等機制能阻止第二次寫入。

最後撤銷測試密鑰，重新運行同一任務。系統應在認證階段停止，並且不請求更多文件權限。

爲 Interaction 建立本地審計記錄

審計記錄不要保存完整源碼和提示，只保存定位運行所需的元數據。推薦結構如下：

 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 使用內部別名，避免把客戶名稱寫進集中日誌。源碼片段只保存在權限更嚴格的任務附件中，並設置獨立過期時間。

人工批准之後仍要重新校驗參數

批准界面展示的參數與執行器收到的參數可能存在時間差。執行前重新計算規範化路徑、命令 argv 和內容哈希；任何一項變化都使原批准失效。

1

approval = hash(tool_name + normalized_arguments + target_revision)

目標分支在等待批准期間發生變化時，Agent 應重新生成 diff。不要把舊補丁靜默應用到新版本代碼。

退出時留下可繼續的狀態

達到預算、超時或人工中止時，輸出已經讀取的文件、尚未驗證的假設、最後一個成功工具調用和工作樹狀態。

下一次運行從這些事實開始，不需要重新掃描整個倉庫。若工作樹含未提交修改，先由人決定繼續、保存補丁還是丟棄，Agent 不自行清理。

• Google：Antigravity Agent API

• Google：Antigravity 平臺介紹