Gemini CLI-Subagenten: Kontextisolierung, Tool-Beschränkungen und ein README-Spezialist

Gemini CLI kann eine Aufgabe auf spezialisierte Hilfsprogramme aufteilen, anstatt alles in ein einziges Gespräch zu packen. Es kommt zu einem Wandel von einem einzigen Allzweck-Agenten zu einem kleinen Netzwerk von Spezialisten, und das beruht auf drei Grundideen: Wie der Kontext verwaltet wird, wie Tools isoliert werden und wie die Arbeit interaktiv koordiniert wird. Dieser erste Überblick behandelt die Grundlagen und erstellt einen minimal funktionsfähigen Spezialisten.

Warum ein langes Gespräch schiefgeht

Bei einer gewöhnlichen LLM-Sitzung sind die Sitzungsdaten im Grunde global. Jeder gelesene Dateiinhalt, jeder ausgeführte Befehl und jede Klärung landen in einer linearen Historie.

Bitten Sie den Assistenten, einen Speicherdurchflussfehler zu beheben, und fragen Sie ihn zehn Minuten später, einen Sitzungsprotokoll-Text zusammenzufassen. Nun befindet sich die Zusammenfassungsanfrage unterhalb von Codeausschnitten und Protokollen, die vom Debuggen übrig geblieben sind. Das ist Kontextverderb, der drei Nachteile mit sich bringt:

• Latenz. Das Modell liest bei jedem Schritt erneut unverwandtes Material.
• Aufmerksamkeitsverlust. Seine Konzentration wird auf Themen verteilt, die miteinander nichts zu tun haben.
• Vergebene Token. Dasselbe Debugging-Log wird immer wieder bezahlt.

Das Problem wird ausführlich diskutiert, und die Lösung in Gemini CLI sind Subagenten.

Stellen Sie sich eine Beratungsfirma vor. Ein Manager, der persönlich jedes Dokument liest, jede Analyse durchführt und jede E-Mail beantwortet, kann letztendlich nicht mehr daran erinnern, was am ersten Tag passiert ist. Ein Manager, der jede Aufgabe an einen Spezialisten delegiert und nur einen einseitigen Bericht erhält, kann viel länger arbeiten, ohne den Überblick zu verlieren. Subagenten wenden dieses Managementmuster auf einen Programmierassistenten an: Der Spezialist erledigt die aufwendige Arbeit im Verborgenen, und nur das Ergebnis gelangt in das gemeinsame Protokoll.

Zentrum und Speichen

Gemini CLI verwendet ein Zentrum-und-Speichen-Design. Die Hauptsession ist das Zentrum und fungiert als Manager, während die Subagenten die Speichen sind und als Spezialisten agieren.

Der Kontext-Reset

Wenn der Manager einen Subagenten aufruft, öffnet dieser mit einem leeren Kontextfenster. Er erhält lediglich die Aufgabe sowie die relevanten Anweisungen. Nach Abschluss sendet er dem Manager eine kurze Zusammenfassung zurück. Die Reihe von Zwischenschritten, wie zum Beispiel das Lesen von zwanzig Dateien oder das Ausführen von fünf Greps, wird aus der Historie entfernt, sodass der Hauptkontext übersichtlich bleibt. Die umfangreiche Erkundung kostet zwar weiterhin Token im eigenen Fenster des Spezialisten, doch diese Token werden einmal verbraucht und anschließend weggeworfen, anstatt in jede weitere Runde des Hauptgesprächs weitergegeben zu werden.

Was einen Subagenten ausmacht

Ein Subagent wird in einer Markdown-Datei definiert, die mit YAML-Frontmatter beginnt. Das Frontmatter enthält hochrangige Metadaten: den Namen des Agents, eine Beschreibung seiner Aufgabe sowie die Tools, die er verwenden darf, unter anderem auch weitere Einstellungen. Die Datei fungiert als Vertrag, der beschreibt, wofür der Spezialist da ist und womit er arbeiten darf. In der offiziellen Dokumentation finden Sie eine Referenz zum Dateiformat für die Agent-Definition, falls Sie die vollständige Feldliste im Voraus einsehen möchten.

Zwei Felder verdienen besondere Aufmerksamkeit. Die Beschreibung ist das, was der Manager liest, wenn er entscheidet, ob eine Aufgabe zu diesem Spezialisten gehört – eine vage Beschreibung führt zu übersehenen oder falsch zuweisenden Aufgaben, während eine präzise Beschreibung eine zuverlässige Zuordnung ermöglicht. Die Liste der Tools stellt die Sicherheitsgrenze dar, da ein Subagent nur über die ihm zur Verfügung gestellten Tools handeln kann. Behandeln Sie die Datei genauso wie eine Stellenbeschreibung in Kombination mit einem Zugangsausweis.

Hello world: Ein Spezialist für READMEs

Der erste Spezialist wird eine einzige Aufgabe erledigen. Er prüft den aktuellen Ordner und erstellt eine solide README.md-Datei, ohne die Möglichkeit, etwas zu ändern.

Vorbereitung des Ordners

Subagenten für ein einzelnes Projekt befinden sich in .gemini/agents/ innerhalb dieses Projekts. Damit sie für Ihren Benutzer überall verfügbar sind, erstellen Sie sie stattdessen unter ~/.gemini/agents. Wählen Sie einen Ordner mit Quelldateien aus, damit der Agent etwas zum Analysieren hat, wechseln Sie dorthin und erstellen Sie den projektbezogenen Ordner:

mkdir .gemini/agents

Erstellung der Definition

Erstellen Sie .gemini/agents/readme-architect.md mit folgendem Inhalt:

---
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.
---

Mehrere Punkte dazu:

1. name und description sind selbst erklärend.
2. Der Eintrag tools listet die einzigen Tools auf, die dieser Agent verwenden darf – hier read_file und glob zur Dateisuche. Dieses Feld ist optional, doch wenn es weggelassen wird, erbt der Subagent alle Tools von seinem Elternteil. Durch die Angabe nur zweier Tools wird sichergestellt, dass dieser Agent nichts schreiben oder speichern kann.
3. Die Einstellung model ermöglicht es, einem Subagent ein spezifisches Modell zuzuweisen. Hier erbt der Agent einfach das Modell der Hauptsession.
4. Der Markdown-Text unter dem Frontmatter ist die Systemanweisung des Subagents und legt fest, wie sich der Agent verhalten soll.

Zusammenfassend besteht ein Subagent aus Metadaten oben und einem prompt, der das Verhalten definiert, darunter. Da es sich lediglich um eine Textdatei im Repository handelt, kann sie genauso wie jede andere Projektdatei überprüft, versioniert und mit Teamkollegen geteilt werden, was es den Spezialisten in einem Team erleichtert, Standards einzuhalten.

Der /agents-Befehl

Der /agents-Befehl dient als Steuerzentrale für das Spezialistennetzwerk. Er ermöglicht es Ihnen, die Subagents zu inspizieren, zu verwalten und zu überprüfen.

Entdeckung und Überprüfung

Nach dem Speichern der Datei prüfen Sie, ob der Manager den neuen Agenten bemerkt hat. Starten Sie die Gemini CLI. Wenn die Datei an der richtigen Stelle ist, erkennt die CLI beim Starten den neuen Agenten und zeigt ein Informationsfeld an. Wählen Sie „Bestätigen“ und „Aktivieren“.

Führen Sie anschließend /agents list aus. Dadurch wird das lokale Register abgefragt, und readme-architect sollte erscheinen. Das bestätigt, dass der Manager den Agenten als verfügbares Tool erkennt. Wenn der Name nicht angezeigt wird, liegen die üblichen Ursachen in einer Datei, die im falschen Ordner gespeichert ist, in einem Frontmatter-Block mit Tippfehlern oder fehlenden Bindestrichen, oder in einer Sitzung, die vor dem Bestehen der Datei gestartet wurde und neu gestartet werden muss.

Hinweis: Die aktuelle CLI-Version enthält außerdem drei eingebaute Subagenten, nämlich codebase_investigator, cli_help und generalist. Hier geht es um benutzerdefinierte Subagenten, daher fallen diese außerhalb des Geltungsbereichs, obwohl die offiziellen Dokumentationen sie beschreiben.

Verwaltung von Agenten während der Laufzeit

Ein Agent kann zu eifrig sein, oder Sie möchten vielleicht nicht, dass der Manager ihn automatisch aufruft. Führen Sie /agents disable readme-architect aus. Dadurch wird er aus dem Pool der automatischen Delegation entfernt, sodass der Manager diesen Experten nicht verwenden wird, es sei denn, Sie rufen ihn explizit mit der @-Syntax auf. /agents enable readme-architect bringt ihn wieder zurück.

Wenn Sie einfach /agents eingeben, werden die anderen verfügbaren Befehle angezeigt, die es wert sind, schnell ausprobiert zu werden:

▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
 > /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)

Subagenten erscheinen als Tools

Sobald Subagenten aktiviert sind, werden sie als Tools des Hauptagenten angezeigt. Führen Sie /tools aus und suchen Sie in der Liste nach readme-architect. Ein Beispiel aus einer Konfiguration sieht so aus:

▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
 > /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)

Outprobieren

Um zu sehen, wie die Kontextisolation und die Tool-Beschränkung funktionieren, führen Sie Folgendes aus:

@readme-architect Analyse dieses Projekts und erstelle eine README-Datei.

Bemerkenswerte Aspekte:

1. Die Benutzeroberfläche ändert sich. Die CLI wechselt in einen Unteraufgabenmodus und überträgt die Aufgabe, wobei angezeigt wird, dass die Analyse sowie die Erstellung der README-Datei an den Subagenten readme-architect delegiert werden.
2. Verwendung von Tools. Der Agent ruft nur die ihm zur Verfügung gestellten Tools auf, read_file und glob.
3. Ergebnis. Nach kurzer Zeit wird die fertige Arbeit zurückgegeben. Ein Beispiel aus einer Dateiordner:

╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ≡ 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?

Das Ergebnis wird an den Hauptagenten übergeben, der anschließend fragt, ob es als README.md im Projektverzeichnis gespeichert werden soll. Sie können zustimmen oder ablehnen, und Ihre eigene Ausführung kann sich von dem Beispiel unterscheiden.

Isolierungsprüfung

Um zu bestätigen, dass der Subagent tatsächlich keine Dateien löschen oder außer read_file und glob keine weiteren Tools verwenden kann, weisen Sie ihm eine zerstörerische Aufgabe zu. Senden Sie diese an den Hauptagenten:

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

Ein Beispiellauf:

▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
 > @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.

Das Ergebnis: Die Datei wird nicht gelöscht, weil der Subagent keine Werkzeuge besitzt, mit denen dies möglich wäre. Das ist die Wirkung der Berechtigungsregeln. Es ist wichtig, weil diese Regeln durch die Liste der verfügbaren Werkzeuge durchgesetzt werden und nicht durch das Vertrauen in die Anweisungen – selbst wenn dem Subagent gesagt würde, etwas zu löschen, gäbe es einfach kein Werkzeug, mit dem diese Aktion ausgeführt werden könnte. Anweisungen lassen sich umgehen, während fehlende Fähigkeiten das nicht tun. Im Beispiel gab der Subagent an, seine Aufgabe sei abgeschlossen, doch die README.md-Datei blieb unberührt. Der Hauptagent stellte fest, dass die Datei immer noch vorhanden war, und bot an, sie selbst zu löschen:

╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ≡ 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.

Automatische Delegation

Bislang wurde der Subagent explizit über @AGENT_NAME aufgerufen. Es ist auch möglich, einfach die Aufgabe anzugeben und den Hauptagenten zu entscheiden zu lassen, ob ein Subagent geeignet ist. Falls ja, wird die Aufgabe delegiert.

Ob das zu Ihrem Arbeitsablauf passt, liegt bei Ihnen. Solange Subagenten aktiviert sind, stehen sie zur Zuweisung zur Verfügung. Sie können pro Projekt mit /agents disable deaktiviert werden, oder die gesamte Funktion kann durch Setzen von enableAgents auf false in settings.json ausgeschaltet werden:

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

Was definiert einen Subagenten?

In der offiziellen Dokumentation werden die Eigenschaften eines Subagenten zusammengefasst:

• Fokussierter Kontext: Jeder Subagent hat seine eigene Systemanweisung und Persönlichkeit.
• Spezialisierte Tools: Er kann auf eine eingeschränkte oder spezialisierte Auswahl an Tools beschränkt sein.
• Unabhängiges Kontextfenster: Seine Interaktionen finden in einem separaten Kontextzyklus statt, wodurch Tokens in der Hauptkonversationshistorie geschont werden.

Insgesamt sind es diese drei Eigenschaften, die erklären, warum die Delegation an einen Spezialisten dazu führt, dass die Hauptsession sauber bleibt, günstiger in der Nutzung ist und sicherer unbeaufsichtigt gelassen werden kann.

Daraus ergeben sich einige Gewohnheiten. Geben Sie jedem Spezialisten eine einzige, klare Verantwortung, denn eine fokussierte Anweisung funktioniert besser als eine umfangreiche. Stellen Sie nur das kleinste Set an Werkzeugen zur Verfügung, das ausreicht, um die Aufgabe zu erledigen, und erweitern Sie es erst, wenn ein echter Bedarf entsteht. Nutzen Sie explizite @-Aufrufe, solange Sie noch lernen, wie ein Agent sich verhält, und erlauben Sie anschließend die automatische Delegation, sobald seine Beschreibung als zuverlässig erwiesen hat. Bewahren Sie außerdem Projekt-Ebene-Agente im Repository auf, damit jeder, der es kloniert, dasselbe Team von Spezialisten erhält.