Google Antigravity SDK 是一个用于构建 AI 代理的 Python SDK，基于 Antigravity 和 Gemini 技术。它提供了安全、可扩展、有状态的基础设施层，抽象了代理循环，让开发者专注于代理的行为而非运行机制。本文档涵盖了安装、快速入门、核心概念（如 Agent 类、流式响应、交互式循环）以及高级用法（如 Conversation 和连接策略）。
核心要点
- SDK 通过
pip install google-antigravity安装，依赖平台特定的二进制文件，必须从 PyPI 安装。 Agent类是最简单的入门方式，管理完整生命周期，支持异步上下文管理器。- 流式响应通过
async for循环实时获取文本令牌，支持零网络开销。 - 高级用法包括流式推理/思考（
response.thoughts）和工具调用事件（response.tool_calls）。 - 默认只读模式，通过
CapabilitiesConfig()启用所有工具（包括写入操作）。
正文
Google Antigravity SDK 是一个用于构建 AI 代理的 Python SDK，基于 Antigravity 和 Gemini 技术。它提供了安全、可扩展、有状态的基础设施层，抽象了代理循环，让开发者专注于代理的行为而非运行机制。
安装
使用 pip 安装：
pip install google-antigravity
重要提示：SDK 依赖一个编译好的运行时二进制文件，该文件包含在发布到 PyPI 的平台特定 wheel 中。仅克隆此仓库不足以运行 SDK。请始终通过
pip install google-antigravity从 PyPI 安装以获取二进制文件。
快速入门
运行 examples/ 目录下的示例，例如 hello_world：
export GEMINI_API_KEY="your_api_key_here"
python ./examples/getting_started/hello_world.py
核心概念
简单代理（Agent）
Agent 类是最简单的入门方式。它通过一个异步上下文管理器管理完整生命周期——包括二进制发现、工具连接、钩子注册和策略默认值。system_instructions 参数是可选的。
import asyncio
from google.antigravity import Agent, LocalAgentConfig
async def main():
config = LocalAgentConfig(
system_instructions="You are an expert assistant for codebase navigation.",
# api_key="your_api_key_here",
)
async with Agent(config) as agent:
response = await agent.chat("What files are in the current directory?")
print(await response.text())
async def run():
await main()
if __name__ == "__main__":
asyncio.run(run())
流式响应
要实时流式传输代理输出（例如用于流畅的 UI 或控制台应用），只需使用 async for 循环迭代 ChatResponse 对象。流式包装器会原生地生成对话文本令牌，零网络开销：
import asyncio
import sys
from google.antigravity import Agent, LocalAgentConfig
async def main():
config = LocalAgentConfig()
async with Agent(config) as agent:
# 立即返回，不阻塞
response = await agent.chat("Write a short poem about space.")
async for token in response:
sys.stdout.write(token)
sys.stdout.flush()
print()
asyncio.run(main())
高级：思考与工具调用流
对于更复杂的用例，可以使用专用的异步流属性实时流式传输内部模型推理/思考或拦截工具调用分发：
# 1. 流式传输推理/思考增量
async for thought in response.thoughts:
show_thinking_bubble(thought)
# 2. 流式传输强类型的 ToolCall 事件
async for call in response.tool_calls:
show_executing_spinner(call.name)
默认情况下，Agent 以只读模式运行以确保安全。传递 capabilities=CapabilitiesConfig() 以启用所有工具（包括写入操作）。
交互式循环
from google.antigravity import Agent, LocalAgentConfig, CapabilitiesConfig
from google.antigravity.utils.interactive import run_interactive_loop
config = LocalAgentConfig(
# api_key="your_api_key_here",
capabilities=CapabilitiesConfig(),
)
async with Agent(config) as agent:
await run_interactive_loop(agent)
高级用法：Conversation
要完全控制连接生命周期，可以直接使用 Conversation 和 ConnectionStrategy。Conversation 是一个有状态的会话，会累积步骤历史，提供 chat() 便捷方法，并暴露状态内省：
import asyncio
from google.antigravity.connections.local import LocalConnectionStrategy
from google.antigravity.conversation.conversation import Conversation
from google.antigravity.tools.tool_runner import ToolRunner
from google.antigravity.types import GeminiConfig
async def main():
tool_runner = ToolRunner()
strategy = LocalConnectionStrategy(
tool_runner=tool_runner,
# gemini_config=GeminiConfig(api_key="your_api_key_here"),
)
async with Conversation.create(strategy) as conversation:
# 高级：一次调用发送并收集
response = await conversation.chat("What files are here?")
print(await response.text())
# 步骤历史自动累积
print(f"Total steps: {len(conversation.history)}")
print(f"Turns: {conversation.turn_count}")
print(f"Last response: {conversation.last_response}")
# 低级：流式步骤
await conversation.send("Tell me more.")
async for step in conversation.receive_steps():
if step.is_complete_response:
print(step.content)
asyncio.run(main())
特性
多模态输入
支持传递丰富的多媒体文件附件（图像、视频、音频和文档...）。
关联概念
- AI Agent
- Gemini
- Antigravity
- Python SDK
- 流式响应
可操作项
- 安装 SDK：运行
pip install google-antigravity。 - 设置 API 密钥：导出环境变量
GEMINI_API_KEY。 - 运行示例：执行
python ./examples/getting_started/hello_world.py。 - 尝试流式响应：修改示例代码，使用
async for循环实时输出。 - 启用所有工具：在
LocalAgentConfig中设置capabilities=CapabilitiesConfig()。
原文: google-antigravity/antigravity-sdk-python
自动加工于 2026-05-21 08:05