Google Antigravity SDK

今天我們推出 Google Antigravity SDK 預覽版 — 這是一個 Python 函式庫，可讓您透過程式存取 Google 頂級的 Antigravity 程式撰寫代理。透過 Antigravity SDK，您可以為複雜的代理應用程式製作原型、建構與反覆迭代。您可以在 Antigravity Agent Runtime 之上以最少程式碼建構，並探索和試驗具有頂尖水準原語的新型代理模式。 GitHub 儲存庫

由 Antigravity 執行階段驅動

SDK 為您提供驅動…的相同代理執行期 Antigravity 2.0 和 Antigravity CLI。您的代理繼承了強大的執行環境——豐富的內建工具集、宣告式安全政策引擎、用於觀察與引導每個工具呼叫的生命週期掛鉤，以及跨互動持續存在的具狀態多回合工作階段。透過 Antigravity SDK，您能以自己的邏輯擴充 Google 內部研究使用的同一框架。隨著 Antigravity 執行階段持續改善——更快的工具執行、更聰明的規劃、更好的內容管理——這些改善會自動流向您的 SDK 代理。

大多數開發人員只需要 Agent — 單一非同步 with 區塊，以不到 20 行慣用 Python 管理完整生命週期。以下是不到 15 行的功能性代理：

pip install google-antigravity

import asyncio
from google.antigravity import Agent, LocalAgentConfig

async def main():
    config = LocalAgentConfig()
    async with Agent(config) as agent:
        response = await agent.chat("What files are in the current directory?")
        print(await response.text())

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

您的代理邏輯與其執行位置解耦：不久後，您將能把本機代理循環換成遠端託管的版本，同一個代理部署至雲端——無需重寫。您專注於代理要做什麼，SDK 處理如何執行與在哪裡執行。

每個代理在初始化時都具備完整的內建工具組——檔案 I/O、程式碼編輯、殼層執行、目錄搜尋、圖片生成與子代理委派。接著，您可以分層加入系統指令以設定身分、新增領域專屬指引，或完全取代預設值。

為 AI 原生開發打造

SDK 的設計對代理友善——無論是您用它建置的應用程式，還是您建置它們的方式。如果您使用 Antigravity，可以要求代理直接在開發工作階段中撰寫、測試並迭代您的 SDK 程式碼。API 介面使用乾淨的 Python 型別（Pydantic V2 模型、原生 Python 集合）、結構化輸出與清晰的命名慣例——這些選擇都是為了讓 AI 代理能像人類開發人員一樣流暢地讀寫與維護 SDK 程式碼。SDK 就是 Antigravity 自己的 API：為您的程式碼建置的代理，從內到外都理解這個框架。

受治理的擴充能力

使用您自己的 Python 函式自訂代理，使用結構化輸出結構描述將其輸出繫結至您的資料型別，並控制工具呼叫的時機與方式。

工具與整合

SDK 支援四種工具集，它們共用一條執行管線、一套串流基礎架構，以及一組安全政策：

1. 內建工具：檔案 I/O、程式碼編輯、shell 執行、目錄搜尋、圖片產生、子代理委派等。
2. 自訂 Python 函式：將任何 Python 可呼叫物件註冊為代理可叫用的工具。
3. MCP 伺服器：連接任何 Model Context Protocol 伺服器（stdio，SSE 或 Streamable HTTP），並將其工具公開給代理。
4. 代理技能：使用以下項目提供可重複使用的技能套件（指示、工具與上下文）路徑 skills_paths 於代理設定。

定義一次政策或掛鉤，即可管理所有工具——無論其來源為何。

安全政策

開箱即用， LocalAgentConfig 啟用所有內建工具，但套用 confirm_run_command() 政策——多數工具無摩擦運作，但 shell 存取預設拒絕。若要啟用完全自主執行，請傳入 policies=[policy.allow_all()]。當您需要更多控制時，政策系統讓您能以宣告方式鎖定一切：

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

policies = [
    deny("*"),                          		# Block everything by default
    allow("view_file"),                 		# Except reading files
    ask_user("run_command", handler=my_handler),	# Human approval for shell
]

生命週期掛鉤

除了政策之外，掛鉤系統讓您擁有生命週期層級的控制權。掛鉤分為三種類別：

• 檢查：唯讀、非封鎖型。觀察事件以進行日誌、指標或稽核軌跡。
• 決定：唯讀、封鎖型。核准或拒絕動作（政策建構於此之上）。
• 轉換：修改、封鎖。重塑傳輸中的資料以進行清理或錯誤復原。

SDK 提供九個具體的掛鉤點——從工作階段開始/結束、回合前/後，到工具呼叫前/後、工具錯誤復原、使用者互動處理，以及上下文壓縮——每個都有裝飾器捷徑可快速接線：

from google.antigravity.hooks import post_tool_call
from google.antigravity.types import ToolResult

@post_tool_call
async def audit_log(result: ToolResult):
    print(f"Tool {result.name} completed")

功能

I/O 與執行

SDK 為輸入、輸出與工作執行提供彈性的選項：

• 串流：在輸出旁存取即時模型推理。透過以下方式反覆運算 async for chunk in response 適用於內容。
• 多模態輸入：在文字提示詞旁傳遞圖片、PDF、音訊與影片。使用以下項目從檔案路徑自動偵測 from_file() 或從原始位元組建構。
• 子代理：產生具有獨立工具、指示與上下文的子代理 — 代理團隊背後的建構基石。
• 思考等級：控制每個要求的推理深度 — MINIMAL, LOW, MEDIUM，或 HIGH — 使用 GenerationConfig.
• 觸發條件：執行對外部事件做出反應並將訊息推送至代理的背景任務。

狀態

您可以跨回合管理對話狀態與結構化回應：

• 工作階段持續性：透過傳遞以下項目，從已儲存的工作階段 ID 恢復對話 conversation_id 回到代理設定。
• 結構化輸出：定義回應結構描述（JSON 結構描述、dict 或 Pydantic 模型），代理會使用以下項目傳回已驗證的具型別資料 response.structured_output().
• 人為介入：代理會在任務中途暫停，提出具預定義選項的結構化問題，並依回應分支。

可觀測性

內建的可觀測性功能協助您監控模型行為與資源消耗：

• 權杖使用量：每回合與累計用量 — 提示詞、候選、快取與思考 Token — 可使用以下項目取得 usage_metadata.
• 推理軌跡：在輸出旁存取思考軌跡，觀察模型的即時推理過程。

搭配 Gemini 3.5 Flash 作為預設模型，SDK 代理可獲得驅動平台其餘部分的效能。掛鉤、子代理與安全政策在 SDK 與以下各處保持一致 CLI，與 Antigravity 2.0 — 在此以程式碼設定，而非透過 UI。

展望未來

我們正與將代理推向我們未曾預料的領域的開發人員、研究人員與平台工程師共同建構。作為研究預覽版，SDK 是一個持續演進的平台，我們正在尋求意見回饋以塑造其未來。

以下是路線圖上的內容：

• 遠端框架：將 SDK 代理部署至 Google Cloud — 持久、可擴充、可透過 Interactions API 存取。在本地建構，遠端部署。
• TypeScript 與 Go：相同的執行階段，額外的語言支援。
• Gemma 整合：我們正在開發 Gemma 支援 — 將完整的代理執行階段帶給您可自行執行與微調的開放模型。
• 外掛程式：可重複使用的指示、工具與上下文套件，可透過程式編寫組成代理，或從社群載入。
• 更深入的可觀測性：背景步驟追蹤、觸發器執行日誌，以及更豐富的遙測資料，用於大規模偵錯與最佳化代理行為。

開始使用

SDK 採用 Apache 2.0 授權，並隨附兩層範例： getting_started/ 適用於單一功能導覽，以及 deep_dives/ 適用於更複雜的模式。完整 API 文件現已提供：

pip install google-antigravity