结论先说
- 安装必须走标准
pip install google-antigravity:官方 PyPI 发布的平台专属安装包(wheel)里打包了底层编译好的运行时二进制程序,不要只拉纯源码目录硬跑。 LocalAgentConfig默认锁死在安全只读模式:不传额外参数时,拉起的智能体只能查代码、不能动硬盘上的任何文件;只有显式传入capabilities=CapabilitiesConfig()才会解锁edit_file和run_command。- 全程采用
asyncio异步上下文管理器:用async with Agent(config) as agent:自动接管底层进程启停与资源回收,await agent.chat(...)会立即返回非阻塞流对象。 - 除了正文 Token,还能分流读取思考链和工具事件:遍历
response.thoughts与response.tool_calls即可在后台监控智能体每一步干了什么。 - 账号配套与跨平台编程订阅入口:运行
agy命令行、SDK 与多子代理并发依赖正常可用的谷歌账号与充裕模型配额,账号准备见本站 谷歌账号说明页,免境外卡开通终端编程会员见 Claude Code 订阅页 与 AI 会员充值总览。

图:本站根据 Antigravity Python SDK 官方仓库 整理的示意图
本文根据 Google Antigravity 官方 Python SDK 文档(github.com/google-antigravity/antigravity-sdk-python)整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 Google 官方网站。
适用于谁
- 想把 Antigravity 的代码检索、修 Bug 或写单测能力集成进自家 Python 脚本与 CI 质检管线的后端工程师;
- 不满足于在图形界面手动点对话框,想用代码批量调度智能体并实时采集工具调用日志的人;
- 刚装好
google-antigravity跑示例时发现智能体只能读文件不能改文件,卡在默认权限开关上的人。
一、安装要求与最小可运行异步示例
打开终端激活你的 Python 虚拟环境,执行官方安装命令:
bash
pip install google-antigravity
确保本机已完成谷歌开发者账号认证后(账号登录与地区条件排查见 Google Antigravity 登录排错指南),新建 demo_agent.py 即可跑通完整的异步流式对话:
python
import asyncio
import sys
from google.antigravity import Agent, LocalAgentConfig, CapabilitiesConfig
async def main():
# 默认不传 capabilities 时为安全只读模式;传入 CapabilitiesConfig() 开启改文件与跑命令能力
config = LocalAgentConfig(
system_instructions="你是负责代码库巡检与单元测试补全的资深 Python 助手,请用中文简明输出结论。",
capabilities=CapabilitiesConfig(),
)
async with Agent(config) as agent:
response = await agent.chat("扫描当前目录下的 Python 文件,列出缺少异常处理的函数名。")
async for token in response:
sys.stdout.write(token)
sys.stdout.flush()
print()
if __name__ == "__main__":
asyncio.run(main())
上面这段代码背后的设计非常省心:Agent 上下文管理器会自动完成运行时二进制发现、工具接线、钩子注册以及退出时的子进程清理,不需要你自己写繁琐的进程守护代码。需要准备独立开发测试用的个人谷歌账号时,可先浏览本站 谷歌账号购买说明 或前往自动发卡的 谷歌邮箱成品号商品页(质保政策以商品页为准)。
二、只读安全模式、思考流监控与权限拦截对比

图:本站根据 Antigravity Python SDK 文档 整理的对比示意图
在把智能体放进自动化流水线时,按任务性质精确控制读写边界与可观测性至关重要:
| 应用场景 | 核心代码配置写法 | 行为边界说明 |
|---|---|---|
| 自动化 PR 代码只读审查 | LocalAgentConfig(system_instructions="...")(省略 capabilities) | 百分百只读,哪怕提示词被恶意注释干扰也无法篡改仓库文件或跑危险 Shell |
| 自动生成补丁与跑单测 | LocalAgentConfig(capabilities=CapabilitiesConfig()) | 允许调用写文件与终端命令工具,建议配合沙箱与策略包装器限制高危命令 |
| 审计后台推理与工具轨迹 | 异步遍历 response.thoughts 与 response.tool_calls | 强类型捕获每次 call.name 与 call.args,方便写入企业内部审计日志 |
| 快速拉起终端交互循环 | 调用 google.antigravity.utils.interactive 下的 run_interactive_loop(agent) | 十行代码把配好自定义系统指令的专属智能体变成交互式命令行助手 |
下面演示如何在同一个脚本里同时捕获智能体的内部思考增量(Thoughts)与每一次工具调用参数:
python
async with Agent(config) as agent:
response = await agent.chat("检查 tests/ 目录下的失败用例并定位根因。")
async for thought in response.thoughts:
print(f"[思考过程] {thought}")
async for call in response.tool_calls:
print(f"[调用工具] {call.name} 参数: {call.args}")
async for token in response:
sys.stdout.write(token)
三、SDK 调用与生命周期钩子、配额的关系
- 声明式权限与 Hooks 双保险:SDK 提供了编程式的策略包装器(如
allow、deny、ask_user)用于在 Python 代码里直接拦截特定函数或run_command调用;同时工作区下的.agents/hooks.json钩子依然能协同生效,底层权限逻辑可对照 Antigravity 终端沙箱与权限策略 与 Antigravity Hooks 生命周期配置。 - 注意批量脚本循环耗尽账号配额:用
for循环一次性并发拉起十几个Agent实例跑大仓库,会迅速吃光当前账号的周期模型限额。建议在脚本里做好串行限流,并按任务复杂度合理选模型,详见 Antigravity 额度限制与模型选择。
常见问题
问:在 Linux 容器里从源码拷目录跑报找不到底层二进制怎么办?
答:官方明确提醒 SDK 依赖随各操作系统架构打包进 PyPI wheel 的编译二进制文件。在 Dockerfile 构建镜像时请直接执行 pip install google-antigravity,让 pip 自动匹配对应架构(如 manylinux、macosx_arm64)的二进制包。
问:SDK 拉起的智能体能自动读取仓库里的 AGENTS.md 和 .agents/skills/ 吗?
答:只要在目标仓库工作目录下启动,底座同样遵循工作区定制发现机制,能复用你写好的项目规则与技能手册。
问:只想在终端手动敲命令对话,有必要自己写 Python 脚本包一层吗?
答:没必要。纯手工交互直接装官方 agy 命令行更轻量,斜杠指令更全,见 Antigravity agy 命令行进阶指南;只有需要把智能体嵌进你自己的 Python 业务逻辑或自动化测试框架时才用 SDK。
问:跑多子代理和终端工具时没有合规谷歌账号或海外信用卡怎么办?
答:可在 本站充值中心 通过支付宝、微信支付或 AlipayHK 即买即发获取 谷歌邮箱成品号,或免上号自助兑换 Claude Pro 自助卡密 与 Claude Max 充值,实时价格与售后边界(封号不在质保范围)以对应商品页为准。
0 条评论
还没有评论,来抢沙发~