Les sous-agents de Gemini CLI : isolation du contexte, limites des outils et un spécialiste README

Gemini CLI permet de diviser une tâche entre plusieurs assistants spécialisés au lieu de regrouper tout dans une seule conversation. On passe d’un agent polyvalent unique à un petit réseau de spécialistes, ce qui repose sur trois principes : la gestion du contexte, l’isolation des outils et l’orchestration interactive du travail. Cette première présentation couvre les bases et permet de créer un spécialiste fonctionnel minimal.

Pourquoi une longue conversation devient problématique

Dans une session classique avec un LLM, les données de la session sont en fait globales. Chaque fichier lu, chaque commande exécutée et chaque précision apportée se retrouvent dans une histoire linéaire unique.

Demandez à l’assistant de diagnostiquer une fuite mémoire, puis demandez-lui dix minutes plus tard de résumer un procès-verbal de réunion. La demande de résumé se retrouve alors parmi des extraits de code et des journaux laissés après le débogage. C’est ce qu’on appelle la dégradation du contexte, ce qui entraîne trois problèmes :

• Latence. Le modèle relit du matériel non pertinent à chaque tour.
• Dérive de l’attention. Son attention est dispersée sur des sujets qui n’ont aucun lien entre eux.
• Token gaspillés. Les mêmes journaux de débogage sont générés encore et encore.

Le problème fait l’objet de nombreuses discussions, et la solution proposée dans Gemini CLI réside dans les sous-agents.

Pensez à une firme de conseil : un manager qui lit personnellement chaque document, effectue chaque analyse et répond à chaque e-mail finit par ne plus se souvenir de ce qui s’est passé le premier jour. Un manager qui confie chaque tâche à un spécialiste et ne reçoit qu’un rapport d’une page peut continuer beaucoup plus longtemps sans perdre le fil. Les sous-agents appliquent le même principe de gestion à un assistant de codage : le spécialiste effectue le travail complexe en privé, et seules les conclusions parviennent au registre partagé.

Hub et rayons

Gemini CLI utilise un design hub-and-spoke. La session principale constitue le hub, agissant en tant que gestionnaire, tandis que les sous-agents représentent les rayons, fonctionnant en tant que spécialistes.

La réinitialisation du contexte

Lorsque le gestionnaire appelle un sous-agent, celui-ci démarre avec une fenêtre de contexte vide. Il ne reçoit que la tâche et les instructions pertinentes. Une fois la tâche terminée, il envoie un bref résumé au gestionnaire. Les étapes intermédiaires, telles que la lecture de vingt fichiers ou l’exécution de cinq recherches, sont supprimées de l’historique, ce qui permet au contexte principal de rester léger. L’exploration approfondie consomme néanmoins des tokens dans la fenêtre propre au spécialiste, mais ces tokens sont utilisés une seule fois puis jetés, au lieu d’être conservés pour chaque étape ultérieure de la conversation principale.

De quoi est composé un sous-agent

Un sous-agent est défini dans un fichier Markdown qui commence par du frontmatter YAML. Le frontmatter contient des métadonnées de haut niveau : le nom de l’agent, une description de sa fonction ainsi que des outils qu’il peut utiliser, parmi d’autres paramètres. Ce fichier agit comme un contrat décrivant à quoi sert le spécialiste et quelles tâches il peut effectuer. La documentation officielle propose une référence au format de fichier de définition des agents si vous souhaitez connaître la liste complète des champs dès le départ.

Deux champs méritent une attention particulière. La description est ce que lit le gestionnaire pour décider si une tâche relève de ce spécialiste ; une description vague entraîne des délégations manquées ou erronées, tandis qu’une description précise assure une correspondance fiable. La liste des outils constitue la limite de sécurité, car un sous-agent ne peut agir qu’au moyen des outils qui lui ont été attribués. Traitez ce fichier comme vous traiteriez une description de poste associée à une carte d’accès.

Hello world : un spécialiste de README

Le premier spécialiste aura une seule fonction : il examine le répertoire courant et rédige un README.md solide, sans pouvoir modifier quoi que ce soit.

Préparation du dossier

Les sous-agents d’un projet donné se trouvent dans .gemini/agents/ à l’intérieur de ce projet. Pour les rendre accessibles partout pour votre utilisateur, créez-les plutôt dans ~/.gemini/agents. Choisissez un dossier contenant des fichiers sources afin que l’agent ait quelque chose à analyser, déplacez-vous à l’intérieur de ce dossier et créez le répertoire au niveau du projet :

mkdir .gemini/agents

Rédaction de la définition

Créez .gemini/agents/readme-architect.md avec ce contenu :

---
name: readme-architect
description: Specialized in analyzing project structures and writing professional README.md files.
tools:
- read_file
- glob
model: inherit
---

You are a Technical Writer. Your goal is to look at the files in the current
directory and draft a README.md that includes:
1. Project Name.
2. Installation instructions.
3. A brief description of the file structure.

Do not modify any files; only provide the Markdown text.
---

Quelques points à ce sujet :

1. name et description sont explicites.
2. La rubrique tools énumère les seuls outils que cet agent peut utiliser, à savoir read_file et glob pour trouver des fichiers. Ce champ est optionnel, mais s’il est omis, le sous-agent hérite de tous les outils de son parent. En ne listant que deux outils, on s’assure que celui-ci ne peut ni écrire ni enregistrer quoi que ce soit.
3. La valeur de model permet de définir un modèle spécifique pour le sous-agent. Ici, l’agent hérite simplement du modèle de la session principale.
4. Le Markdown situé sous le frontmatter constitue le prompt système du sous-agent et définit son comportement.

En résumé, un sous-agent se compose de métadonnées en haut et d’une instruction définissant son comportement en dessous. Comme il s’agit simplement d’un fichier texte à l’intérieur du répertoire, il peut être examiné, versionné et partagé avec les collègues de la même manière que n’importe quel autre fichier de projet, ce qui facilite la standardisation des spécialistes au sein d’une équipe.

La commande /agents

La commande /agents est un centre de contrôle pour le réseau de spécialistes. Elle vous permet d’inspecter, de gérer et de vérifier les sous-agents.

Découverte et vérification

Après avoir enregistré le fichier, vérifiez que le gestionnaire ait pris note du nouvel agent. Lancez Gemini CLI. Si le fichier se trouve à l’endroit prévu, la CLI détecte le nouvel agent au démarrage et affiche une boîte d’information. Choisissez « Acknowledge and Enable ».

Exécutez ensuite /agents list. Cela interroge le registre local, et readme-architect devrait apparaître. Cela confirme que le gestionnaire considère cet agent comme un outil disponible. Si le nom n’apparaît pas, les causes les plus probables sont un fichier enregistré dans le dossier incorrect, un bloc frontmatter contenant une faute d’orthographe ou des tirets manquants, ou une session lancée avant l’existence du fichier qui nécessite une redémarrage.

Remarque : la version actuelle de la CLI inclut également trois sous-agents intégrés, codebase_investigator, cli_help et generalist. Les sous-agents personnalisés sont le sujet principal ici, donc ceux-ci ne sont pas pris en compte, bien que la documentation officielle les décrit.

Gestion des agents en temps de exécution

Un agent peut se montrer trop zélé, ou vous ne voulez peut-être pas que le gestionnaire l’utilise automatiquement. Exécutez /agents disable readme-architect. Cela le retire du pool de délégation automatique, de sorte que le gestionnaire n’utilisera cet expert que si vous l’appelez explicitement avec la syntaxe @. /agents enable readme-architect le remet en service.

En tapant simplement /agents, vous verrez les autres commandes disponibles, qui méritent d’être essayées rapidement :

▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
 > /agents
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
 reload    Reload the agent registry
 list      List available local and remote agents
 enable    Enable a disabled agent
 disable   Disable an enabled agent
 config    Configure an agent
 workspace (/directory)

Les sous-agents apparaissent comme des outils

Lorsque les sous-agents sont activés, ils apparaissent comme des outils de l’agent principal. Exécutez /tools et cherchez readme-architect dans la liste. Un exemple issu d’une configuration correspondante est le suivant :

▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
 > /tools
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
Available Gemini CLI tools:

  - Activate Skill (activate_skill)
  - Ask User (ask_user)
  - CLI Help Agent (cli_help)
  - Codebase Investigator Agent (codebase_investigator)
  - Edit (replace)
  - Enter Plan Mode (enter_plan_mode)
  - FindFiles (glob)
  - Generalist Agent (generalist)
  - GoogleSearch (google_web_search)
  - ReadFile (read_file)
  - ReadFolder (list_directory)
  - readme-architect (readme-architect)
  - SaveMemory (save_memory)
  - SearchText (grep_search)
  - Shell (run_shell_command)
  - WebFetch (web_fetch)
  - WriteFile (write_file)

Essai

Pour voir le fonctionnement de l’isolation contextuelle et des restrictions d’outils, exécutez :

@readme-architect Analysez ce projet et rédigez un README.

Points à noter :

1. Changement d’interface. La CLI passe en mode sous-tâche et transfère le travail, avec une ligne indiquant qu’elle déléguera l’analyse et la rédaction du README à l’agent subsidiaire readme-architect.
2. Utilisation des outils. L’agent n’appelle que les outils qui lui ont été fournis, read_file et glob.
3. Résultat. Après un certain temps, le travail terminé revient. Exemple provenant d’un dossier :

╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ≡ Agent Completed (ctrl+o to expand)                                                                                                                                                    │
│ ✓ readme-architect · Completed successfully                                                                                                                                             │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

✦ The readme-architect has drafted a README for your project:

  MyTasks Math Utility

  A lightweight JavaScript utility library for performing basic arithmetic operations.

  Installation

  Since this project consists of a single utility file without external dependencies, you can integrate it into your environment as follows:

   1. Clone or download this repository.
   2. Copy math.js into your project's directory.
   3. Import the functions into your Node.js application:

   1 const math = require('./math.js');

  Usage

   1 const { add, subtract, multiply, divide } = require('./math.js');
   2
   3 console.log(add(10, 5));      // Output: 15
   4 console.log(subtract(10, 5)); // Output: 5
   5 console.log(multiply(10, 5)); // Output: 50
   6 console.log(divide(10, 5));   // Output: 2

  File Structure

  The project is organized as follows:

   - math.js: The main library file containing the arithmetic functions (add, subtract, multiply, divide).
   - steps/: Contains a chronological log of the project's development and task completion.
     - 1.md: Record of the initial file creation and basic addition functionality.
     - 2.md: Record of the expansion to include subtraction, multiplication, and division.
   - .gemini/: Configuration and instruction sets for Gemini AI agents managing this repository.

  Would you like me to save this to a README.md file in the project root?

Le résultat est transmis à l’agent principal, qui demande alors s’il doit le sauvegarder sous le nom de README.md dans la racine du projet. Vous pouvez accepter ou refuser, et votre propre exécution peut différer de l’exemple.

Test d’isolation

Pour confirmer que le sous-agent ne peut vraiment pas supprimer de fichiers ni utiliser d’outil autre que read_file et glob, assignez-lui une tâche destructrice. Envoyez ceci à l’agent principal :

@readme-architect Delete any README.md files that you see in this folder.

Exécution de test :

▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
 > @readme-architect Delete any README.md files that you see in this folder.
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
  Responding with gemini-3-flash-preview
✦ I'll delegate the deletion of README.md files to the readme-architect sub-agent as requested.

Le résultat : le fichier n’est pas supprimé, car le sous-agent ne dispose d’aucun outil permettant de le faire. C’est là que s’applique la limite des permissions. Cela est important car cette limite est imposée par la liste des outils, et non en se fiant aux instructions fournies : même si l’on demandait au sous-agent de supprimer quelque chose, il n’existe tout simplement aucun outil permettant d’effectuer cette action. Les instructions peuvent être contournées, tandis qu’une capacité manquante ne l’est pas. Dans l’exemple, le sous-agent a indiqué que sa tâche était terminée, pourtant le README.md est resté inchangé, et l’agent principal a remarqué que le fichier était toujours présent, proposant alors de le supprimer lui-même :

╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ≡ Agent Completed (ctrl+o to expand)                                                                                                                                                    │
│ ✓ readme-architect · Completed successfully                                                                                                                                             │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

✦ I'll check if the README.md file still exists in the root directory.


╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓  FindFiles 'README.md'                                                                                                                                                                │
│                                                                                                                                                                                         │
│ Found 1 matching file(s)                                                                                                                                                                │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

✦ I'll delete the README.md file since the readme-architect sub-agent did not do so.

Délégation automatique

Jusqu’à présent, le sous-agent était invoqué explicitement via @AGENT_NAME. Il est également possible de simplement décrire la tâche et de laisser l’agent principal décider s’un sous-agent convient. S’il convient, la tâche est déléguée.

Cela convient ou non à votre flux de travail relève de votre choix. Tant que les sous-agents sont activés, ils sont des candidats à l’affectation. Ils peuvent être désactivés pour un projet donné à l’aide de /agents disable, ou la fonctionnalité dans son ensemble peut être désactivée en mettant enableAgents à false dans settings.json :

{
"experimental": { "enableAgents": false }
}

Qu’est-ce qui définit un sous-agent ?

La documentation officielle résume les caractéristiques d’un sous-agent :

• Contexte ciblé : chacun dispose de son propre prompt système et de sa propre personnalité.
• Outils spécialisés : il peut être limité à un ensemble restreint ou spécialisé d’outils.
• Fenêtre de contexte indépendante : ses interactions ont lieu dans un cycle de contexte séparé, ce qui permet d’économiser des tokens dans l’historique principal de la conversation.

Prises ensemble, ces trois propriétés expliquent pourquoi déléguer à un spécialiste permet de maintenir la session principale propre, de réduire ses coûts d’exécution et de la rendre plus sûre lorsqu’on ne s’en occupe pas directement.

Quelques habitudes en découlent. Accordez à chaque spécialiste une responsabilité précise, car une instruction ciblée fonctionne mieux qu’une instruction trop vaste. Fournissez uniquement l’ensemble minimal d’outils nécessaire pour accomplir la tâche, et élargissez-le uniquement lorsqu’une véritable nécessité apparaît. Utilisez des appels @ explicites tant que vous apprenez encore le comportement de l’agent, puis autorisez la délégation automatique une fois que sa description s’est avérée fiable. Conservez également les agents au niveau du projet dans le répertoire, afin que toute personne qui le clone dispose du même groupe de spécialistes.