---
url: /antigravity/sdk-overview.md
description: 了解 Google Antigravity SDK，一个用于构建、测试和运行自主 AI Agent 的声明式 Python 编程框架。
---

# Google Antigravity SDK

Google Antigravity SDK 是一个用于构建、测试和运行自主 AI Agent 的声明式 Python 编程框架。它扩展了支持 Antigravity CLI 和 Antigravity 2.0 的相同核心 Agent 引擎体系，允许您将高级的 Agent 能力直接集成到您自己的应用程序和工作流中。

SDK 将您 Agent 的逻辑与其运行位置解耦，使您能够专注于 Agent 的行为；而 SDK 会处理它如何以及在何处执行。

## 快速入门 (Quick Start)

使用 `pip` 安装 SDK：

```bash
pip install google-antigravity
```

### Hello World 示例

一个在 15 行 Python 代码内与您的本地环境进行交互的可用 Agent：

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

## 核心支柱 (Core Pillars)

### 1. 受控的可扩展性 (工具)

每个 Agent 都始于一个内置的工具集（文件 I/O、代码编辑、Shell 执行、目录搜索），并可以在统一的执行管道下使用四种类型的工具进行扩展：

* **内置工具 (Built-in Tools)**：核心文件和系统操作能力。
* **自定义 Python 函数 (Custom Python Functions)**：将任何 Python 可调用对象注册为 Agent 工具。
* **MCP 服务端 (MCP Servers)**：连接任何模型上下文协议 (MCP) 服务端（stdio、SSE 或 HTTP）。
* **Agent 技能包 (Agent Skills)**：加载指令和工具的复用包。

### 2. 声明式安全策略

使用声明式的“默认拒绝”策略系统配置 Agent 权限，以控制工具在何时以及如何被执行：

```python
from google.antigravity.hooks.policy import deny, allow, ask_user

policies = [
    deny("*"),                                         # 默认阻止所有工具
    allow("view_file"),                                # 允许静默读取文件
    ask_user("run_command", handler=my_handler),       # 执行 Shell 命令需要人工审批
]
```

### 3. 生命周期钩子 (Lifecycle Hooks)

通过在 9 个具体的生命周期阶段（例如会话启动、轮次前/后、工具调用前/后）使用三类钩子，实现对 Agent 执行的细粒度控制：

* **检查 (Inspect - 只读、非阻塞)**：用于日志记录、审计追踪和指标收集。
* **决策 (Decide - 只读、阻塞)**：用于自定义批准/拒绝逻辑（策略）。
* **转换 (Transform - 修改、阻塞)**：用于清洗传输中的数据或从工具错误中恢复。

## 核心能力 (Key Capabilities)

* **流式输出 (Streaming)**：访问实时模型推理并在生成时输出 Chunk。
* **多模态输入 (Multimodal Input)**：使用 `from_file()` 原生传入图像、PDF、音频和视频。
* **子 Agent (Sub-agents)**：生成具有独立工具和上下文的子 Agent，以构建多 Agent 团队。
* **结构化输出 (Structured Output)**：使用 Pydantic 模型定义 Schema 以直接返回经过验证的类型化数据。
* **人机共协 (Human-in-the-Loop)**：暂停执行以提出结构化问题，并基于用户输入进行分支。
* **可观测性 (Observability)**：跟踪每轮及累积的 Token 使用情况，并访问思考轨迹。

若要在 Antigravity 2.0 中更轻松地使用 SDK，请使用 Antigravity SDK 技能包。要了解关于 Antigravity SDK 的更多信息并查看更多如何使用它的示例，请访问 GitHub 仓库。