agy-sdk

Antigravity SDK

google-antigravity embeds the Antigravity harness as a Python library: it owns the agent loop, tool execution, and subagent delegation, so orchestration is expressed as configuration rather than a hand-rolled loop. The interactive CLI (agy) is a separate product on separate credentials — see §1. Project conventions come from python-stack; google-adk stays the default agent framework, and this SDK is the choice when the harness itself (sandboxed tools, policies, budgets) is the value.

1. Install and Authenticate

uv add google-antigravity                              # ships a ~126 MB harness binary; a git clone alone will not run
export GEMINI_API_KEY="<aistudio-key>"                 # Gemini Developer API, pay-as-you-go with a free tier
gcloud auth application-default login                  # Vertex path instead: LocalAgentConfig(vertex=True, project=..., location=...)

Billing is the Gemini API, never the Antigravity subscription. The SDK reads only GEMINI_API_KEY (or GOOGLE_CLOUD_PROJECT / GOOGLE_CLOUD_LOCATION with Vertex ADC); it never touches the OAuth login the agy CLI and IDE write to ~/.gemini, so a Google AI Pro/Ultra plan grants it nothing. Without a key it fails closed at connect time with AntigravityValidationError: A Gemini API key is required. Keep the key in the environment or a secret manager per sops-secrets; never inline it in LocalAgentConfig(api_key=...) in committed code.

2. Orchestrate

references/orchestrator.py is a runnable parent-plus-two-subagent fan-out; the pieces that matter:

• Static subagents: types.SubagentConfig(name, description, system_instructions, tools) in LocalAgentConfig(subagents=[...]) gives each worker its own context window and instructions. Prefer these — a named role is reviewable, whereas dynamic self-cloning is not.
• Dynamic subagents: types.CapabilitiesConfig(enable_subagents=True) alone lets the parent clone itself on demand, inheriting its toolset. Use it only for open-ended decomposition.
• Register tools twice: any callable a subagent uses must appear in the parent's tools=[...] as well, or the subagent starts without it.
• Bound the fan-out: max_subagent_depth caps nesting and allowed_subagents pins the roster; both belong in CapabilitiesConfig.
• Typed results: response_schema=<pydantic model> plus await response.structured_output() returns a validated dict, which is what makes a subagent's output safe to route programmatically.
• Resume: conversation_id with session_continuation_mode (CREATE_ONLY, CREATE_OR_RESUME, RESUME) and save_dir persists a long orchestration across processes.