google-antigravity/antigravity-sdk-python

Google Antigravity SDK (Python)

是什么 – 一个 Python 库，可让你使用 Google 的 Gemini 模型（或本地 Gemma-4 模型）构建“代理型” AI 应用程序。SDK 隐藏了代理循环的底层实现（网络通信、工具执行、状态管理），让你可以专注于希望代理执行的任务。

安装

pip install google-antigravity   # 拉取平台特定的二进制 wheel 包

必须使用二进制运行时；仅克隆仓库无法运行。

快速开始

import asyncio
from google.antigravity import Agent, LocalAgentConfig

async def main():
    cfg = LocalAgentConfig(system_instructions="You are a helpful assistant.")
    async with Agent(cfg) as agent:
        resp = await agent.chat("List the files in the current directory.")
        print(await resp.text())

asyncio.run(main())

设置 GEMINI_API_KEY（或 Vertex AI 凭据）后，运行 examples/ 中的示例脚本。

核心概念

概念	作用
Agent	高级入口点；管理二进制发现、工具连接、策略和流式响应。
Conversation	有状态会话，保持步骤历史记录；当你需要对发送/接收进行细粒度控制时非常有用。
LocalAgentConfig / LiteRTAgentConfig	用于云（Gemini/Vertex）或离线（通过 LiteRT-LM 的 Gemma-4）模型的配置对象。
Tools	注册普通 Python 函数，代理可在聊天过程中调用。
Hooks & Policies	声明式规则（allow, deny, ask_user, enforce），控制哪些工具可以运行及在何种条件下运行。
Triggers	可向代理推送消息的后台异步任务（例如，定期状态检查）。
MCP 集成	连接到外部 Model Context Protocol 服务器，以暴露额外工具。

主要特性

• 统一的云与本地执行 – 通过 Vertex AI（API 密钥或 ADC）使用 Gemini，或通过 LiteRT-LM 离线运行 Gemma-4 26B 模型。
• 流式输出 – 迭代 ChatResponse（或其 thoughts / tool_calls）以获得逐 token 更新，且无需额外网络开销。
• 多模态输入 – 通过内容类（Image, from_file）直接附加图像、PDF、视频等。
• 自定义工具注册 – 将任意 Python 可调用对象转换为代理可调用的工具。
• 策略引擎 – 细粒度安全控制（阻止所有工具、仅允许特定工具、在危险操作前询问用户）。
• 后台触发器 – 可定期或事件驱动地向代理发送消息的后台任务。
• 三层架构 – 简单的 Agent API、会话级 Conversation 层，以及与传输无关的适配器层。

典型工作流程

1. 安装该包（如计划本地运行，还需安装 litert-lm）。
2. 选择配置：
   • 云：LocalAgentConfig(vertex=True, api_key=…) 或依赖 ADC。
   • 本地：LiteRTAgentConfig(model_path=…)。
3. 可选地注册工具、策略或触发器。
4. 在 async with 块内创建 Agent（或 Conversation）。
5. 调用 agent.chat(prompt) – 提示可以是字符串，或混合文本与内容对象的列表。
6. 通过 await resp.text() 消费响应，或使用 async for token in resp 流式获取令牌。

架构快照

层级	职责	核心类
简化	多数用例的一行入口点	Agent
会话	维护历史记录，提供 chat()，暴露流式对象	Conversation, ChatResponse, Step, ToolCall, AgentConfig, HookRunner, ToolRunner, TriggerRunner
适配器	抽象传输（云、本地二进制、MCP）	Connection, ConnectionStrategy, LocalConnection

许可证 – Apache License 2.0。

---

以上所有细节均直接取自仓库的 README。