Google Antigravity SDK：用 Python 编排自主 Agent

今天，我们正式推出 Google Antigravity SDK 预览版——这是一个 Python 库，支持以编程方式调用 Google 顶尖的 Antigravity 编程 Agent。借助 Antigravity SDK，你可以构建、迭代复杂的 Agent 应用并快速制作原型。只需极少的代码即可基于 Antigravity Agent 运行时（Agent Runtime）构建，并利用先进的原语探索和验证新颖的 Agent 模式。GitHub 代码库

由 Antigravity 运行时驱动

该 SDK 为你提供了与 Antigravity 2.0 和 Antigravity CLI 完全相同的 Agent 运行时。你的 Agent 将直接继承一个强大的执行环境——丰富的内置工具集、声明式安全策略引擎、用于观测和引导每次工具调用的生命周期钩子，以及跨交互持久保存的有状态多轮会话。借助 Antigravity SDK，你可以用自己的业务逻辑扩展 Google 内部研究所使用的同一套运行框架。随着 Antigravity 运行时的不断改进——更快的工具执行、更聪明的规划、更出色的上下文管理——你的 SDK Agent 也会自动获得这些改进。

大多数开发者只需要使用 Agent——通过单个 async with 代码块即可在不到 20 行地道 Python 代码中管理完整的生命周期。以下是一个不到 15 行代码即可运行的完整 Agent：

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())

你的 Agent 逻辑与它的运行位置是解耦的：不久之后，你将能够把本地 Agent 循环无缝切换为远程托管的循环，同一个 Agent 无需重写任何代码即可部署到云端。你只需专注于 Agent 做什么，至于如何运行以及在哪里运行，全部交给 SDK 处理。

每个 Agent 在初始化时都直接配备了一套完整的内置工具集——文件 I/O、代码编辑、Shell 执行、目录搜索、图像生成以及子 Agent 委派——随时可用。在此基础上，你可以叠加系统指令来设定身份、添加特定领域的指导说明，或者完全替换默认设置。

专为 AI 原生开发而打造

该 SDK 采用对 Agent 友好的设计——无论是你用它构建的应用程序，还是你构建这些应用的方式都是如此。如果你使用 Antigravity，可以直接在开发会话中让 Agent 编写、测试和迭代你的 SDK 代码。API 接口采用了清晰的 Python 类型（Pydantic V2 模型、原生 Python 集合）、结构化输出以及明确的命名规范——所有这些设计选择都是为了让 AI Agent 能够像人类开发者一样流畅地阅读、编写和维护 SDK 代码。该 SDK 本身就是 Antigravity 自己的 API：帮你编写代码的 Agent 从内到外都深谙这套框架。

受治理的可扩展性

使用你自己的 Python 函数自定义 Agent，利用结构化输出 Schema 将其输出绑定到你的数据类型，并精准控制工具的调用时机与调用方式。

工具与集成

SDK 支持四种类型的工具集，它们共享同一条执行流水线、同一套流式传输基础设施以及同一组安全策略：

内置工具：文件 I/O、代码编辑、Shell 执行、目录搜索、图像生成、子 Agent 委派等。
自定义 Python 函数：将任意 Python 可调用对象注册为 Agent 可调用的工具。
MCP 服务器：连接任意模型上下文协议（Model Context Protocol）服务器（支持 stdio、SSE 或 Streamable HTTP），并将其工具暴露给 Agent。
Agent 技能：在 Agent 配置中使用 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
]

生命周期钩子（Lifecycle hooks）

除了策略之外，钩子（Hook）系统还为你提供了生命周期级别的控制能力。钩子分为三大类：

Inspect（检查）：只读、非阻塞。观测事件以用于日志记录、指标收集或审计追踪。
Decide（决策）：只读、阻塞。批准或拒绝操作（安全策略正是建立在此基础之上）。
Transform（转换）：可修改、阻塞。重塑传输中的数据，以用于数据脱敏或错误恢复。

SDK 提供了九个具体的钩子挂载点——从会话开始/结束，到每轮对话前/后（pre/post turn），再到工具调用前/后（pre/post tool call）、工具错误恢复、用户交互处理以及上下文压缩——每个挂载点都配有便捷的装饰器简写方式，方便快速接入：

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 为输入、输出和任务执行提供了灵活的选项：

流式传输（Streaming）：在获取输出的同时实时访问模型的推理过程。使用 async for chunk in response 循环遍历内容。
多模态输入（Multimodal input）：随文本提示词一起传入图像、PDF、音频和视频。支持使用 from_file() 从文件路径自动检测格式，或直接从原始字节构建。
子 Agent（Sub-agents）：派生具有独立工具、指令和上下文的子 Agent——这是构建 Agent 团队的核心基石。
思考级别（Thinking levels）：使用 GenerationConfig 按请求控制推理深度——支持 MINIMAL、LOW、MEDIUM 或 HIGH。
触发器（Triggers）：运行对外部事件做出反应的后台任务，并将消息推送到 Agent 中。

状态管理

你可以跨多轮对话管理会话状态与结构化响应：

会话持久化（Session persistence）：通过将 conversation_id 传回 Agent 配置，即可从已保存的会话 ID 恢复对话。
结构化输出（Structured output）：定义响应 Schema（支持 JSON Schema、字典或 Pydantic 模型），Agent 即可通过 response.structured_output() 返回经过验证的强类型数据。
人机协同：Agent 可在任务中途暂停，向用户提出带有预定义选项的结构化问题，并根据回答结果执行分支处理。

可观测性

内置的可观测性功能可帮助你监控模型行为和资源消耗：

Token 用量（Token usage）：通过 usage_metadata 即可获取单轮及累计的 Token 用量——包括提示词、候选输出、缓存读取以及思考 Token。
推理轨迹（Reasoning traces）：在获取输出的同时访问思考轨迹，以观察模型的实时推理过程。

得益于将 Gemini 3.5 Flash 设为默认模型，SDK Agent 能够直接获得驱动整个平台的高性能表现。钩子（Hooks）、子 Agent 和安全策略在 SDK、CLI 和 Antigravity 2.0 之间保持完全一致——区别仅在于这里是通过代码而非 UI 配置。

展望未来

我们正与那些将 Agent 推向我们未曾预见领域的开发者、研究人员和平台工程师共同打造这款产品。作为一项研究预览（Research Preview），该 SDK 是一个不断演进的平台，我们期待听到你的反馈，共同塑造它的未来。

以下是我们的路线图规划：

远程运行框架（Remote harness）：将 SDK Agent 部署到 Google Cloud——持久运行、可扩展，并可通过 Interactions API 访问。本地构建，远程部署。
TypeScript 与 Go：相同的运行时，支持更多编程语言。
Gemma 集成：我们正在开发对 Gemma 的支持——将完整的 Agent 运行时带给你可自行运行和微调的开源模型。
插件（Plugins）：由指令、工具和上下文组成的可复用软件包，你可以通过编程方式将其组合到 Agent 中，或从社区加载。
更深入的可观测性：后台步骤追踪、触发器执行日志以及更丰富的遥测数据，助力大规模调试和优化 Agent 行为。

开始使用

该 SDK 采用 Apache 2.0 开源许可。它附带了两个层级的示例：用于单功能演示的 getting_started/，以及展示更复杂设计模式的 deep_dives/。完整的 API 文档现已开放：

pip install google-antigravity

由 Antigravity 运行时驱动

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())

专为 AI 原生开发而打造

受治理的可扩展性

使用你自己的 Python 函数自定义 Agent，利用结构化输出 Schema 将其输出绑定到你的数据类型，并精准控制工具的调用时机与调用方式。

工具与集成

SDK 支持四种类型的工具集，它们共享同一条执行流水线、同一套流式传输基础设施以及同一组安全策略：

内置工具：文件 I/O、代码编辑、Shell 执行、目录搜索、图像生成、子 Agent 委派等。
自定义 Python 函数：将任意 Python 可调用对象注册为 Agent 可调用的工具。
MCP 服务器：连接任意模型上下文协议（Model Context Protocol）服务器（支持 stdio、SSE 或 Streamable HTTP），并将其工具暴露给 Agent。
Agent 技能：在 Agent 配置中使用 skills_paths 提供可复用技能包（包含指令、工具和上下文）的路径。

只需定义一次策略或钩子，它就能管控每一个工具——无论该工具来自何处。

安全策略

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
]

生命周期钩子（Lifecycle hooks）

除了策略之外，钩子（Hook）系统还为你提供了生命周期级别的控制能力。钩子分为三大类：

Inspect（检查）：只读、非阻塞。观测事件以用于日志记录、指标收集或审计追踪。
Decide（决策）：只读、阻塞。批准或拒绝操作（安全策略正是建立在此基础之上）。
Transform（转换）：可修改、阻塞。重塑传输中的数据，以用于数据脱敏或错误恢复。

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 为输入、输出和任务执行提供了灵活的选项：

流式传输（Streaming）：在获取输出的同时实时访问模型的推理过程。使用 async for chunk in response 循环遍历内容。
多模态输入（Multimodal input）：随文本提示词一起传入图像、PDF、音频和视频。支持使用 from_file() 从文件路径自动检测格式，或直接从原始字节构建。
子 Agent（Sub-agents）：派生具有独立工具、指令和上下文的子 Agent——这是构建 Agent 团队的核心基石。
思考级别（Thinking levels）：使用 GenerationConfig 按请求控制推理深度——支持 MINIMAL、LOW、MEDIUM 或 HIGH。
触发器（Triggers）：运行对外部事件做出反应的后台任务，并将消息推送到 Agent 中。

状态管理

你可以跨多轮对话管理会话状态与结构化响应：

会话持久化（Session persistence）：通过将 conversation_id 传回 Agent 配置，即可从已保存的会话 ID 恢复对话。
结构化输出（Structured output）：定义响应 Schema（支持 JSON Schema、字典或 Pydantic 模型），Agent 即可通过 response.structured_output() 返回经过验证的强类型数据。
人机协同：Agent 可在任务中途暂停，向用户提出带有预定义选项的结构化问题，并根据回答结果执行分支处理。

可观测性

内置的可观测性功能可帮助你监控模型行为和资源消耗：

Token 用量（Token usage）：通过 usage_metadata 即可获取单轮及累计的 Token 用量——包括提示词、候选输出、缓存读取以及思考 Token。
推理轨迹（Reasoning traces）：在获取输出的同时访问思考轨迹，以观察模型的实时推理过程。

展望未来

以下是我们的路线图规划：

远程运行框架（Remote harness）：将 SDK Agent 部署到 Google Cloud——持久运行、可扩展，并可通过 Interactions API 访问。本地构建，远程部署。
TypeScript 与 Go：相同的运行时，支持更多编程语言。
Gemma 集成：我们正在开发对 Gemma 的支持——将完整的 Agent 运行时带给你可自行运行和微调的开源模型。
插件（Plugins）：由指令、工具和上下文组成的可复用软件包，你可以通过编程方式将其组合到 Agent 中，或从社区加载。
更深入的可观测性：后台步骤追踪、触发器执行日志以及更丰富的遥测数据，助力大规模调试和优化 Agent 行为。

开始使用

pip install google-antigravity

Google Antigravity SDK：用 Python 编排自主 Agent

AI 总结

由 Antigravity 运行时驱动

专为 AI 原生开发而打造

受治理的可扩展性

工具与集成

安全策略

生命周期钩子（Lifecycle hooks）

核心能力

I/O 与执行

状态管理

可观测性

展望未来

开始使用

同来源文章

Google Antigravity SDK：用 Python 编排自主 Agent

AI 总结

由 Antigravity 运行时驱动

专为 AI 原生开发而打造

受治理的可扩展性

工具与集成

安全策略

生命周期钩子（Lifecycle hooks）

核心能力

I/O 与执行

状态管理

可观测性

展望未来

开始使用

同来源文章