# Rapid Setup & First Run

> Installation nuances (PyPI wheels vs source clones), environment variables, and the hello_world.py entry point for immediate verification.

- 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`
- `examples/getting_started/hello_world.py`
- `examples/README.md`
- `CONTRIBUTING.md`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [README.md](README.md)
- [examples/getting_started/hello_world.py](examples/getting_started/hello_world.py)
- [examples/README.md](examples/README.md)
- [google/antigravity/connections/local/local_connection.py](google/antigravity/connections/local/local_connection.py)
- [google/antigravity/connections/local/local_connection_config.py](google/antigravity/connections/local/local_connection_config.py)
- [pyproject.toml](pyproject.toml)
- [google/antigravity/types.py](google/antigravity/types.py)
</details>

# Rapid Setup & First Run

Getting started with the Google Antigravity SDK is designed to be a streamlined experience, moving from installation to a functional agentic turn in minutes. This page covers the critical nuances of the SDK's platform-specific distribution, required environment configuration, and the standard verification path using the built-in examples.

The SDK is not just a collection of Python modules; it is an orchestration layer that interfaces with a specialized Go-based runtime binary called the `localharness`. Understanding how this binary is discovered and how to properly authenticate with the Gemini API is essential for a successful first run.

## Installation Nuances

The Google Antigravity SDK requires a compiled runtime binary to function. This binary handles the heavy lifting of tool execution, state management, and communication with the Gemini backend.

### PyPI Wheels vs. Source Clones

There is a critical distinction between installing via `pip` and cloning the repository:

*   **PyPI Installation (Recommended):** When you run `pip install google-antigravity`, you receive a platform-specific wheel that includes the pre-compiled `localharness` binary. This is the only supported way for most users to obtain the SDK.
*   **Source Clones:** Cloning the repository from GitHub provides the Python source code but **does not include the binary**. The SDK will fail to initialize if it cannot find the `localharness` executable.

Sources: [README.md:15-19](README.md#L15-L19), [pyproject.toml:60-64](pyproject.toml#L60-L64)

### Binary Discovery Logic

The SDK attempts to locate the `localharness` binary using the following priority:
1.  **Environment Variable:** The value of `ANTIGRAVITY_HARNESS_PATH` if set.
2.  **Metadata Discovery:** Searching the installed `google-antigravity` package metadata for the path `google/antigravity/bin/localharness`.
3.  **Resource Discovery:** Falling back to `importlib.resources`.

Sources: [google/antigravity/connections/local/local_connection.py:1307-1330](google/antigravity/connections/local/local_connection.py#L1307-L1330)

## Environment Configuration

The SDK relies on a few key environment variables for authentication and advanced configuration.

| Variable | Description | Required |
| :--- | :--- | :--- |
| `GEMINI_API_KEY` | Your Google Gemini API key used for model inference. | **Yes** |
| `ANTIGRAVITY_HARNESS_PATH` | Explicit path to the `localharness` binary (primarily for development). | No |

Alternatively, the API key can be passed explicitly in the configuration:
```python
config = LocalAgentConfig(api_key="your_api_key_here")
```

Sources: [examples/README.md:10](examples/README.md#L10), [google/antigravity/connections/local/local_connection_config.py:62](google/antigravity/connections/local/local_connection_config.py#L62)

## First Run Verification

Once installed, the `hello_world.py` example is the gold standard for verifying your environment is correctly configured.

### Running Hello World

Navigate to the `examples/getting_started/` directory and execute the script:

```bash
export GEMINI_API_KEY="your_api_key_here"
python hello_world.py
```

### What Happens Internally

When you initialize an `Agent`, the SDK starts the `localharness` binary as a subprocess and establishes a WebSocket connection for real-time communication.

```mermaid
sequenceDiagram
    participant App as Python Application
    participant SDK as Antigravity SDK
    participant Bin as localharness (Binary)
    participant API as Gemini API

    App->>SDK: Agent(config)
    SDK->>Bin: Start Process (subprocess.Popen)
    Bin->>SDK: Port & API Key (stdout)
    SDK->>Bin: Connect (WebSocket)
    App->>SDK: agent.chat("Say 'Hello World!'")
    SDK->>Bin: Forward Prompt (WS)
    Bin->>API: Inference Request
    API-->>Bin: Tokens
    Bin-->>SDK: Tokens (WS)
    SDK-->>App: ChatResponse (Stream)
```

Sources: [examples/getting_started/hello_world.py:34-45](examples/getting_started/hello_world.py#L34-L45), [google/antigravity/connections/local/local_connection.py:1552-1575](google/antigravity/connections/local/local_connection.py#L1552-L1575)

## Requirements & Dependencies

The SDK requires **Python 3.10 or higher**. Core dependencies include `pydantic`, `google-genai`, `mcp`, and `websockets`.

Sources: [pyproject.toml:23-34](pyproject.toml#L23-L34)

Summary: Successful setup of the Google Antigravity SDK depends on installing from PyPI to obtain the mandatory `localharness` binary and providing a valid `GEMINI_API_KEY`. Verification can be performed using the [hello_world.py](examples/getting_started/hello_world.py) script.
Sources: [README.md:15-19](README.md#L15-L19)