Sandboxes à distance à état avec des agents gérés antigravité et le SDK GenAI
Agents gérant l’antigravité avec le GenAI SDK : maintenir une sandbox Ubuntu à distance active entre les tours, se reconnecter via l’ID de l’environnement et récupérer l’aperçu de l’espace de travail.
Sources: Orchestrating with Antigravity: A Crescendo of Agents (Part 1)
Certains développeurs vivent dans le terminal. S’ils ne peuvent pas automatiser un outil à l’aide de bash, ils l’ignorent, et leur flux de travail quotidien en intelligence artificielle repose sur des agents en ligne de commande tels que gemini-cli et son successeur antigravity-cli (agy). C’est la méthode de travail des « BashOps », par opposition aux « ClickOps » qui préfèrent les outils graphiques.
Cette approche rencontre des limites lorsque le travail des agents s’intensifie. Exécuter plusieurs agents de codage en même temps, gérer des boucles à plusieurs étapes et suivre les modifications de fichiers peut signifier de surveiller six à douze fenêtres de terminal réparties sur autant de bureaux virtuels, ce qui devient rapidement une charge mentale importante. La première solution consiste en la persistance : fournir à chaque agent un espace de travail qui survive entre les appels. La deuxième, qui consiste à exécuter en parallèle des sous-agents locaux de manière sécurisée à l’aide de git worktrees, relève d’un sujet distinct.
Ici, nous examinons le fonctionnement des environnements de test distants à état avec les agents gérés Antigravity de Google, en utilisant le SDK Google GenAI ainsi que le modèle d’agent en version préliminaire antigravity-preview-05-2026. Vous verrez comment se reconnecter à un environnement de conteneur et comment récupérer l’espace de travail de l’agent sur votre propre machine depuis une invite de commande locale. L’architecture et le côté hébergé des agents gérés sont abordés en détail ailleurs, par exemple dans l’article de Philipp Schmid expliquant le fonctionnement interne de ces agents. L’objectif ici est de les faire fonctionner de manière programmée afin de créer des boucles d’automatisation.
Agents à état en pratique
Dans une appel API classique avec un agent, il n’y a pas de mémoire persistante. Vous envoyez une instruction, l’agent répond, et l’espace de travail disparaît. Si vous souhaitez qu’il modifie un fichier qu’il a créé lors d’un tour précédent, vous devez renvoyer l’intégralité du fichier dans l’instruction. Cela entraîne une consommation accrue de tokens, une augmentation de la latence, et rend la génération de code sur plusieurs tours lente et coûteuse.
La solution d’Antigravity est le sandbox distant à état. En passant "remote" comme paramètre d’environnement, le SDK s’occupe de ce qui suit :
- il crée un conteneur Ubuntu privé et sécurisé sur Google Cloud ;
- l’agent s’exécute à l’intérieur de ce conteneur ;
- le conteneur reste actif après l’appel, et un
environment_idest retourné pour l’identifier ; - tout appel ultérieur peut se connecter à ce même conteneur et trouver le système de fichiers inchangé.
Le moyen le plus simple de le comprendre est de voir le code.
Exemple : un analyste d’IPO éloigné de Python
Pour illustrer cette idée, voici un script qui orchestre une session d’agent à trois étapes et dotée d’un état. Cet agent joue le rôle d’un analyste d’IPO. Lors de la première étape, il étudie la cotation en bourse d’une entreprise et enregistre un rapport au format Markdown. Lors de la deuxième étape, il se reconnecte au même conteneur, ouvre ce rapport et le reconstitue en tableau de bord HTML avec son propre fichier de style, tout en générant une image correspondante. Lors de la troisième étape, le script télécharge une capture d’écran de l’ensemble de l’espace de travail.
Les fonctionnalités liées à l’état sont mises en œuvre grâce au SDK Python standard de Google GenAI, en appelant le modèle d’agent de prévisualisation avec environment="remote".
import os
import requests
import tarfile
from google import genai
client = genai.Client()
print("🚀 Turn 1: Launching SRE/Financial Agent in remote Ubuntu Sandbox...")
# Turn 1: Launch agent to research and write a report in a remote sandbox
interaction_1 = client.interactions.create(
agent="antigravity-preview-05-2026",
input="Research SpaceX IPO and save report as spacex-report.md.",
environment="remote" # Launches a remote Ubuntu sandbox
)
env_id = interaction_1.environment_id
print(f"✅ Turn 1 Complete. Container Environment ID: {env_id}")
print("\n🔄 Turn 2: Re-attaching to same container and converting to HTML...")
# Turn 2: Re-attach to the SAME sandbox and preserve conversation memory
interaction_2 = client.interactions.create(
agent="antigravity-preview-05-2026",
environment=env_id, # ← Re-attaches to same sandbox
previous_interaction_id=interaction_1.id, # ← Preserves conversation memory
input="Convert that spacex-report.md file into a clean index.html webpage" +
" with styling and generate a custom nanobanana image."
)
print("✅ Turn 2 Complete.")
print("\n📦 Turn 3: Downloading the entire container snapshot (.tar) locally...")
# Turn 3: Download the entire sandbox environment state (.tar) locally
api_key = os.environ.get("GEMINI_API_KEY")
response = requests.get(
f"https://generativelanguage.googleapis.com/v1beta/files/environment-{env_id}:download",
params={"alt": "media"},
headers={"x-goog-api-key": api_key},
)
tar_path = "snapshot_env.tar"
with open(tar_path, "wb") as f:
f.write(response.content)
print(f"✅ Snapshot downloaded to {tar_path}. Extracting...")
with tarfile.open(tar_path) as tar:
tar.extractall(path="./workspace_extract")
# Wow! We've dumped the remote agent workspace locally!
print("🎉 Workspace extracted successfully! Check ./workspace_extract/")
Ce que fait le script, étape par étape :
- Démarrage et investigation. Google lance un conteneur sur une machine Ubuntu, une instance réelle avec un disque réel, et l’agent commence ses recherches.
- Poursuite et conversion. La deuxième étape transforme le Markdown en HTML. C’est une séparation absurde, car la première étape aurait pu produire directement du HTML, mais cela prouve qu’il est possible de mettre de côté le travail aujourd’hui pour le reprendre demain avec la session intacte, voire depuis une application de messagerie.
- Récupération des résultats localement. C’est cette étape qui donne l’impression que tout est réel. Le conteneur contient un espace de travail réel, éventuellement avec un répertoire cloné et des tests unitaires ajoutés. Lors de cette exécution, il contenait le rapport Markdown de la première étape, un
index.html, un fichier d’image et un fichier de style provenant de la deuxième étape.
Ouvrir index.html dans un navigateur affiche le tableau de bord généré, y compris une section comparant les tendances haussières et baissières pour l’analyse des investissements.
Exemple : prototypage d’un petit jeu pour enfants
Le même principe s’applique à la création de logiciels. Prenons par exemple un jeu d’identification des heures pour les enfants. Le problème qu’il résout est concret : un enfant doué en arithmétique peut encore avoir du mal à traduire l’affichage d’une horloge analogique, par exemple affichant 19:45, en la représentation numérique correspondante. Une fois la forme numérique obtenue, il devient facile de calculer des différences comme 08:45 plus ou moins 20 minutes. L’obstacle est purement visuel, ce qui rend utile un jeu permettant de relier les deux représentations.
L’ambition était de créer un jeu mobile multiplateforme en Flutter, en partie parce que les déplacements fréquents rendent utile une application qui fonctionne hors ligne sur le téléphone pendant un vol. Pour commencer, un seul script agent à état a permis de produire le premier prototype. On lui a donné des instructions détaillées en plusieurs étapes lui demandant de lire un fichier de spécifications du produit, d’implémenter le jeu, de démarrer un serveur local, de prendre une capture d’écran et d’ouvrir une demande de fusion sur GitHub.
Le cœur de ce script utilise le SDK google-genai pour configurer le sandbox distant, monter le répertoire git, puis télécharger et extraire l’aperçu final de l’espace de travail :
from google import genai
import requests, os
client = genai.Client()
api_key = os.environ["GEMINI_API_KEY"]
gh_token = os.environ.get("GITHUB_TOKEN") # optional: enables the agent to push a PR
# Mount the git repo AND inject the GitHub token as a file into the sandbox
sources = [
{"type": "repository",
"source": "https://github.com/palladius/orologia.io",
"target": "/workspace"},
{"type": "inline",
"target": "/workspace/.github_token",
"content": gh_token}, # ← secret injection!
]
# The prompt tells the agent exactly what to build
prompt = """
You are an expert full-stack developer agent.
The repo orologia.io is mounted at /workspace.
1. Read docs/PRD.md and implement a beautiful clock-learning game...
2. Make it stunning: analog clock with rotating hands, digital display, ..
3. Optionally screenshot it, then commit and open a PR using the token
at /workspace/.github_token.
""" # Full prompt: https://github.com/palladius/orologia.io/blob/main/solutions/20260615-antigravity-managed-agents/run-agent-prototype.py
# Launch remote stateful sandbox agent
interaction = client.interactions.create(
agent="antigravity-preview-05-2026",
input=prompt,
environment={"type": "remote", "sources": sources}
)
# Download final snapshot locally
url = ...
response = requests.get(url, headers={"x-goog-api-key": api_key}, params={"alt": "media"})
Au lieu de se lancer directement dans une application Flutter complexe, l’agent a écrit un prototype rapide et temporaire en HTML, CSS et JavaScript classiques. Ayant reçu une description du comportement de l’horloge ainsi que de son boucle de rétroaction en une seule étape, l’agent a créé une application d’horloge interactive en environ une minute. Il a également conçu des options interactives qui associent une heure analogique à plusieurs boutons de réponse numériques.
Cela a démontré la valeur du prototypage rapide par un seul agent. Passer à plus d’un prototype constitue un problème différent, car la mise en œuvre du jeu complet en Flutter avec plusieurs sous-agents en même temps est là où une simple boucle CLI commence à poser des difficultés. Gérer cela de manière sûre exige des worktrees git isolés ainsi qu’une configuration d’orchestration dédiée.
À quoi servent les agents distants
La question naturelle est de savoir à quoi servent réellement ces agents distants. On pourrait argumenter que tout est plus pratique en localhost. Une interprétation plus intéressante consiste à les considérer comme la première étape vers des « Dockerfiles pour agents ». On commence par expérimenter localement, puis on crée progressivement un conteneur d’agent avec ses propres scripts, un dossier de configuration d’outil et éventuellement une clé de compte de service cloud. En peu de temps, on dispose d’un environnement sécurisé, autonome et reproductible où un agent peut accéder à Internet, grâce à une combinaison puissante de git clone et de clés API.
Conseils pratiques :
- Évitez cela pour une investigation ponctuelle. L’interface web ou une CLI locale sont bien plus rapides.
- Utilisez-le pour des workflows répétables où la configuration est bien plus complexe que la requête finale. Si vous exécutez cinq requêtes et que les quatre premières ne changent jamais tandis que la cinquième change constamment, c’est là le cas idéal.
- Essayez également les outils en ligne de commande de l’API Gemini, décrits par Philipp Schmid dans son guide de développement pour les agents gérés.
Un exemple de cas répétable est un planificateur de voyage familial containerisé où vous indiquez uniquement la destination, les dates et les contraintes. Il fonctionne un peu comme un modèle affiné, à ceci près que tout le système de fichiers est observable et modifiable, ce qui vous permet de télécharger le index.html généré par la suite. Lors d’une seule exécution, un agent a élaboré un plan complet de voyage sur une île, avec une carte itinéraire et des liens de réservation vérifiables, à partir de trois requêtes dont les deux premières sont restées constantes.
Précautions avant de l’adopter
Quelques vérifications essentielles s’appliquent à toute configuration de ce type :
- Un snapshot peut contenir tout ce que l’agent a vu, y compris les répertoires clonés et toutes les identifiants que vous avez montés. Traitez le fichier tar comme étant sensible et évitez d’inclure les clés de compte de service dans les sandboxes sauf si c’est absolument nécessaire.
- Le nom du modèle indiqué ici correspond à une version préliminaire obsolète. Fixez-le délibérément, en sachant que le comportement et les points d’entrée peuvent changer.
- Conservez l’ID de l’environnement dans un endroit fiable. Le perdre signifie perdre la capacité de le réassocier.
- Vérifiez quel est le coût d’un sandbox à état et combien de temps il reste actif avant de compter sur des workflows du type « revenir demain ».
Lectures complémentaires
- Agents de codage parallèles avec des worktrees Git, le chef d’orchestre et Antigravity 2.0 — Comment un agent coordinateur, des worktrees Git par agent et des pistes basées sur les problèmes permettent de développer une douzaine de fonctionnalités SRE en environ cinq heures, ainsi que des leçons sur les questions relatives à HITL et à l’hygiène des fusionnements.
- Décharger les charges de travail d’Apps Script vers un environnement Linux sandbox géré par Gemini — Comment Google Apps Script peut faire fonctionner un environnement Linux sandbox persistant, transférer des fichiers vers Drive à l’aide de ggsrun, contourner les limites de 50 MB et de tokens, et exécuter des tâches avec Playwright, FFmpeg et esbuild.