Podagenty Gemini CLI: izolacja kontekstu, ograniczenia narzędzi i specjalista README

Gemini CLI może rozdzielić zadanie między specjalistycznymi asystentami zamiast gromadzić wszystko w jednej rozmowie. Chodzi tu o przejście od pojedynczego, wszechstronnego agenta do małej sieci specjalistów, co opiera się na trzech zasadach: sposobie zarządzania kontekstem, izolacji narzędzi oraz interaktywnym koordynowaniu pracy. Ten wstępny przegląd omawia podstawy i tworzy minimalnego, funkcjonalnego specjalistę.

Dlaczego długa rozmowa może się nie udać

W zwykłej sesji LLM dane z sesji są praktycznie globalne. Każdy przeczytany plik, każdy wykonywany polecenie oraz każde uzupełnienie informacji trafia do jednej, liniowej historii.

Poproś asystenta o naprawę wycieku pamięci, a dziesięć minut później poproś go o streszczenie protokołu spotkania. Teraz prośba o streszczenie znajduje się wśród fragmentów kodu i logów pozostałych po naprawianiu błędów. To jest zepsucie kontekstu, które powoduje trzy problemy:

• Opóźnienie. Model za każdym razem ponownie czyta niepowiązane materiały.
• Odchylenie uwagi. Jego uwaga jest rozproszona między tematami, które nie mają ze sobą żadnego związku.
• Marnowane tokeny. Te same logi diagnostyczne są płatne raz po raz.

Problem ten jest szeroko omawiany, a rozwiązaniem w Gemini CLI są subagenty.

Pomyśl o firmie konsultingowej. Menedżer, który osobiście czyta każdy dokument, przeprowadza każdą analizę i odpowiada na każdy e-mail, w końcu nie jest w stanie przypomnieć sobie, co wydarzyło się pierwszego dnia. Menedżer, który przekazuje każde zadanie specjaliście i otrzymuje w zamian tylko jednostronicowy raport, może pracować znacznie dłużej bez utraty kontekstu. Subagenty stosują ten sam model zarządzania w przypadku asystenta programistycznego: specjalista wykonuje pracę w tajemnicy, a tylko wnioski trafiają do wspólnego zapisu.

Centrum i promienie

Gemini CLI wykorzystuje projekt typu centrum i promienie. Główna sesja pełni rolę centrum, działając jako menedżer, natomiast podagenty są promieniami, pełniącymi rolę specjalistów.

Przyczyńanie kontekstu

Gdy menedżer wzywa podagenta, ten otwiera się z pustym oknem kontekstowym. Otrzymuje jedynie zadanie oraz odpowiednie instrukcje. Po jego wykonaniu wysyła krótkie podsumowanie do menedżera. Seria kroków pośrednich, takich jak przeczytanie dwudziestu plików lub uruchomienie pięciu zadań grep, jest usuwana z historii, dzięki czemu główny kontekst pozostaje zredukowany. Długa eksploracja nadal wymaga tokenów wewnątrz własnego okna specjalisty, ale te tokeny są wykorzystywane raz i następnie wyrzucane, zamiast być przenoszone do każdego kolejnego kroku głównej rozmowy.

Z czego składa się podagent

Podagent jest definiowany w pliku Markdown, który zaczyna się od danych frontmatter w formacie YAML. Te dane zawierają metadane na wysokim poziomie: nazwę agenta, opis jego przeznaczenia oraz narzędzia, których może używać, wraz z innymi ustawieniami. Plik ten pełni rolę umowy określającej, do czego służy dany specjalista i z jakimi zadaniami może się zajmować. Oficjalna dokumentacja zawiera informacje na temat formatu pliku definiującego agenta, jeśli chcesz od razu poznać pełną listę pól.

Dwa pola wymagają szczególnej uwagi. Opis to to, co czyta menedżer podczas decydowania, czy dane zadanie należy do tego specjalisty – niejasny opis prowadzi do błędnej lub nieodpowiedniej delegacji zadań, natomiast precyzyjny opis zapewnia wiarygodne dopasowanie. Lista narzędzi stanowi granicę bezpieczeństwa, ponieważ podagent może działać wyłącznie za pomocą narzędzi, które mu zostały przydzielone. Traktuj ten plik tak, jak opis stanowiska w połączeniu z kartą dostępu.

Hello world: specjalista od README

Pierwszy specjalista będzie wykonywał jedno zadanie. Bada on bieżącą katalog i tworzy solidny plik README.md, nie mając możliwości zmiany czegokolwiek.

Przygotowanie folderu

Podagenty do pojedynczego projektu znajdują się w katalogu .gemini/agents/ wewnątrz tego projektu. Aby były dostępne wszędzie dla twojego użytkownika, utwórz je zamiast tego w katalogu ~/.gemini/agents. Wybierz folder zawierający pliki źródłowe, aby agent miał co analizować, przenieś się do niego i utwórz katalog na poziomie projektu:

mkdir .gemini/agents

Pisanie definicji

Stwórz plik .gemini/agents/readme-architect.md z następującym treścią:

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

Kilka uwag na ten temat:

1. name i description są oczywiste.
2. Wpis tools wymienia jedynie narzędzia, których może używać ten agent – w tym read_file i glob do wyszukiwania plików. To pole jest opcjonalne, ale jeśli zostanie pominęte, podagent odziedzicza wszystkie narzędzia od swojego rodzica. Wymienienie tylko dwóch gwarantuje, że ten podagent nie będzie mógł niczego pisać ani zapisywać.
3. Ustawienie model pozwala określić konkretny model dla podagenta. W tym przypadku agent po prostu odziedzicza model głównej sesji.
4. Markdown znajdujący się poniżej frontmatter to komenda systemowa podagenta, która określa jego zachowanie.

Podsumowując, subagent składa się z metadanych u góry oraz instrukcji określających zachowanie poniżej. Ponieważ jest to zwykły plik tekstowy w repozytorium, można go przeglądać, wersjonować i udostępniać kolegom z zespołu w taki sam sposób jak każdy inny plik projektu, co ułatwia standaryzację prac specjalistów w zespole.

Polecenie /agents

Polecenie /agents stanowi centrum sterowania siecią specjalistów. Umożliwia ono inspekcję, zarządzanie oraz weryfikację subagentów.

Odkrywanie i weryfikacja

Po zapisaniu pliku sprawdź, czy menedżer zauważył nowego pracownika. Uruchom Gemini CLI. Jeśli plik znajduje się we właściwym miejscu, CLI wykryje nowego agenta podczas uruchamiania i pokaże okno z informacjami. Wybierz opcje Acknowledge i Enable.

Następnie uruchom /agents list. To zapytanie kierowane jest do lokalnego rejestru, a readme-architect powinien się pojawić. Potwierdza to, że menedżer postrzega ten agent jako dostępne narzędzie. Jeśli nazwa się nie pojawi, najczęstszymi przyczynami są plik zapisany w niewłaściwej folderze, blok frontmatter z błędem pisowni lub brakującymi myślnikami, albo sesja rozpoczęta przed istnieniem pliku, która wymaga ponownego uruchomienia.

Uwaga: obecna wersja CLI zawiera również trzy wbudowane podagenty – codebase_investigator, cli_help oraz generalist. Tematem tego tekstu są podagenty dostosowane pod potrzeby użytkownika, więc one nie wchodzą w zakres omówień, chociaż oficjalna dokumentacja je opisuje.

Zarządzanie agentami w czasie działania

Agent może okazać się zbyt chętny, albo może nie chcieć się Pan/Pani, aby menedżer korzystał z niego samodzielnie. Wykonaj polecenie /agents disable readme-architect. To usunie go z puli automatycznej delegacji, dzięki czemu menedżer nie będzie używał tego eksperta, chyba że wywoła go wyraźnie za pomocą składni @. Polecenie /agents enable readme-architect przywróci go.

Wpisanie samego /agents pokazuje pozostałe dostępne polecenia, które warto szybko wypróbować:

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

Podagenty pojawiają się jako narzędzia

Gdy podagenty zostaną włączone, pojawiają się jako narzędzia głównego agenta. Uruchom /tools i poszukaj w wykazie readme-architect. Przykład z jednej konfiguracji wygląda tak:

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

Próba działania

Aby zobaczyć, jak działa izolacja kontekstu i ograniczenia narzędzi, uruchom:

@readme-architect Przeprowadź analizę tego projektu i przygotuj plik README.

Rzeczy, na które należy zwrócić uwagę:

1. Zmiana interfejsu. CLI przechodzi w tryb podzadania i przekazuje zadanie dalej, z informacją o delegowaniu analizy oraz przygotowania README do podagenta readme-architect.
2. Używanie narzędzi. Agent korzysta wyłącznie z narzędzi, które otrzymał, mianowicie read_file i glob.
3. Wynik. Po chwili powraca ukończone zadanie. Przykład z jednej folderu:

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

Wynik jest przekazywany głównemu agentowi, który następnie pyta, czy zapisać go jako README.md w korzeniu projektu. Możesz to zaakceptować lub odrzucić, a twoja własna sesja może się różnić od przykładu.

Test izolacji

Aby potwierdzić, że podagent rzeczywiście nie może usuwać plików ani używać żadnych narzędzi poza read_file i glob, przydziel mu destruktywną zadanie. Wyślij je do głównego agenta:

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

Przykładowe uruchomienie:

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

Wynik: plik nie zostaje usunięty, ponieważ podagent nie posiada żadnego narzędzia, które mogłoby to zrobić. To właśnie działa granica uprawnień. Ma to znaczenie, ponieważ granica ta jest egzekwowana przez listę narzędzi, a nie poprzez zaufanie do polecenia – nawet jeśli podagentowi kazano coś usunąć, po prostu nie ma narzędzia, za pomocą którego ta czynność mogłaby zostać wykonana. Polecenia można obejść, natomiast brakującą funkcjonalność nie. W przykładzie podagent zgłosił, że jego zadanie zostało ukończone, jednak README.md pozostał nietknięty, a główny agent zauważył, że plik wciąż tam jest, i zaproponował, że sam go usunie:

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

Automatyczne delegowanie

Do tej pory podagent był wywoływany wyraźnie za pomocą @AGENT_NAME. Możliwe jest również jedynie określenie zadania i pozostawienie decyzji głównemu agentowi, czy pasuje podagent. Jeśli tak, zadanie jest delegowane.

Czy to odpowiada twojemu procesowi pracy, zależy od ciebie. Gdy podagenci są włączone, są kandydatami do przydzielenia. Można je wyłączyć dla konkretnego projektu za pomocą polecenia /agents disable, lub całkowicie wyłączyć tę funkcję, ustawiając enableAgents na false w pliku settings.json:

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

Co definiuje subagenta

Oficjalna dokumentacja podsumowuje cechy subagenta:

• Zdefiniowany kontekst: każdy z nich ma swój własny prompt systemowy oraz osobowość.
• Specjalistyczne narzędzia: może być ograniczony do ograniczonego lub specjalistycznego zestawu narzędzi.
• Oddzielne okno kontekstu: jego interakcje odbywają się w osobnym cyklu kontekstowym, co chroni tokeny w głównej historii rozmowy.

W połączeniu te trzy właściwości wyjaśniają, dlaczego delegowanie zadań specjaliście pomaga utrzymać główną sesję w czystości, jest tańsze w obsłudze i bezpieczniejsze przy pozostawieniu bez nadzoru.

Wynikają z tego kilka nawyków. Przyporządkuj każdemu specjaliście jedną wąską odpowiedzialność, ponieważ precyzyjne polecenie daje lepsze wyniki niż rozległe. Udziel mu najmniejszego zestawu narzędzi niezbędnych do wykonania zadania i rozszerz go tylko wtedy, gdy pojawi się rzeczywista potrzeba. Korzystaj z wyraźnych wywołań @, dopóki jeszcze uczysz się, jak zachowuje się agent, a następnie zezwalaj na automatyczną delegację, gdy jego opis okaże się wiarygodny. Przechowuj również agenty na poziomie projektu w repozytorium, aby wszyscy, którzy go sklonują, mieli tę samą grupę specjalistów.