Créer des agents managés avec l'API Gemini : guide complet pour les développeurs

Les agents autonomes capables de raisonner, d’écrire et d’exécuter du code, de naviguer sur le web et de gérer des fichiers nécessitaient auparavant des semaines de travail d’infrastructure. Avec le lancement de Managed Agents sur l'API Gemini, Google a réduit cette configuration à un seul appel API. Une requête suffit pour lancer un sandbox Linux éphémère et sécurisé hébergé par Google — avec un agent prêt à effectuer un vrai travail à l’intérieur.

Ce guide couvre tout ce que les développeurs doivent savoir : comment fonctionne l’agent Antigravity, comment créer et déployer des agents personnalisés, comment forker des environnements pour des exécutions reproductibles, comment verrouiller le réseau et les identifiants, et comment la nouvelle Gemini CLI s’intègre dans un workflow centré sur les agents.

Que sont les Managed Agents de l’API Gemini ?

Les Managed Agents sont le nouveau primitive de développement de Google pour les agents IA autonomes sur l’API Gemini. Au lieu d’assembler vous-même la logique d’orchestration, les environnements d’exécution de code, l’infrastructure d’appel d’outils et les contrôles de sécurité, l’API prend tout cela en charge.

Un seul appel à l’Interactions API provisionne un environnement Linux sandboxé, lance un agent propulsé par Gemini et exécute votre tâche de bout en bout. L’agent peut raisonner et planifier, appeler des outils, exécuter du code, gérer des fichiers et naviguer sur le web — le tout dans un runtime sécurisé géré par Google pour vous.

Deux interfaces rendent cela possible :

• L’Interactions API — l’interface d’exécution. Envoyez une tâche, recevez en retour un agent qui raisonne et agit.
• L’Agents API — le plan de contrôle. Définissez, enregistrez et gérez des agents nommés avec des instructions, des outils, des compétences et des configurations d’environnement personnalisées.

L’agent Antigravity : un agent polyvalent prêt à l’emploi

Le premier agent managé polyvalent sur l’API Gemini est Antigravity. Il est propulsé par Gemini 3.5 Flash et s’exécute sur le même harness que l’IDE Antigravity et d’autres produits d’agents first-party de Google. Avant Antigravity, Deep Research était le seul agent managé disponible — un agent spécialisé pour les workflows de recherche en plusieurs étapes.

Antigravity est son équivalent polyvalent : un seul appel API qui provisionne un environnement Linux distant et se met au travail.

Ce que Antigravity peut faire

Dans son sandbox managé, l’agent Antigravity peut :

• Raisonner et planifier à l’aide du harness d’agent Gemini
• Exécuter du code et gérer des fichiers dans un environnement Linux sécurisé
• Naviguer sur le web pour récupérer et traiter des données en temps réel
• Utiliser des outils comme la recherche web, l’exécution de code et les opérations d’E/S de fichiers

Votre premier appel API Antigravity

Voici l’appel Antigravity le plus simple possible — un seul appel API qui provisionne un environnement distant, exécute l’agent et renvoie le résultat :

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Research the top 10 AI stories today and create a PDF briefing with summaries",
    environment="remote",  # Remote Linux environment hosted by Google
)

print(interaction.output_text)

Voilà. Pas de configuration de conteneur. Pas de code de sandboxing. Pas d’ossature pour l’appel d’outils. Google s’occupe de tout.

Environnements persistants : agents stateful à plusieurs tours

Les environnements persistent entre les appels. La première interaction provisionne un sandbox et renvoie un environment_id. Passez cet ID dans les requêtes suivantes et l’agent reprend avec tous les fichiers, paquets et états exactement là où le précédent appel s’est arrêté.

# First call — provisions a new remote environment
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    environment="remote",
    input="Research the top 10 AI stories today and create a PDF briefing with summaries",
)

# Second call — resumes in the same environment with full state intact
interaction_2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    environment=interaction.environment_id,
    previous_interaction_id=interaction.id,
    input="Now create a landing page using javascript and html",
)

print(interaction_2.output_text)

C’est cette persistance d’état qui rend les workflows multi-étapes pratiques. Un agent qui installe des paquets, écrit des fichiers et exécute des analyses lors d’un appel peut transmettre tout cela de manière transparente au suivant — sans réinitialisation, sans retéléchargement, sans réexécution.

Les environnements acceptent aussi des données externes au démarrage : dépôts Git, objets Google Cloud Storage ou contenu inline peuvent tous être montés dans le sandbox avant que l’agent ne commence à travailler.

Créer des agents managés personnalisés

L’agent Antigravity couvre bien les tâches généralistes. Mais les cas d’usage en production nécessitent presque toujours un comportement personnalisé — instructions spécifiques, compétences métier, outils propriétaires ou sources de données sélectionnées. C’est à cela que sert l’Agents API.

Les agents managés Gemini vous permettent d’assembler des instructions, des compétences, des outils et un environnement dans un agent nommé que vous invoquez par ID. Au lieu d’écrire un code d’orchestration complexe, vous définissez tout de manière déclarative — dans des fichiers markdown comme AGENTS.md et SKILL.md — puis vous les enregistrez une fois pour toutes.

Définir un agent à partir de sources

Créez un agent depuis zéro en spécifiant des instructions système et des sources. Les sources peuvent être des dépôts GitHub, des chemins Google Cloud Storage ou du contenu inline. La plateforme provisionne un sandbox vierge avec vos fichiers à chaque invocation.

agent = client.agents.create(
    name="data-analyst",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "You are a data analyst agent..."
            },
            {
                "type": "inline",
                "target": ".agents/slide-maker/SKILL.md",
                "content": "Instructions for creating slides..."
            },
            {
                "type": "github",
                "source": "https://github.com/my-org/data-templates.git",
                "target": "/workspace/"
            },
            {
                "type": "gcs",
                "source": "gs://my-bucket/analysis-skills/",
                "target": "/.agents/skills/"
            },
        ]
    }
)

result = client.interactions.create(
    agent="data-analyst",
    input="Analyze Q1 revenue data and create a slide deck.",
    environment="remote",
)

print(result.output_text)

Une fois enregistré, data-analyst devient un agent durable que vous pouvez invoquer par son nom. Chaque exécution provisionne un environnement propre avec votre configuration exacte — aucune fuite d’état entre les invocations.

Forker un environnement existant

Parfois, la voie la plus rapide vers un agent personnalisé est l’itération. Commencez par travailler de manière interactive avec l’agent de base Antigravity — installez des paquets, créez des modèles, configurez l’environnement — puis forkez ce snapshot d’environnement en un agent nommé réutilisable.

# Step 1: Iterate with the base agent in a remote environment
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Install pandas and matplotlib. Create an analysis template.",
    environment="remote"
)

# Step 2: Create a new agent from the existing environment snapshot
agent = client.agents.create(
    name="my-data-analyst",
    base_agent="antigravity-preview-05-2026",
    instructions="You are a data analyst that creates slide presentations.",
    base_environment=interaction.environment_id,
)

Une fois enregistré, chaque invocation suivante de my-data-analyst forkera à partir de ce snapshot de base — en repartant à chaque fois d’un état propre et préconfiguré.

result = client.interactions.create(
    agent="my-data-analyst",
    input="Analyze Q1 revenue data and create a slide deck.",
    environment="remote"
)

print(result.output_text)

Le schéma fork-and-register est particulièrement efficace pour les agents qui dépendent d’une configuration lourde : graphes de dépendances complexes, gros artefacts de modèles ou modèles précompilés qui prendraient trop de temps à reconstruire à chaque invocation.

Réseau sécurisé et proxy d’identifiants

Les agents en production doivent presque toujours accéder à des services externes — GitHub, API internes, registres de paquets — et presque toujours le faire sans exposer d’identifiants sensibles dans le sandbox. Les agents managés gèrent les deux grâce à un proxy d’egress configurable.

La configuration réseau sert deux objectifs :

1. Les allowlists restreignent les connexions sortantes aux domaines explicitement autorisés, empêchant un agent d’atteindre des services externes non souhaités.
2. Les transformations d’en-têtes injectent les identifiants côté serveur, afin que les jetons API et secrets ne soient jamais transmis dans l’environnement sandbox lui-même.

agent = client.agents.create(
    id="issue-resolver",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/my-org/backend",
                "target": "/workspace/repo",
            }
        ],
        "network": {
            "allowlist": [
                {
                    "domain": "api.github.com",
                    "transform": {
                        "Authorization": "Bearer ghp_your_github_token"
                    },
                },
                {"domain": "pypi.org"},
            ]
        },
    },
)

Dans cette configuration, l’agent ne peut accéder qu’à api.github.com et pypi.org. Toute tentative de connexion à un autre domaine est bloquée. Les requêtes GitHub sont automatiquement transformées pour inclure l’en-tête Authorization — le code dans le sandbox ne voit jamais le jeton directement.

Cette architecture est essentielle pour les agents déployés sur des dépôts de code internes, des API propriétaires ou tout environnement où l’hygiène des identifiants est une exigence de conformité.

La CLI Gemini API : une expérience développeur centrée sur l’agent

En plus de l’API, Google a publié une Gemini API CLI open source expérimentale conçue pour permettre aux agents de code d’interagir avec l’API Gemini de manière structurée et adaptée aux agents.

# Run a prompt against any model
gemini-api run "What is the capital of France?"

# Image generation
gemini-api run "A cat in space" --model gemini-3.1-flash-image-preview --output cat.png

# Text-to-speech
gemini-api run "Hello from Gemini" --model gemini-3.1-flash-tts-preview --voice Kore --output hello.wav

# Scaffold, test, and deploy an agent
gemini-api agents init my-agent
gemini-api agents test --prompt "Analyze the Q1 revenue data"
gemini-api agents create

# Run against a deployed agent
gemini-api run "Summarize this quarter" --agent my-agent

Le workflow agents init / agents test / agents create reflète un changement dans la façon dont Google attend des développeurs qu’ils construisent sur l’API Gemini : définir le comportement de l’agent dans des fichiers, tester localement, déployer comme agent managé nommé — le même schéma familier des outils infrastructure-as-code.

Outils complémentaires

Au-delà de la CLI, deux ajouts permettent aux agents de code de rester à jour avec l’API Gemini :

• Gemini API Docs MCP server — fournit un accès en direct à la documentation Gemini, aux SDK et aux informations sur les modèles via MCP. Les agents de code peuvent interroger la documentation directement au lieu de se fier à des données d’entraînement obsolètes.
• gemini-interactions-api Skill — injecte automatiquement dans le contexte d’un agent les patterns et bonnes pratiques de l’Interactions API, afin que les agents construits avec les Managed Agents Gemini écrivent dès le départ un code d’interaction idiomatique.

Pourquoi les Managed Agents comptent pour les cas d’usage en production

L’idée centrale derrière les Managed Agents est que la majeure partie du travail difficile dans le développement d’agents ne concerne pas le modèle — mais l’infrastructure autour. Le sandboxing, l’intégration des outils, la gestion des identifiants, la reproductibilité des environnements et la sécurité réseau sont autant de problèmes que chaque équipe qui livre des agents doit résoudre indépendamment. Les Managed Agents en font désormais le problème de Google.

Ce changement a des implications concrètes pour les déploiements en production :

Exécutions reproductibles. Les environnements forkés garantissent que chaque invocation d’agent démarre depuis une base identique — aucune dérive de dépendances, aucune contamination d’état entre les exécutions.

Surface d’attaque réduite. Les identifiants n’entrent jamais dans le sandbox. L’egress réseau est allowlisté. L’environnement d’exécution est éphémère et isolé. Ce ne sont pas des étapes de durcissement optionnelles ; c’est le comportement par défaut.

Itération plus rapide. Le workflow fork-and-register permet aux équipes d’expérimenter de manière interactive, de stabiliser une configuration et de la promouvoir en agent nommé — sans réécrire l’infrastructure entre le prototype et la production.

Compatibilité framework. Les Managed Agents fonctionnent avec les frameworks d’orchestration que les équipes utilisent déjà. Les partenaires de lancement incluent Vercel AI SDK, LiteLLM, Agno, Eigent, et LlamaIndex — les workflows existants n’ont donc pas besoin d’être entièrement réécrits pour profiter de l’infrastructure managée.

Les Managed Agents pour l’entreprise

Pour les entreprises qui doivent exécuter des agents managés personnalisés à grande échelle, Google propose la Gemini Enterprise Agent Platform — les mêmes API, avec en plus de la gouvernance, une visibilité centralisée et des contrôles de politique au niveau de l’organisation.

Les Managed Agents dans l’API Gemini sont actuellement disponibles en preview. Les équipes enterprise peuvent accéder aux mêmes primitives d’agents managés via l’Enterprise Agent Platform, avec des contrôles supplémentaires pour l’audit, l’application du DLP et la gouvernance multi-équipes.

Points clés à retenir

Le lancement des Managed Agents de l’API Gemini offre aux développeurs trois choses qu’il était auparavant difficile d’obtenir ensemble : un agent généraliste capable, prêt à l’emploi dès le départ (Antigravity), une API propre pour définir et déployer des agents personnalisés avec une sécurité de niveau production, et une expérience développeur — CLI, serveur MCP, Skills — conçue pour des agents qui construisent des agents.

Les choix d’infrastructure sont solides : environnements persistants, fork d’environnements, allowlists d’egress et injection d’identifiants côté serveur sont les bons primitives pour déployer des agents en production. La CLI open source et la Skill reflètent la reconnaissance par Google que l’expérience développeur des agents est aussi importante que les capacités du modèle sous-jacent.

Pour les équipes qui construisent sur la plateforme agnostique de modèles d’Eigent, les Managed Agents Gemini représentent une cible de déploiement très intéressante — une solution qui s’associe bien à la capacité d’Eigent à acheminer intelligemment les tâches entre plusieurs fournisseurs de modèles pendant que Google gère la couche d’exécution sandboxée.

Pour commencer, essayez l’agent Antigravity dans le AI Studio Playground, consultez la documentation Managed Agents, et installez le Python SDK ou le JavaScript SDK.

Questions fréquentes

Que sont les Managed Agents de l’API Gemini ?

Les Managed Agents de l’API Gemini sont des agents IA autonomes qui s’exécutent dans des environnements Linux sandboxés hébergés par Google. Un seul appel à l’Interactions API provisionne le sandbox, lance un agent propulsé par Gemini et exécute votre tâche — y compris l’exécution de code, la navigation web et la gestion de fichiers — sans aucune configuration d’infrastructure de votre part.

Qu’est-ce que l’agent Antigravity ?

Antigravity est l’agent managé polyvalent de Google sur l’API Gemini, propulsé par Gemini 3.5 Flash. Il peut raisonner et planifier, exécuter du code, gérer des fichiers et naviguer sur le web dans un environnement Linux distant sécurisé. Il utilise le même harness d’agent qui alimente l’IDE Antigravity et d’autres produits d’agents first-party de Google.

Comment fonctionnent les environnements persistants ?

Le premier appel d’interaction avec environment="remote" provisionne un nouveau sandbox et renvoie un environment_id. Le fait de transmettre cet ID dans les appels suivants reprend l’agent dans le même environnement — avec tous les fichiers, paquets installés et états conservés. Cela permet des workflows stateful à plusieurs tours sans réinitialisation entre les appels.

Comment créer un agent managé personnalisé ?

Utilisez l’Agents API pour définir un agent nommé en spécifiant un agent de base, des instructions et des sources (dépôts GitHub, objets GCS ou contenu inline). Une fois enregistré, invoquez votre agent par son nom via l’Interactions API. Vous pouvez aussi itérer de manière interactive avec Antigravity, puis forker l’environnement obtenu en un agent nommé en utilisant client.agents.create() avec un base_environment pointant vers un environment_id existant.

Comment fonctionne le proxy d’identifiants ?

Le proxy d’egress des agents managés se place entre le sandbox et Internet. Vous configurez une allowlist de domaines autorisés et, éventuellement, des règles de transform d’en-têtes par domaine. Le proxy injecte automatiquement des en-têtes (comme Authorization: Bearer <token>) dans les requêtes sortantes correspondantes — le code du sandbox n’a donc jamais accès directement aux valeurs des jetons.

Quels frameworks sont compatibles avec les Managed Agents Gemini ?

Les Managed Agents Gemini fonctionnent d’emblée avec Vercel AI SDK, LiteLLM, Agno, Eigent et LlamaIndex au lancement. L’Interactions API est basée sur REST, donc tout framework d’orchestration capable de faire des requêtes HTTP peut s’y intégrer.

Qu’est-ce que la Gemini API CLI ?

La Gemini API CLI est un outil open source expérimental conçu pour permettre aux agents de code d’interagir avec l’API Gemini. Elle prend en charge l’exécution de prompts, la génération d’images et d’audio, ainsi que la gestion du cycle de vie complet des agents managés — init, test, create et run — depuis la ligne de commande.

Les Managed Agents Gemini sont-ils disponibles pour un usage enterprise ?

Oui. Les mêmes API Managed Agents sont disponibles via la Gemini Enterprise Agent Platform, avec des contrôles de gouvernance supplémentaires, une visibilité centralisée, l’application du DLP et la gestion des politiques organisationnelles. Les Managed Agents dans l’API Gemini sont actuellement disponibles en preview.