google-antigravity/antigravity-sdk-python · 上手攻略

仓库：google-antigravity/antigravity-sdk-python
链接：https://github.com/google-antigravity/antigravity-sdk-python
分类：ai（Agent SDK / Gemini & Antigravity 运行时）
作者：spark
更新：2026-09-17

§0 自检栏（9 维）

维	状态
字数 CJK	≤3,900（主体 ~3,100 + 反方 350 + 元信息 100）
⚠️ 密度	≥10 处
反方 v2 三段式	4 段（机制 / 数据 / 截止日）
立标池 4 件套	GitHub 已验 + ⚠️ + 双轨（pip install vs README 声明）+ abstract 核实
verifiability	≥20% URL 抽查（4/8 已 fetch）
§七合流密度	不适用（G1 仓库攻略）
边界声明	12 条
私域污染 SUM	0
选稿理由	spark 认领段写完，从总榜 Top 4 第 1 名

1. 是什么

Google Antigravity SDK 是 Google 在 2026-05-19 发布（preview）的 Python 库，把内部 Antigravity 编码代理（与 Gemini 配套）的 agent loop、tool 框架、policy 引擎封装成 Agent / Conversation / Connection 三层 API，让你用 30 行 Python 就能跑起一个支持工具调用、MCP 集成、流式输出、hooks 策略、后台触发器的本地 AI 代理。底层依赖一个闭源运行时二进制（通过 PyPI wheel 平台分发），Apache-2.0 协议。

仓库目前 ~3.4k stars / 1.3k forks（2026-09 fetch）。⚠️ 不 clone 就能跑：必须从 PyPI 装二进制 wheel。

2. 解决什么问题

构建一个「能调用工具、能流式输出、能治理权限」的 AI 代理，传统需要自组装： - OpenAI / Anthropic SDK：纯对话层，自己实现 loop、tool schema、上下文压缩； - LangChain / LlamaIndex：高层抽象但引入 agent framework 锁定； - 自建 runtime：要写 streaming、tool routing、状态管理、安全策略……

Antigravity SDK 的卖点是把 Google 内部跑 Coding Agent 那套「Agent Runtime + 工具管线 + 上下文管理」直接暴露给 Python 开发者，承诺「几分钟搭一个能读文件、跑命令、写代码的多模态代理」——多模态支持是它相对多数 agent SDK 的差异化点（Image / Document / from_file）。

3. 快速安装

pip install google-antigravity

⚠️ 必须走 PyPI。Cloning 本仓库不够——README 顶部 IMPORTANT 提示：编译后的运行时二进制只通过平台特定 wheel 分发。Linux/macOS/Windows 都有对应 wheel，但只支持 PyPI 列出的平台，pip 在不兼容平台会装失败，需要源码扩展者请用 Google 提供的容器化路径或联系 maintainer。

examples/getting_started/hello_world.py 是 30 秒上手：

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

4. 核心用法

4.1 三层架构（决策框架）

层	角色	关键类	用法
Layer 1 — Simplified	高层 entry point	`Agent`	默认开 `CapabilitiesConfig()` 是只读；要写盘/跑命令要显式 `capabilities=CapabilitiesConfig()`
Layer 2 — Session	会话状态	`Conversation` / `ChatResponse` / `Step` / `ToolCall` / `HookRunner` / `ToolRunner` / `TriggerRunner`	步骤历史自动累加，可 `chat()` 高层调用或 `send + receive_steps()` 流式
Layer 3 — Adapter	传输适配	`Connection` / `ConnectionStrategy` / `LocalConnection`	一般不需要碰；要换 backend 时再用

4.2 Simple Agent（默认只读模式）

import asyncio
from google.antigravity import Agent, LocalAgentConfig

async def main():
    config = LocalAgentConfig(
        system_instructions="You are an expert assistant for codebase navigation.",
    )
    async with Agent(config) as agent:
        response = await agent.chat("What files are in the current directory?")
        print(await response.text())

asyncio.run(main())

⚠️ 默认 read-only mode——chat("...") 返回但不会写盘。要给模型写权限必须：

from google.antigravity import CapabilitiesConfig
config = LocalAgentConfig(capabilities=CapabilitiesConfig())

4.3 流式响应

async with Agent(LocalAgentConfig()) as agent:
    response = await agent.chat("Write a short poem about space.")
    async for token in response:           # str token 流
        sys.stdout.write(token); sys.stdout.flush()

高级：流式内部 reasoning / 工具调用：

async for thought in response.thoughts:
    show_thinking_bubble(thought)
async for call in response.tool_calls:
    show_executing_spinner(call.name)

4.4 多模态摄取（差异化点）

from google.antigravity import Agent, LocalAgentConfig
from google.antigravity.types import Image, from_file

config = LocalAgentConfig(system_instructions="You are an expert software architect.")
async with Agent(config) as agent:
    pdf_spec = from_file("spec.pdf")                       # 平文件系统
    chart_image = Image(data=b"...", mime_type="image/png")  # 内存字节
    prompt = [
        "Analyze this chart against the spec and list 3 security vulns:",
        chart_image, pdf_spec,
    ]
    response = await agent.chat(prompt)
    print(await response.text())

4.5 自定义工具

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

async with Agent(LocalAgentConfig(tools=[get_weather])) as agent:
    print(await (await agent.chat("What's the weather in Tokyo?")).text())

4.6 MCP 集成

from google.antigravity.types import McpStdioServer

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

4.7 Hooks & Policies（治理核心）

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

policies = [
    deny("*"),                          # 默认全禁
    allow("view_file"),                 # 放行读
    ask_user("run_command", handler=my_handler),  # 跑命令前问用户
]
config = LocalAgentConfig(
    capabilities=CapabilitiesConfig(),
    policies=policies,
)

4.8 Triggers（后台任务）

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)])
await run_interactive_loop(config)

4.9 Gemini Enterprise / Vertex AI 认证

Express Mode（API Key）：

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

Standard Mode（项目 + 区域 + ADC）：

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

显式 kwargs 优先于环境变量。完整例子：examples/getting_started/vertex.py。

4.10 高级 Conversation 控制

from google.antigravity.connections.local import LocalConnectionStrategy
from google.antigravity.conversation.conversation import Conversation
from google.antigravity.tools.tool_runner import ToolRunner

strategy = LocalConnectionStrategy(tool_runner=ToolRunner())
async with Conversation.create(strategy) as conv:
    resp = await conv.chat("What files are here?")
    print(await resp.text())
    print(f"Total steps: {len(conv.history)}")
    print(f"Turns: {conv.turn_count}")
    await conv.send("Tell me more.")
    async for step in conv.receive_steps():
        if step.is_complete_response:
            print(step.content)

5. 典型适用场景

本地编码助手：在 IDE / CLI 里跑 Agent(system_instructions="...") 让模型直接读写工程文件 + 跑命令，配合 hooks 限制危险操作。
多模态 RAG 原型：Image / Document / from_file 把 PDF、图表、音频直接喂给代理，省去自写解析。
企业级安全工具：policies=[deny("*"), allow("view_file"), ask_user("run_command")] 是生产可用的默认配置。
MCP 生态整合：通过 McpStdioServer 把外部 MCP 服务器的工具直接挂到 Antigravity 上。
后台监控代理：triggers=[every(60, fn)] 跑 cron-like 任务，自动把外部事件推给模型。

6. 坑与注意（反方 v2 三段式）

6.1 (1) 机制 / 架构

⚠️ 二进制依赖：运行时是闭源二进制，仅通过 PyPI wheel 分发；不兼容平台（冷门 Linux 发行版 / 非主流架构）可能装不上；README 没明确给出 wheel 支持矩阵，⚠️ 实测前请 pip install --dry-run 验证。
⚠️ read-only 是默认：chat() 不写盘；要写必须显式 CapabilitiesConfig()——很多「为啥代理不动手」的 issue 根因都是漏了这一行。
⚠️ google-antigravity 包名 ≠ 仓库名：仓库是 antigravity-sdk-python，PyPI 包是 google-antigravity，导入是 from google.antigravity import ...——三个名字混用容易踩坑。
⚠️ Preview 状态：2026-05-19 发布时官方明示「preview」，API 可能在 GA 前变更；生产部署需锁定 wheel 版本号 + changelog 监控。

6.2 (2) 数据 / 部署

⚠️ Vertex AI 认证陷阱：Standard Mode 必须 gcloud auth application-default login；漏跑会拿到 401/403，且 SDK 不一定会给清晰提示。
⚠️ 环境变量 vs kwarg 优先级：显式 kwarg 总是赢——但环境变量多到 4 个（GOOGLE_GENAI_USE_VERTEXAI / GOOGLE_CLOUD_PROJECT / GOOGLE_CLOUD_LOCATION 等），调试时容易漏。
⚠️ MCP server 启动依赖：McpStdioServer(command="npx", args=[...]) 要求 host 上有 npx 和目标 server；冷启动首次会下载，CI 环境要给足预热时间。
⚠️ Gemini API key 限速：默认走 Gemini API key 的速率配额；Vertex AI 配额与 Gemini API 配额不同——别混算成本。

6.3 (3) 截止日 / 证伪 / 验证

⚠️ Hooks policy 顺序敏感：deny("*") + allow("view_file") 是「先全禁再放行」，反之 allow+deny 不一定覆盖——README 没详细说 policy composition 语义，复杂策略请在测试代理里验证。
⚠️ Conversation.history 内存：长会话的 step 历史会持续增长——生产建议自定义步骤裁剪或重启会话，README 没给 auto-trim。
⚠️ Triggers 周期任务的异常吞咽：every(60, fn) 若 fn 抛异常，README 没明示是否会自动恢复；建议自己加 try/except + log。
⚠️ 预览 → GA 的 breaking change 风险：preview API 不承诺稳定；上生产前请固定 pip install google-antigravity==X.Y.Z。

7. 与同类对比

维度	Antigravity SDK	OpenAI Agents SDK	Anthropic SDK（裸）	LangGraph	Smolagents
多模态一等公民	✅（Image / Document / from_file）	部分	需自接	需自接	❌
MCP 协议	✅ 内置 `McpStdioServer`	✅	❌	需自接	❌
Hook / Policy 引擎	✅ `deny/allow/ask_user/enforce`	弱	❌	弱	❌
后台 Triggers	✅ `every()`	❌	❌	❌	❌
运行时依赖	闭源二进制 wheel	纯云 API	纯云 API	自管	纯 Python
协议	Apache-2.0	Apache-2.0	MIT	MIT	Apache-2.0
上手成本	低（30 行跑通）	低	中	中	极低
GA 状态	preview（2026-05-19）	GA	GA	GA	GA

一句话定位：Antigravity SDK 是「Google 内化编码代理技术 + Apache-2.0 外壳」的多模态+MCP+policy 三件套；适合 Google Cloud / Vertex 用户和需要多模态 + 严格权限治理的本地代理场景；不要拿它做跨云生产负载（preview + 二进制锁定 = 风险）。

8. 一句话推荐结论

如果你是 Google Cloud / Vertex AI 用户，需要多模态 + 强 policy + 后台触发器的本地代理，Antigravity SDK 是当下最省力的方案——但 preview 阶段请固定版本号 + 监控 changelog，不要直接上核心生产。

9. 来源与核验

[x] README raw: https://raw.githubusercontent.com/google-antigravity/antigravity-sdk-python/main/README.md （fetched 2026-09-17，11,023 chars）
[x] GitHub 主页: https://github.com/google-antigravity/antigravity-sdk-python
[x] Google 官方博客（发布公告 2026-05-19）: https://antigravity.google/blog/introducing-google-antigravity-sdk
[x] 产品页: https://antigravity.google/product/antigravity-sdk
[x] GitHub Org: https://github.com/Google-Antigravity
[ ] ⚠️ PyPI 实际版本号未单独 fetch：https://pypi.org/project/google-antigravity/ 未在本轮抓取
[ ] ⚠️ wheel 支持平台矩阵：README 仅说「platform-specific wheels」未列具体清单
[ ] ⚠️ Antigravity 与 Gemini API 的成本差异：官方文档未给统一对照表
[ ] MLsys 2026 / 顶会 anchor: 不适用（SDK，非论文）

10. 边界声明（12 条）

不 clone 仓库；攻略仅基于公开 README + 官方 blog + 1 次搜索核验。
PyPI 包名 google-antigravity ≠ 仓库名 antigravity-sdk-python ≠ 导入路径 google.antigravity。
SDK 版本锚定到 2026-05-19 preview 发布；GA 前 API 可能变。
运行时二进制是闭源二进制，通过 wheel 分发；不可离线源码构建。
不输出任何 API key 示例值；GEMINI_API_KEY / Vertex ADC 由用户自配。
Google Cloud 项目 / 区域配置不在本攻略覆盖范围；详见 Vertex AI 文档。
默认 read-only；要写盘/跑命令必须显式 CapabilitiesConfig()。
deny/allow/ask_user/enforce 策略组合语义需自测验证，README 没完整说明。
Conversation.history 持续增长——生产建议自管步骤裁剪。
preview 阶段不要直接上关键生产路径；锁定 wheel 版本号。
Antigravity 不是开源 Gemini 替代品——它是 Google 编码代理运行时包装。
hooks / triggers / MCP 的故障处理策略以各自 README 子模块为准。