Gemini Managed Agents: Build Autonomous Agents with the Interactions API

Gemini Managed Agents let you build autonomous agents with a single API call. The Gemini Interactions API coordinates reasoning, code execution, package installation, file management, and web retrieval inside an isolated cloud sandbox. You don't orchestrate steps — the agent runs in a sandboxed environment until the task is done.

In July 2026, Google expanded Managed Agents significantly: Gemini 3.6 Flash became the default model, environment hooks were added (block/lint/audit tool calls inside the sandbox), plus budget controls, scheduled triggers, and free-tier access.

The Managed Agent Model

A single interaction call runs an agent with its own sandboxed environment:

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
  agent: "antigravity-preview-05-2026",
  input: "Audit all dependencies in package.json, upgrade outdated packages, and verify the build by running npm test.",
  environment: "remote",
});

console.log(interaction.output_text);

If you use an AI coding assistant, add the skill directly:

npx skills add google-gemini/gemini-skills --skill gemini-interactions-api

Model Selection

The antigravity-preview-05-2026 agent now defaults to Gemini 3.6 Flash. No code changes needed — your next interaction picks it up automatically. Explicitly select a model with agent_config.model:

const interaction = await client.interactions.create({
  agent: "antigravity-preview-05-2026",
  input: "Audit all modules in this repo and generate a migration report.",
  environment: "remote",
  agent_config: {
    type: "antigravity",
    model: "gemini-3.5-flash-lite",
  },
});

Environment Hooks

Hooks run your custom scripts before or after every tool call the agent makes inside its sandbox. Add a .agents/hooks.json to your environment; the runtime executes handlers on pre_tool_execution or post_tool_execution events.

The matcher field supports regex — target multiple tools with |, or catch everything with *:

{
  "security-gate": {
    "pre_tool_execution": [
      {
        "matcher": "code_execution|write_file",
        "hooks": [
          { "type": "command", "command": "python3 /.agents/hooks-scripts/gate.py", "timeout": 10 }
        ]
      }
    ]
  },
  "auto-format": {
    "post_tool_execution": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "python3 /.agents/hooks-scripts/auto_lint.py", "timeout": 15 }
        ]
      }
    ]
  }
}

• The security-gate group runs gate.py before every code_execution or write_file call. If the script returns {"decision": "deny", "reason": "..."}, the tool call is skipped and the rejection reason passes into the model's context.
• The auto-format group runs auto_lint.py after every tool to enforce code styling.
• Hooks also support http-type handlers that POST directly to an external endpoint.

This is the answer to the managed-sandbox trust gap: your validation code runs where the agent works. For a fuller security treatment, see Prompt Security.

Budget Controls

Managed agents run autonomous multi-turn loops that can consume significant tokens. Cap total consumption (input + output + thinking) with max_total_tokens:

const interaction = await client.interactions.create({
  agent: "antigravity-preview-05-2026",
  input: "Audit all modules in this repo and generate a migration report.",
  agent_config: {
    type: "antigravity",
    max_total_tokens: 10000,
  },
  environment: "remote",
});

When the limit is reached, execution safely pauses and the interaction returns status: "incomplete". The environment state is preserved — pass previous_interaction_id with a fresh budget to continue where it stopped.

Scheduled Triggers

Automate recurring agent tasks with scheduled triggers. A trigger binds an agent, environment, prompt, and cron schedule into a persistent resource that fires without manual intervention. Each run reuses the same sandbox, so files persist across executions — ideal for daily reports, dependency audits, or watchdogs.

Environments API

The Environments API lets you list, inspect, and delete sandbox sessions from code. Recover environment IDs after a disconnect, or clean up sandboxes when your pipeline finishes instead of waiting for the 7-day TTL.

Free Tier

Managed agents are available on free-tier projects. Experiment with agentic workflows using an API key from a project without active billing.

Common Patterns

Related Pages

• Gemini Function Calling — the tool-use foundation
• Structured Output & JSON — typed agent outputs
• Agentic Prompting — agent design patterns
• Gemini CLI to Antigravity Migration (Blog) — CLI-side Antigravity