Building Managed Agents with the Gemini API: A Complete Developer Guide

Autonomous agents that reason, write and execute code, browse the web, and manage files used to require weeks of infrastructure work. With the launch of Managed Agents on the Gemini API, Google has collapsed that setup into a single API call. One request spins up a secure, ephemeral Linux sandbox hosted by Google — and an agent ready to do real work inside it.

This guide covers everything developers need to know: how the Antigravity agent works, how to build and deploy custom agents, how to fork environments for reproducible runs, how to lock down networking and credentials, and how the new Gemini CLI fits into an agent-first workflow.

What Are Gemini API Managed Agents?

Managed Agents are Google's new developer primitive for autonomous AI agents on the Gemini API. Instead of stitching together orchestration logic, code execution environments, tool-calling infrastructure, and security controls yourself, the API handles all of it.

A single call to the Interactions API provisions a sandboxed Linux environment, starts an agent powered by Gemini, and executes your task end-to-end. The agent can reason and plan, call tools, execute code, manage files, and browse the web — all within a secure runtime Google manages on your behalf.

Two surfaces make this possible:

• The Interactions API — the runtime interface. Send a task, get back an agent that reasons and acts.
• The Agents API — the control plane. Define, register, and manage named agents with custom instructions, tools, skills, and environment configurations.

The Antigravity Agent: A General-Purpose Agent Ready to Use

The first general-purpose managed agent on the Gemini API is Antigravity. It's powered by Gemini 3.5 Flash and runs on the same harness behind the Antigravity IDE and other Google first-party agent products. Before Antigravity, Deep Research was the only managed agent available — a specialized agent for multi-step research workflows.

Antigravity is the general-purpose counterpart: a single API call that provisions a remote Linux environment and gets to work.

What Antigravity Can Do

Inside its managed sandbox, the Antigravity agent can:

• Reason and plan using the Gemini agent harness
• Execute code and manage files in a secure Linux environment
• Browse the web to fetch and process live data
• Use tools including web search, code execution, and file I/O

Your First Antigravity API Call

Here's the simplest possible Antigravity invocation — one API call that provisions a remote environment, runs the agent, and returns output:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Research the top 10 AI stories today and create a PDF briefing with summaries",
    environment="remote",  # Remote Linux environment hosted by Google
)

print(interaction.output_text)

That's it. No container setup. No sandboxing code. No tool-calling scaffolding. Google handles all of it.

Persistent Environments: Stateful Multi-Turn Agents

Environments persist across calls. The first interaction provisions a sandbox and returns an environment_id. Pass that ID in follow-up requests and the agent resumes with all files, packages, and state exactly as the previous call left them.

# First call — provisions a new remote environment
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    environment="remote",
    input="Research the top 10 AI stories today and create a PDF briefing with summaries",
)

# Second call — resumes in the same environment with full state intact
interaction_2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    environment=interaction.environment_id,
    previous_interaction_id=interaction.id,
    input="Now create a landing page using javascript and html",
)

print(interaction_2.output_text)

This statefulness is what makes multi-step workflows practical. An agent that installs packages, writes files, and runs analysis in one call can hand all of that off seamlessly to the next call — no re-setup, no re-download, no re-execution.

Environments also accept external data at startup: Git repositories, Google Cloud Storage objects, or inline content can all be mounted into the sandbox before the agent starts working.

Building Custom Managed Agents

The Antigravity agent covers general-purpose tasks well. But production use cases almost always need custom behavior — specific instructions, domain skills, proprietary tools, or curated data sources. That's what the Agents API is for.

Gemini Managed Agents let you bundle instructions, skills, tools, and an environment into a named agent you invoke by ID. Instead of writing complex orchestration code, you define everything declaratively — in markdown files like AGENTS.md and SKILL.md — and register them once.

Defining an Agent from Sources

Create an agent from scratch by specifying system instructions and sources. Sources can be GitHub repositories, Google Cloud Storage paths, or inline content. The platform provisions a fresh sandbox with your files on every invocation.

agent = client.agents.create(
    name="data-analyst",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "You are a data analyst agent..."
            },
            {
                "type": "inline",
                "target": ".agents/slide-maker/SKILL.md",
                "content": "Instructions for creating slides..."
            },
            {
                "type": "github",
                "source": "https://github.com/my-org/data-templates.git",
                "target": "/workspace/"
            },
            {
                "type": "gcs",
                "source": "gs://my-bucket/analysis-skills/",
                "target": "/.agents/skills/"
            },
        ]
    }
)

result = client.interactions.create(
    agent="data-analyst",
    input="Analyze Q1 revenue data and create a slide deck.",
    environment="remote",
)

print(result.output_text)

Once registered, data-analyst is a durable agent you can invoke by name. Each run provisions a clean environment with your exact configuration — no state leaks between invocations.

Forking an Existing Environment

Sometimes the fastest path to a custom agent is iteration. Start by working interactively with the base Antigravity agent — install packages, create templates, configure the environment — then fork that environment snapshot into a reusable named agent.

# Step 1: Iterate with the base agent in a remote environment
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Install pandas and matplotlib. Create an analysis template.",
    environment="remote"
)

# Step 2: Create a new agent from the existing environment snapshot
agent = client.agents.create(
    name="my-data-analyst",
    base_agent="antigravity-preview-05-2026",
    instructions="You are a data analyst that creates slide presentations.",
    base_environment=interaction.environment_id,
)

Once saved, every subsequent invocation of my-data-analyst forks from that base snapshot — starting from a clean, pre-configured state every time.

result = client.interactions.create(
    agent="my-data-analyst",
    input="Analyze Q1 revenue data and create a slide deck.",
    environment="remote"
)

print(result.output_text)

The fork-and-register pattern is particularly effective for agents that depend on heavy setup: complex dependency graphs, large model artifacts, or pre-compiled templates that would take too long to rebuild on every invocation.

Secure Networking and Credentials Proxy

Production agents almost always need to reach external services — GitHub, internal APIs, package registries — and almost always need to do so without exposing sensitive credentials inside the sandbox. Managed Agents handle both with a configurable egress proxy.

The network configuration serves two purposes:

1. Allowlists restrict outbound connections to explicitly permitted domains, preventing an agent from reaching unintended external services.
2. Header transforms inject credentials server-side, so API tokens and secrets are never passed into the sandbox environment itself.

agent = client.agents.create(
    id="issue-resolver",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/my-org/backend",
                "target": "/workspace/repo",
            }
        ],
        "network": {
            "allowlist": [
                {
                    "domain": "api.github.com",
                    "transform": {
                        "Authorization": "Bearer ghp_your_github_token"
                    },
                },
                {"domain": "pypi.org"},
            ]
        },
    },
)

In this configuration, the agent can only reach api.github.com and pypi.org. Any attempt to connect to another domain is blocked. GitHub requests are automatically transformed to include the Authorization header — the sandbox code never sees the token directly.

This architecture is essential for agents deployed against internal code repositories, proprietary APIs, or any environment where credential hygiene is a compliance requirement.

The Gemini API CLI: An Agent-First Developer Experience

Alongside the API, Google shipped an experimental open-source Gemini API CLI designed for coding agents to interact with the Gemini API in a structured, agent-friendly way.

# Run a prompt against any model
gemini-api run "What is the capital of France?"

# Image generation
gemini-api run "A cat in space" --model gemini-3.1-flash-image-preview --output cat.png

# Text-to-speech
gemini-api run "Hello from Gemini" --model gemini-3.1-flash-tts-preview --voice Kore --output hello.wav

# Scaffold, test, and deploy an agent
gemini-api agents init my-agent
gemini-api agents test --prompt "Analyze the Q1 revenue data"
gemini-api agents create

# Run against a deployed agent
gemini-api run "Summarize this quarter" --agent my-agent

The agents init / agents test / agents create workflow reflects a shift in how Google expects developers to build on the Gemini API: define agent behavior in files, test locally, deploy as a named managed agent — the same pattern familiar from infrastructure-as-code tooling.

Complementary Tooling

Beyond the CLI, two additions keep coding agents current with the Gemini API:

• Gemini API Docs MCP server — provides live access to Gemini documentation, SDKs, and model information via MCP. Coding agents can query the docs directly rather than relying on stale training data.
• gemini-interactions-api Skill — injects Interactions API patterns and best practices into an agent's context automatically, so agents built with Gemini Managed Agents write idiomatic interaction code from the start.

Why Managed Agents Matter for Production Use Cases

The core bet behind Managed Agents is that most of the hard work in agent development isn't the model — it's the infrastructure around it. Sandboxing, tool integration, credential management, environment reproducibility, and network security are all problems that every team shipping agents has to solve independently. Managed Agents make them Google's problem instead.

That shift has practical implications for production deployments:

Reproducible runs. Forked environments guarantee that every agent invocation starts from an identical baseline — no dependency drift, no state contamination between runs.

Reduced attack surface. Credentials never enter the sandbox. Network egress is allowlisted. The execution environment is ephemeral and isolated. These aren't optional hardening steps; they're the default.

Faster iteration. The fork-and-register workflow means teams can experiment interactively, stabilize a configuration, and promote it to a named agent — without rewriting infrastructure between prototype and production.

Framework compatibility. Managed Agents work with the orchestration frameworks teams already use. Launch partners include Vercel AI SDK, LiteLLM, Agno, Eigent, and LlamaIndex — so existing workflows don't require a full rewrite to take advantage of managed infrastructure.

Managed Agents for Enterprise

For enterprises that need to run custom managed agents at scale, Google offers the Gemini Enterprise Agent Platform — the same APIs, with added governance, centralized visibility, and organizational-level policy controls.

Managed Agents in the Gemini API are currently available in preview. Enterprise teams can access the same managed agent primitives through the Enterprise Agent Platform, with additional controls for audit, DLP enforcement, and multi-team governance.

Key Takeaways

The Gemini API Managed Agents launch gives developers three things that were previously hard to get together: a capable general-purpose agent (Antigravity) ready to use out of the box, a clean API for defining and deploying custom agents with production-grade security, and a developer experience — CLI, MCP server, Skills — designed for agents building agents.

The infrastructure decisions are sound: persistent environments, environment forking, egress allowlists, and server-side credential injection are the right primitives for production agent deployments. The open-source CLI and Skill reflect Google's acknowledgment that the developer experience for agents is as important as the model capabilities underneath.

For teams building on Eigent's model-agnostic platform, Gemini Managed Agents represent a compelling deployment target — one that pairs well with Eigent's ability to route tasks intelligently across model providers while Google handles the sandboxed execution layer.

To get started, try the Antigravity agent in the AI Studio Playground, read the Managed Agents documentation, and install the Python SDK or JavaScript SDK.

Frequently Asked Questions

What are Gemini API Managed Agents?

Gemini API Managed Agents are autonomous AI agents that run inside Google-hosted, sandboxed Linux environments. A single call to the Interactions API provisions the sandbox, starts an agent powered by Gemini, and executes your task — including code execution, web browsing, and file management — without any infrastructure setup on your part.

What is the Antigravity agent?

Antigravity is Google's general-purpose managed agent on the Gemini API, powered by Gemini 3.5 Flash. It can reason and plan, execute code, manage files, and browse the web inside a secure remote Linux environment. It uses the same agent harness that powers the Antigravity IDE and other Google first-party agent products.

How do persistent environments work?

The first interaction call with environment="remote" provisions a new sandbox and returns an environment_id. Passing that ID in subsequent calls resumes the agent in the same environment — with all files, installed packages, and state preserved. This enables stateful multi-turn workflows without re-setup between calls.

How do I build a custom managed agent?

Use the Agents API to define a named agent by specifying a base agent, instructions, and sources (GitHub repos, GCS objects, or inline content). Once registered, invoke your agent by name via the Interactions API. Alternatively, iterate interactively with Antigravity, then fork the resulting environment into a named agent using client.agents.create() with a base_environment pointing to an existing environment_id.

How does the credentials proxy work?

The managed agent egress proxy sits between the sandbox and the internet. You configure an allowlist of permitted domains and, optionally, header transform rules per domain. The proxy injects headers (like Authorization: Bearer <token>) into matching outbound requests automatically — so the sandbox code never has direct access to the token values.

Which frameworks are compatible with Gemini Managed Agents?

Gemini Managed Agents work with Vercel AI SDK, LiteLLM, Agno, Eigent, and LlamaIndex out of the box at launch. The Interactions API is REST-based, so any HTTP-capable orchestration framework can integrate with it.

What is the Gemini API CLI?

The Gemini API CLI is an experimental open-source tool designed for coding agents to interact with the Gemini API. It supports running prompts, generating images and audio, and managing the full managed agent lifecycle — init, test, create, and run — from the command line.

Are Gemini Managed Agents available for enterprise use?

Yes. The same Managed Agents APIs are available through the Gemini Enterprise Agent Platform, with additional governance controls, centralized visibility, DLP enforcement, and organizational policy management. Managed Agents in the Gemini API are currently available in preview.