Google Antigravity SDK for Python: A Compiled Runtime Behind an Async Agent Loop

The Problem Antigravity SDK Solves, and Who Feels It

Building an agent on top of a model API means writing the same scaffolding every time: a loop that sends a prompt, inspects the response, decides whether a tool call is needed, dispatches it, feeds the result back, and repeats until the model stops asking. The Antigravity SDK exists to remove that scaffolding. Its README describes it as a "secure, scalable, and stateful infrastructure layer that abstracts the agentic loop, letting you focus on what your agent does rather than how it runs." That is the pitch, and it is a narrow one. The intended user is a Python developer who has already chosen Gemini or the Gemini Enterprise Agent Platform (formerly Vertex AI) and does not want to hand-roll conversation state, tool dispatch, or capability gating. The README's own quickstart is a hello_world script run with a GEMINI_API_KEY, which tells you the entry bar is low. The advanced path assumes more: Conversation, ConnectionStrategy, ToolRunner. If you are evaluating model providers, this SDK is not the place to start, because it commits you to Google's stack in both authentication and model access.

What Actually Runs: Agent, Conversation, and a Compiled Binary

Two layers are visible in the documentation. The top layer is Agent, which the README says manages "the full lifecycle: binary discovery, tool wiring, hook registration, and policy defaults" behind one async context manager. The lower layer is Conversation, created via Conversation.create(strategy) with a LocalConnectionStrategy that takes a ToolRunner. Conversation is described as a stateful session that accumulates step history and exposes conversation.history, conversation.turn_count, and conversation.last_response. The data flow is a step stream: conversation.send() pushes a turn, conversation.receive_steps() yields step objects, and a step exposes is_complete_response and content. Response objects expose three async iterables: plain text tokens, response.thoughts for reasoning deltas, and response.tool_calls for typed tool call events. That thoughts stream is the most distinctive part of the API surface, because most SDKs of this shape expose only final text. Note the phrase "binary discovery" in the lifecycle description. The SDK is not pure Python. A compiled runtime binary sits underneath, and the README is explicit that it is included in platform-specific wheels on PyPI.

Installing It: PyPI Only, and the Wheel Constraint

Installation is one command: pip install google-antigravity. The README attaches an important warning to it: "Cloning this repository alone is not sufficient to run the SDK." The compiled runtime binary arrives in platform-specific wheels, so a source checkout gives you code without the engine. For anyone who normally vendors dependencies or builds from a git tag, that is a real change in workflow, and it also means your supported platforms are whatever wheels were published. The quickstart then sets an API key and runs a bundled example: export GEMINI_API_KEY="your_api_key_here" followed by python ./examples/getting_started/hello_world.py. Configuration flows through LocalAgentConfig, which accepts system_instructions (optional), api_key, capabilities, and the Vertex fields vertex, project, and location. The README states that explicit kwargs always take precedence over environment variables, which matters when GOOGLE_GENAI_USE_VERTEXAI, GOOGLE_CLOUD_PROJECT, and GOOGLE_CLOUD_LOCATION are set in a shell profile and a config object disagrees with them.

Vertex Authentication: Two Modes with Different Operational Costs

The SDK supports two ways to reach the Gemini Enterprise Agent Platform. Express mode sets vertex=True with an api_key and, per the README, requires no Google Cloud project, no regional configuration, and no Application Default Credentials. Standard mode sets vertex=True with project and location, and authenticates through ADC by default, which means running gcloud auth application-default login before the agent starts. The two modes are not interchangeable in an enterprise setting. Express mode is faster to stand up but bypasses the project and region routing that standard mode uses, and the README frames standard mode specifically for "enterprise deployments routing to regional endpoints." If your organization requires data residency or per-project quota accounting, express mode is the wrong choice regardless of how convenient it looks in a prototype. The environment variable route, GOOGLE_GENAI_USE_VERTEXAI with GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION, is offered as an alternative to kwargs, with the precedence rule noted above.

Read-Only by Default, and Why That Will Surprise You

The README states that Agent runs in read-only mode by default for safety, and that you pass capabilities=CapabilitiesConfig() to enable all tools, including writes. This is a sound default and a common source of first-run confusion. An agent asked to modify a file will not do it until you opt in, and the failure appears as a tool that simply does not fire rather than an exception with an obvious cause. The interactive loop example makes the opt-in explicit by constructing LocalAgentConfig with capabilities=CapabilitiesConfig() alongside run_interactive_loop. The trade-off is that capability configuration is coarse at this level: the README shows an all-tools constructor and a default read-only state, with nothing in between documented in the material provided. If your agent needs to write to one directory and read from another, the supplied documentation does not show how to express that, and you would need to check the package source or the tools module before assuming a per-tool policy exists.

Multimodal Input and Where the Documentation Stops

The SDK accepts images, videos, audio, and documents alongside text prompts. The README shows two ingestion paths: content classes for in-memory bytes, and a filesystem helper imported as from_f, which the README says resolves types and guesses MIME formats automatically. The README text for this section is truncated mid-example, so the full signature of from_f and the complete list of content classes are not confirmable from the material available. Treat multimodal input as advertised but under-documented until you read the types module directly. The same caution applies to the streaming claim. The README says the stream wrapper yields text tokens "with zero network overhead." That phrasing is about the wrapper not adding a second request, not a measured latency figure, and no benchmark numbers appear anywhere in the supplied material. There are also no releases retrieved for this repository, so there is no published version history to check for API stability.

The Alternative: LangGraph and Explicit State Machines

The closest comparison is a framework like LangGraph, where you define the agent loop yourself as a graph of nodes and edges with explicit state. The difference in approach is who owns the control flow. Antigravity hides the loop behind Agent and Conversation and gives you hooks into it: thoughts, tool_calls, step history. LangGraph makes the loop the artifact you author, which is more code but also means the retry policy, the branching conditions, and the termination criteria are yours to read and change. LangGraph is also not tied to one model vendor. The practical split: if your agent's value is in a well-understood loop over Gemini, Antigravity removes boilerplate. If your agent's value is in unusual control flow (custom retries, human approval gates, non-linear branching), a graph framework expresses that directly, and Antigravity's step stream may not be the right abstraction. The compiled binary is the second differentiator. With a pure-Python framework you can read every line that runs; here, part of the runtime is opaque.

Maintenance, Licensing, and What to Check Before Committing

The repository is licensed Apache-2.0, which permits commercial use and modification, and it is not archived. The licence covers the repository code; the compiled runtime binary distributed in the wheels is a separate artifact, and the supplied material does not state its terms. If your legal or security review requires source access to everything that executes, that gap needs resolving before adoption, and this is not legal advice. On upgrade cost, the coupling runs in one direction: your code depends on LocalAgentConfig fields and the Agent and Conversation APIs, while the agentic loop itself lives in the binary. A runtime upgrade can change loop behaviour without a corresponding change in the Python you can read, so pinning the package version and reading the changelog before bumping is the practical mitigation. The README also names GOOGLE_GENAI_USE_ENTERPRISE as an alternative to GOOGLE_GENAI_USE_VERTEXAI for enabling Vertex, which suggests the environment variable surface has been renamed at least once alongside the Vertex AI to Gemini Enterprise Agent Platform transition. Confirm which variable your installed version reads rather than assuming either name works.

Editorial conclusion

Adopt it if you are already on Gemini or Vertex AI and want the agentic loop, tool wiring, and policy defaults handled by a single Agent context manager. Do not adopt it if you need a runtime you can patch, audit, or build from source: the SDK depends on a compiled binary that only ships in platform-specific wheels, so cloning the repository is not enough. Before writing production code, verify three things on your own machine: that a wheel exists for your OS and Python version, that your chosen Vertex authentication mode works (express with vertex=True and api_key, or standard with project and location plus gcloud auth application-default login), and whether the default read-only mode blocks the tool calls your agent needs before you pass CapabilitiesConfig().

Official sources

1. google-antigravity/antigravity-sdk-python on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README