How to Use Gemini Managed Agents (Background Tasks and Remote MCP in the Interactions API)

Read time: ~7 minutes. Key facts:

  • Google shipped a Managed Agents update to the Gemini Interactions API on July 7, 2026.
  • A managed agent runs from a single endpoint — Gemini handles reasoning, code execution, package installation, file management, and web access inside an isolated cloud sandbox.
  • The new release adds background execution (background=true, requires store=true), remote MCP server tools, custom function calling (a requires_action step), and network credential refresh via environment_id.
  • The Interactions API has been Generally Available since June 2026 and is Google’s recommended interface for new projects.

Sourcing note: the quickstart code and parameters are from Google’s official Managed Agents Quickstart and Interactions API overview; the four new features are from Google’s July 7 announcement. Where the docs don’t publish an exact status string or schema field, this guide says so instead of inventing one — confirm those against the live docs. Links at the bottom.

Building an autonomous agent usually means you own the hard parts: a sandbox to run code, package installation, file handling, retry logic, and a way to survive long-running tasks without a fragile open HTTP connection. Google’s Managed Agents in the Gemini Interactions API move all of that server-side. As of the July 7, 2026 update, you call one endpoint and Gemini runs the whole loop in an isolated cloud sandbox — and now it can run in the background, reach your private MCP servers, and hand control back to your code when it needs a local function. Here’s how to use each piece, with the code Google actually documents.

1. What a managed agent is

From the official docs: “With managed agents in the Gemini Interactions API, you call a single endpoint and Gemini handles reasoning, code execution, package installation, file management and web information inside an isolated cloud sandbox.”

The key mental model: a managed agent isn’t a chat completion. It’s an agent that Google runs for you. You send an instruction; Gemini plans, writes and executes code in a sandbox, installs whatever packages it needs, reads and writes files, and returns the result. You don’t provision the sandbox, and you don’t babysit the loop.

The interface is the Interactions API, which has been Generally Available since June 2026 and is Google’s recommended interface for all new projects.

2. Quickstart: your first managed agent

Install the Google GenAI SDK and create a client. From the official quickstart:

from google import genai

client = genai.Client()
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

Now run an agent. This example (verbatim from Google’s quickstart) asks the agent to write code, save a file, then read it back — all inside the remote sandbox:

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. Then read the file and print its contents.",
    environment="remote",
)
print(f"Interaction ID: {interaction.id}")
print(f"Environment ID: {interaction.environment_id}")
print(f"Output: {interaction.output_text}")

Three things to note:

  • agent="antigravity-preview-05-2026" is the current managed-agent version. (Google also documents custom agents you define yourself — e.g. a "fibonacci-analyst" — but the default managed agent is where you start.)
  • environment="remote" provisions a fresh isolated sandbox for this run. You can instead pass an existing environment_id to reuse a warm sandbox (more on that in §6).
  • The response carries interaction.id, interaction.environment_id, and interaction.output_text — the agent’s final result, after it has already executed the code and file operations for you.

That’s a complete autonomous agent in ~10 lines, with no sandbox to run yourself.

3. New: background execution for long-running tasks

The headline of the July 7 update. Long agent runs (deep research, multi-step builds) don’t fit a single synchronous HTTP call — the connection times out or drops. Background execution fixes that: the API returns immediately with an ID, the agent keeps working server-side, and you poll for the result.

Per the announcement, you enable it with background=true. One hard constraint from the docs: background execution requires store=true — the docs state store=false is “incompatible with background execution,” because the server needs to persist the interaction state while it runs.

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Analyze the last 30 days of deployment logs and summarize the top failure causes.",
    environment="remote",
    background=True,
    store=True,   # required when background=True
)
print(f"Started: {interaction.id}")
# The call returns right away — the agent runs remotely.

You then poll the interaction by its ID until it finishes, and read the output. The docs describe this poll-until-done pattern (start in the background, then check status in a loop and retrieve the result when it’s done) but do not publish the exact status field name or its string values in the overview page — so rather than hard-code a value here, retrieve the interaction by id and check its status against the current status enum in Google’s docs. The important part is the shape: fire once, get an ID, poll, collect the result — no fragile long-held connection.

This is the right pattern for anything that might run for minutes: research agents, batch code generation, or multi-tool workflows.

4. New: remote MCP servers

The second big addition. Your agent often needs data that only lives behind your own APIs — a private database, an internal deployment tracker. Previously that meant writing proxy middleware. Now you attach a remote MCP server directly as a tool, and the agent calls it inside the same run.

From the Interactions API docs, an MCP tool is passed in tools with type: 'mcp_server', a name, the server URL, and auth headers:

const interaction = await client.interactions.create({
  agent: "antigravity-preview-05-2026",
  input: "Check the status of my last server deployment.",
  tools: [
    {
      type: "mcp_server",
      name: "Deployment Tracker",
      url: "https://mcp.example.com/mcp",
      headers: { Authorization: "Bearer my-token" },
    },
  ],
  background: true,
});

The agent now has your built-in sandbox tools plus your private MCP server in the same interaction — no custom proxy layer. This is what turns a generic code-running agent into one that can act on your systems. (If MCP is new to you, it’s the open Model Context Protocol for exposing tools and data to LLMs; here Gemini is the MCP client, your server is the tool provider.)

5. New: custom function calling with requires_action

Not every tool should run in Google’s sandbox — sometimes the agent needs your local code (business logic, a function only your app can execute). The update adds custom function calling: you register custom tools alongside the built-in ones, and when the agent decides to call one, the interaction transitions to a requires_action state (via “step matching”). Your client runs the function locally, returns the result, and the agent continues.

The pattern, in shape: provide custom tool definitions → agent hits requires_action → you execute locally → submit the result → the run resumes. This is the same “the model pauses and asks your code to do something” loop you may know from function calling, but now composed inside a managed-agent run that’s also doing sandboxed code execution. Confirm the exact submit-result method name against the docs before wiring it up.

6. New: keep the sandbox warm with credential refresh

Long-lived agents hit a practical problem: access tokens and API keys expire mid-session, but you don’t want to throw away a sandbox that already has packages installed and files written. The update adds network credential refresh — pass the existing environment_id with a new network configuration, and per the announcement the sandbox state and installed packages remain intact while the credentials update.

Combined with §2’s environment_id reuse, this is how you run a stateful, long-lived agent: provision once, keep the warm environment across interactions (via environment_id), preserve conversation history (via previous_interaction_id, below), and refresh credentials without a cold restart.

7. Multi-turn state: previous_interaction_id

For a conversation across multiple interactions.create calls, pass previous_interaction_id. The server retrieves the prior history so you don’t resend the full transcript. The docs note it preserves only the conversation history (inputs and outputs) — other parameters stay interaction-scoped, so re-declare tools/config on each call.

followup = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Now chart those failure causes as a bar chart and save it as a PNG.",
    environment=interaction.environment_id,      # reuse the warm sandbox
    previous_interaction_id=interaction.id,      # carry the conversation
)

Reusing environment_id and previous_interaction_id together gives you continuity of both the sandbox and the conversation — the agent still has the files it wrote in the previous turn.

8. When to use this (and the honest caveats)

Use managed agents when you want autonomous, code-executing behavior without running your own sandbox infrastructure — research agents, data analysis, code generation that runs and self-checks, or agents that must reach your internal systems over MCP. Background execution makes the long-running cases practical, and remote MCP makes them useful on your data.

Be clear-eyed about a few things:

  • It’s a managed cloud service. Your inputs, and whatever the sandbox touches, run on Google’s infrastructure — factor that into data-sensitivity decisions. For fully on-prem control you’d run an open-weight model and your own agent loop instead.
  • The agent versions are preview-dated (antigravity-preview-05-2026) — expect them to move; pin the version you test against.
  • A couple of exact values (background poll status strings, the custom-function submit method) aren’t spelled out on every doc page — this guide flags those rather than guessing. Check the live docs when you implement them.
  • Pricing and model coverage weren’t specified in the July 7 announcement — confirm current pricing before you build a cost model.

The takeaway

Google’s July 7, 2026 Managed Agents update turns the Gemini Interactions API into a place to run real autonomous agents from one endpoint: Gemini executes code, installs packages, and manages files in an isolated cloud sandbox, and the new release adds the four things production agents actually need — background execution (background=true + store=true) for long tasks, remote MCP tools to reach your private systems, custom function calling (requires_action) for local logic, and credential refresh that keeps a warm sandbox alive. Start with the ~10-line quickstart, add background=true when a task outgrows a single request, and attach an mcp_server tool when the agent needs your data. Just pin the preview agent version and confirm the few unspecified values against Google’s live docs.

For more on Gemini in practice, see how to use Gemini 3.5 Flash, the Gemini 3.5 Flash overview, and why long-running coding agents drift.

Sources

  • Expanding Managed Agents in Gemini API — Google blog, July 7, 2026 — the four new features: background execution (background=true), remote MCP server tools, custom function calling with requires_action (“step matching”), and network credential refresh via environment_id (sandbox state/packages preserved); single-endpoint managed agents in an isolated cloud sandbox; @google/genai SDK
  • Managed Agents Quickstart — Gemini API docs — client init (from google import genai / GoogleGenAI), client.interactions.create(agent="antigravity-preview-05-2026", input=..., environment="remote"), returned id / environment_id / output_text, custom agents
  • Interactions API overview — Gemini API docs — GA since June 2026; background=true requires store=true (store=false incompatible with background); previous_interaction_id preserves conversation history only; observable execution steps
  • Agent versions are preview-dated and subject to change; exact background poll status values, the mcp_server schema fields, and the custom-function submit method should be confirmed against the live docs. Pricing/model coverage not specified in the July 7 announcement. Verified July 8, 2026.