Gemini Managed Agents Explained: What Developers Need to Know

Google has been pushing Gemini API toward autonomous workflows for a while, but the tool that actually changes how teams ship AI agents arrived at Google I/O in spring 2026. Gemini Managed Agents let you spin up a working agent sandbox with a single API call — no container orchestration, no infrastructure to babysit, no manual state management. It sounds like just another wrapper around a language model at first glance. In practice, it's a separate infrastructure layer that handles isolation, file storage, network rules, and the entire lifecycle of the execution environment. All a developer has to do is describe the task and read the result.

This article covers what Gemini Managed Agents actually are, how they work under the hood, which ready-made agents Google ships, what risks to watch for, and how all of this fits alongside infrastructure you run yourself — a VPS hosting your backend, task queue, or proxy layer for Gemini API calls, for example.

What Gemini Managed Agents Actually Are

Managed Agents on Gemini API amount to a configurable agent harness: a set of prebuilt components that take a prompt or instruction, launch an isolated Linux sandbox, and let the model reason, write and execute code, read and create files, and reach out to the internet. All of this happens through a single call to the Interactions API — the same endpoint that now handles every agentic and multi-turn scenario in Gemini API. The environment itself runs on Ubuntu with Python 3.12 and Node.js 22 preinstalled, along with a baseline toolkit — git, curl, wget, jq, ripgrep, htop, and a dozen other utilities that normally have to be installed by hand when building an agent sandbox from scratch.

Put simply, Google took on a chunk of work that used to require a dedicated infrastructure team: sandbox scaling, OS-level isolation, state snapshots, and cleanup of idle environments. A developer describes the task and, if needed, attaches a data source — a GitHub repository, a Cloud Storage bucket, or a plain text file with instructions — and the agent takes it from there, operating within its allotted resources.

How It Works: From API Call to Finished Result

The process breaks down into a handful of steps, and it's worth understanding them before wiring Gemini Managed Agents into a production pipeline.

Step 1. Call the Interactions API. You send a request specifying an agent (the default Antigravity agent, for instance) and the task description. You can also set the environment — either "remote" for a fresh sandbox, an existing environment ID, or a config object listing sources and network rules.

Step 2. Environment provisioning. The sandbox spins up within seconds, with fixed resources of 4 CPU cores and 16 GB of memory. If the config lists sources — repository, gcs, or inline — the files get mounted into the working directory before the agent starts.

Step 3. The agent's working loop. The underlying model defaults to Gemini 3.6 Flash, though 3.5 Flash and 3.5 Flash-Lite are also selectable. It reasons through the task, runs code, reads and writes files, and, if network access is allowed, reaches out to external resources. A single loop can span several "reason → act → observe" iterations, and token usage per interaction typically runs anywhere from 100,000 to 3 million, depending on task complexity.

Step 4. The environment lifecycle. The sandbox doesn't disappear the moment a request finishes — it moves to an Idle state, takes an automatic snapshot, and shuts down after roughly 15 minutes of inactivity. From there it sits Offline for up to 7 days, long enough to reconnect to the same environment ID and keep working with the same files and installed packages already in place. After a week, the environment is deleted automatically.

Antigravity Agent, Deep Research, and Custom Agents

Google ships two ready-made managed agents plus a mechanism for building your own. Antigravity agent is the general-purpose option: it writes and runs code, works with files, and searches the web from inside its sandboxed environment. It also serves as the foundation for custom setups — agent_config lets you swap the underlying model, while AGENTS.md and SKILL.md files let you layer in your own instructions, skills, and data. The second built-in option is Deep Research, an agent built for autonomous multi-step research — market analysis, due diligence, literature reviews. It plans its own steps, gathers sources, and synthesizes a final report without step-by-step oversight from the developer.

Save a configured environment as a named agent, and you can call it later by ID — handy for teams that want consistent agent behavior across a project. The current cap sits at 1,000 managed agents per project, and two features aren't there yet: versioning with rollback to a prior configuration, and nesting subagents inside a single agent.

Pros and Cons of Gemini Managed Agents

The managed-agent model brings clear advantages to teams without the headcount to run a dedicated infrastructure group around AI agents, but it comes with trade-offs worth weighing up front. Before moving any critical product logic onto Gemini Managed Agents, it's worth checking these pros and cons against your specific project — they determine whether the free tier is enough to start, or whether you should budget for token costs right away.

Strengths: zero infrastructure setup — the sandbox spins up on API call; reusable environments that keep files and installed packages between sessions; flexible model choice to match task and budget; a ready toolset for coding and web search out of the box; compatibility with popular frameworks — LangChain, LlamaIndex, CrewAI, Vercel AI SDK, Google ADK; a free tier for experimentation with a limited quota.

Weaknesses: public preview status — Google explicitly warns that schemas and behavior may change, and support is limited; no agent versioning, which complicates rollback after a bad configuration change; the agent still can't read binary files, only text and images; token spend on complex tasks can get significant, running into the millions per interaction; network access is unrestricted by default, which is worth keeping in mind from day one.

Limitations and Risks

The core risk here isn't the model itself — it's autonomy. The agent can execute code and reach out over the network on its own, without step-by-step confirmation for each action. The model choice is secondary; what matters is the boundaries you set for it. By default, a sandbox has unrestricted outbound network access — for sensitive data or integrations, that's worth locking down with a domain allowlist, adding only the addresses the agent actually needs for the task.

Credentials are passed through an egress proxy and injected into request headers — they never land inside the sandbox as environment variables or files, but the agent can still use whatever access you've granted it. The practical rule follows from that: issue tokens with the minimum necessary permissions and a short lifespan, rather than standing keys with broad scope. Worth noting — Google itself recommends reviewing agent output manually before applying generated code or config changes to real systems, especially when production data is involved. There are also hard technical limits to keep in mind: mounted repositories are capped at 500 MB, Cloud Storage objects at 2 GB, and inline sources at 1 MB per file and 2 MB total. These rarely bite on typical tasks, but they're worth remembering when prepping larger datasets.

CHOOSE A SERVER

Practical Use Cases

Script and utility prototyping. A single Gemini API call can have the agent install dependencies, write a data-processing script, and verify it runs — no local environment setup required on your own machine.

Working with a private repository. Using a repository source with an authorization token, the agent clones the codebase, runs the test suite, and fixes failing checks, and you can download the result as an environment archive through the Files API.

Research tasks. Deep Research fits well for gathering and synthesizing information about a market or technology — the agent decides which sources to check and how to structure the final report, which is useful when preparing analysis for product decisions.

A named agent for your team. With AGENTS.md and SKILL.md you describe a working style, available skills, and data once, save it as a dedicated agent, and call it by ID from different services and scripts — the configuration gets reused instead of rewritten for every task.

A backend service orchestrating agents. If you're building a product around Gemini API — an automated code-review service or a report generator, say — the orchestration layer (task queues, webhooks, interaction history storage) usually lives separately from the managed agents themselves. That's where your own VPS comes in: it runs the API proxy, cache, and request queue while Google's agents handle the heavy lifting inside their own sandbox. Serverspace offers VPS plans with flexible CPU and memory configurations for backend services like this, plus ready-made images for Python and Node.js — so the API layer spins up almost as fast as the agent sandbox itself.

Common Mistakes When Working with Managed Agents

• Leaving the agent's network access wide open instead of configuring a domain allowlist.
• Handing out long-lived keys with broad permissions where a short-lived, task-scoped token would do.
• Not saving the environment ID and spinning up a fresh sandbox each time instead of reusing an already-configured environment with its packages installed.
• Using preview functionality for sensitive or proprietary data, despite Google's explicit guidance against it at this stage.
• Deploying agent-generated code or configuration without manual review, especially for tasks that touch production data.

There's also an architectural mistake worth flagging: teams try to cram orchestration logic — scheduling, retries, state storage across independent tasks — into the managed agent itself. An agent handles a specific task well within its own session, but it isn't a substitute for a task queue or scheduler; that logic belongs in your own service.

Conclusion

Gemini Managed Agents solve a concrete engineering problem: launching an autonomous AI agent used to require dedicated infrastructure for sandboxing, isolation, and state storage, and now a single call to the Interactions API covers all of it. Antigravity agent handles a broad range of code-and-files tasks, Deep Research fits research-heavy scenarios, and the AGENTS.md/SKILL.md combination lets you assemble a named agent tailored to your team. That said, the public preview status and the network access left open by default aren't details to skip — they're things to plan for before connecting Gemini Managed Agents to real data. The sensible approach: test scenarios on non-critical tasks first, keep network and credential permissions to a minimum, and keep the service's orchestration layer on your own infrastructure, whether that's a VPS running an API proxy or a full backend.

FAQ