Сабагенти й оркестрація

Що таке сабагент простими словами?

Сабагент (subagent) — це окремий екземпляр моделі, запущений з нуля: власне контекстне вікно, власний системний промпт, свій обмежений набір інструментів і дозволів. Він не бачить розмову провідного агента й не ділить із ним памʼять. Уся взаємодія зводиться до трьох речей: він отримує доручення, робить роботу у своєму вікні й повертає одне фінальне повідомлення. Для QA це спосіб віддати «брудну» роботу (пошук, читання пачки файлів, перебір гіпотез) убік, щоб головний контекст не заплив нею.

Навіщо взагалі ділити роботу на сабагентів, якщо один агент теоретично впорається?

Головна причина — не швидкість, а чистота контексту. Один агент на великій задачі неминуче засмічує собі вікно: туди лягають проміжні викиди інструментів, які більше не знадобляться, і гіпотези, від яких він уже відмовився, — а кожен крок агента ще й перевідсилає всю цю історію заново. Це прямо псує якість (на довгому контексті модель гірше тримає деталі) і роздуває рахунок. Сабагент забирає цю роботу у своє вікно й повертає лише вичавку, тож головний контекст лишається чистим. Паралелізм і спеціалізація — приємні бонуси, але суть саме в ізоляції.

Які три різні задачі розвʼязує поділ на сабагентів, і яка з них головна?

Ізоляція контексту, паралелізм і спеціалізація — і плутати їх не варто. Ізоляція: сабагент тримає брудну роботу у власному вікні, а нагору віддає підсумок — це головний виграш. Паралелізм: незалежні підзадачі йдуть одночасно, тож реальний час до результату коротшає. Спеціалізація: кожен сабагент має власний системний промпт і вузький інструментарій — окремий «дослідник», окремий «рецензент». Показовий момент: навіть на одній машині без жодного паралелізму сабагенти вже виправдані, бо бережуть головний контекст.

З чого складається взаємодія оркестратора з сабагентом?

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

Що означає, що канал між оркестратором і сабагентом «вузький і лоссі»?

Що між ними лише один прохід: задача вниз, звіт угору — і більше нічого. Це схоже на виклик функції з серіалізацією аргументів: усе, що не поклали в задачу, всередині сабагенту недоступне, а все, чого він не вписав у звіт, зовні втрачено назавжди. Лоссі (з втратами, lossy) — бо транскрипт сабагента після завершення зникає, і дістати з нього щось постфактум уже не вийде. Практичний висновок: і бриф, і звіт — це інтерфейси, які треба свідомо проєктувати, а не сподіватися, що «і так зрозуміло».

Чому доручення сабагенту має бути самодостатнім?

Бо сабагент не бачить контекст оркестратора — для нього розмови вище не існує. Доручення на кшталт «полагодь ці тести» без переліку файлів, симптомів і критерію готовності приречене: сабагент або вигадає деталі, або зробить не те. Добрий бриф — це, по суті, добре написаний баг-репорт, відданий інженеру, якого не було в кімнаті: шляхи, факти, очікуваний результат — усе в тексті. Ця помилка одна з найчастіших: люди пишуть задачу так, ніби сабагент читав усю попередню розмову.

Сабагент зробив роботу, але оркестратор не отримав ключову знахідку. Як таке можливо?

Звіт вийшов неповним. Скажімо, сабагент знайшов точний шлях до зламаного локатора, але у фінальне повідомлення його не вписав — а транскрипт із усіма проміжними кроками вже зник разом із контекстом сабагента. Оркестратор бачить лише те, що прийшло у звіті, тож знахідку він просто не дістане. Саме тому звіт треба проєктувати як повний артефакт: усе важливе — знахідки, шляхи, невдалі спроби — має бути явно в тексті, а не лишатися «в голові» сабагента.

Що робить оркестратор і чому його теж треба обмежувати?

Оркестратор (orchestrator) — це провідний агент, чия робота не «зробити самому», а розбити мету на незалежні підзадачі, роздати кожну сабагенту з самодостатнім брифом, зібрати звіти й звести їх у результат (узгодивши суперечності й вирішивши, чи потрібен ще раунд). Важливо, що він теж агент у циклі: його «дії» — це виклики сабагентів, а «спостереження» — їхні звіти. А отже, він так само може зациклитись чи згубити мету, тож ті самі запобіжники — ліміт кроків, умови зупинки — потрібні й тут.

Що таке патерн «оркестратор-виконавці» (orchestrator-workers)?

Це канонічна схема мультиагентності, де провідний агент динамічно вирішує, на скільки й яких саме підзадач бити роботу, а не йде за жорстко прописаним наперед планом. Оркестратор тримає загальну картину й стратегію, виконавці-сабагенти тримають деталі й тактику. Гнучкість тут і є цінністю: якщо після першого раунду звітів видно, що покриття недостатнє, оркестратор може нарізати ще підзадач. Це відрізняє його від статичного пайплайна з фіксованими кроками, який не вміє підлаштуватись під те, що реально знайшлося.

Коли сабагентів можна запускати паралельно, а коли — ні?

Паралелити можна лише незалежне — умова та сама, що й для паралельного запуску автотестів. Добре паралеляться read-heavy віяльні задачі: пошук, аудит, збір інформації — вони нічого не змінюють, тож не заважають одне одному, і три пошуки завершаться приблизно за час найдовшого, а не їхньої суми. Погано паралеляться write-heavy звʼязані задачі: два сабагенти, що одночасно правлять той самий файл чи сидять на тих самих тестових даних, влаштують гонку — конфлікти, перезаписи, недетермінований результат. Спільний змінюваний стан тут таке саме джерело болю, як у неізольованих тестах.

Як у Claude Code технічно описується сабагент?

Це Markdown-файл із YAML-фронтматером у .claude/agents/ для конкретного проєкту або в ~/.claude/agents/ для всіх ваших проєктів. У фронтматері — поля name, description, tools (обмежує інструментарій) і model (дозволяє посадити дешевшу роботу на дешевшу модель). Тіло файлу під фронтматером — це системний промпт сабагента, тобто його роль та інструкції. Ключова деталь: поле description не декоративне — саме за ним провідний агент вирішує, коли делегувати задачу цьому сабагенту, тож опис має чітко казати, для чого цей сабагент і коли його кликати.

Що таке headless-режим і навіщо він потрібен у CI?

Інтерактивний агент у терміналі розрахований на людину поруч, яка підтверджує дії. У CI такої людини немає, тому вмикається headless-режим (безголовий, неінтерактивний): у Claude Code це прапорець -p (він же --print) — агент отримує промпт, робить роботу, друкує результат і завершується. Щоб наступний крок пайплайна міг розпарсити відповідь, вивід роблять структурованим через --output-format json (є ще text і stream-json), і там же повертається вартість запуску — зручно стежити за витратами. Типові сценарії: тріаж падінь у нічному прогоні, генерація тесту з тікета, лінтер-рецензент на дифі PR.

Що небезпечного в запуску агента headless у CI?

Headless прибирає головний запобіжник агента — human-in-the-loop (людину в контурі): підтверджувати дії нема кому. Тому інструменти доводиться дозволяти наперед через --allowedTools і тримати цей список навмисно вузьким; для зачинених прогонів існують суворі режими дозволів, що забороняють усе, крім явно дозволеного. Найгостріше питання — незворотні дії: сабагент із правами на видалення даних, деплой чи git push і без нагляду — це та сама каскадна біда, що й у звичайного агента, тільки тепер її нема кому спинити. Рецепт: пісочниця, read-only там, де можна, і туго обмежений інструментарій.

Чому мультиагентність коштує кратно більше токенів?

Бо кожен сабагент — це окреме вікно з власним системним промптом і власною наростаючою історією, і кожен крок кожного агента перевідсилає свою історію заново. За оцінкою Anthropic, їхня багатоагентна дослідницька система спалювала приблизно у 15 разів більше токенів, ніж звичайна чат-взаємодія. Додає й сам вузький канал: бриф униз і звіт угору — це токени понад корисну роботу. До прямої ціни в токенах додаються ще й непрямі: дебажити важче (причина поганого результату може бути в розбитті оркестратора, у самому сабагенті або у зведенні звітів), а недетермінізм множиться на кількість агентів.

Коли мультиагентність — це overkill, і що робити спершу?

Правило те саме, що й для агентів загалом: спершу найпростіше рішення. Один агент дешевший і передбачуваніший, тож сабагенти виправдані лише тоді, коли задача справді ділиться на незалежні шматки й виграє від ізоляції контексту — широкий пошук, аудит набору, дослідження. Для тісно звʼязаної послідовної роботи, де кожен крок залежить від попереднього, один агент упорається дешевше й надійніше. Червоний прапорець на співбесіді — кандидат, що тулить сабагентів усюди: сильна відповідь називає ціну (кратно більше токенів, складніший дебаг) і починає з простого.

Дрібну задачу розбили на сабагентів, а рахунок несподівано зріс. Чому?

Бо на малому обсязі накладні витрати зʼїдають будь-яку вигоду. Кожен сабагент наново завантажує свій системний промпт, описи всіх доступних інструментів і піднімає власний контекст — і якщо корисної роботи там на кілька кроків, ця фіксована «плата за вхід» переважує економію. Ізоляція контексту окупається лише на масштабі, коли брудної роботи справді багато й вона діляється. Отже, симптом «розбили на сабагентів, а стало дорожче й не швидше» — це майже завжди ознака того, що задача була замала для мультиагентності й її мав робити один агент.

Три кейси, де видно механіку сабагентів на реальній роботі QA: як описати сабагента в Claude Code й чим добрий бриф відрізняється від «сабагент осліп», як за таблицею рішень обрати між одним агентом і роздачею на виконавців, і як безпечно запустити тріаж падінь headless у CI. Скрізь — що робити і чому саме так.

Кейс 1. Сабагент у Claude Code: файл, бриф, звіт

Задача — проаудитувати e2e-набір на крихкі локатори (XPath за індексом, класи з хешем від CSS-модулів). Це класична робота під сабагента: read-heavy, ділиться на пакети, засмічує контекст читанням десятків файлів. Опис сабагента кладемо у .claude/agents/locator-auditor.md:

---
name: locator-auditor
description: Знаходить крихкі локатори в e2e-тестах (XPath за позицією, класи з хешем, прив'язка до тексту) і повертає список підозрілих із файлом і рядком. Кликати при аудиті стабільності набору.
tools: Read, Grep, Glob
model: sonnet
---

Ти — аудитор стабільності локаторів. Для кожного переданого файлу
знайди селектори, що ламаються на кожному білді, і поверни звіт:
шлях, рядок, тип ризику, пропонована заміна на data-testid чи ARIA.
Нічого не редагуй — лише звітуй.

Тіло під фронтматером — системний промпт, tools тримає сабагента в режимі «тільки читати» (жодного Write чи Bash), description каже оркестратору, коли цей сабагент доречний.

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

Поганий:  «Подивись наші тести й познач погані локатори.»
Добрий:   «Проаналізуй файли tests/e2e/checkout/*.spec.ts.
           Крихкими вважай: XPath із позиційним індексом,
           CSS-класи з 6+ hex-символами, getByText на динамічному тексті.
           Поверни таблицю: файл | рядок | тип ризику | заміна.»

Що дивитися і чому:

• Поганий бриф прирікає сабагента на вигадування. «Наші тести» — де вони? «Погані» — за яким критерієм? Сабагент осліп до контексту оркестратора, тож він або піде шукати навмання, або вирішить за вас, що таке «поганий локатор». Самодостатній бриф — це шляхи, критерії й формат виходу в самому тексті, як баг-репорт для інженера, якого не було в кімнаті.
• Формат звіту задають у брифі, а не сподіваються. Якщо сабагент поверне суцільний абзац міркувань, оркестратору важко буде звести це з іншими пакетами. Проситимете таблицю з полем рядок — отримаєте те, що можна злити докупи.
• Звіт — єдине, що переживе сабагента. Усі проміжні кроки (десятки прочитаних файлів) лишаться в його контексті й зникнуть. Якщо сабагент знайшов крихкий локатор, але не вписав шлях у таблицю, — оркестратор його вже не дістане.

Кейс 2. Таблиця рішень: один агент чи сабагенти

Найдорожча помилка — тулити сабагентів туди, де вистачило б одного агента (роздутий рахунок), або навпаки садити одного агента на задачу, що просить поділу. Спершу — коли поділ виправданий:

Коли поділ обрано, друге питання — паралелити чи послідовно:

Логіка обох таблиць одна: спільний змінюваний стан — джерело болю, точно як у неізольованих паралельних тестів. Хочете паралелити — спершу переконайтеся, що шматки роботи не перетинаються; сумніваєтесь — робіть послідовно або одним агентом.

Кейс 3. Headless-тріаж падінь у CI

Нічний прогон червоний, треба автоматично протріажити лог і повісити ймовірну причину, без людини поруч. Це headless-режим: агент отримує промпт, працює, друкує JSON і виходить. Ключ до безпеки — туго обмежений інструментарій.

claude -p "Проаналізуй лог падіння з файлу $LOG_PATH. Визнач ймовірну
причину (таймаут / гонка / зіпсовані дані / баг застосунку) і коротко
обґрунтуй. Поверни лише JSON з полями reason та evidence." \
  --allowedTools "Read" \
  --output-format json > triage.json

Наступний крок пайплайна парсить структурований вивід і, наприклад, лишає коментар у тікеті:

REASON=$(jq -r '.result | fromjson | .reason' triage.json)
COST=$(jq -r '.total_cost_usd' triage.json)
echo "Ймовірна причина: $REASON (вартість тріажу: \$$COST)"

Що дивитися і чому:

• --allowedTools "Read" — і жодного Write, Bash чи мережі. У headless нема кому підтверджувати дії: human-in-the-loop зник. Тріаж має лише читати лог, тож дозволяємо рівно це. Дати сюди Bash чи права на деплой — означає пустити незворотні дії без гейта й без нагляду.
• --output-format json робить вивід машиночитним. Без нього наступний крок довелося б парсити регулярками з вільного тексту. У JSON-відповіді приходить і total_cost_usd — зручно тримати око на витратах headless-прогонів, які легко ростуть непомітно.
• Оркестрація теж може бути headless. Скрипт здатен запустити агента, який сам роздасть роботу сабагентам, — і все відпрацює без людини. Саме тому в CI безпека важить особливо: прогін тримають у пісочниці, дають read-only там, де можна, а незворотні дії (видалення, деплой, git push) гейтять окремо.
• Тріаж каже «ймовірна причина», а не вирок. Агент читає лог і висуває гіпотезу — далі її ще має підтвердити людина або окремий крок. Автоматично закривати тікет як «не баг» на основі одного headless-тріажу небезпечно: недетермінізм нікуди не подівся.

Навіщо ділити роботу

• Можу назвати головну причину сабагентів — ізоляція контексту, а не паралелізм чи «щоб швидше».
• Розумію, чому один агент на великій задачі сам собі засмічує вікно: проміжні викиди інструментів і покинуті гіпотези, які щокроку перевідсилаються заново.
• Не плутаю три різні вигоди поділу: ізоляція контексту, паралелізм, спеціалізація.

Анатомія сабагента

• Знаю, що сабагент — окремий екземпляр моделі зі своїм вікном, промптом, інструментами й дозволами, який не бачить історію оркестратора.
• Можу назвати три складові взаємодії: контекст (з чим стартує), задача (доручення вниз), звіт (єдине повідомлення нагору).
• Знаю, що в Claude Code сабагент — це Markdown-файл із фронтматером у .claude/agents/ (проєкт) чи ~/.claude/agents/ (глобально), а тіло файлу — його системний промпт.
• Розумію, що поле description не декор: саме за ним оркестратор вирішує, коли делегувати задачу цьому сабагенту.

Вузький канал: задача і звіт

• Розумію, що канал між оркестратором і сабагентом один і лоссі: задача вниз, звіт угору, а транскрипт роботи назад не перетинає.
• Можу пояснити, чому задача має бути самодостатньою (сабагент осліп до контексту вище) — і що добрий бриф схожий на баг-репорт для інженера, якого не було в кімнаті.
• Можу пояснити, чому звіт має бути повним артефактом, а не «і так зрозуміло»: після завершення транскрипт сабагента зникає.

Оркестрація і паралелізм

• Можу описати роль оркестратора чотирма дієсловами: розбити, роздати, зібрати, звести.
• Знаю патерн orchestrator-workers: оркестратор динамічно вирішує, на скільки й яких підзадач бити, а не йде за жорстким планом.
• Знаю, що паралелити можна лише незалежне: read-heavy пошук/аудит — так, write-heavy зі спільним станом — гонка.

Headless у CI

• Розумію, що headless (-p / --print) прибирає human-in-the-loop, тож дозволи треба видавати наперед через --allowedTools і тримати список вузьким.
• Знаю, навіщо --output-format json: машиночитний вивід для наступного кроку пайплайна плюс вартість запуску.
• Можу пояснити, чому незворотні дії (видалення, деплой, git push) у headless-прогоні треба гейтити або тримати в пісочниці.

Ціна й коли не варто

• Знаю порядок ціни: багатоагентна система ≈ 15x токенів проти звичайного чату (оцінка Anthropic).
• Розумію, чому дебаг мультиагента важчий: причина може бути в розбитті, у сабагенті або у зведенні, а недетермінізм множиться на кількість агентів.
• Можу пояснити правило «спершу найпростіше»: для звʼязаної послідовної роботи один агент дешевший і передбачуваніший.
• Розумію, чому дрібну задачу не варто дробити: накладні витрати на кожен сабагент зʼїдають вигоду, і сабагенти окупаються лише на масштабі.