| name | managed-agents |
| description | Use this skill when running Gemini API Managed Agents through the Interactions API, especially background execution (background=True, poll and reconnect by interaction id), attaching remote MCP servers as tools, custom function calling with the requires_action flow, and reusing a server side sandbox across turns with environment_id. Covers the antigravity managed agent, the client.interactions SDK surface, and the agent vs model gotcha. SDKs and tools used, google-genai Python SDK (client.interactions), Python 3.10+, Gemini API key. |
Gemini Managed Agents Skill
Managed Agents run server side in a Google hosted sandbox that can write files and run code for you. The Interactions API drives them, through client.interactions in the google-genai SDK. July 2026 added four capabilities on top of the existing managed agents. Three are covered below with verified code, background execution, remote MCP tools, and custom function calling. The fourth, network credential refresh, is documented on the antigravity agent page linked at the bottom.
[!IMPORTANT]
The managed agent is antigravity-preview-05-2026, powered by Gemini 3.5 Flash. Pass it in the agent field, never model. Passing it as model returns HTTP 400, "antigravity-preview-05-2026 is not supported as a model. Use it as an agent instead." Google's own background execution doc shows model= here, which throws, while the antigravity agent doc and Google's Interactions API skill both correctly use agent. The name carries preview for a reason, expect it to change, do not hardcode it as permanent.
[!IMPORTANT]
client.interactions lives in google-genai 2.x, which requires Python 3.10 or newer. Install pip install "google-genai>=2.3.0". On the Python 3.9 that ships with macOS, pip caps at 1.47.0, which does not have client.interactions, and the samples will AttributeError, that is an interpreter version issue, not a missing feature. Managed agent interactions also require environment="remote".
[!WARNING]
Managed Agents are not new in July 2026, they already existed. The Interactions API itself went GA in June 2026, but the managed agent model is still Preview, and environment compute is not billed during preview, that will change. You still pay for tokens.
Quick Start
Set the key once, then create a client.
export GEMINI_API_KEY=your_key_here
import os, time
from google import genai
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
AGENT = "antigravity-preview-05-2026"
Background execution, fire and reconnect
Kick off a long task, get an id back immediately, then poll it from anywhere, no held connection.
inter = client.interactions.create(
agent=AGENT,
input="Create a folder stream-tools/ and write chapters.py inside that turns "
"a list of video timestamps into YouTube chapter markers.",
environment="remote",
background=True,
)
interaction_id = inter.id
print(inter.status)
while True:
rec = client.interactions.get(interaction_id)
if rec.status != "in_progress":
break
time.sleep(2)
for step in rec.steps:
print(step.type, getattr(step, "name", ""))
[!WARNING]
A background interaction that creates its own sandbox returns environment_id as None, on the create response AND on the completed record, so that sandbox can never be referenced again. Passing an existing environment_id INTO a background create works and the files persist. The pattern, seed the sandbox with one foreground turn to get its environment_id, then run any number of background turns inside it, see the next block.
[!TIP]
To resume a dropped live stream instead of polling, client.interactions.get(id, stream=True, last_event_id=last_seen) replays from the last event you saw.
[!IMPORTANT]
The id is your ONLY handle on an interaction. A dropped connection does not kill the work, a foreground streaming run killed mid task kept working server side and was fully retrievable by get(id) afterward. But there is no list endpoint (GET on the interactions collection returns 404), so an interaction whose id you never captured is unrecoverable even though it completed. Persist the id the moment you receive it, and prefer background=True, which returns the id instantly instead of at the end of the run.
Reuse a sandbox across turns with environment_id
A foreground interaction returns environment_id. Chain the next turn with both previous_interaction_id and environment to land in the same sandbox with your files intact.
first = client.interactions.create(
agent=AGENT,
input="Write episode-notes.txt containing the single line: background agents keep working.",
environment="remote",
)
second = client.interactions.create(
agent=AGENT,
previous_interaction_id=first.id,
environment=first.environment_id,
input="List the files and show the contents of episode-notes.txt.",
)
[!WARNING]
Forget environment on the chained call and you get a brand new sandbox with none of your files. Both previous_interaction_id and environment are required together.
Attach a remote MCP server as a tool
The agent keeps its built in sandbox tools and also gets the remote MCP server's tools in the same interaction.
inter = client.interactions.create(
agent=AGENT,
input="Do I need a jacket in Berlin today? Use the weather tool.",
environment="remote",
tools=[{
"type": "mcp_server",
"name": "weather",
"url": "https://gemini-api-demos.uc.r.appspot.com/mcp",
}],
)
[!WARNING]
A remote MCP server is a live network dependency inside your agent run. Observed live, a second tool call on this demo server returned CONNECTION_CLOSED mid interaction, the error surfaced as a function_result step with agent_error and the agent still answered from the data it already had. Treat a remote MCP server like any other flaky upstream, expect per call failures in the step trace and have a fallback.
Custom function calling, the requires_action flow
Add your own tools next to the sandbox tools. The agent pauses at status == "requires_action", you run the pending function_call steps, then return each function_result.
final = client.interactions.create(
agent=AGENT,
previous_interaction_id=inter.id,
environment=inter.environment_id,
input=[{
"type": "function_result",
"call_id": fc_step.id,
"result": your_result,
}],
)
Interaction record shape
create and get return an Interaction object. inter.steps is a list of typed step objects, in the order the agent produced them. Which tool-step types appear depends on how the agent solved the task (it may write a file or run code).
step.type | key attributes |
|---|
thought | summary |
function_call | name, arguments (dict), id |
function_result | result (list of text parts), call_id, is_error |
code_execution_call | arguments.code, arguments.language, id |
code_execution_result | result (str), call_id, is_error |
model_output | content (list of text parts, each with .text) |
Statuses observed against the live API, in_progress, completed, requires_action.
Supporting files
- scripts/agent.py, tiny SDK helper,
create, get, poll, show_steps (handles both file-write and code-execution step traces). Import it, the three demos below do.
- scripts/background_run.py, fire a background task and print the id. Run it, then pass the id to the next one.
- scripts/reconnect.py,
python reconnect.py <id>, poll by id and print the step trace the agent ran while you were disconnected.
- scripts/mcp_tool.py, attach the demo weather MCP server and print what the agent called.
- requirements.txt, the one dependency,
google-genai>=2.3.0 (Python 3.10+).
Documentation Pages
You MUST fetch the matching page below before writing code. These hosted docs are the source of truth for parameters, types, and edge cases, do not rely solely on the examples above. The SDK samples need google-genai >= 2.3.0 on Python 3.10+, and the background execution page shows model= where the working call needs agent=.
From the episode
Built live on the Friday stream, video link to follow.
