# Start Here

> What this repo is, the fastest read order, the entry points to open first, and the vocabulary (Agent, Conversation, Hook, Trigger) a new reader needs.

- Repository: google-antigravity/antigravity-sdk-python
- GitHub: https://github.com/google-antigravity/antigravity-sdk-python
- Human wiki: https://grok-wiki.com/public/wiki/google-antigravity-antigravity-sdk-python-2abd361a7867
- Complete Markdown: https://grok-wiki.com/public/wiki/google-antigravity-antigravity-sdk-python-2abd361a7867/llms-full.txt

## Source Files

- `README.md`
- `pyproject.toml`
- `google/antigravity/agent.py`
- `google/antigravity/types.py`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [README.md](README.md)
- [pyproject.toml](pyproject.toml)
- [google/antigravity/agent.py](google/antigravity/agent.py)
- [google/antigravity/types.py](google/antigravity/types.py)
- [google/antigravity/conversation/conversation.py](google/antigravity/conversation/conversation.py)
- [google/antigravity/hooks/hooks.py](google/antigravity/hooks/hooks.py)
- [google/antigravity/triggers/triggers.py](google/antigravity/triggers/triggers.py)
</details>

# Start Here

Welcome to the Google Antigravity SDK. This Python SDK provides a secure, scalable, and stateful infrastructure layer for building AI agents powered by Antigravity and Gemini. By abstracting the complex "agentic loop," the SDK allows developers to focus on defining agent behavior rather than managing the underlying execution runtime or transport logic.

This page provides an orientation for new readers, defining the core vocabulary, outlining the architectural layers, and recommending a sequence for exploring the codebase. Whether you are building a simple chatbot or a complex autonomous system, understanding these primitives is essential for effective development.

## Core Vocabulary

The Antigravity SDK uses a specific set of terms to describe its components and their interactions. Familiarizing yourself with these concepts is the first step toward mastering the SDK.

### Agent
The **Agent** is the primary, high-level entry point for most applications (Layer 1). It provides a "batteries-included" interface that manages the full lifecycle of an agent session—including binary discovery, tool wiring, hook registration, and policy enforcement—behind a single asynchronous context manager.
Sources: [google/antigravity/agent.py:36-39](), [README.md:32-36]()

### Conversation
A **Conversation** represents a stateful session (Layer 2). While the `Agent` handles higher-level orchestration, the `Conversation` specifically manages the accumulation of step history, tracks turn indices, and provides convenience methods for sending prompts and receiving streaming responses.
Sources: [google/antigravity/conversation/conversation.py:59-64](), [google/antigravity/types.py:763-765]()

### Hook
**Hooks** are interceptors that allow you to inject logic into the agent's lifecycle. They are categorized into three types: `InspectHook` (observability), `DecideHook` (policies/blocking), and `TransformHook` (data modification). Common hook points include turn start/end, tool call dispatch, and context compaction events.
Sources: [google/antigravity/hooks/hooks.py:65-115]()

### Trigger
A **Trigger** is a long-lived asynchronous function that runs alongside an agent session. Triggers react to external events—such as timers, filesystem changes, or webhooks—and push messages into the agent's context, allowing the agent to react to its environment proactively.
Sources: [google/antigravity/triggers/triggers.py:21-26](), [README.md:243-246]()

## Entry Points

The SDK is organized into a three-layer architecture to support varying levels of complexity and control.

| Layer | Purpose | Primary Class |
| :--- | :--- | :--- |
| **Layer 1: Simplified** | High-level, batteries-included orchestration. | `Agent` |
| **Layer 2: Session** | Stateful history management and streaming controls. | `Conversation` |
| **Layer 3: Adapter** | Low-level transport and backend abstraction. | `Connection` |

Sources: [README.md:265-272]()

### For Most Users: `google.antigravity.Agent`
Most developers should start with the `Agent` class. It simplifies configuration by using a `LocalAgentConfig` and handles the setup of underlying connections and runners automatically.

```python
from google.antigravity import Agent, LocalAgentConfig

async with Agent(LocalAgentConfig()) as agent:
    response = await agent.chat("Hello!")
    print(await response.text())
```
Sources: [google/antigravity/agent.py:195-204](), [README.md:44-51]()

### For Power Users: `google.antigravity.conversation.Conversation`
If you need direct control over the `ConnectionStrategy` or want to manage session state manually without the `Agent` abstraction, use `Conversation` directly.
Sources: [google/antigravity/conversation/conversation.py:89-93]()

## Architecture Overview

The following diagram illustrates how these components interact within an active session. The `Agent` orchestrates the `Conversation`, while `Hooks` and `Triggers` provide the extensibility points for custom logic and environmental reactivity.

```mermaid
graph TD
    User([User Application]) -->|Layer 1| Agent[Agent Class]
    Agent -->|Layer 2| Conv[Conversation Session]
    Conv -->|Layer 3| Strategy[Connection Strategy]
    
    subgraph Extensibility
        Agent -.->|Registers| Hook[Hooks / Policies]
        Agent -.->|Starts| Trigger[Triggers]
    end
    
    Trigger -->|Push Notifications| Strategy
    Strategy -->|Intercept Events| Hook
    Strategy -->|Transport| Runtime((Local Harness Binary))
```

## Recommended Read Order

To quickly understand the SDK's implementation, follow this reading path:

1.  **[README.md](README.md)**: Orientation and quickstart examples.
2.  **[google/antigravity/agent.py](google/antigravity/agent.py)**: The main entry point for the "Layer 1" API.
3.  **[google/antigravity/types.py](google/antigravity/types.py)**: The canonical Pydantic models used across all boundaries.
4.  **[examples/](examples/)**: Practical implementation patterns for personas, tools, and triggers.

The Google Antigravity SDK is designed to be provider-neutral and portable, utilizing the Model Context Protocol (MCP) and a flexible hook system to integrate with diverse environments and tools.
Sources: [pyproject.toml:19-24](), [README.md:204-207]()