google-antigravity/antigravity-sdk-python

Google Antigravity SDK (Python)

What it is – A Python library that lets you build "agentic" AI applications powered by Google’s Gemini models (or local Gemma‑4 models). The SDK hides the low‑level plumbing of the agent loop—networking, tool execution, state management—so you can focus on the tasks you want the agent to perform.

Installation

pip install google-antigravity   # pulls a platform‑specific binary wheel

The binary runtime is required; cloning the repo alone won’t work.

Getting started

import asyncio
from google.antigravity import Agent, LocalAgentConfig

async def main():
    cfg = LocalAgentConfig(system_instructions="You are a helpful assistant.")
    async with Agent(cfg) as agent:
        resp = await agent.chat("List the files in the current directory.")
        print(await resp.text())

asyncio.run(main())

Run the example scripts in examples/ after setting GEMINI_API_KEY (or Vertex AI credentials).

Main concepts

Concept	What it does
Agent	High‑level entry point; manages binary discovery, tool wiring, policies, and streaming responses.
Conversation	Stateful session that keeps a history of steps; useful when you need fine‑grained control over send/receive.
LocalAgentConfig / LiteRTAgentConfig	Configuration objects for cloud (Gemini/Vertex) or offline (Gemma‑4 via LiteRT‑LM) models.
Tools	Register ordinary Python functions that the agent can call during a chat.
Hooks & Policies	Declarative rules (allow, deny, ask_user, enforce) that govern which tools may run and under what conditions.
Triggers	Background async tasks that can push messages into the agent (e.g., periodic status checks).
MCP Integration	Connect to external Model Context Protocol servers to expose additional tools.

Key features

• Unified cloud & local execution – Use Gemini via Vertex AI (API‑key or ADC) or run offline with Gemma‑4 26B via LiteRT‑LM.
• Streaming output – Iterate over ChatResponse (or its thoughts / tool_calls) to get token‑by‑token updates with zero extra network cost.
• Multimodal ingestion – Attach images, PDFs, videos, etc., directly via content classes (Image, from_file).
• Custom tool registration – Turn any Python callable into a tool the agent can invoke.
• Policy engine – Fine‑grained safety controls (block all tools, whitelist specific ones, ask the user before dangerous actions).
• Background triggers – Periodic or event‑driven tasks that can send messages to the agent.
• Three‑layer architecture – Simple Agent API, a session‑level Conversation layer, and a transport‑agnostic adapter layer.

Typical workflow

1. Install the package (and litert-lm if you plan to run locally).
2. Choose a config:
   • Cloud: LocalAgentConfig(vertex=True, api_key=…) or rely on ADC.
   • Local: LiteRTAgentConfig(model_path=…).
3. Optionally register tools, policies, or triggers.
4. Create an Agent (or Conversation) inside an async with block.
5. Call agent.chat(prompt) – the prompt can be a string or a list mixing text and content objects.
6. Consume the response via await resp.text() or stream tokens with async for token in resp.

Architecture snapshot

Layer	Responsibility	Core classes
Simplified	One‑line entry point for most use‑cases	Agent
Session	Maintains history, provides chat(), exposes streaming objects	Conversation, ChatResponse, Step, ToolCall, AgentConfig, HookRunner, ToolRunner, TriggerRunner
Adapter	Abstracts transport (cloud, local binary, MCP)	Connection, ConnectionStrategy, LocalConnection

License – Apache License 2.0.

---

All details above are taken directly from the repository’s README.