gemini-cli subagents ai-agents context-management developer-tools

Підагенти Gemini CLI: ізоляція контексту, обмеження інструментів та спеціаліст README.

Підагенти Gemini CLI підтримують чистоту основного чату: хаб та споки, файл визначення агента, команда /agents та агент README лише для читання з суворими обмеженнями.

Видавець: REACTAPP.TOPДодано на сайт 28 жовт. 2026 р.9 хв читання2138 слів

Джерела: Mastering Gemini CLI Subagents: Part 1 : Introduction

Gemini CLI може розділити завдання між спеціалізованими асистентами замість того, щоб збирати все в одній розмові. Відбувається перехід від єдиного універсального агента до невеликої мережі спеціалістів, і все зводиться до трьох принципів: як керувати контекстом, як ізолювати інструменти та як інтерактивно організовувати роботу. У цьому короткому огляді розглядаються основи та створюється мінімальний функціональний спеціаліст.

Чому довга розмова призводить до проблем

У звичайній сесії LLM дані сесії є фактично глобальними. Кожен прочитаний файл, кожна виконана команда та кожне уточнення потрапляють у одну лінійну історію.

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

Затримка. Модель щоразу перечитує непов’язаний матеріал.
Відхилення уваги. Її увага розсіюється між темами, які не мають між собою жодного зв’язку.
Марні витрати токенів. Одні й ті самі журнали дебагування оплачуються знову та знову.

Ця проблема активно обговорюється, і рішенням у 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.
---

Кілька зауважень щодо цього:

name та description є зрозумілими без пояснень.
У полі tools перелічуються єдині інструменти, які може використовувати цей агент — тут read_file та glob для пошуку файлів. Це поле є необов’язковим, але якщо його пропустити, підагент успадковує всі інструменти від свого батьківського агента. Вказання лише двох інструментів гарантує, що цей підагент не зможе нічого записувати чи зберігати.
Налаштування model дозволяє вказати конкретну модель для підагента. У цьому випадку агент просто успадковує модель основної сесії.
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.

Що варто звернути уваги:

Інтерфейс змінюється. CLI переходить у режим підзавдання та передає роботу, показуючи рядок із інформацією про те, що аналіз та створення README будуть делеговані підагенту readme-architect.
Використання інструментів. Агент використовує лише ті інструменти, які йому були надані — read_file та glob.
Результат. Через деякий час повертається готова робота. Приклад з однієї папки:

╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ≡ 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 у false у файлі settings.json:

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

Що визначає підагента

У офіційній документації узагальнено характеристики підагента:

Фокусований контекст: кожен має власний системний запит та персону.
Спеціалізовані інструменти: він може бути обмежений вузьким або спеціалізованим набором інструментів.
Незалежне вікно контексту: його взаємодія відбувається у окремому контекстному циклі, що дозволяє зберігати токени у основній історії розмови.

Разом ці три властивості є причиною того, чому делегування завдань спеціалісту допомагає зберігати основну сесію охайною, зменшує витрати на її функціонування та робить її безпечнішою для безперервної роботи без нагляду.

З цього випливають кілька звичок. Надайте кожному спеціалісту одну вузьку відповідальність, адже чіткий запит працює краще, ніж розпливчастий. Надайте найменший набір інструментів, який дозволяє виконати роботу, і розширюйте його лише тоді, коли з’являється справжня потреба. Використовуйте прямі позиви @, поки ви ще вивчаєте поведінку агента, а потім дозвольте автоматичну делегацію, коли його опис виявиться надійним. Також зберігайте агентів на рівні проекту у репозиторії, щоб усі, хто клонує його, отримували ту саму команду спеціалістів.

Пов’язана література

Практичні нотатки: розробка функцій за допомогою Gemini CLI subagents — Детальний огляд Практичних нотаток: розробка функцій за допомогою Gemini CLI subagents: контракти, перевірки та шаблони коду для команд, які використовують цю модель.

Практичні нотатки: Що я дізнався про відправку продакшн-агента ШІ з Google — Детальний посібник з Практичних нотаток: Що я дізнався про відправку продакшн-агента ШІ з Google: контракти, перевірки та шаблони коду для команд, які використовують цю модель.

← Усі статті Надіслати бриф