Мой дэйли дайджест

одно техническое понятие в день

Мастер Claude · Блок 3. Субагенты

Урок 28 из 93 · ~10 мин чтения

Оркестратор + субагенты

Урок пока закрыт

Курс проходится последовательно.

К текущему уроку

День 28: Оркестратор + субагенты

Почему это важно именно вам

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

Директор по развитию редко решает задачу, которая требует ровно одного типа экспертизы. Квартальный отчёт для руководства — это аналитика данных плюс редактура плюс структурирование для аудитории. Аудит папки с договорами — это чтение каждого документа плюс сводка по рискам плюс список приоритетов. В реальной работе задачи многосоставные, и управлять несколькими агентами вручную означает добавлять себе ту же координационную нагрузку, от которой вы пытались избавиться.

Оркестратор — это ответ на этот вопрос. Агент, единственная задача которого — управлять другими агентами. Он получает задачу от вас, разбивает её на части, запускает нужных субагентов параллельно или последовательно, собирает результаты и возвращает вам итог. Вы даёте одно задание — получаете готовый результат. То, что происходит внутри, вас не касается. Именно так работает нормальная команда под управлением нормального менеджера.

Что это такое

Оркестратор — это обычный субагент, который получает доступ к специальному инструменту: Agent (старое имя Task работает как псевдоним). Этот инструмент позволяет агенту запускать других агентов. Без Agent — просто агент. С Agent — координатор, который может делегировать.

Аналогия из управления: руководитель проекта. Он не пишет код, не рисует макеты, не ведёт переговоры с клиентом сам. Его работа — разбить проект на задачи, назначить каждую нужному специалисту, отследить выполнение и собрать результат. Оркестратор в Claude Code работает точно так же. У него нет специальных знаний про анализ данных или редактуру текста — это не его дело. Его дело — понять, что нужно, найти нужного исполнителя и передать задачу с правильным контекстом.

Главное отличие от обычного вызова агента

Когда вы вызываете агента напрямую (@analyst), вы — координатор. Вы сами решаете, кого вызвать, что передать, как использовать результат. Когда вы вызываете оркестратора (@orchestrator), он берёт эту роль на себя. Вы описываете задачу, а не процесс. Это другой уровень абстракции.

Ключевая особенность многоагентных сценариев — параллельность. Если аналитик и редактор не зависят друг от друга, оркестратор может запустить их одновременно. Анализ трёх договоров займёт столько же времени, сколько анализ одного — потому что три агента работают параллельно. В одиночном режиме вы получаете последовательность. В многоагентном — конвейер или параллельную очередь, в зависимости от задачи.

Как работает на практике

Разберём конкретный сценарий: у вас папка с отчётами за квартал от нескольких подразделений. Нужно проанализировать каждый и получить общий дайджест.

Шаг 1. Структура папки агентов

Для многоагентного сценария нужно минимум два файла в .claude/agents/: сам оркестратор и хотя бы один субагент. Обычно у вас уже есть субагенты — добавляем оркестратора.

.claude/
└── agents/
    ├── orchestrator.md     ← оркестратор
    ├── data-analyst.md     ← уже существует
    └── editor.md           ← уже существует

Шаг 2. Создаём оркестратора

Файл .claude/agents/orchestrator.md:

---
name: orchestrator
description: Координирует анализ нескольких отчётов или документов. Вызывай когда нужно обработать папку с файлами и получить сводный результат.
tools:
  - Agent
  - Read
  - Glob
  - Write
---

Ты координатор аналитических задач. Твоя работа — организовать обработку нескольких документов и собрать итоговый дайджест.

Алгоритм работы:
1. Найди все целевые файлы в указанной папке (используй Glob)
2. Для каждого файла запусти субагента data-analyst с задачей: "Проанализируй файл [имя], выдели ключевые показатели, риски и рекомендации. Формат: три секции — Показатели, Риски, Рекомендации."
3. Дождись результатов от всех субагентов
4. Объедини результаты в один документ: сначала сводная таблица (все файлы в строках, три секции в столбцах), потом отдельные разделы с детализацией по каждому файлу
5. Сохрани итоговый документ как digest_YYYY-MM-DD.md в той же папке

Если субагент не смог обработать файл — отметь это в дайджесте отдельно с причиной.
Не пересказывай процесс работы — возвращай только готовый дайджест.

Разберём ключевые моменты:

tools: [Agent, Read, Glob, Write] — оркестратору нужны четыре инструмента. Agent — запускать субагентов. Read — читать файлы при необходимости. Glob — находить файлы по шаблону. Write — сохранить итоговый документ.

Алгоритм в промте — оркестратор должен знать не только «что делать», но и «как координировать». Это не аналитические правила, а управленческие: найди исполнителей, распредели задачи, собери результат, обработай ошибки.

Явный формат для субагентов — когда оркестратор передаёт задачу субагенту, он передаёт конкретный формат ожидаемого результата. Иначе каждый субагент вернёт что-то своё, и сборка дайджеста станет головной болью.

Шаг 3. Как оркестратор запускает субагентов

Когда оркестратор получает задачу, он использует инструмент Agent примерно так (это происходит внутри, вы этого не видите напрямую):

Agent: запустить субагента data-analyst
Задача: "Проанализируй файл reports/Q1_marketing.md, 
выдели ключевые показатели, риски и рекомендации.
Формат: три секции — Показатели, Риски, Рекомендации."

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

Параллельность по умолчанию

Если оркестратор запускает несколько задач без явной последовательности («сначала одно, потом другое»), Claude Code может выполнять их параллельно. Для анализа папки с пятью файлами это означает, что время выполнения ≈ время анализа одного файла, а не пяти. Реальная экономия, особенно на больших объёмах.

Шаг 4. Вызов оркестратора

Запустите Claude Code в рабочей директории и напишите:

@agent-orchestrator Проанализируй все файлы .md в папке reports/ и сделай квартальный дайджест

Оркестратор найдёт файлы через Glob, запустит data-analyst для каждого, дождётся результатов и вернёт вам готовый документ. Вы дали одну команду.

Шаг 5. Последовательный сценарий — когда один зависит от другого

Не все задачи можно выполнять параллельно. Иногда второй шаг зависит от первого. Например: сначала аналитик разбирает данные, потом редактор готовит текст на основе этого анализа.

В этом случае оркестратор строит цепочку явно:

Алгоритм работы для отчёта:
1. Запусти data-analyst: "Проанализируй [файл], верни структурированные данные в JSON-формате"
2. После получения результата запусти editor: "На основе этих данных [вставить результат] напиши краткий отчёт для руководства, 1-2 страницы, деловой стиль"
3. Сохрани финальный текст как report_[имя_файла].md

Ключевое — явная передача результата первого субагента второму. Оркестратор — мост между ними. Он получил от аналитика данные, завернул их в контекст для редактора, запустил редактора.

Не перегружайте контекст оркестратора

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

Шаг 6. Проверка, что агенты видны

Перед запуском убедитесь, что оркестратор видит своих субагентов. В Claude Code:

/agents

Наберите @ в чате и посмотрите, все ли агенты появились в подсказке. Файлы с испорченным frontmatter найдёт claude plugin validate .claude/agents. Команда /agents списка больше не выводит. Если какого-то агента нет — проверьте frontmatter его файла.

Частые ошибки

Ошибка 1: Давать оркестратору аналитические задачи

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

Признак проблемы: промт оркестратора длиннее промта субагентов. Это инверсия. Оркестратор — лёгкий и управленческий. Субагенты — тяжёлые и специализированные.

Ошибка 2: Не передавать формат ожидаемого результата субагентам

Оркестратор запустил пятерых субагентов. Первый вернул таблицу в Markdown, второй — маховой текст, третий — JSON, четвёртый — список с разными заголовками, пятый — что-то совсем непохожее. Сборка дайджеста превратилась в ручную работу.

Исправление простое: в задаче для каждого субагента явно укажите формат вывода. Три-четыре строки про структуру результата экономят час на постобработке. «Верни три абзаца: выводы, риски, рекомендации» лучше, чем «проанализируй и расскажи».

Ошибка 3: Запускать оркестратор без готовых субагентов

Оркестратор вызывает субагентов по имени. Если субагент не существует или его файл содержит ошибку в frontmatter — оркестратор либо упадёт с ошибкой, либо попытается выполнить задачу самостоятельно, выйдя за пределы своей роли.

Перед первым запуском: наберите @ в чате и убедитесь, что все субагенты, которых планирует вызывать оркестратор, видны в списке. Если какого-то нет — разберитесь с его файлом, прежде чем запускать систему.

Ошибка 4: Пропустить обработку ошибок в оркестраторе

Один из пяти файлов оказался повреждённым. Субагент не справился. Оркестратор молча пропустил этот файл и не сообщил об этом. Вы получили дайджест по четырём файлам из пяти и не знаете об этом.

В промте оркестратора всегда прописывайте: что делать, если субагент вернул ошибку или пустой результат. «Отметь в дайджесте отдельно с причиной» — минимальный разумный вариант. Оркестратор должен возвращать полный результат, включая информацию о том, что не сработало.

Когда нужно / когда нет

Оркестратор нужен, если:

У вас есть повторяющаяся задача, которая состоит из нескольких однотипных или последовательных шагов. Еженедельный анализ папки с отчётами, ежемесячная сводка по договорам, регулярный аудит документов — всё это кандидаты для оркестратора. Один раз настроил, дальше один вызов.

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

Работа состоит из независимых этапов, которые разные субагенты выполнят лучше, чем один универсальный. Аналитик + редактор + структуратор — каждый в своей роли, оркестратор координирует.

Оркестратор не нужен, если:

Задача разовая и нетипичная. Написать одно конкретное письмо партнёру по нестандартной ситуации — быстрее сделать напрямую с нужным агентом или без агентов вообще.

Задача однородная и для одного субагента. Если вам нужно проанализировать один договор — просто вызовите аналитика. Оркестратор здесь лишнее звено.

У вас ещё нет субагентов под задачу. Оркестратор без исполнителей — бессмысленно. Сначала создайте и проверьте субагентов (Дни 21-24), потом добавляйте координатора.

Оркестратор — последний шаг, не первый

Частая ошибка — начинать проектирование с оркестратора. «Буду делать сложную систему». На практике: сначала убедитесь, что один субагент работает хорошо. Потом второй. Потом посмотрите, нужна ли координация между ними — и только тогда добавляйте оркестратора. Система, которая выросла снизу вверх, работает надёжнее той, что спроектирована сверху вниз на бумаге.

Связь с другими уроками

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

День 22 — создание первого агента с frontmatter, полем tools и системным промтом. Оркестратор устроен так же — это обычный файл в .claude/agents/, только с Agent в списке инструментов и управленческим промтом вместо специализированного. Всё, что вы узнали про структуру файла агента, применяется здесь без изменений.

День 29 разберёт безопасность агентных систем — что происходит, когда агенты получают инструкции от других агентов, а не от вас напрямую. Это прямое продолжение сегодняшнего урока: вы уже знаете, как строить систему. Завтра узнаете, как убедиться, что она не сделает что-то неожиданное.

Задание на сегодня

Создайте файл .claude/agents/orchestrator.md с минимальным рабочим оркестратором для вашей папки с документами.

Конкретные шаги:

  1. Выберите папку, в которой у вас есть несколько однотипных файлов — отчёты, протоколы, договоры, любые документы одного типа. Достаточно двух-трёх файлов.
  2. Создайте файл оркестратора по шаблону из урока. В tools обязательно включите Agent. В промте укажите: какой субагент вызывать, в каком формате запрашивать результат, как собрать итог.
  3. Убедитесь, что субагент, которого будет вызывать оркестратор, уже существует и появляется в подсказке по @.
  4. Запустите оркестратора одним запросом: @agent-orchestrator [задача по вашим файлам].
  5. Посмотрите на итоговый результат.

Критерий выполнено: оркестратор обработал минимум два файла через субагентов и вернул объединённый результат — без того, чтобы вы вызывали субагентов вручную по одному.

Если что-то не сработало — наберите @ и проверьте, что оба агента в подсказке; испорченный frontmatter покажет claude plugin validate .claude/agents. Это решает большинство проблем при первом запуске.

Резюме

Следующий урок откроется после отметки.