Skip to content
Back to search

antigravity-sdk-python

A Python library for building AI agents that leverage the full power of Google Antigravity.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/google-antigravity--antigravity-sdk-python/badge.svg)](/listings/google-antigravity--antigravity-sdk-python)

HTML

<a href="/listings/google-antigravity--antigravity-sdk-python"><img src="/api/listings/google-antigravity--antigravity-sdk-python/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

pip install google-antigravity

> [!IMPORTANT] > The Google Antigravity SDK relies on a compiled runtime binary that is > included in the platform-specific wheels published to > [PyPI](https://pypi.org/project/google-antigravity/). **Cloning this > repository alone is not sufficient to run the SDK.** Always install from > PyPI with `pip install google-antigravity` to obtain the binary.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 404 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Google Antigravity SDK
  2. The Google Antigravity SDK is a Python SDK for building AI agents powered by
  3. Antigravity and Gemini. It provides a secure, scalable, and stateful
  4. infrastructure layer that abstracts the agentic loop, letting you focus on what
  5. your agent *does* rather than how it runs.
  6. ## Installation
  7. ```sh
  8. pip install google-antigravity
  9. ```
  10. > [!IMPORTANT]
  11. > The Google Antigravity SDK relies on a compiled runtime binary that is
  12. > included in the platform-specific wheels published to
  13. > [PyPI](https://pypi.org/project/google-antigravity/). **Cloning this
  14. > repository alone is not sufficient to run the SDK.** Always install from
  15. > PyPI with `pip install google-antigravity` to obtain the binary.
  16. ## Quickstart
  17. Get started by running one of the [`examples/`](examples/), such as the
  18. `hello_world` example with:
  19. ```sh
  20. export GEMINI_API_KEY="your_api_key_here"
  21. python ./examples/getting_started/hello_world.py
  22. ```
  23. ## Gemini Enterprise Agent Platform (formerly Vertex AI)
  24. To use the SDK with Gemini Enterprise Agent Platform (formerly Vertex AI),
  25. the SDK supports two authentication modes:
  26. ### 1. Express Mode (API Key)
  27. For fast setup without requiring Google Cloud projects, regional configuration,
  28. or Application Default Credentials (ADC), provide an API key with `vertex=True`:
  29. ```python
  30. from google.antigravity import Agent, LocalAgentConfig
  31. config = LocalAgentConfig(
  32. vertex=True,
  33. api_key="your_api_key_here",
  34. )
  35. async with Agent(config) as agent:
  36. response = await agent.chat("Hello!")
  37. print(await response.text())
  38. ```
  39. ### 2. Standard Mode (Project & Location with ADC)
  40. For enterprise deployments routing to regional endpoints, configure
  41. `LocalAgentConfig` with `vertex=True`, `project`, and `location`. By default,
  42. this mode authenticates via Application Default Credentials (ADC).
  43. ```python
  44. from google.antigravity import Agent, LocalAgentConfig
  45. config = LocalAgentConfig(
  46. vertex=True,
  47. project="your-gcp-project",
  48. location="us-central1",
  49. )
  50. async with Agent(config) as agent:
  51. response = await agent.chat("Hello!")
  52. print(await response.text())
  53. ```
  54. Alternatively, you can leave these fields unset in `LocalAgentConfig` and
  55. export the environment variables instead:
  56. ```sh
  57. # Either GOOGLE_GENAI_USE_VERTEXAI or GOOGLE_GENAI_USE_ENTERPRISE enable Vertex.
  58. export GOOGLE_GENAI_USE_VERTEXAI=True
  59. export GOOGLE_CLOUD_PROJECT="your-gcp-project"
  60. export GOOGLE_CLOUD_LOCATION="us-central1"
  61. ```
  62. Explicit kwargs always take precedence over env vars.
  63. Ensure you have authenticated locally before running the agent in Standard Mode:
  64. ```sh
  65. gcloud auth application-default login
  66. ```
  67. See [vertex.py](./examples/getting_started/vertex.py) for a complete example.
  68. ## Concepts
  69. ### Simple Agent
  70. The `Agent` class is the easiest way to get started. It manages the full
  71. lifecycle — binary discovery, tool wiring, hook registration, and policy
  72. defaults — behind a single async context manager.
  73. The `system_instructions` parameter is optional.
  74. ```python
  75. import asyncio
  76. from google.antigravity import Agent, LocalAgentConfig
  77. async def main():
  78. config = LocalAgentConfig(
  79. system_instructions="You are an expert assistant for codebase navigation.",
  80. # api_key="your_api_key_here",
  81. )
  82. async with Agent(config) as agent:
  83. response = await agent.chat("What files are in the current directory?")
  84. print(await response.text())
  85. async def run():
  86. await main()
  87. if __name__ == "__main__":
  88. asyncio.run(run())
  89. ```
  90. ### Streaming Responses
  91. To stream agent output in real-time (e.g., for fluid UI or console applications), simply iterate over the `ChatResponse` object using an `async for` loop. The stream wrapper natively yields conversational `str` text tokens as they arrive, with zero network overhead:
  92. ```python
  93. import asyncio
  94. import sys
  95. from google.antigravity import Agent, LocalAgentConfig
  96. async def main():
  97. config = LocalAgentConfig()
  98. async with Agent(config) as agent:
  99. # Returns instantly — does not block
  100. response = await agent.chat("Write a short poem about space.")
  101. async for token in response:
  102. sys.stdout.write(token)
  103. sys.stdout.flush()
  104. print()
  105. asyncio.run(main())
  106. ```
  107. ### Sugared Thoughts & Tool Call Streams (Advanced)
  108. For more complex use cases, you can also stream internal model reasoning/thinking or intercept tool call dispatches in real-time using dedicated async stream properties:
  109. ```python
  110. # 1. Stream reasoning/thinking deltas
  111. async for thought in response.thoughts:
  112. show_thinking_bubble(thought)
  113. # 2. Stream strongly-typed ToolCall events
  114. async for call in response.tool_calls:
  115. show_executing_spinner(call.name)
  116. ```
  117. By default, `Agent` runs in **read-only mode** for safety. Pass
  118. `capabilities=CapabilitiesConfig()` to enable all tools (including writes).
  119. ### Interactive Loop
  120. ```python
  121. from google.antigravity import LocalAgentConfig, CapabilitiesConfig
  122. from google.antigravity.utils.interactive import run_interactive_loop
  123. config = LocalAgentConfig(
  124. # api_key="your_api_key_here",
  125. capabilities=CapabilitiesConfig(),
  126. )
  127. await run_interactive_loop(config)
  128. ```
  129. ### Advanced Usage with Conversation
  130. For full control over the connection lifecycle, use `Conversation` with a
  131. `ConnectionStrategy` directly. `Conversation` is a stateful session that
  132. accumulates step history, provides a `chat()` convenience method, and exposes
  133. state introspection:
  134. ```python
  135. import asyncio
  136. from google.antigravity.connections.local import LocalConnectionStrategy
  137. from google.antigravity.conversation.conversation import Conversation
  138. from google.antigravity.tools.tool_runner import ToolRunner
  139. async def main():
  140. tool_runner = ToolRunner()
  141. strategy = LocalConnectionStrategy(
  142. tool_runner=tool_runner,
  143. )
  144. async with Conversation.create(strategy) as conversation:
  145. # High-level: one-call send + collect
  146. response = await conversation.chat("What files are here?")
  147. print(await response.text())
  148. # Step history accumulates automatically
  149. print(f"Total steps: {len(conversation.history)}")
  150. print(f"Turns: {conversation.turn_count}")
  151. print(f"Last response: {conversation.last_response}")
  152. # Low-level: streaming steps
  153. await conversation.send("Tell me more.")
  154. async for step in conversation.receive_steps():
  155. if step.is_complete_response:
  156. print(step.content)
  157. asyncio.run(main())
  158. ```
  159. ## Features
  160. ### Multimodal Ingestion
  161. Pass rich multimedia file attachments (images, videos, audio, and documents) to the agent alongside textual instruction prompt lists.
  162. You can attach assets **directly using content classes** (perfect for in-memory bytes) or **conveniently from a filesystem path** (which automatically resolves types and guesses MIME formats):
  163. ```python
  164. from google.antigravity import Agent, LocalAgentConfig
  165. from google.antigravity.types import Image, from_file
  166. config = LocalAgentConfig(system_instructions="You are an expert software architect.")
  167. async with Agent(config) as agent:
  168. # 1. Flat filesystem shortcut (automatically resolves as types.Document)
  169. pdf_spec = from_file("spec.pdf")
  170. # 2. Direct constructor instantiation (perfect for in-memory raw bytes)
  171. chart_image = Image(
  172. data=b"raw_png_bytes_here",
  173. mime_type="image/png",
  174. description="Architecture blueprint"
  175. )
  176. # Send a mixed list of text instructions and content classes
  177. prompt = [
  178. "Analyze this chart against the specification and list three security vulnerabilities:",
  179. chart_image,
  180. pdf_spec
  181. ]
  182. response = await agent.chat(prompt)
  183. print(await response.text())
  184. ```
  185. ### Custom Tools
  186. Register Python functions as tools that the agent can call:
  187. ```python
  188. def get_weather(city: str) -> str:
  189. """Returns the current weather for a city."""
  190. return f"It's sunny in {city}."
  191. config = LocalAgentConfig(
  192. tools=[get_weather],
  193. )
  194. async with Agent(config) as agent:
  195. response = await agent.chat("What's the weather in Tokyo?")
  196. ```
  197. ### MCP Integration
  198. Connect to external [MCP](https://modelcontextprotocol.io/) servers and expose
  199. their tools to the agent:
  200. ```python
  201. from google.antigravity import Agent, LocalAgentConfig
  202. from google.antigravity.types import McpStdioServer
  203. config = LocalAgentConfig(
  204. mcp_servers=[McpStdioServer(name="my_server", command="npx", args=["my-mcp-server"])],
  205. )
  206. async with Agent(config) as agent:
  207. response = await agent.chat("Use the MCP tools to help me.")
  208. ```
  209. ### Hooks and Policies
  210. Control agent behavior with a declarative policy system:
  211. ```python
  212. from google.antigravity import LocalAgentConfig, CapabilitiesConfig
  213. from google.antigravity.hooks.policy import deny, allow, ask_user, enforce
  214. from google.antigravity.utils.interactive import run_interactive_loop
  215. policies = [
  216. deny("*"), # Block all tools by default
  217. allow("view_file"), # Allow reading files
  218. ask_user("run_command", handler=my_handler), # Ask before running commands
  219. ]
  220. config = LocalAgentConfig(
  221. capabilities=CapabilitiesConfig(),
  222. policies=policies,
  223. )
  224. await run_interactive_loop(config)
  225. ```
  226. ### Triggers
  227. Run background tasks that react to external events and push messages into the
  228. agent:
  229. ```python
  230. from google.antigravity import LocalAgentConfig
  231. from google.antigravity.triggers import every
  232. from google.antigravity.utils.interactive import run_interactive_loop
  233. async def check_status(ctx):
  234. await ctx.send("Check the deployment status.")
  235. config = LocalAgentConfig(
  236. triggers=[every(60, check_status)],
  237. )
  238. await run_interactive_loop(config)
  239. ```
  240. ### Local AI Models
  241. The Antigravity SDK supports local, offline agentic workflows powered by Gemma 4 and LiteRT-LM. By pairing your SDK scripts with local models, you can run LLM-driven tasks completely offline.
  242. > [!NOTE]
  243. >
  244. > * Currently, this works best with `gemma-4-26B-A4B-it-gpu.litertlm`. Other `.litertlm` files may not work well, or not work at all.
  245. > * We recommend at least 24GB of VRAM/shared memory.
  246. > * We recommend using a 64K context size.
  247. #### Prerequisites and Installation
  248. First, it is recommended to create and activate a virtual environment:
  249. ```bash
  250. python3 -m venv .venv
  251. source .venv/bin/activate
  252. ```
  253. Next, install the Antigravity SDK along with LiteRT-LM:
  254. ```bash
  255. pip install google-antigravity litert-lm
  256. ```
  257. Import the Gemma 4 26B MoE model. Take note of the imported model path (e.g. on MacOS, typically models are imported to USER/.litert-lm/models):
  258. ```bash
  259. litert-lm import \
  260. --from-huggingface-repo=litert-community/gemma-4-26B-A4B-it-litert-lm \
  261. gemma-4-26B-A4B-it-gpu.litertlm \
  262. gemma4-26b
  263. ```
  264. Quick Start for Local Models:
  265. ```python
  266. import asyncio
  267. import os
  268. from google.antigravity import Agent, LiteRTAgentConfig
  269. # Point directly to the locally imported LiteRT-LM model path
  270. MODEL_PATH = os.path.expanduser("~/.litert-lm/models/gemma4-26b/model.litertlm")
  271. async def main():
  272. print(f"Using local LiteRT model: {MODEL_PATH}")
  273. config = LiteRTAgentConfig(
  274. model_path=MODEL_PATH,
  275. ).lightweight()
  276. async with Agent(config) as agent:
  277. response = await agent.chat("What files are in the current directory?")
  278. async for token in response:
  279. print(token, end="", flush=True)
  280. if __name__ == "__main__":
  281. asyncio.run(main())
  282. ```
  283. ## Architecture
  284. The SDK follows a three-layer architecture:
  285. | Layer | Purpose | Key Classes |
  286. |:------|:--------|:------------|
  287. | **Layer 1** — Simplified | High-level, batteries-included entry point | `Agent` |
  288. | **Layer 2** — Session | Stateful session with history and convenience methods | `Conversation`, `ChatResponse`, `Step`, `ToolCall`, `AgentConfig`, `HookRunner`, `ToolRunner`, `TriggerRunner` |
  289. | **Layer 3** — Adapter | Transport and backend abstraction | `Connection`, `ConnectionStrategy`, `LocalConnection` |
  290. ## Component Documentation
  291. For more detailed documentation on specific components, see:
  292. - [Agent](google/antigravity/agent.py) — High-level, batteries-included entry point.
  293. - [Connections](google/antigravity/connections/README.md) — Transport and backend abstraction.
  294. - [Conversation](google/antigravity/conversation/README.md) — Stateful session management.
  295. - [Hooks](google/antigravity/hooks/README.md) — Agent lifecycle interception and policies.
  296. - [MCP](google/antigravity/mcp/README.md) — Model Context Protocol integration.
  297. - [Tools](google/antigravity/tools/README.md) — In-process tool execution.
  298. - [Triggers](google/antigravity/triggers/README.md) — Background tasks and external events.
  299. ## License
  300. [Apache License 2.0](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.