Agents managés dans l’API Gemini : un tutoriel pratique

Combien coûtent les agents managés dans l’API Gemini ?

La tarification des Gemini Managed Agents comporte de nombreux éléments, ce qui complique les estimations précises. Le coût repose principalement sur quatre facteurs :

1. Utilisation du modèle (tokens) : La facturation dépend du nombre de tokens en entrée et en sortie traités par le modèle Gemini sous-jacent. Notez que cela inclut les tokens générés dans les résultats intermédiaires. Par exemple, si l’agent génère un script Python pour produire un rapport, les tokens de ce script sont également facturés.
2. Frais d’infrastructure et de plateforme : Les agents managés s’exécutent dans l’environnement intégré de Google, ce qui implique des frais de service pour l’utilisation des outils de la plateforme (comme Vertex AI Agent Builder) afin de gérer et déployer les agents.
3. Context caching : Si les agents réutilisent fréquemment les mêmes données, ils peuvent exploiter la mise en cache du contexte. Cela permet généralement une réduction significative des coûts par rapport à la tarification standard des tokens.
4. Grounding : Si l’agent utilise des services d’ancrage Google comme Google Search ou Google Maps, ils sont facturés séparément, souvent avec un quota de requêtes gratuites, puis un coût par 1 000 requêtes (en général autour de 14 $ / 1 000 requêtes). 

Dans ce tutoriel, nous allons construire un agent à partir de l’agent antigravity-preview-05-2026 alimenté par Gemini 3.5 Flash. Les coûts en tokens de Gemini 3.5 Flash sont les suivants :

Comment créer des agents managés dans l’API Gemini

Dans ce guide, nous allons créer un agent managé avec l’API Gemini et Python. Comme il s’agit d’une sortie récente, actuellement en bêta, gardez à l’esprit que certains détails d’implémentation peuvent évoluer.

Tout le code que nous écrivons dans ce tutoriel est disponible dans ce dépôt GitHub, que nous utiliserons également pour partager des données avec l’agent analyste de données.

Configuration de l’API

Pour créer une clé d’API, rendez-vous sur le Google AI Studio et cliquez sur « Create API Key » en haut à droite.

Les clés d’API doivent être associées à un projet Google Cloud. Vous pouvez en sélectionner un existant ou en créer un nouveau. Ici, j’en ai créé un nommé gemini-managed-agents.

Après avoir créé la clé, copiez-la. Créez ensuite un fichier nommé .env dans le dossier où vous créerez vos agents et collez-la au format suivant :

GEMINI_API_KEY=<paste_your_api_key_here>

Avant de quitter Google AI Studio, il faut activer la facturation sur la clé d’API que nous venons de créer. Sans cela, nos requêtes seront refusées car Google ne pourra pas nous facturer. Pour configurer la facturation, cliquez sur le bouton « Set up billing ».

Configuration de l’environnement Python

Nous allons utiliser Anaconda pour préparer un environnement Python dédié au projet. Pour créer un environnement avec Anaconda, exécutez la commande :

conda create --name gemini_agents python=3.12 -y

Cela crée un environnement nommé gemini_agents utilisant Python 3.12. Le paramètre -y valide automatiquement toutes les questions lors de la création de l’environnement.

Activez-le ensuite :

conda activate gemini_agents

Enfin, installez les dépendances nécessaires :

pip install google-genai requests python-dotenv

Créer une interaction basique avec un agent managé

Nous avons désormais tout en place pour exécuter notre premier agent. Celui-ci fera simple : il va installer matplotlib et indiquer la version installée.

Voici, étape par étape, comment interagir avec un agent managé (le code complet est disponible dans le script simple_interaction.py du dépôt) :

Commencez par importer les paquets nécessaires et charger la clé d’API depuis le fichier .env créé plus tôt :

from dotenv import load_dotenv
from google import genai

# Load secure environment variables
load_dotenv()

Initialisez ensuite le client Gemini et créez une interaction avec l’agent de base, actuellement nommé antigravity-preview-05-2026, en lui demandant d’installer matplotlib :

# Initialize the GenAI Client
client = genai.Client()

# Create a basic interaction with a managed agent
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Install the matplotlib package, verify its version, and report back.",
    environment="remote"
)

Enfin, récupérez la sortie de l’agent en inspectant les propriétés status, environment_id et output_text :

# Output the status of the agent
print(f"Status: {interaction.status}")
print(f"Environment ID: {interaction.environment_id}")
print(f"Output:\n{interaction.output_text}")

Voici le résultat :

Status: completed
Environment ID: 104ad7f8-32e0-4b8d-b344-24d92eb74eb6
Output:
I have successfully installed the matplotlib package in the sandbox environment and verified its installation.

Here are the details:
- **Installation Command:** python3 -m pip install --break-system-packages matplotlib
- **Installed Version:** 3.10.9

États du cycle de vie du bac à sable

Dans l’exemple ci-dessus, nous avons affiché l’identifiant d’environnement de l’interaction de l’agent managé :

Environment ID: 104ad7f8-32e0-4b8d-b344-24d92eb74eb6

Cette valeur est importante : elle représente l’identifiant de l’environnement dans lequel l’agent a été exécuté. Les interactions des agents sont stockées dans un environnement éphémère conservé jusqu’à 7 jours après la dernière activité, avant suppression.

Le schéma ci-dessous illustre le cycle de vie du bac à sable dans lequel l’agent s’exécute lors d’une interaction.

Tant que l’environnement n’est pas supprimé, nous pouvons y accéder et effectuer d’autres interactions en réutilisant son identifiant.

Effectuer plusieurs interactions

Dans cet exemple, nous montrons comment enchaîner plusieurs interactions. Le code complet est disponible dans le fichier multiple_interactions.py du dépôt.

# First interaction
inter1 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Write a Python script sum.py that adds all integers from 1 to 100.",
    environment="remote"
)

# Second interaction
inter2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    previous_interaction_id=inter1.id, # Passes the conversation history
    environment=inter1.environment_id, # Keeps the same filesystem state
    input="Execute 'sum.py' using Python and display the standard output."
)

# Output the status of the agent
print(f"Output:\n{inter2.output_text}")

Notez que, lors de la seconde interaction, nous avons ajouté deux paramètres :

• previous_interaction_id : l’identifiant de l’interaction précédente, pour que l’agent conserve l’historique de la conversation.

• environment : l’identifiant de l’environnement afin que l’agent sache dans quel bac à sable s’exécuter.

Partager des fichiers avec un agent

Impossible de créer un agent analyste de données sans lui donner accès aux données. Plusieurs options s’offrent à nous :

• Données en ligne (inline) : charger le contenu du fichier dans une chaîne de caractères et l’envoyer pendant l’interaction.
• Fichier hébergé : héberger les données sur une URL publique et fournir cette URL pour que l’agent les télécharge.
• Dépôt GitHub : fournir à l’agent l’URL d’un dépôt GitHub public.
• Bucket Google Cloud : héberger un fichier dans un bucket Google Cloud Storage et configurer le projet pour que l’agent y ait accès.

Nous n’explorerons pas toutes ces solutions ici. Nous montrerons comment envoyer des données en ligne en chargeant un fichier local dans une chaîne, ainsi que comment partager un dépôt GitHub. La première option est idéale pour de petits fichiers locaux (jusqu’à 1 Mo par fichier, avec une limite totale de 2 Mo pour l’ensemble), la seconde convient mieux à des fichiers plus volumineux, comme des jeux de données.

Partager des données en ligne (inline)

Voici un exemple d’envoi de données en ligne (code complet dans inline_example.py) :

inter = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Add all the numbers in the /workspace/numbers.txt file.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                # The file where to store the data in the agent environment
                "target": "/workspace/numbers.txt",
                # Assumes that the file data/numbers.txt exists
                "content": utils.read_text_file("data/numbers.txt")
            }
        ]
    }
)

Les données sont fournies via le paramètre sources de la configuration environment. Le target définit l’emplacement où seront stockées les données dans l’environnement de l’agent. Les fichiers doivent être placés dans le dossier workspace. Ici, il s’agira du fichier number.txt. 

Le paramètre content renseigne le contenu du fichier. Pour les sources inline, c’est simplement une chaîne de caractères, lue ici via la fonction read_text_file() du fichier utils.py.

Partager un dépôt GitHub

Pour partager des fichiers plus volumineux, nous pouvons fournir l’URL d’un dépôt GitHub. Exemple :

inter = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Add all the numbers in the /workspace/repository/numbers.txt file.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/fran-aubry/gemini-agents-tutorial",
                "target": "/workspace/repository"
            }
        ]
    }
)

Dans l’exemple ci-dessus, le dépôt https://github.com/fran-aubry/gemini-agents-tutorial est cloné dans un dossier nommé repository à l’intérieur de l’espace de travail de l’agent.

Télécharger l’environnement d’un agent

Nous avons vu comment interagir avec des agents managés et leur fournir des fichiers. Pour créer notre agent analyste de données, il nous reste à apprendre à télécharger l’environnement d’un agent, afin de récupérer les graphiques et résultats générés.

Chaque espace de travail peut être téléchargé à l’URL :

https://generativelanguage.googleapis.com/v1beta/files/environment-<env_id>:download

Où <env_id> doit être remplacé par l’identifiant de l’environnement à télécharger.

Voici une fonction Python qui utilise le paquet requests pour télécharger un paquet (elle fait partie du fichier utils.py) :

def download_env(env_id, path="environments"):
    download_url = f"https://generativelanguage.googleapis.com/v1beta/files/environment-{env_id}:download"
    try:
        request_params = {"alt": "media"}  # Retrieves raw media binary
        request_headers = {"x-goog-api-key": os.environ.get("GEMINI_API_KEY")}
        # Download the environment
        print(f"Downloading environment: {env_id}")
        response = requests.get(
            download_url,
            params=request_params,
            headers=request_headers,
            allow_redirects=True
        )
        response.raise_for_status()
        # Save the compressed workspace archive locally
        archive_name = f"{env_id}.tar"
        output_path = os.path.join(path, archive_name)
        with open(output_path, "wb") as archive_file:
            archive_file.write(response.content)
        print(f"Successfully downloaded workspace snapshot archive: {output_path}")     
    except requests.exceptions.RequestException as error:
        print(f"Failed to download sandbox workspace via HTTP request: {error}")
    except tarfile.TarError as archive_error:
        print(f"Failed to unpack download tarball: {archive_error}")

Créer un agent analyste de données

Dans cette section, nous allons créer un agent qui réalise une analyse de données. Pour le tester, nous utiliserons ce jeu de données Netflix issu de Kaggle, également stocké dans le dossier data de notre dépôt.

Dans tous les exemples précédents, nous avons toujours interagi avec l’agent de base : antigravity-preview-05-2026. Ici, nous allons d’abord créer un agent via la fonction client.agents.create().

Créer un agent

Voici comment créer un agent :

agent = client.agents.create(
            id=”data-analyst”,
            base_agent="antigravity-preview-05-2026",
            base_environment={
                "type": "remote",
                "sources": [
                    {
                        "type": "inline", 
                        "target": ".agents/AGENTS.md", 
                        "content": read_text_file(".agents/AGENTS.md")
                    },
                    # Explicitly load the skill
                    {
                        "type": "inline", 
                        "target": ".agents/skills/csv-aggregator/SKILL.md", 
                        "content": read_text_file(".agents/skills/csv-aggregator/SKILL.md")
                    },	
                    {
                        "type": "repository",
                        "source": "https://github.com/fran-aubry/gemini-agents-tutorial",
                        "target": "/workspace/repository"
                    }
                ]
            }

Détaillons chaque paramètre :

• id : le nom de l’agent, ici data-analyst. Nous utiliserons cet identifiant dans la méthode client.interactions.create() à la place de antigravity-preview-05-2026 utilisé jusqu’ici. 

• base_agent : l’agent à utiliser comme base. Nous construisons donc un agent au-dessus de antigravity-preview-05-2026.

• base_environment : comme précédemment, cela nous permet de fournir des fichiers à l’agent. Nous avons inclus deux fichiers spéciaux : .agents/AGENTS.md et .agents/skills/csv-aggregator/SKILL.md. Ces fichiers définissent le comportement de l’agent. Le fichier AGENTS.md définit le comportement général, tandis que SKILL.md décrit une compétence spécifique. Nous avons aussi donné accès au dépôt afin qu’il puisse lire les fichiers de données à analyser.

Comprendre AGENTS.md

Ce fichier s’apparente à un « prompt système ». Il sert de guide principal pour l’agent. On y précise clairement son rôle, ses objectifs et les limites à respecter pendant l’exécution. 

C’est aussi l’endroit idéal pour lister les outils ou sources de données autorisés, et donner des exemples de ton attendu ou de gestion des tâches. 

En gardant des consignes simples et bien structurées, on aide l’agent à comprendre comment se comporter et quel résultat livrer.

L’emplacement du fichier dans l’environnement de l’agent doit être .agents/AGENTS.md.

Comprendre SKILL.md

Les fichiers de compétence servent à doter l’agent de capacités spécifiques. Un agent peut en avoir plusieurs, chacune décrite dans un fichier SKILL.md situé dans .agents/skills/<skill_name>/SKILL.md, en remplaçant <skill_name> par le nom de la compétence.

La structure d’un fichier de compétence doit être :

---
name: <skill_name>
description: <description of when to use the skill>
---
<steps on how to perform the task>

Pour l’illustrer, nous avons équipé l’agent data-analyst d’une compétence nommée csv-aggregator définie ici. Cette compétence sert lorsque l’on souhaite regrouper les lignes d’un CSV par une colonne et additionner une autre colonne. 

Avec le jeu de données Netflix, si l’on veut connaître les genres les plus regardés, on groupe par la colonne Genre et on additionne les valeurs de la colonne Viewership. Le fichier de compétence explique à l’agent comment procéder.

Charger l’agent

Les agents étant persistants, si vous tentez de créer deux fois le même agent, une erreur surviendra. Pour cette raison, nous avons créé la fonction load_or_create_agent() dans le fichier utils.py. Elle essaie de créer l’agent et, s’il existe, le charge via client.agents.load().

Tout assembler

Maintenant que nous avons un agent analyste de données, testons-le en lui demandant d’analyser les genres Netflix. 

Comme précédemment, commencez par importer les bibliothèques, charger la clé d’API et initialiser le client :

from dotenv import load_dotenv
from google import genai
import utils

load_dotenv()
client = genai.Client()

Créez ensuite (ou chargez-le si ce n’est pas la première exécution du script) l’agent data-analyst avec la fonction utils.load_or_create_agent() :

data_analyst = utils.load_or_create_agent(client, "data-analyst")
print(f"Agent '{data_analyst.id}' initialized.")

Vous pouvez à présent interagir avec l’agent comme précédemment. La seule différence : dans le paramètre agent, nous indiquons notre agent au lieu de antigravity-preview-05-2026.

On commence par lui demander d’installer le paquet matplotlib :

inter1 = client.interactions.create(
    agent=data_analyst.id,
    input="Install the matplotlib package.",
    environment="remote"
)

Notez que, puisque l’environnement a déjà été configuré au niveau de l’agent, nous n’avons plus besoin de fournir des fichiers ; il suffit d’indiquer la chaîne ”remote”.

Ensuite, nous lui demandons d’utiliser l’outil csv-aggregator pour analyser les données Netflix par genres et identifier les genres les plus regardés :

inter2 = client.interactions.create(
    agent=data_analyst.id,
    input="Use the csv-aggregator to plot the top 10 genres from /workspace/repository/data/netflix.csv in terms of viewership",
    environment=inter1.environment_id
)

Remarquez que nous fournissons l’identifiant de l’environnement de l’interaction précédente pour que l’agent poursuive son travail dans le même contexte.

Enfin, nous lui demandons de tracer les données en exécutant le script genres.py créé à l’étape précédente (le fichier SKILL.md indique à l’agent de créer ce script) :

inter3 = client.interactions.create(
    agent=data_analyst.id,
    input="Execute the genres.py script using python.",
    environment=inter2.environment_id
)

Après cette interaction, le graphique devrait être généré. Nous pouvons le récupérer localement en téléchargeant l’environnement :

utils.download_env(inter3.environment_id)

Voici le résultat :

Le code complet de l’interaction avec l’agent est disponible dans analyze_netflix_genres.py.

Conclusion

Pouvoir créer des agents complexes en un seul appel d’API, sans dépendre d’une infrastructure cloud sophistiquée pour mettre en place un bac à sable, est extrêmement puissant. Cette capacité facilite grandement la création d’agents performants sans se soucier de l’environnement d’exécution.

Dans ce tutoriel, nous avons couvert les fondamentaux des Gemini Managed Agents sans aller jusqu’à des agents véritablement complexes. Nous vous encourageons à creuser davantage et à capitaliser sur ces bases pour développer vos compétences.