深度解读 Google Antigravity SDK：Google 的 Agent 基础设施入场券

May 20, 2026

深度解读 Google Antigravity SDK：Google 的 Agent 基础设施入场券

2026年5月19日的 Google I/O 上，Google 正式发布了 Antigravity 2.0，同步开源了 Antigravity SDK for Python。这不是一个简单的 API wrapper——它是一个完整的 Agent 基础设施层，将 Agent Loop（推理→工具调用→结果→推理）抽象为 SDK 层的核心能力。本文将深度剖析这个项目的架构设计、策略引擎、MCP 集成，并与其生态位相近的 Hermes Agent 进行对比分析。

项目速览

组织google-antigravity（Google 官方）
仓库antigravity-sdk-python
创建时间2026-04-29（~3周前）
最近推送2026-05-19（I/O 发布日）
Stars / Forks357 / 48
Open Issues4
许可证Apache 2.0（OSI 批准，真正开源）
主要语言Python (~650K 行) + Shell (~11K 行)
PyPI 包google-antigravity v0.1.0
主要贡献者karmel (59 commits), kibergus (8), allenhutchison (6)
开发阶段Alpha
Python 版本≥3.10（支持 3.10–3.13）

核心定位

Antigravity SDK 的定位非常明确：让开发者只需定义 Agent 做什么，而非怎么跑。它将 Agent Loop 的完整生命周期——二进制发现、工具接线、Hook 注册、策略默认值——封装在单个异步上下文管理器中。

与 Hermes Agent 的独立进程模式不同，Antigravity 走的是 SDK + 编译型 Runtime 路线。核心 Agent Loop 实现在一个预编译的 Go binary（google/antigravity/bin/localharness）中，通过平台特定的 wheel 分发。这意味着：

  • 优势：高性能、低延迟、内存可控，启动零依赖
  • 劣势：不能纯源码安装（必须 pip install google-antigravity），架构绑定，调试不如纯 Python 透明

架构深度拆解

三层架构

层级职责核心组件
Layer 1 — Simplified 电池全包入口，单行启动 Agent
Layer 2 — Session 状态管理 + 历史 + 流式响应 Conversation, ChatResponse, HookRunner, ToolRunner, TriggerRunner
Layer 3 — Adapter 传输和后端抽象 Connection, ConnectionStrategy, LocalConnection → Go Runtime → Gemini API

这种分层设计使得每一层都可以独立替换。理论上，ConnectionStrategy 可以对接任意后端（OpenAI、Anthropic 等），但目前只有 LocalConnection 实现，绑定 Gemini API。

类型系统

全部公开类型使用 Pydantic V2 模型，零 proto 依赖。自定义 AntigravityValidationError 包装 Pydantic 错误，解耦 SDK 公共 API 与实现细节。这是一个非常干净的架构选择——类型安全、验证、序列化三位一体。

11 个内置工具

SDK 定义了 11 个内置工具（BuiltinTools），分为四个类别：

  • read_only()：list_directory, search_directory, find_file, view_file, finish
  • nondestructive()：read_only + create_file, edit_file, ask_question, start_subagent, generate_image
  • file_tools()：view_file, create_file, edit_file（可配合 workspace_only() 路径限制）
  • all_tools()：以上全部 + run_command

工具分类体系的设计非常实用——开发者可以根据安全等级精确控制 Agent 的能力边界。

策略引擎：Agent 安全的基础设施

这是我在此项目中见到的最精细的设计之一。Antigravity 的策略引擎采用 6 级优先级桶 模型：


优先级（从高到低）：
  Specific Deny > Specific Ask > Specific Allow >
  Wildcard Deny > Wildcard Ask > Wildcard Allow

同桶内：先注册先匹配（short-circuit）

关键设计：工具可见性 vs 工具拒绝

文档中对这两个概念的区分写得极好：

  • CapabilitiesConfig.disabled_tools：工具从模型上下文中完全移除，模型不可见，零 token 浪费
  • policy.deny()：工具对模型可见但调用时拒绝，模型可理解拒绝原因并调整策略（消耗 token）

这种区分看似细微，实则关键——它回答了 "什么时候应该让模型知道某个工具存在但不能用" vs "什么时候应该让模型完全不知道某个工具存在" 这个工程难题。

快捷策略函数

SDK 提供了一系列开箱即用的策略构建器：

  • allow_all() / deny_all()：全局开关
  • safe_defaults(handler)：只读工具放行，其余需用户确认
  • confirm_run_command()：run_command 需确认/拒绝，其余放行（LocalAgentConfig 默认策略）
  • workspace_only(paths)：文件操作限制在指定目录
  • 自定义 predicate：deny("run_command", when=lambda args: "rm" in args.get("command", ""))

安全的默认值

这是一个值得所有 Agent 框架学习的实践：默认拒绝危险操作。当启用写工具或 MCP servers 但没有配置任何策略时，Agent 启动会直接抛出 ValueError——不允许在无安全策略的情况下静默运行。开发者必须显式声明 allow_all() 或配置具体的 allow/deny 规则。

MCP 集成

Antigravity SDK 原生支持三种 MCP 传输方式：

  • McpStdioServer：本地 stdio 进程
  • McpSseServer：SSE 远程端点
  • McpStreamableHttpServer：Streamable HTTP（带超时、重连、SSE 读取超时配置）

MCP server 的工具会自动 Merge 到 Agent 可用工具列表中，工具选择对开发者透明。

多模态支持

SDK 原生支持四种媒体类型的输入：

  • Image：bmp, jpeg, png, webp
  • Document：pdf, json, csv, html, txt, xml, rtf, css, js
  • Audio：wav, mp3, aac, ogg, flac, opus, m4a, l16
  • Video：3gpp, avi, mp4, mpeg, webm, wmv, quicktime, flv

from_file(path) 函数自动根据 MIME 类型解析为正确的媒体类——这是非常实用的开发者体验设计。

Streaming 架构

ChatResponse 的流式设计采用了 独立 cursor 模式：

  • 每个迭代器（.chunks、.thoughts、.tool_calls、async for token in response）返回一个独立的 cursor
  • 多个 cursor 可以安全地顺序或并发消费同一个底层流
  • asyncio.Lock 序列化网络拉取——只有一个 cursor 在等待上游 __anext__，其他 cursor 从共享缓冲区读取

这套并发模式设计非常优雅，允许多个消费者（UI 渲染、日志记录、工具调用拦截）同时读取同一个流而不阻塞彼此。

与 Hermes Agent 的对比

维度Antigravity SDKHermes Agent
定位Python SDK，嵌入式 Agent独立 Agent 进程，多平台接入
Runtime编译型 Go binary（wheel 内置）Python + 插件系统
模型Gemini 优先，可配置多 provider（OpenAI/Anthropic/BitFun 等）
配置方式LocalAgentConfig() 编程式config.yaml + CLI
策略系统6 级优先级桶 + predicateapproval injection + hooks
MCP原生三种传输原生 MCP client
多模态Image/Doc/Audio/Video 全支持取决于模型能力
会话持久化conversation_id 恢复state.db SQLite
子 Agentstart_subagent 工具delegate_task
部署pip installCLI + systemd/Docker
生态Google 生态（Gemini/Vertex AI）开放生态（任何 provider）

潜在问题与待观察

  1. Alpha 阶段（v0.1.0），API 可能大幅变更
  2. Gemini 锁定风险：虽然架构抽象了 Connection，但当前只有 LocalConnection 实现
  3. 编译型 Runtime 调试困难：Go binary 是黑盒，问题排查不如纯 Python 透明
  4. 社区 SDK 需求：已有 Issue 提出 C#（#9）、JavaScript（#10）SDK 需求
  5. 企业认证：Issue #8 提出需要 Vertex AI / Gemini Enterprise 认证支持
  6. 仓库元数据不足：仓库描述和 topics 为空

对 Agent 基础设施的启示

Antigravity SDK 在设计上有几个值得 Agent 基础设施开发者借鉴的点：

  1. Priority-bucket 策略模型：比简单的 allow/deny 列表更精细，特定规则自动覆盖通配规则
  2. 工具可见性 vs 工具拒绝的分离：disabled_tools（省 token）+ policy.deny()（模型理解拒绝原因）——两种场景各有用处
  3. Streaming cursor 模式：多消费者并发安全读取同一流——UI 渲染、工具拦截、日志记录可以共享底层流
  4. Fail-Closed 安全默认：写工具 + 无策略 → 直接报错，不允许静默运行——将安全前置而非后置
  5. Pydantic 类型边界：公开 API 类型与实现细节的清晰边界——类型安全且可序列化

总结

Google Antigravity SDK 是 Google 在 Agent Infrastructure 领域的正式入局之作。尽管只有 v0.1.0，但其设计成熟度远超典型 Alpha 项目——三层架构、6 级策略引擎、原生 MCP 支持、编译型 Runtime——这些选择都显示出深厚的工程积累。

对于 Agent 基础设施开发者来说，这是一个必读项目。其策略引擎设计和 fail-closed 安全哲学尤其值得学习。而对于 Agent 使用者，它提供了可能是目前最简洁的 Python Agent 开发体验：

import asyncio
from google.antigravity import Agent, LocalAgentConfig

async def main():
    config = LocalAgentConfig(
        system_instructions="You are a helpful assistant.",
    )
    async with Agent(config) as agent:
        response = await agent.chat("What files are in this directory?")
        print(await response.text())

asyncio.run(main())

项目地址：https://github.com/google-antigravity/antigravity-sdk-python

PyPI：pip install google-antigravity

许可证：Apache 2.0（OSI 批准）