Gemini Managed Agents let a developer start a long-running agentic job with the Gemini Interactions API while Google provisions and operates the Linux sandbox in which the agent reasons, writes and runs code, manages files and retrieves web material. Google’s July 28, 2026 update added the controls that make the preview much more relevant to marketing operations: Gemini 3.6 Flash as the default, pre/post tool hooks, a total-token budget, scheduled triggers, environment inspection and free-tier access.
This is not another launch summary. It is an implementation guide for a controlled recurring workflow—for example, collecting approved first-party marketing sources, producing a cited change brief and stopping before publication. The existing DMT agent-harness guide owns the broader architecture; this page shows how to assemble and operate the Gemini-specific controls.
Managed Agents in one table
| Capability | Current official behaviour | Marketing implementation decision |
|---|---|---|
| Agent harness | Antigravity managed agent via the Interactions API | Use for bounded, multi-step jobs that genuinely need code/files/web; do not use it for a single summary |
| Default model | Gemini 3.6 Flash for the preview agent | Pin a model when reproducibility or cost comparison matters |
| Environment | Isolated remote Linux sandbox with Python 3.12 and Node 22 | Keep secrets out of prompts/files; configure outbound network restrictions |
| Hooks | Pre- and post-tool command or HTTP handlers | Block unapproved tools/domains before execution; validate outputs after writes |
| Budget | max_total_tokens covers input, output and thinking | Set a task-level ceiling and handle incomplete as a normal state |
| Scheduling | Triggers bind an agent, environment, prompt and cron schedule | Reuse durable files carefully; persist cursors and receipts, not uncontrolled state |
| Network | Outbound network is unrestricted by default | Apply an allowlist; “sandboxed” does not mean “no internet” |
| Preview economics | Free tier available; environment compute unbilled during preview; model tokens still matter | Instrument tokens, tools, retries and review time; do not assume future pricing |
The reference workflow: a controlled marketing change monitor
The example job checks an allowlist of official product/documentation pages, compares them with the previous run, writes a source ledger and a concise marketing-impact brief, then stops for human approval. It does not publish, send messages or crawl arbitrary sites.
- Read
state/cursors.jsonand the source allowlist. - Fetch only allowed URLs; record status, canonical URL and retrieval time.
- Diff normalized text or structured release data against the previous snapshot.
- For material changes, write
output/change-brief.mdandoutput/source-ledger.json. - Run a post-write validator that rejects uncited material claims and unexpected domains.
- Return the files and a machine-readable run receipt.
- Require a human or separate release worker to decide whether any content should be created or published.
This separation is important. A useful content machine has discovery, qualification, production and release states; combining all four in one autonomous prompt hides errors and makes rollback difficult.
1. Install the official SDK and create a client
Google’s announcement uses the official @google/genai JavaScript/TypeScript SDK. Install it in a dedicated project and supply the API key through the environment or your secret manager—not a checked-in source file.
npm install @google/genai
# optional: install Google's Interactions API skill in a coding assistant
npx skills add google-gemini/gemini-skills --skill gemini-interactions-apiUse a project without active billing if you are deliberately testing the free tier, but still implement a budget. “Free tier” is an access/pricing state, not protection from runaway logic or future pricing changes.
2. Start the managed interaction with an explicit budget
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
agent: "antigravity-preview-05-2026",
input: `Run the approved marketing change-monitor workflow.
Read /workspace/config/sources.json.
Fetch only allowed domains.
Write /workspace/output/change-brief.md and source-ledger.json.
Do not publish, email, post, or modify an external system.`,
agent_config: {
type: "antigravity",
model: "gemini-3.6-flash",
max_total_tokens: 20000
},
environment: "remote"
});
console.log(interaction.status);
console.log(interaction.output_text);max_total_tokens covers input, output and thinking. Pick the number from a measured dry run plus a modest safety margin. A very high cap is not a plan; it merely moves the failure boundary.
3. Add pre-tool and post-tool hooks
Place hook configuration in .agents/hooks.json inside the managed environment. A pre-tool hook can deny a call before it executes. A post-tool hook can lint, normalize, scan or validate the result after execution. Google supports command and HTTP handlers and regular-expression matchers.
{
"source-policy": {
"pre_tool_execution": [
{
"matcher": "web_fetch|code_execution|write_file",
"hooks": [
{
"type": "command",
"command": "python3 /.agents/hooks-scripts/policy_gate.py",
"timeout": 10
}
]
}
]
},
"evidence-check": {
"post_tool_execution": [
{
"matcher": "write_file",
"hooks": [
{
"type": "command",
"command": "python3 /.agents/hooks-scripts/validate_evidence.py",
"timeout": 20
}
]
}
]
}
}A denial response follows Google’s documented pattern: {"decision":"deny","reason":"..."}. The reason returns to the model so it can choose a compliant next step. Your gate should default to deny when input is malformed, a domain is not allowlisted or the requested action exceeds the run’s mutation policy.
| Control | Pre-tool check | Post-tool check |
|---|---|---|
| Source rights | URL domain/path is on the allowlist | Ledger contains source URL, owner and capture time |
| Filesystem | Write target stays under /workspace/output or /workspace/state | Required files exist and parse |
| External mutation | Deny email, social, CMS and unknown network tools | Receipt proves zero external writes |
| Claims | Prompt requires primary evidence | Every material claim maps to a ledger entry |
| Secrets | Reject credentials in tool arguments | Scan output for secret patterns before return |
4. Treat network access as a separate security boundary
Google describes the sandbox as OS-isolated, but outbound network is unrestricted by default. Those are different controls. A compromised dependency or an over-broad prompt can still send data outward if you permit arbitrary egress. Configure the environment’s network allowlist for the exact official domains and package registries required by the task.
- Prefer a closed list of official source hosts.
- Pin packages and lockfiles; do not let every run install arbitrary dependencies.
- Use Google’s credential injection/egress-proxy pattern so the model does not read raw credentials.
- Use short-lived, least-privilege credentials.
- Exclude client CRMs, ad accounts and production CMS credentials from a discovery environment.
5. Handle budget exhaustion as a normal state
When the total-token limit is reached, the interaction can return status: "incomplete". Google preserves the environment, so you can continue with previous_interaction_id and a fresh budget. Do not automatically continue forever. First inspect the partial output and decide whether the remaining work is still valuable.
if (interaction.status === "incomplete") {
// Human or policy service checks the partial receipt first.
const continuation = await client.interactions.create({
previous_interaction_id: interaction.id,
input: "Continue only the unfinished evidence-validation step. Do not refetch completed sources.",
agent_config: {
type: "antigravity",
max_total_tokens: 6000
}
});
}Record why the first budget was insufficient. Repeated continuation usually signals an oversized reader job, uncontrolled source scope, poor state reuse or a validation loop that never converges.
6. Add a scheduled trigger without creating a publishing robot
A trigger binds the agent, environment, prompt and cron schedule. Each run can reuse the same sandbox, which is useful for cursors and normalized source snapshots. It also means stale or compromised files persist. Keep a versioned state manifest, validate it at the start, and make the job capable of rebuilding state from primary sources.
| Persist | Do not persist |
|---|---|
| Canonical source registry | Long-lived API keys |
| ETag/Last-Modified/content hash | Unreviewed executable downloads |
| Last successful cursor | Raw customer data |
| Prior run receipt and schema version | Temporary prompt injection text |
| Approved taxonomy and rules | Hidden assumptions from a failed run |
For marketing, schedule discovery and qualification separately from publication. A daily monitor can produce candidate packages; a release worker should act only on an approved item after duplicate, rights, quality and CMS gates. This is the same queue discipline recommended in DMT’s Work/Codex automation guide.
7. Monitor the environment and clean it up
Use the Environments API to list, inspect and delete sandboxes. Google says inactive environments are deleted after seven days and may cold-start after spin-down; do not build a critical recovery plan around an undocumented warm state. The preview limit is up to 1,000 agents, but a large quota is not a reason to create one environment per trivial task.
- Log interaction ID, environment ID, agent/model, start/end time and status.
- Log total tokens, continuations, tool calls, denied calls and validation failures.
- Store hashes and paths for output files.
- Record whether a human accepted, rejected or corrected the result.
- Delete the environment when the workflow is retired or sensitive state should not persist.
Cost and capacity planning
Google warns that a typical managed-agent interaction can consume roughly 100,000 to 3 million tokens. That wide range makes task decomposition and acceptance measurement essential. Environment compute is unbilled during the preview and free-tier projects can experiment, but those facts can change; they do not make token waste or reviewer time free.
| Metric | Why it matters |
|---|---|
| Tokens per run | Shows raw model consumption and whether scope is growing |
| Cost per accepted brief | Includes failed and rejected runs, not just the successful call |
| Denied tool-call rate | High rate can reveal a prompt-policy mismatch or attack attempts |
| Continuation rate | Shows whether the token budget or task boundaries are realistic |
| Human correction minutes | Often dominates model cost in low-quality workflows |
| Fresh material discoveries per run | Prevents an active monitor from becoming a noise machine |
Run-receipt schema
Make every scheduled interaction return a small machine-readable receipt even when it also produces Markdown. A practical schema is:
{
"run_id": "2026-08-11T19:00:00+05:30",
"interaction_id": "...",
"environment_id": "...",
"agent": "antigravity-preview-05-2026",
"model": "gemini-3.6-flash",
"status": "completed",
"source_checks": 28,
"material_changes": 2,
"candidates_created": 1,
"tokens_total": 143220,
"tool_calls": 47,
"denied_calls": 1,
"continuations": 0,
"external_mutations": 0,
"output_files": [
{"path":"output/change-brief.md","sha256":"..."},
{"path":"output/source-ledger.json","sha256":"..."}
],
"blockers": [],
"next_action": "human_review"
}Validate this receipt after the interaction. A model saying “external_mutations: 0” is not proof by itself; pair it with the tool log and network/mutation policy. Hashes help show which artifact the reviewer accepted.
Common implementation failures
| Failure | Why it happens | Correction |
|---|---|---|
| Agent repeatedly refetches every source | No cursor/hash contract or persistent state is distrusted | Store canonical URL, ETag/hash and last successful check; rebuild only on schema failure |
| Budget reached before validation | Research has no source cap or the agent spends the entire budget drafting | Reserve explicit validation budget and split discovery from drafting |
| Hook blocks legitimate calls | Matcher/policy is broader than the task contract | Log denials, add narrow allow rules and keep the default deny |
| “Sandboxed” workflow leaks data | Outbound egress remained unrestricted | Use an allowlist and credential proxy; scan arguments for sensitive values |
| Same candidate appears every run | Deduplication uses headline text only | Use canonical event/source IDs plus DMT owner and reader-job state |
| Persistent environment drifts | Packages/files change without a manifest | Pin dependencies, version state and periodically rebuild from a clean environment |
Model-selection and escalation policy
Gemini 3.6 Flash is the current default and Google also lists Gemini 3.5 Flash and 3.5 Flash-Lite. Pin the model in evaluations. A sensible workflow uses the cheapest configuration that meets the acceptance rubric, then escalates only failed or high-risk items. Escalation should be caused by an observable condition—conflicting primary sources, validation failure, an incomplete interaction after one bounded continuation—not by the agent’s self-reported desire for a stronger model.
Production checklist
- The reader job genuinely needs an agentic loop.
- The model and preview agent ID are explicit.
- The task has a total-token ceiling and bounded continuation policy.
- Outbound network is allowlisted.
- Credentials are short-lived, least-privilege and not visible to the model.
- Pre-tool hooks deny unexpected domains, paths and mutations.
- Post-tool hooks validate evidence, schema, secrets and required files.
- Persistent state has a schema version, cursor and rebuild path.
- Every run writes a receipt and an acceptance decision.
- Publication and other external mutations remain in a separately approved stage.
FAQ
Are Gemini Managed Agents generally available?
No. Google labels Managed Agents as a public preview. Review outputs and actions before sensitive workflows and re-check documentation before production commitments.
Is the sandbox disconnected from the internet?
No. Google documents OS-level isolation but unrestricted outbound network by default. Configure an allowlist when data exfiltration or arbitrary downloads would be harmful.
What happens when max_total_tokens is reached?
The interaction can pause as incomplete while preserving environment state. You can continue with the previous interaction ID and a fresh budget after reviewing the partial work.
How this guide was verified
DMT checked the July 28 Google announcement against the current Gemini API Managed Agents, hooks, Antigravity and Interactions documentation, captured the official control examples, and separated public-preview facts from this article’s recommended operating design. Code derived from documentation is presented as an implementation pattern and must be tested against the current SDK before production.
Bottom line
The 2026 update makes Gemini Managed Agents a credible building block for recurring technical marketing work, but the safety comes from the surrounding design—not the word “managed.” Use hooks to enforce policy, budgets to bound loops, allowlists to control egress, durable state to avoid rework, receipts to make runs auditable and human approval before external mutation. Then measure cost per accepted output instead of admiring how much autonomous activity the agent produced.
Continue with DMT’s accepted-result measurement method, agent cost-control playbook and worker/reviewer separation pattern when turning this architecture into a production content or research system.
