Antigravity

Run Google's Managed Agents (Gemini API) as an AgentOS agent using AntigravityAgent.

AntigravityAgent wraps Managed Agents in the Gemini API so a Google-managed, sandboxed agent can be served through AgentOS. A single API call spins up a secure Linux environment where the agent plans, executes code, searches the web, and reads/writes files. AgentOS handles sessions, streaming, and the UI.

1from kern.agents.antigravity import AntigravityAgent
2from kern.db.sqlite import SqliteDb
3from kern.os import AgentOS
4
5agent = AntigravityAgent(name="Antigravity")
6
7agent_os = AgentOS(
8    agents=[agent],
9    db=SqliteDb(db_file="tmp/agentos.db"),
10)
11app = agent_os.get_app()
12
13if __name__ == "__main__":
14    agent_os.serve(app="antigravity_agent:app", reload=True)

Install

1uv pip install pyyaml
2export GEMINI_API_KEY=...

pyyaml is only required for from_agent_directory.

Parameters

Parameter	Type	Default	Description
`name`	`str`	`None`	Display name for the agent.
`id`	`str`	`None`	Unique identifier. Auto-generated from `name` if unset.
`api_key`	`str`	`None`	Gemini API key. Falls back to `GEMINI_API_KEY`.
`base_url`	`str`	Gemini v1beta	API base URL.
`agent`	`str`	`"waverunner"`	Base agent identifier sent to the API, or a custom agent name.
`sources`	`List[Dict]`	`None`	GCS / repository / inline sources to seed the sandbox on the first turn.
`custom_agent_name`	`str`	`None`	Register/invoke a named custom agent instead of the base agent.
`custom_agent_instructions`	`str`	`None`	System instructions for the custom agent definition.
`custom_agent_description`	`str`	`None`	Description for the custom agent definition.
`timeout`	`int`	`600`	Per-request timeout in seconds.
`db`	`BaseDb`	`None`	Database for session persistence. Required for cross-turn sandbox reuse.

Concepts

Sessions and environment persistence

Each interaction provisions a managed Linux sandbox and returns an environment_id. When a db is configured, AntigravityAgent persists that id (and the previous interaction id) in the session, so subsequent turns with the same session_id reuse the same sandbox. Files, installed packages, and state carry over.

Without a db, every turn provisions a fresh sandbox (no cross-turn reuse).

1from kern.agents.antigravity import AntigravityAgent
2from kern.db.sqlite import SqliteDb
3
4agent = AntigravityAgent(name="Antigravity", db=SqliteDb(db_file="tmp/antigravity.db"))
5
6agent.print_response("Write a file notes.txt containing 'hello'.", session_id="s1")
7agent.print_response("Read notes.txt back to me.", session_id="s1")  # same sandbox

Seeding the environment with sources

Pass sources to preload files into the sandbox before the agent runs. Three source types are supported: inline content, Google Cloud Storage, and Git repositories.

1agent = AntigravityAgent(
2    name="Antigravity",
3    sources=[
4        {"type": "inline", "content": "kern is an agent framework", "target": "/workspace/about.txt"},
5        # {"type": "gcs", "source": "gs://my-bucket/data/", "target": "/data"},
6        # {"type": "repository", "source": "github://user/repo", "target": "/repo"},
7    ],
8)

Inline sources are limited to 75 KB per file; use GCS or a Git repo for larger files.

Custom agents

Register a reusable named agent (instructions + sources stored server-side), then invoke it by name. Registration is explicit and idempotent (an already-existing agent is reused).

1agent = AntigravityAgent(
2    name="Haiku Bot",
3    custom_agent_name="kern-haiku-bot",
4    custom_agent_instructions="You only ever respond with a single haiku.",
5)
6agent.ensure_custom_agent()  # POST /agents, idempotent
7agent.print_response("Topic: autumn.")

Defining an agent from a directory

from_agent_directory builds an agent from a local folder following the Managed Agents layout: agent.yaml (id, base_agent, description, system_instruction), AGENTS.md (overrides system_instruction), workspace/ (mounted at the sandbox root), and skills/ (mounted under /.agents/skills/). It registers the agent with the API before returning (register=True default).

1from kern.agents.antigravity import AntigravityAgent
2
3agent = AntigravityAgent.from_agent_directory("./my-agent")
4agent.print_response("Write me a haiku about Python.")

Downloading an environment snapshot

Pull the sandbox filesystem (after a run modified it) as a tar archive.

1agent = AntigravityAgent(name="Antigravity", db=SqliteDb(db_file="tmp/antigravity.db"))
2agent.print_response("Create /workspace/report.md", stream=False, session_id="s1")
3agent.download_environment_snapshot("snapshot.tar", session_id="s1")