Сабагенты Gemini CLI: изоляция контекста, ограничения инструментов и специалист README.

Gemini CLI позволяет распределять задачи между специализированными помощниками вместо того, чтобы собирать всё в одном диалоге. Происходит переход от единого универсального агента к небольшой сети специалистов, что основано на трёх принципах: способе управления контекстом, изоляции инструментов и интерактивном организовании работы. В этом кратком обзоре рассматриваются основы и создаётся минимальный рабочий специалист.

Почему длинные диалоги становятся неэффективными

В обычной сессии с большой языковой моделью данные сессии фактически являются глобальными. Каждый прочитанный файл, каждая выполненная команда и каждое уточнение остаются в одной линейной истории.

Попросите помощника отладить утечку памяти, а затем через десять минут попросите его подвести итоги протокола встречи. Теперь запрос на краткое изложение оказывается среди фрагментов кода и логов, оставшихся после отладки. Это явление называется порчей контекста, и оно влечёт за собой три негативных последствия:

• Задержка. Модель снова читает несвязанный материал при каждом запросе.
• Смещение внимания. Её внимание рассеивается на темы, которые не имеют между собой никакой связи.
• Потеря токенов. Одни и те же логи отладки приходится покупать снова и снова.

Эта проблема широко обсуждается, и решением в Gemini CLI являются субагенты.

Представьте консалтинговую фирму. Менеджер, который лично читает каждый документ, выполняет каждый анализ и отвечает на каждое письмо, в конечном итоге не может вспомнить, что происходило в первый день. Менеджер, который поручает каждую задачу специалисту и получает в ответ лишь одностраничный отчет, может работать гораздо дольше, не теряя нити разговора. Субагенты применяют ту же схему управления к помощнику-программисту: специалист выполняет сложную работу в одиночку, а в общий реестр попадает только вывод.

Центр и лучи

Gemini CLI использует конструкцию «центр и лучи». Основная сессия является центром, выполняющим роль менеджера, а подагенты — лучами, выступающими в роли специалистов.

Сброс контекста

Когда менеджер вызывает подагента, тот открывается с пустым окном контекста. Он получает только задание и соответствующие инструкции. По завершении работы он возвращает краткое резюме менеджеру. Набор промежуточных действий, таких как чтение двадцати файлов или выполнение пяти операций grep, удаляется из истории, благодаря чему основной контекст остается лаконичным. Длительные операции всё равно потребляют токены в собственном окне специалиста, но эти токены тратятся один раз и затем удаляются, вместо того чтобы сохраняться для последующих этапов основного диалога.

Из чего состоит подагент

Подагент определяется в файле Markdown, который начинается с YAML-фронтматтера. Фронтматтер содержит метаданные высокого уровня: имя агента, описание его назначения и инструментов, которые он может использовать, а также другие настройки. Этот файл служит своего рода контрактом, описывающим, для чего предназначен специалист и с чем он может работать. В официальной документации приведен образец формата файла с определением агента, если вам нужен полный список полей заранее.

Два поля заслуживают особого внимания. Описание — это то, что читает менеджер при принятии решения о том, относится ли задача к этому специалисту; нечеткое описание приводит к упущениям или неправильной передаче задач, тогда как точное описание обеспечивает надежное сопоставление. Список инструментов представляет собой границы безопасности, поскольку подагент может действовать только с помощью предоставленных ему инструментов. Относитесь к этому файлу так же, как к описанию должности в сочетании с пропуском на вход.

Привет, мир: специалист по README

Первый специалист будет выполнять одну задачу. Он анализирует текущую директорию и составляет качественный файл README.md, не имея возможности что-либо изменить.

Подготовка папки

Подагенты для отдельного проекта находятся в папке .gemini/agents/ внутри этого проекта. Чтобы они были доступны пользователям в любом месте, создайте их вместо этого в папке ~/.gemini/agents. Выберите папку, содержащую исходные файлы, чтобы у агента было что анализировать, перейдите в неё и создайте директорию уровня проекта:

mkdir .gemini/agents

Написание определения

Создайте файл .gemini/agents/readme-architect.md с следующим содержимым:

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

Несколько замечаний по этому поводу:

1. name и description объясняются сами собой.
2. В поле tools перечисляются единственные инструменты, которые может использовать этот агент — здесь read_file и glob для поиска файлов. Это поле является необязательным, но если оно пропущено, подагент наследует все инструменты от своего родителя. Указание лишь двух инструментов гарантирует, что этот подагент не сможет ничего записывать или сохранять.
3. Параметр model позволяет задать конкретную модель для подагента. В данном случае агент просто наследует модель основной сессии.
4. Markdown-текст под frontmatter представляет собой системное указание подагента, которое определяет его поведение.

Подводя итог, сабагент состоит из метаданных в верхней части и инструкции, определяющей его поведение, ниже них. Поскольку это всего лишь текстовый файл в репозитории, его можно просматривать, версионировать и делиться с коллегами так же, как и любым другим проектным файлом, что облегчает стандартизацию работы специалистов в команде.

Команда /agents

Команда /agents является центром управления сетью специалистов. Она позволяет проверять, управлять и верифицировать сабагентов.

Обнаружение и проверка

После сохранения файла убедитесь, что менеджер заметил нового сотрудника. Запустите Gemini CLI. Если файл находится в правильном месте, CLI обнаружит нового агента при запуске и отобразит информационное окно. Выберите опции «Подтвердить» и «Включить».

Затем выполните команду /agents list. Она запрашивает информацию из локального реестра, и там должен появиться readme-architect. Это подтверждает, что менеджер рассматривает этот агент как доступный инструмент. Если имя не отображается, наиболее вероятными причинами являются сохранение файла в неверной папке, ошибка в блоке frontmatter или отсутствие дефисов, либо запуск сессии до появления файла, что требует её перезапуска.

Примечание: текущая версия CLI также включает три встроенных подагента — codebase_investigator, cli_help и generalist. Здесь речь идет о пользовательских подагентах, поэтому они не входят в рамки обсуждения, хотя они описаны в официальной документации.

Управление агентами во время выполнения

Агент может оказаться слишком ретивым, или вы можете не хотеть, чтобы менеджер сам его вызывал. Выполните команду /agents disable readme-architect. Это исключит его из пула автоматической делегации, так что менеджер не будет использовать этого эксперта, если только вы не вызовете его явно с помощью синтаксиса @. Команда /agents enable readme-architect восстановит его в список.

Если ввести просто /agents, будет показан список других доступных команд, которые стоит быстро попробовать:

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

Подагенты отображаются как инструменты

После включения подагентов они появляются как инструменты основного агента. Запустите /tools и найдите в списке readme-architect. Пример из одной настройки выглядит так:

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

Пробная работа

Чтобы увидеть, как работают изоляция контекста и ограничения инструментов, выполните:

@readme-architect Analyze this project and draft a README.

На что обратить внимание:

1. Изменение интерфейса. CLI переходит в режим подзадачи и передаёт работу, указывая строкой, что анализ и составление README будут делегированы подагенту readme-architect.
2. Использование инструментов. Агент использует только те инструменты, которые ему были предоставлены: read_file и glob.
3. Результат. Через некоторое время возвращается готовый результат. Пример из одной папки:

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

Результат передаётся главному агенту, который затем спрашивает, следует ли сохранить его в виде файла README.md в корне проекта. Вы можете согласиться или отказаться, причём ваша работа может отличаться от примера.

Тест изоляции

Чтобы убедиться, что подагент действительно не может удалять файлы или использовать какие-либо инструменты помимо read_file и glob, задайте ему разрушительную задачу. Отправьте её главному агенту:

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

Пример запуска:

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

Результат: файл не удаляется, потому что у подагента отсутствуют инструменты, способные это сделать. Это проявление границ разрешений. Это важно, поскольку эти границы соблюдаются за счёт списка инструментов, а не благодаря доверию к командам: даже если подагенту прикажут что-то удалять, просто не существует инструмента, с помощью которого можно было бы выполнить эту операцию. С командами можно найти обходные пути, но с отсутствующими возможностями — нет. В примере подагент сообщил, что его задача выполнена, однако файл README.md остался нетронутым, и главный агент заметил, что файл всё ещё там, и предложил удалить его сам:

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

Автоматическое делегирование

До сих пор подагент вызывался явно с помощью @AGENT_NAME. Также возможно просто указать задачу и позволить основному агенту решить, подходит ли для неё подагент. Если он подходит, задача делегируется.

Решение о том, подходит ли это вашему рабочему процессу, остаётся за вами. Пока подагенты включены, они являются кандидатами на выполнение задач. Их можно отключить для конкретного проекта с помощью команды /agents disable, либо полностью выключить всю эту функцию, установив значение enableAgents в settings.json в false:

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

Что определяет подагента

В официальной документации описаны характеристики подагента:

• Специфический контекст: у каждого подагента есть свой собственный системный промпт и персона.
• Специализированные инструменты: он может использовать ограниченный или специализированный набор инструментов.
• Независимое окно контекста: его взаимодействия происходят в отдельном цикле контекста, что позволяет экономить токены в основной истории разговора.

В совокупности именно эти три свойства обеспечивают чистоту основного сеанса при делегировании задач специалисту, снижают затраты на его работу и делают его более безопасным при отсутствии наблюдения.

Из этого следуют несколько привычек. Предоставьте каждому специалисту одну узкую обязанность, поскольку четко сформулированная задача выполняется лучше, чем расплывчатая. Дайте минимальный набор инструментов, необходимых для выполнения работы, и расширяйте его только тогда, когда появляется реальная необходимость. Используйте явные указания @, пока вы еще изучаете поведение агента, а затем разрешите автоматическую делегацию, когда его описание окажется надежным. Также храните агентов на уровне проекта в репозитории, чтобы все, кто его клонирует, получали одну и ту же команду специалистов.