Gemini Managed Agents Can Now Deny Tool Calls, and Run on a Free API Key

Google DeepMind added environment hooks to Gemini API Managed Agents on July 28, 2026. A hook runs a script you supply right before and right after the agent invokes a tool. If the script returns a denial, the tool call never executes. Philipp Schmid and Mariano Cocirio of Google DeepMind published the announcement on the official developer blog.

Managed Agents works like this: one API call provisions an isolated Linux sandbox that Google hosts, and inside it the agent runs code, installs packages, writes files, and browses the web. It launched in preview on May 19, 2026, and you shape agent behavior with AGENTS.md and SKILL.md markdown files. Ramp, ResembleAI, and Klipy were named as early testers.

The convenience came with one hole. The sandbox lives on someone else's server, so there was nowhere to put your own code to inspect what the agent produced.

Google filled that gap in two steps over two months. The July 7 release covered runtime and connectivity: pass background: true and the API returns an interaction ID immediately while long jobs keep running server-side, so you no longer hold an HTTP connection open. Remote MCP server connections and custom function calling landed then too. The July 28 release covers control.

The hook runs on Google's server, not yours

Your validation script executes inside the Google sandbox rather than on your laptop. Where the hook runs is the part that changed in this release.

Alston Lin, founder and CTO of the AI investment bank OffDeal, described the gap directly in the announcement. OffDeal's analysis agent Archie places more than 30 company logos into materials bankers will use, and each logo needs checking: is it the right company, are the size and aspect ratio correct, is the background transparent, is there enough contrast against a white slide?

Before agent hooks, we couldn't do this on Gemini Managed Agents. The sandbox is remote, so there was no place for our verification code to run.

Now, the moment Archie writes a company list, a post_tool_execution hook runs the logo verification pipeline inside the sandbox. It gathers candidates, applies pixel-level quality checks, then confirms each logo with Gemini vision. Only files that pass make it into the manifest, and images absent from the manifest cannot enter the deliverable.

Configuration means dropping a .agents/hooks.json into the environment. The matcher field takes a regular expression, so you can group several 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 }
        ]
      }
    ]
  }
}

With this config, gate.py runs every time the agent is about to execute code or write a file. If the script returns {"decision": "deny", "reason": "..."}, the runtime skips that tool call and passes the refusal reason into the model's context. The agent reads why it was blocked and looks for another route. Besides command, which runs a script inside the sandbox, handlers support an http type that POSTs to an external endpoint.

Free tier, and a cap on token spend

The second change is entry cost. Managed Agents now works with an API key from a project that has no billing enabled. Per the official docs, charges apply to Gemini model tokens and tool usage, and environment compute is not billed during preview.

Google opened the door for free but left token control to you. The docs state that a single interaction typically consumes 100K to 3M tokens. Because the agent runs multiple turns autonomously, one mistake is expensive. agent_config.max_total_tokens caps the combined total of input, output, and thinking 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 cap is hit, execution halts on the spot and the interaction returns status: "incomplete". Environment state survives, so attaching a fresh budget to previous_interaction_id resumes from where it stopped. Running out of budget does not force a restart from scratch, which lowers the cost of retries.

Schedule triggers bundle an agent, environment, prompt, and cron schedule into a single persistent resource. Every run reuses the same sandbox, so files persist between runs. The Environments API lets you list, inspect, and delete sandbox sessions from code, which is how you recover an environment ID after a dropped connection or clean up at the end of a pipeline instead of waiting out the 7-day TTL.

The default model changed as well. The antigravity-preview-05-2026 agent now runs on gemini-3.6-flash, applied automatically from your next interaction with no code changes. To cut cost further, set agent_config.model to gemini-3.5-flash-lite.

Who holds the sandbox

What separates the three agent SDKs is not benchmark scores but who operates the execution environment. Google put both the sandbox and the policy-script runtime inside its own API. The OpenAI Agents SDK offers nine sandbox clients and lets you pick: Blaxel, Cloudflare, Daytona, Docker, E2B, Modal, Runloop, Vercel, and local Unix. Anthropic's Claude Agent SDK exposes fine-grained hook events, but they run inside your own process, so you provide the isolation yourself.

Choosing Google's path ties you to the Gemini API. The sandbox, hook runtime, and scheduler all sit inside Google, so switching models later means moving a lot. In exchange, a single API key with no payment method attached gets you a cloud agent with policy, budget, and schedule already wired in. When Google's ADK Go 2.0 added human approval steps to graph workflows, developers still ran that approval logic on their own servers. These hooks execute entirely inside Google.

Remote MCP connections arrived back on July 7. The mcp_server tool attaches private databases or internal APIs to the sandbox, and layering hooks on top means external tool calls pass through the same policy script. The stateless MCP specification was finalized on the same day, July 28, so if you operate remote MCP servers it is worth reviewing both changes together.

What preview still can't do

The official docs list six preview constraints.

• antigravity-preview-05-2026 is the only available base_agent.
• There is no agent versioning or rollback. Change a definition and there is no official path back to the previous state.
• There is no subagent delegation. Splitting work to run in parallel requires orchestration on the calling side.
• The limit is 1,000 managed agents per project.
• Environments are permanently deleted after 7 days of inactivity, and VMs shut down after a shorter idle period.
• The free tier carries its own request limits and usage quotas.

Hooks also stop at the granularity of a tool call. Once code is running inside the sandbox, hooks do not watch what it does next. If you must place credentials in the sandbox, the network credential refresh path added on July 7 keeps token lifetimes short: keep the same environment_id and pass new network settings, and the filesystem and installed packages stay intact while only the credentials rotate.