# Google Antigravity SDK for Python: What the Agent Loop Actually Hides

> A Python library that wraps the agentic loop behind an async context manager, at the cost of a compiled runtime binary you cannot get from the repository. Here is what it does, how to install it, and where it stops being the right tool.

**google-antigravity/antigravity-sdk-python** — A Python library for building AI agents that leverage the full power of Google Antigravity.

- Repository: https://github.com/google-antigravity/antigravity-sdk-python
- Website: https://antigravity.google/product/antigravity-sdk
- Stars: 3,600 · Forks: 1,419
- Language: Python
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/google-antigravity-antigravity-sdk-python

## What the Antigravity SDK removes from your Python agent code

Building an agent in Python usually means assembling the same pieces yourself: a loop that calls the model, a dispatcher that executes tool calls and feeds results back, a session object that remembers prior turns, and some policy layer that decides which tools are even allowed to run. The Antigravity SDK packages those into a library so your code describes what the agent does rather than how the loop is driven.

The intended audience is a Python developer who already has a Gemini API key or a Google Cloud project and wants an agent that can read a filesystem, call tools, and stream tokens back. The README frames the SDK as an "infrastructure layer that abstracts the agentic loop." That framing is accurate about scope: this is not a prompt library and not a hosted service. It is a client-side runtime plus a session model, and it assumes you are writing asyncio code from the first line.

One distinction worth stating plainly, because the search data suggests people conflate them: the Antigravity IDE and the Antigravity SDK are separate products. The IDE is an editor; this repository is a pip-installable Python package whose homepage points at antigravity.google/product/antigravity-sdk. Nothing in the README describes the SDK as an editor plugin or as requiring the IDE.

## The agent loop, the connection strategy, and the compiled binary underneath

The architecture visible in the README has three layers. At the top, Agent is the convenience wrapper: it handles binary discovery, tool wiring, hook registration, and policy defaults behind a single async context manager. Below it sits Conversation, a stateful session that accumulates step history and exposes chat(), send(), receive_steps(), turn_count, and last_response. At the bottom is a ConnectionStrategy, with LocalConnectionStrategy as the concrete local implementation, which takes a ToolRunner.

That ToolRunner is where tools live, and it is also where the compiled runtime matters. The README carries an explicit warning: the SDK relies on a compiled runtime binary included in the platform-specific wheels on PyPI, and cloning the repository alone is not sufficient to run it. So the Python source you read on GitHub is not the whole program. The agentic loop, or some part of it, executes in a binary you receive only through pip. That is a deliberate distribution choice, and it has consequences for anyone who wants to audit, patch, or cross-compile the runtime.

Data flows in one direction through a stream. You call chat(), which returns a ChatResponse without blocking. Iterating over that response with async for yields conversational text tokens. Separately, response.thoughts yields reasoning deltas and response.tool_calls yields typed ToolCall events, so a UI can show a thinking indicator and a tool-execution spinner from the same response object. The dependency list backs this up: websockets, uvicorn, protobuf, pydantic, and mcp, which together suggest a local WebSocket or HTTP channel between the Python process and the runtime, with MCP as the tool protocol and pydantic validating the message shapes.

## Installing the Antigravity SDK and running a first agent

Installation is a single pip command, and the README is emphatic that this is the only supported path because the compiled binary arrives with the wheel. Do not clone the repository and expect to run the examples from source.

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

After that, the quickstart exports a Gemini API key and runs a bundled example. The README gives the hello_world example under examples/getting_started/.

```bash
export GEMINI_API_KEY="your_api_key_here"
python ./examples/getting_started/hello_world.py
```

For your own script, the smallest useful program constructs a LocalAgentConfig, opens an Agent as an async context manager, and calls chat(). The system_instructions parameter is optional, and the api_key field in the config is shown commented out in the README, which implies the GEMINI_API_KEY environment variable is picked up when the field is unset.

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

async def main():
    config = LocalAgentConfig(
        system_instructions="You are an expert assistant for codebase navigation.",
    )
    async with Agent(config) as agent:
        response = await agent.chat("What files are in the current directory?")
        print(await response.text())

asyncio.run(main())
```

The README also documents an interactive loop for console use. Note the capabilities argument here: without it, the agent stays read-only, so a question about listing files is fine but a request to modify one is not.

```python
from google.antigravity import LocalAgentConfig, CapabilitiesConfig
from google.antigravity.utils.interactive import run_interactive_loop

config = LocalAgentConfig(
    capabilities=CapabilitiesConfig(),
)
await run_interactive_loop(config)
```

If you are routing through Gemini Enterprise Agent Platform (the README notes this was formerly Vertex AI), there are two documented modes. Express mode needs only vertex=True plus an API key and skips Google Cloud projects, regional configuration, and Application Default Credentials entirely. Standard mode uses vertex=True with project and location, and authenticates through ADC by default, which means running gcloud auth application-default login first. The README states that explicit kwargs always take precedence over environment variables, and that either GOOGLE_GENAI_USE_VERTEXAI or GOOGLE_GENAI_USE_ENTERPRISE can enable Vertex from the environment.

## Read-only by default, and other limits the README states

The most consequential default is that Agent runs in read-only mode for safety. Writing requires passing capabilities=CapabilitiesConfig() explicitly. This is the right default for a tool that can touch your filesystem, but it also means the first thing many developers will hit is an agent that appears to refuse a perfectly reasonable instruction, with the cause buried in a constructor argument rather than in an error message the README describes.

Three other constraints are documented or directly visible. First, the package is classified Development Status :: 3 - Alpha and the version in pyproject.toml is 0.1.16, so the public API is not a stability commitment. Second, requires-python is >=3.10, which rules out 3.9 and older. Third, the dependency floor on protobuf is >=7.35, a version high enough that it can conflict with other packages in an existing environment; the same is true of mcp>=1.0,<3.0, which caps below a major version the SDK does not yet support.

The compiled runtime is the limitation that cannot be worked around. The README does not document how to build the binary from source, and it does not describe a source-only fallback. If your organisation requires reproducible builds from source, or if you need to run on a platform with no published wheel, this SDK is the wrong tool. The README does not document rollback or version pinning behaviour either, so treat the installed version as something you pin yourself in your own requirements file.

Finally, the whole design is async. There is no synchronous entry point in the README. If your application is a WSGI service or a synchronous script, you will be writing an event loop wrapper before you write any agent logic.

## Antigravity SDK versus wiring google-genai yourself

The obvious alternative is the google-genai package, which is already a dependency of this SDK. The difference is where the loop lives. With google-genai you own the conversation state, the tool dispatch, and the retry and streaming logic; you get a thinner client and full visibility into every message. With the Antigravity SDK, Conversation.create() plus a ConnectionStrategy gives you accumulated step history, turn counts, and a receive_steps() iterator without writing that machinery, but the execution happens in a binary you did not compile.

A second alternative, for teams that want tools to be portable across agent frameworks, is to write the tool layer against MCP directly rather than through ToolRunner. The SDK depends on mcp, so the protocol is in the stack either way; going direct trades the SDK's convenience wrappers for the ability to reuse the same tool server with a different client.

The honest comparison is not about capability. It is about how much of the stack you want to own. If you are prototyping an agent that reads files and streams answers, the SDK's async context manager is less code than assembling the same behaviour on a raw client. If you are shipping something where you must be able to read every line that executes, the compiled runtime is a boundary you cannot cross.

## Licence, maintenance, and upgrade cost

The package is licensed Apache-2.0, both in the LICENSE file and in the pyproject.toml licence field, with Google LLC as the author. Apache-2.0 permits commercial use and modification and includes a patent grant, but the runtime binary is distributed through PyPI wheels rather than as source, so the licence you receive covers the Python code in a way that is easier to reason about than the binary. Whether the compiled component carries additional terms is not stated in the README or pyproject.toml. That is a question for your own legal review, not something this article can settle.

The repository is not archived, and the last push was on 2026-09-02, which is recent. That tells you the project is being touched, not that its API is stable. The alpha classifier and the 0.1.x version line are the stronger signal: expect breaking changes between minor versions, and pin the exact version you deploy. The upgrade cost is dominated by two things. The protobuf>=7.35 floor will force upgrades elsewhere in a shared environment. And because the runtime binary ships inside the wheel, an upgrade replaces executable behaviour you cannot diff, so the practical review step is checking the changelog and re-running your own agent tests rather than reading a patch.

## Conclusion

Adopt it if you want an async Python agent loop with Gemini or Vertex routing and you are comfortable pinning an alpha package whose runtime ships as a compiled wheel. Do not adopt it if you need to vendor or patch the runtime, if you are staying on Python 3.9, or if you want synchronous code. Before writing production code, verify three things: that pip install google-antigravity resolves a wheel for your platform and Python version, that your chosen authentication path works (an API key with vertex=True, or ADC plus GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION), and that read-only default capabilities are what you want, since writing requires passing CapabilitiesConfig() explicitly.

## FAQ

### What is the Google Antigravity SDK?

It is a Python SDK for building AI agents powered by Antigravity and Gemini, installed with pip install google-antigravity. The README describes it as an infrastructure layer that abstracts the agentic loop, handling binary discovery, tool wiring, hook registration, and policy defaults so you write the agent's behaviour instead of the loop.

### What is the difference between the Antigravity IDE and the Antigravity SDK?

They are separate products. The Antigravity SDK is a pip-installable Python package with its own homepage at antigravity.google/product/antigravity-sdk, and nothing in the README describes it as an editor plugin or as requiring the IDE.

### What is a SDK in Python?

In this case it is a Python package, google-antigravity, that you install from PyPI and import as google.antigravity. It exposes classes such as Agent, LocalAgentConfig, CapabilitiesConfig, and Conversation, and it requires Python 3.10 or newer.

## Sources

- [google-antigravity/antigravity-sdk-python on GitHub](https://github.com/google-antigravity/antigravity-sdk-python)
- [Issues](https://github.com/google-antigravity/antigravity-sdk-python/issues)
- [License: Apache-2.0](https://github.com/google-antigravity/antigravity-sdk-python/blob/main/LICENSE)
- [Project website](https://antigravity.google/product/antigravity-sdk)
- [README](https://github.com/google-antigravity/antigravity-sdk-python/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/google-antigravity-antigravity-sdk-python