Antigravity SDK: What It Is, How to Install It, and Build a First Agent

What is the Antigravity SDK?

An SDK gives application code a supported way to call a product capability. The Antigravity SDK lets developers define an agent, connect approved tools, and consume a result from Python. It fits assistants, repository helpers, test harnesses, and repeatable workflows.

The key distinction is ownership: the IDE is for interactive work, the CLI is for terminal commands, and the SDK is where your program owns the workflow. They complement one another but do not share one universal version or configuration file.

How to install the Antigravity Python SDK

Start with the official SDK getting-started page and current PyPI metadata. Check the Python requirement, extras, authentication, and import paths instead of copying an old snippet. Use a disposable virtual environment, keep secrets outside Git, and make the first request read-only or reversible.

python -m venv .venv
.venv\Scripts\activate  # Windows
source .venv/bin/activate   # macOS or Linux
python -m pip install --upgrade pip
python -m pip install google-antigravity

1. Create an isolated environmentUse a project-local virtual environment for predictable package resolution and rollback.
2. Install from the maintained sourceFollow the official package instructions, including current extras or authentication steps.
3. Pin only after a successful testRun the smallest example, then record the version and Python runtime that passed.
4. Keep configuration out of commitsUse environment variables or a secret store and ignore local config files.
5. Read the release notes before upgradingSDK APIs can change independently from the desktop app, CLI, or IDE.

Confirm the current Python requirement and package instructions before production use.

Build a first small agent

A good first agent has one job, one instruction, and a result you can check by hand. Summarize a short release note or classify a local fixture. Avoid browser, shell, database, and write access together; failures are harder to isolate.

Class names and response properties belong to the current SDK release. The example shows the shape: configure, send one request, inspect the result, and follow the documented lifecycle. Treat it as a scaffold, not a permanent API promise.

from google.antigravity import Agent, AgentConfig

config = AgentConfig(
    instructions="Summarize the supplied release note in three bullets."
)
agent = Agent(config=config)
result = agent.run("Release note: the test suite now reports flaky browser checks.")
print(result)

• Input — Use a short fixture with an expected answer.
• Result — Inspect the result before adding automation.
• Lifecycle — Follow documented lifecycle and retry behavior.
• Repeatability — Save the prompt, version, settings, and observed result.

Add tools one at a time

Tools bridge agent reasoning and external action. Choose the smallest useful action, define a narrow input contract, validate arguments, and return a bounded result. Log safe identifiers and outcomes; never expose a home directory or grant write access when read-only data is enough.

Use subagents for separate jobs

A subagent helps when a task has a separate role, such as planning, retrieval, validation, or formatting. Give each role a clear input and output boundary; a planner should not inherit validator credentials.

Start sequentially so each handoff is inspectable. Add parallel work, timeouts, and retries only after the boundaries are stable, and expose partial failure.

Return structured output your program can trust

Free-form text is convenient for a person but fragile for application logic. When a result feeds a database, UI, test, or next agent, use the SDK's current structured-output feature with a small schema and validate it locally.

A schema does not make a response true: check types, allowed values, required fields, and business rules. Keep raw diagnostics separate from user-facing output.

result = agent.run("Classify the fixture.")
validated = {
    "label": result.label,
    "confidence": float(result.confidence),
    "needs_review": bool(result.needs_review),
}
assert validated["label"] in {"pass", "review", "fail"}

• Validate the returned object locally.
• Use enums and bounded strings for finite choices.
• Treat missing or malformed fields as a visible failure.
• Keep diagnostics separate from user-facing output.

SDK vs IDE vs CLI: choose the right surface

The SDK embeds an agent workflow in code; the IDE is for interactive projects; the CLI is for terminal commands and scripts. Pick the surface that owns the job rather than treating each as a different button for the same workflow.

Their releases can move on different schedules, so record the source and date for the component you use.

Security and reliability checks before wider use

An SDK can make an agent part of a real application, so review package provenance, credentials, network destinations, local paths, tool arguments, and logs. Begin with a disposable project and test account when tools reach external data.

Keep approval visible for actions that change files, send messages, spend money, alter accounts, or publish content. Add timeouts and bounded retries, and distinguish invalid input, unavailable services, denied permission, and human-review results.

• Credentials — Use a secret store; never commit tokens or paste them into prompts.
• Paths — Allow only project directories, not a drive root or home directory.
• Actions — Separate reads from writes, shell, browser, and network calls.
• Observability — Record IDs, durations, outcomes, and safe error categories.
• Recovery — Document how to disable, revoke access, replay a fixture, and roll back.

Common Antigravity SDK troubleshooting paths

When the first run fails, reduce the system to one variable at a time.

The package installs but the import fails

Confirm the virtual environment and interpreter, then compare the import path with the current quickstart. Check package metadata before changing application code.

The agent returns an authorization error

Compare credential source, account scope, and required permissions with the current documentation. Remove secrets from logs and retry the smallest request.

A tool call hangs or repeats

Add a timeout, log the boundary, and test the tool with fixed input. Keep retries bounded; never repeat an unknown write automatically.

Structured output is incomplete

Make the schema smaller and validate required fields locally. Treat refusal, truncation, or malformed data as review, not success.

Version snapshot and source-of-truth rule

On September 12, 2026, PyPI showed google-antigravity v0.1.16. Official listings showed desktop v2.13.0, CLI v1.2.0, and IDE v2.5.5; these surfaces move independently.

Use current official setup pages and record the installed version. The official download page remains the desktop and CLI fallback.