Tutoriel : Gemini Managed Agents — background, MCP distant et credentials (juillet 2026)

Tutoriel : Gemini Managed Agents — background, MCP distant et credentials (juillet 2026)

Un agent qui s'arrête quand vous fermez le terminal n'est pas un agent de production. Gemini Managed Agents changent la donne.

Le 7 juillet 2026, Google annonce une extension majeure des Gemini Managed Agents via l'Interactions API, désormais Generally Available depuis juin 2026. Quatre capacités arrivent en production : l'exécution background (background=true, avec store=true), l'intégration de serveurs MCP distants, le function calling custom avec statut requires_action, et le refresh des credentials via environment_id. L'agent par défaut reste Antigravity (antigravity-preview-05-2026), un sandbox Linux managé propulsé par Gemini 3.5 Flash.

Ce tutoriel est conçu pour les développeurs et équipes produit qui veulent passer du prototype à un agent fiable. Nous utilisons exclusivement le SDK google-genai en Python 3.10+, avec des exemples testables alignés sur la documentation officielle Antigravity et le quickstart Managed Agents. Si vous déployez déjà des serveurs MCP, croisez cet article avec notre analyse de la spec MCP 2026-07-28 stateless et notre tutoriel de déploiement MCP en 20 minutes.

---

Pourquoi les Managed Agents changent l'architecture agentique

Avant l'Interactions API GA, construire un agent autonome impliquait d'assembler vous-même : un orchestrateur de boucles tool-use, un sandbox d'exécution de code, un gestionnaire d'état conversationnel, une file de jobs asynchrones, et une couche d'observabilité. Chaque équipe réinventait ce runtime.

Les Managed Agents déplacent ce runtime chez Google. Un seul appel client.interactions.create() provisionne un sandbox Linux isolé, lance la boucle agentique (raisonnement → outil → observation → répétition), et retourne un objet Interaction avec output_text, steps, environment_id et status. Vous vous concentrez sur le quoi (input, tools, instructions) plutôt que sur le comment (orchestration bas niveau).

La mise à jour du 7 juillet 2026 comble les lacunes qui bloquaient la production :

Cette maturité rapproche Gemini des attentes entreprise : jobs traçables, outils standardisés via MCP, secrets rafraîchissables sans perdre l'état du workspace.

---

Prérequis : Python 3.10+, clé API et SDK google-genai

Environnement Python

Le SDK google-genai exige Python 3.10 minimum. Sur Ubuntu ou Debian :

python3 --version   # doit afficher 3.10, 3.11 ou 3.12
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade google-genai requests

Clé API Gemini

Créez une clé sur Google AI Studio. Exportez-la :

export GEMINI_API_KEY="votre-cle-api"

Ne commitez jamais cette clé. En production, utilisez un gestionnaire de secrets (Vault, GCP Secret Manager, variables CI chiffrées).

Premier client

from google import genai

client = genai.Client()  # lit GEMINI_API_KEY automatiquement

De Python 3.10+ au sandbox Linux distant via le SDK google-genai et l'agent antigravity-preview-05-2026

---

Étape 1 : votre première interaction Antigravity

Commençons par une interaction synchrone simple. Trois paramètres suffisent :

• agent="antigravity-preview-05-2026" — version preview actuelle d'Antigravity
• environment="remote" — provisionne un sandbox Linux frais
• input — instruction en langage naturel

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input=(
        "Écris un script Python qui génère les 20 premiers nombres de Fibonacci, "
        "sauvegarde-les dans fibonacci.txt, puis affiche le contenu du fichier."
    ),
    environment="remote",
)

print(f"Interaction ID : {interaction.id}")
print(f"Environment ID : {interaction.environment_id}")
print(f"Status : {interaction.status}")
print(f"Output :\n{interaction.output_text}")

La réponse contient un objet Interaction. Conservez impérativement interaction.id (contexte conversationnel via previous_interaction_id) et interaction.environment_id (état du sandbox : fichiers, packages installés).

Multi-tour : conversation + sandbox

L'API gère deux dimensions d'état indépendantes :

1. Contexte conversationnel — historique, raisonnement, tool calls → previous_interaction_id
2. État du sandbox — fichiers, dépendances, repos clonés → environment_id

interaction_2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    previous_interaction_id=interaction.id,
    environment=interaction.environment_id,
    input="Trace la suite de Fibonacci en graphique et sauvegarde chart.png.",
)

print(interaction_2.output_text)

Le fichier fibonacci.txt du tour 1 est toujours présent. L'agent conserve aussi le contexte conversationnel. La compaction automatique (~135k tokens) évite le « context rot » sur les sessions longues, selon la doc Managed Agents.

Télécharger les fichiers du sandbox

Quand l'agent crée des artefacts (PDF, CSV, images), récupérez-les via l'API Files :

import os
import requests
import tarfile

env_id = interaction_2.environment_id
api_key = os.environ["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},
    allow_redirects=True,
    timeout=120,
)

with open("snapshot.tar", "wb") as f:
    f.write(response.content)

with tarfile.open("snapshot.tar") as tar:
    tar.extractall(path="extracted_snapshot")

---

Étape 2 : exécution background (background=true + store=true)

Les tâches agentiques — cloner un dépôt, lancer des tests, générer un rapport — peuvent prendre plusieurs minutes. Le mode synchrone bloque votre processus Python et risque un timeout HTTP.

La solution : background=True. L'API retourne immédiatement avec status: in_progress. Vous pollez ensuite jusqu'à completed ou failed.

import time
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Clone le dépôt google/generative-ai-python et exécute ses tests.",
    environment="remote",
    background=True,
)

print(f"Tâche lancée : {interaction.id} — status : {interaction.status}")

while interaction.status == "in_progress":
    time.sleep(5)
    interaction = client.interactions.get(id=interaction.id)
    print(f"  Polling… status = {interaction.status}")

if interaction.status == "completed":
    print(interaction.output_text)
elif interaction.status == "requires_action":
    print("Action requise — voir section custom functions.")
else:
    print(f"Terminé avec status : {interaction.status}")

Règle store=true

background=True exige store=True, qui est la valeur par défaut. Si vous passez explicitement store=False, l'exécution background échoue. store=False désactive aussi previous_interaction_id et l'observabilité des steps — réservé aux cas où vous ne persistez aucun état côté serveur.

Création asynchrone, polling GET toutes les 5 secondes, récupération du résultat et de l'environment_id

Pattern production : classe BackgroundRunner

Encapsulez le polling dans un helper réutilisable :

import time
from dataclasses import dataclass
from typing import Optional
from google import genai
from google.genai import types

@dataclass
class BackgroundResult:
    interaction_id: str
    environment_id: Optional[str]
    output_text: str
    status: str
    steps_count: int

def run_background(
    client: genai.Client,
    input_text: str,
    *,
    poll_interval: float = 5.0,
    max_wait: float = 1800.0,
    environment: str = "remote",
    tools: Optional[list] = None,
) -> BackgroundResult:
    kwargs = {
        "agent": "antigravity-preview-05-2026",
        "input": input_text,
        "environment": environment,
        "background": True,
    }
    if tools:
        kwargs["tools"] = tools

    interaction = client.interactions.create(**kwargs)
    elapsed = 0.0

    while interaction.status == "in_progress" and elapsed < max_wait:
        time.sleep(poll_interval)
        elapsed += poll_interval
        interaction = client.interactions.get(id=interaction.id)

    return BackgroundResult(
        interaction_id=interaction.id,
        environment_id=getattr(interaction, "environment_id", None),
        output_text=getattr(interaction, "output_text", "") or "",
        status=interaction.status,
        steps_count=len(getattr(interaction, "steps", []) or []),
    )

Annulation et streaming

Pour annuler une tâche bloquée :

client.interactions.cancel(id=interaction.id)

Pour suivre la progression en temps réel pendant un background job, combinez background=True avec stream=True — voir le guide Streaming de l'Interactions API. Le streaming background émet des deltas de steps (raisonnement, tool calls) utiles pour une UI de monitoring.

Création rapide, exécution agent longue, polling régulier, récupération quasi instantanée

Piège documenté : environment_id et background

Si un run background crée son propre sandbox sans environment_id préalable, le champ peut revenir null à la complétion — le sandbox devient alors inaccessible pour les tours suivants. Pattern recommandé : seedez le sandbox avec un tour foreground, récupérez environment_id, puis enchaînez des tours background en passant cet ID. Nous validons ce comportement en conditions réelles lors de nos audits agents chez BOVO Digital.

---

Étape 3 : connecter un serveur MCP distant

La mise à jour du 7 juillet 2026 permet d'enregistrer des serveurs MCP distants comme outils Antigravity. L'agent découvre les tools via tools/list et les invoque via tools/call — exactement comme Claude ou n8n, mais orchestré par Google.

Configuration minimale

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Interroge le serveur météo et donne la température actuelle à Tokyo.",
    environment="remote",
    tools=[{
        "type": "mcp_server",
        "name": "weather",  # OBLIGATOIRE : minuscules alphanumériques
        "url": "https://gemini-api-demos.uc.r.appspot.com/mcp",
    }],
)

print(interaction.output_text)

Serveur MCP avec authentification

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Liste les 5 derniers deals du CRM et résume le pipeline.",
    environment="remote",
    tools=[{
        "type": "mcp_server",
        "name": "bovo_crm",
        "url": "https://mcp.votre-domaine.com/mcp",
        "headers": {"Authorization": "Bearer VOTRE_TOKEN_MCP"},
        "allowed_tools": ["list_deals", "get_deal", "list_contacts"],
    }],
    background=True,
)

Limitations officielles : le transport SSE n'est pas supporté (Streamable HTTP uniquement). Un name en majuscules provoque une erreur 400 générique. Ces contraintes s'alignent avec la direction stateless de la spec MCP 2026-07-28 — chaque requête MCP doit être autonome derrière un load balancer.

L'agent Antigravity invoque un serveur MCP Streamable HTTP qui expose vos APIs métier

Combiner MCP + background + multi-tour

import time
from google import genai

client = genai.Client()
MCP_TOOLS = [{
    "type": "mcp_server",
    "name": "n8n_ops",
    "url": "https://n8n.votre-domaine.com/mcp-server/http",
    "headers": {"Authorization": "Bearer N8N_MCP_TOKEN"},
    "allowed_tools": ["search_workflows", "execute_workflow"],
}]

# Tour 1 : analyse en background
job = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Via MCP, liste les workflows n8n taggés 'production' et exporte un CSV.",
    environment="remote",
    tools=MCP_TOOLS,
    background=True,
)

while job.status == "in_progress":
    time.sleep(5)
    job = client.interactions.get(id=job.id)

# Tour 2 : même sandbox, nouvelle instruction
followup = client.interactions.create(
    agent="antigravity-preview-05-2026",
    previous_interaction_id=job.id,
    environment=job.environment_id,
    input="Génère un graphique à partir du CSV et sauvegarde report.png.",
    tools=MCP_TOOLS,
    background=True,
)

while followup.status == "in_progress":
    time.sleep(5)
    followup = client.interactions.get(id=followup.id)

print(followup.output_text)

Pour connecter n8n spécifiquement, notre guide connecter n8n à un serveur MCP détaille l'architecture côté orchestrateur. Ici, Antigravity devient le cerveau et votre serveur MCP le bras armé vers les systèmes métier.

---

Étape 4 : custom functions et statut requires_action

Toutes vos APIs ne peuvent pas transiter par MCP. Pour les systèmes internes (ERP legacy, API REST propriétaire, base on-premise), définissez des custom functions que vous exécutez côté client quand l'agent renvoie requires_action.

Définir l'outil

get_weather_tool = {
    "type": "function",
    "name": "get_weather",
    "description": "Retourne la météo actuelle pour une ville donnée.",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "Ville et pays, ex. Paris, France",
            }
        },
        "required": ["location"],
    },
}

Tour 1 : l'agent demande l'exécution

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Quelle est la météo à Tokyo ?",
    environment="remote",
    tools=[
        {"type": "code_execution"},
        get_weather_tool,
    ],
)

print(f"Status après tour 1 : {interaction.status}")

Tour 2 : exécuter localement et renvoyer le résultat

def handle_requires_action(client, interaction):
    if interaction.status != "requires_action":
        return interaction

    executed = {s.call_id for s in interaction.steps if s.type == "function_result"}
    pending = [
        s for s in interaction.steps
        if s.type == "function_call" and s.id not in executed
    ]

    if not pending:
        return interaction

    fc = pending[0]
    print(f"Function demandée : {fc.name} — args : {fc.arguments}")

    # Exécutez VOTRE logique métier ici
    if fc.name == "get_weather":
        result = {"temperature": 23, "unit": "celsius", "condition": "nuageux"}
    else:
        result = {"error": f"Fonction inconnue : {fc.name}"}

    return client.interactions.create(
        agent="antigravity-preview-05-2026",
        previous_interaction_id=interaction.id,
        environment=interaction.environment_id,
        input=[{
            "type": "function_result",
            "name": fc.name,
            "call_id": fc.id,
            "result": result,
        }],
    )

final = handle_requires_action(client, interaction)
print(final.output_text)

Point critique : le function calling Antigravity est stateful uniquement. Vous devez utiliser previous_interaction_id — reconstruire l'historique manuellement (mode stateless) n'est pas supporté selon les limitations officielles.

Boucle complète avec plusieurs function calls

def run_until_complete(client, interaction, max_rounds=10):
    current = interaction
    for _ in range(max_rounds):
        if current.status == "completed":
            return current
        if current.status != "requires_action":
            break
        current = handle_requires_action(client, current)
    return current

Les outils filesystem du sandbox (write_file, read_file) apparaissent aussi comme function_call dans steps, mais sont exécutés automatiquement par l'environnement — filtrez-les via la comparaison call_id / function_result.

---

Étape 5 : refresh des credentials via environment_id

Les agents longue durée butent sur un problème classique : les tokens expirent alors que le sandbox contient déjà des packages installés, des fichiers générés et un contexte utile. La mise à jour du 7 juillet 2026 introduit le network credential refresh : passez l'environment_id existant avec une nouvelle configuration network, et les règles réseau sont remplacées sans toucher au filesystem.

Premier accès avec credentials

from google import genai

client = genai.Client()

first = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Liste les objets du bucket GCS reports/ via l'API.",
    environment={
        "type": "remote",
        "network": {
            "allowlist": [{
                "domain": "storage.googleapis.com",
                "transform": {
                    "Authorization": "Bearer TOKEN_INITIAL"
                },
            }],
        },
    },
)

print(f"Environment ID à conserver : {first.environment_id}")

Refresh sans cold restart

refreshed = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Télécharge reports/q1.csv et calcule les statistiques descriptives.",
    environment={
        "type": "remote",
        "environment_id": first.environment_id,
        "network": {
            "allowlist": [{
                "domain": "storage.googleapis.com",
                "transform": {
                    "Authorization": "Bearer TOKEN_RAFRAICHI"
                },
            }],
        },
    },
)

print(refreshed.output_text)

Les packages installés au tour 1 restent disponibles. Seules les règles réseau changent. En production, intégrez ce pattern dans votre gestionnaire de secrets : quand le token rotate, déclenchez automatiquement la prochaine interaction avec le nouveau Bearer.

Bonnes pratiques sécurité

• Scope minimal : chaque allowlist ne couvre que les domaines nécessaires à la tâche courante
• Tokens courts : préférez des tokens de 15–60 minutes avec refresh automatique
• Jamais dans les logs : redigez les headers Authorization dans vos journaux applicatifs
• Séparation MCP / network : les headers MCP (tools[].headers) et les transforms network sont deux canaux distincts — ne dupliquez pas les secrets

---

Arbre de décision : quel mode choisir ?

Background vs synchrone, MCP vs tools natifs, custom functions vs credential refresh

---

Observabilité, coûts et limites preview

Inspecter les steps

Chaque Interaction expose steps : raisonnement, appels d'outils, exécutions de code. Exploitez-les pour le debug et l'UI :

for i, step in enumerate(interaction.steps or []):
    print(f"[{i}] type={step.type} name={getattr(step, 'name', '—')}")

Estimation des coûts

Selon la documentation Antigravity, une interaction agentique consomme nettement plus de tokens qu'un chat simple — jusqu'à 3–5 millions de tokens sur des workflows complexes (~5 $). Surveillez via streaming et interactions.cancel() si l'agent diverge.

Limitations à connaître (juillet 2026)

• Agent et Interactions API en preview — schémas susceptibles d'évoluer
• Pas de temperature, top_p, max_output_tokens — erreur 400 si passés
• Pas de structured output sur Antigravity
• Entrées multimodales : texte et image uniquement (pas audio/vidéo/document)
• file_search, computer_use, google_maps non disponibles
• Compute sandbox non facturé pendant la preview

---

Intégration dans une stack BOVO Digital type

Voici l'architecture que nous recommandons à nos clients PME et ESN :

1. Serveur MCP maison — expose CRM, base métier, tickets (tutoriel 20 min)
2. Antigravity Managed Agent — raisonnement, code, web, orchestration MCP
3. n8n — triggers métier, alertes, human-in-the-loop (guide n8n + MCP)
4. Credential vault — rotation automatique vers environment_id refresh

L'agent Antigravity ne remplace pas n8n : il complète l'orchestration visuelle pour les tâches agentiques lourdes (analyse, génération de code, recherche) pendant que n8n gère les workflows déterministes (webhooks, SLA, notifications).

---

Étape 6 : sauvegarder un agent managé personnalisé

Une fois votre configuration stabilisée (instructions, skills, sources, règles réseau), persiste-la comme managed agent réutilisable par ID. Vous évitez de répéter la configuration à chaque interaction.

agent = client.agents.create(
    id="analyste-donnees-bovo",
    base_agent="antigravity-preview-05-2026",
    system_instruction=(
        "Tu es un agent d'analyse de données. Génère toujours un tableau récapitulatif "
        "et un graphique. Exporte les résultats en CSV et PNG."
    ),
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "Priorité : reproductibilité et traçabilité des calculs.",
            },
            {
                "type": "repository",
                "source": "https://github.com/votre-org/skills-analyse",
                "target": ".agents/skills",
            },
        ],
    },
)

print(f"Agent sauvegardé : {agent.id}")

Invoquez-le ensuite par son identifiant — chaque run forke le base_environment pour partir d'un état propre tout en conservant vos instructions et skills :

result = client.interactions.create(
    agent="analyste-donnees-bovo",
    input="Analyse le dataset ventes_q2.csv et produis un rapport exécutif.",
    environment="remote",
    background=True,
)

Ce pattern est particulièrement utile quand plusieurs équipes partagent le même profil agent (support, ops, data) avec des garde-fous identiques. Chez BOVO Digital, nous versionnons ces définitions dans Git et les déployons via CI, exactement comme un serveur MCP.

Streaming en production

Pour une interface utilisateur qui affiche la progression, préférez le streaming synchrone ou le streaming background documenté dans l'Interactions API :

stream = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Analyse les 10 derniers articles de blog et propose un plan éditorial.",
    environment="remote",
    stream=True,
)

for event in stream:
    if hasattr(event, "delta") and event.delta:
        print(event.delta, end="", flush=True)

Le streaming expose les tokens de raisonnement et les mises à jour d'outils en direct — indispensable pour le debug et l'acceptation utilisateur. Combinez-le avec background=True quand la tâche dépasse la durée d'une session HTTP standard mais que l'utilisateur doit quand même voir l'avancement.

Gestion des erreurs en production

Les agents de production doivent absorber les échecs transitoires :

import time
from google import genai

def create_with_retry(client, max_retries=3, **kwargs):
    for attempt in range(max_retries):
        try:
            return client.interactions.create(**kwargs)
        except Exception as exc:
            if attempt == max_retries - 1:
                raise
            wait = 2 ** attempt
            print(f"Retry {attempt + 1}/{max_retries} après {wait}s : {exc}")
            time.sleep(wait)

Enveloppez les appels MCP et les boucles requires_action avec des timeouts explicites. Journalisez interaction.id à chaque échec — le support Google et vos post-mortems internes en dépendent.

---

Checklist de mise en production

• Python 3.10+ et google-genai à jour
• GEMINI_API_KEY dans un secret manager, jamais en clair
• store=True pour tout usage background ou multi-tour
• Polling avec timeout max et alerte si in_progress > seuil
• environment_id persisté en base pour reprendre les sandboxes
• Serveur MCP en Streamable HTTP, pas SSE
• allowed_tools restrictif sur chaque mcp_server
• Boucle requires_action testée pour chaque custom function
• Credential refresh automatisé avant expiration token
• Logs des steps sans secrets ni PII

---

Conclusion : de la démo à l'agent de production

L'Interactions API GA et la mise à jour Managed Agents du 7 juillet 2026 transforment Gemini en runtime agentique crédible. background=true libère vos workers des timeouts HTTP. Les serveurs MCP distants réutilisent l'investissement que vous avez déjà fait sur le protocole. requires_action connecte les systèmes que MCP ne couvre pas encore. Le refresh via environment_id résout le problème des tokens expirés sans sacrifier l'état du sandbox.

Commencez petit : une interaction synchrone, puis un background job, puis un serveur MCP, puis une custom function. Chaque couche s'ajoute sans réécrire la précédente.

Vous voulez un agent Antigravity connecté à vos outils métier dès le POC ? Notre offre de création d'agents IA démarre par un cadrage technique (MCP, credentials, observabilité) avant tout engagement production.

Vous orchestrez déjà avec n8n ? Notre agence d'automatisation n8n intègre Antigravity comme couche agentique lourde au-dessus de vos workflows existants — sans remplacer ce qui fonctionne.

Vous hésitez entre Managed Agents Google, agent maison ou stack hybride ? Demandez un audit automatisation : nous évaluons votre maturité MCP, vos contraintes de souveraineté et le ROI réel d'Antigravity sur vos cas d'usage.