Cico Debug

Agenti · Google

Gemini Managed Agents: ora il codice dell'agente gira nella tua sandbox

I Managed Agents della Gemini API accettano ambienti self-hosted: modello e ciclo dell'agente restano su Google, shell e file girano su una macchina tua, collegata con un worker open source che usa solo HTTPS in uscita.

I Managed Agents della Gemini API, finora legati a una sandbox Linux ospitata da Google, ora possono eseguire i propri tool su un’infrastruttura scelta da chi sviluppa: un container, una microVM di un provider cloud, un cluster Kubernetes o il proprio portatile. Google la chiama Self-Hosted Environments. Il modello, il ciclo dell’agente e l’orchestrazione dei tool restano sui server di Google; i sette tool di shell e file girano dentro la tua macchina, collegata da un worker open source che apre solo connessioni HTTPS in uscita e non richiede nessuna porta in ingresso. Google pubblica ricette pronte per otto piattaforme, da Cloud Run a Modal, E2B e Fly.io, più Docker, Podman e l’esecuzione locale: chi ha già una sandbox può usare quella, con le proprie immagini, la propria rete e le proprie regole.

Cosa c’era prima e cosa cambia

Secondo la documentazione degli Agents, una singola chiamata all’API provisiona una sandbox Linux dove l’agente ragiona, esegue codice, gestisce file e naviga il web. L’agente generico è Antigravity, costruito su Gemini 4 Hydrogen; accanto c’è Deep Research. L’ambiente ospitato è Ubuntu con Python 3.12 e Node.js 22, ha CPU e memoria fisse, si ferma dopo 15 minuti di inattività con uno snapshot automatico e viene cancellato dopo 7 giorni senza uso.

Il parametro environment di interactions.create accettava già tre forme: "remote" per una sandbox nuova, l’id di un ambiente esistente per riusarne file e pacchetti, oppure un oggetto di configurazione con sources, regole network e variabili env. La novità è un quarto tipo di ambiente, creato con mode: "self_hosted", che si passa con il suo id come gli altri: il codice del client resta uguale e i tool vengono eseguiti sulla macchina collegata.

Secondo la pagina Environments, sources, network, env e gli snapshot /files valgono solo per gli ambienti di Google, e un ambiente self-hosted li rifiuta con 400 INVALID_ARGUMENT. Clonare il repository, installare i pacchetti, limitare la rete e gestire i segreti diventa quindi compito di chi ospita la sandbox.

Come funziona il worker

Il runtime è dentro la CLI open source gemini-api (repository google-gemini/gemini-api-cli, licenza Apache 2.0, un singolo binario Go per macOS, Linux e Windows). In modalità single-worker un processo gira nel container o nella VM, si aggancia all’ambiente SELF_HOSTED e interroga POST /v1beta/environments:leaseInteractions. Quando un client crea un’interazione su quell’ambiente, l’API consegna al worker l’interazione insieme a un lease token di breve durata (prefisso lt_v1_). Da lì parte il ciclo: l’API invia la chiamata al tool in sospeso, il worker la esegue confinata in --root-dir e --workdir, poi rimanda l’output e rinnova il lease con un heartbeat. A turno finito l’API restituisce la risposta al client. I risultati dei tool, cioè ciò che il modello legge per decidere il passo successivo, passano quindi comunque dalle API di Google: sulla tua macchina restano solo i file e i processi.

I tool integrati sono sette, ognuno con alcuni alias:

  • execute_bash (run_command, run_shell_command, bash, shell): parte in --workdir, ha un timeout per comando (--command-timeout, default 2m), un output massimo di 4 MiB e un ambiente di sistema ripulito; si può spegnere con --disable-bash.
  • view_file (read_file), list_dir, grep_search, find_by_name: lettura e ricerca, confinate a --root-dir tramite os.Root, che blocca .. e i symlink che escono dalla radice.
  • write_to_file (write_file) e replace_file_content (edit_file): scrittura, con lo stesso confinamento.

Come si collega una sandbox

Servono tre passi. Il primo crea l’ambiente con la propria GEMINI_API_KEY:

curl -fsSL -X POST \
  "https://generativelanguage.googleapis.com/v1beta/environments" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "self_hosted"}'

La risposta contiene un id (un UUID, senza prefisso environments/) e una environment_key che l’API restituisce una sola volta, al momento della creazione. Poi, dentro la sandbox, si installa la CLI e si avvia il worker passando solo la chiave dell’ambiente, così la chiave del progetto non entra nell’ambiente di esecuzione:

gemini-api environments connect \
  --environment-key "$GEMINI_ENVIRONMENT_KEY" \
  --root-dir /workspace \
  --workdir /workspace

Infine si manda il compito, dalla propria macchina, indicando l’id come environment:

gemini-api agent run \
  "Create hello.txt and run uname -a in bash." \
  --agent antigravity-preview-05-2026 \
  --body "{\"environment\": \"$GEMINI_ENVIRONMENT_ID\"}"

Il worker ha altre opzioni con default espliciti: --max-concurrent (4 interazioni), --poll-interval (2s), --heartbeat-interval (5s) e --worker-id.

Due topologie: connect oppure poll e serve

Oltre a connect, la guida descrive una modalità divisa pensata per Docker, Podman e Agent Substrate su Kubernetes. Un poller di controllo, gemini-api environments poll, gira in una zona fidata con la chiave API, prende in carico le interazioni e per ognuna lancia un comando di provisioning (--provision-cmd) passandogli su stdin un JSON v1 con interaction_id, environment_id, lease_token, server_url e un custom_config libero, che l’API inoltra senza modificarlo. Il comando avvia un container o un Pod dove gira gemini-api environments serve con solo --interaction-id e --lease-token.

Il vantaggio dichiarato è che nei container di esecuzione non ci sono né chiavi API né chiavi d’ambiente: anche se il codice generato legge /proc/self/environ, non trova credenziali durature. Un solo poller può servire tutti gli ambienti self-hosted di un progetto, e montando un volume per ambiente (gemini-self-hosted-<hash>) su /workspace i file sopravvivono tra un turno e l’altro mentre i container --rm scendono a zero.

Cosa raccomanda Google sulla sicurezza

L’avvertimento principale riguarda execute_bash: --root-dir confina i tool strutturati sui file, ma la shell esegue comandi generati dal modello con bash -c e può leggere $HOME, le chiavi SSH e le credenziali cloud. Per questo la modalità locale è indicata solo per ambienti di sviluppo usa e getta, o con --disable-bash. Per tutto il resto la guida chiede container, microVM o VM, e fornisce una checklist: utente non root 1000:1000, --cap-drop=ALL, no-new-privileges, --pids-limit=256, --memory=2g e --cpus=2, filesystem in sola lettura con scrittura solo su /workspace e un /tmp in tmpfs. Sulla rete il worker ha bisogno solo di HTTPS in uscita (TCP 443) verso generativelanguage.googleapis.com; vanno bloccati le reti private RFC1918 e l’endpoint dei metadati cloud 169.254.169.254.

Provider supportati e prima prova sul campo

La cartella providers/ contiene ricette in tre comandi (crea l’istanza, installa la CLI, lancia connect) per Vercel Sandbox, Daytona, E2B, Modal, Fly.io (Sprites e Machines), Google Cloud Run e Cloudflare Sandbox, affiancate dalla configurazione per Agent Substrate e dai Dockerfile per Docker e Podman.

Su Fly.io uno Sprite va in pausa quando è inattivo, e il polling in uscita non conta come attività (altri provider potrebbero comportarsi allo stesso modo); per questo la ricetta registra il worker come servizio e tiene attivo un task di 5 minuti rinnovato ogni 60 secondi. Il team di Fly.io ha documentato la sua prova nella pull request della guida: con la CLI 0.4.6 e una chiave del piano gratuito, il worker ha preso in carico l’interazione, ha eseguito execute_bash e write_to_file e ha scritto hello.txt. Il compito di due passi ha richiesto circa 10 minuti, quasi tutti di attesa del modello; una seconda prova circa un’ora, con pause fino a 28 minuti.

Prezzi e limiti

I Managed Agents si pagano a consumo, in base ai token del modello e ai tool usati. Secondo Google una singola interazione consuma di solito tra 100.000 e 3 milioni di token; le stime per l’agente Antigravity vanno da 0,25-0,80 dollari per un compito di progettazione a 0,70-3,25 dollari per l’elaborazione dati, fino a circa 5 dollari per flussi da 3-5 milioni di token. Si può fissare un tetto con max_total_tokens in agent_config. Il calcolo della sandbox ospitata non è fatturato durante l’anteprima; quello di una sandbox self-hosted lo paghi al tuo provider, e la guida di Fly.io ricorda che uno Sprite attivo consuma finché il worker gira.

Gli altri limiti: Managed Agents è in Public Preview, con funzioni e schemi che possono cambiare; si possono avere fino a 1.000 managed agent; l’agente legge solo file di testo e immagini. Google precisa che configurazioni e manifest della guida sono implementazioni di riferimento, non un prodotto supportato ufficialmente, e che la CLI è in beta con possibili breaking change tra una release e l’altra.

Cosa resta poco chiaro

La documentazione non dice se il limite di 7 giorni di inattività valga anche per gli ambienti self-hosted, né come si comporti un’interazione quando il worker si scollega a metà turno. Il video di lancio mostra environment: "environments/my-sandbox" con l’agente antigravity-preview-09-2026, mentre le guide self-hosted usano un UUID senza prefisso e antigravity-preview-05-2026: conviene seguire le guide.

Altro in Agenti