Субагенты (Subagents): распределение задач для параллельного выполнения (только по вашему требованию)
📚 Навигация по серии: Предыдущая статья [20 · Подключение внешних инструментов через MCP] объясняла интеграцию Codex с внешними ресурсами для поиска документации и работы с API. В этой главе мы изменим подход: вместо подключения новых инструментов мы научимся распределять задачи для параллельного выполнения. Субагенты (Subagents) — это пул специализированных помощников с независимыми моделями, системными инструкциями и правами доступа. Несколько таких агентов могут работать одновременно, возвращая сводный результат в основную сессию.
Коллеги, сегодня мы разберем одну из самых интригующих и часто неправильно понимаемых функций Codex — субагентов.
Название звучит солидно: «параллельные агенты», будто вы командуете целым спецотрядом. Когда я впервые обнаружил этот функционал, мне сразу захотелось разбивать каждую задачу на пять-шесть агентов — казалось, что именно так выглядит профессиональная разработка.
Но признаемся честно: субагенты в Codex работают иначе, чем в других инструментах. Здесь действует важное контринтуитивное правило: по умолчанию Codex не разделяет задачи самостоятельно. Руководство говорит об этом прямо: субагенты создаются только тогда, когда вы явно требуете этого в промпте. Если вы не напишете команду вроде «запусти параллельно нескольких агентов», Codex будет выполнять задачу в одиночку. Это правило определяет логику использования инструмента.
В этой статье мы не просто научимся вызывать субагентов, создавать для них конфигурации и распределять модели. Главное — мы определим границу применимости: какие задачи действительно выигрывают от параллельного выполнения, а какие принесут лишь лишние траты и путаницу.
После прочтения этой статьи вы получите:
- Четкое понимание сущности субагентов и их отличий от классической работы с одной моделью
- Способы устранения проблем засорения (context pollution) и деградации (context rot) контекста, а также правила выбора задач для разделения
- Применение трех встроенных субагентов (
default,worker,explorer), доступных без дополнительных настроек - Пошаговую инструкцию по созданию конфигураций пользовательских агентов в файлах TOML в глобальных и локальных каталогах
- Тонкую настройку моделей (
model) и глубины логики (model_reasoning_effort) для повышения эффективности субагентов - Практику: написание и запуск пользовательского агента в режиме «только чтение» для безопасного сбора информации
⚠️ Все консольные команды, ключи конфигурации и значения по умолчанию приведены согласно официальной документации Codex. Версии пакетов и имена моделей могут меняться, ориентируйтесь на фактические названия в вашей системе.
01 Что такое субагенты
Начнем с определения: субагенты — это пул специализированных агентов, временно создаваемых Codex для решения конкретных подзадач. Они работают в изолированных потоках и возвращают в основной чат только готовое резюме, не перегружая его логами своей работы.
Аналогия: распределение расследования между группой детективов. Вы выступаете в роли шефа полиции (основная сессия). Перед вами стоит комплексная задача: «провести аудит безопасности, производительности и тестирования нового функционала». Вместо того чтобы проверять эти направления по очереди самому, вы поручаете дело трем детективам. Один фокусируется строго на безопасности, второй — на тестах, третий — на скорости работы. Они работают параллельно. По окончании расследования они не приносят вам сотни страниц черновых записей, а кладут на стол краткие отчеты с выводами. В итоге вы получаете лаконичную структурированную сводку.
Субагенты выполняют задачи в обособленных окружениях. Разберем ключевые понятия:
- Subagent: дочерний агент, созданный Codex под конкретное поручение;
- Agent thread: изолированный поток выполнения команд субагентом (вы можете переключаться между ними в консоли с помощью команды
/agent).
Сравнение параметров потоков:
| Параметр | Основная сессия (ваш диалог) | Субагент (выделенный поток) |
|---|---|---|
| Контекст / Поток | Общая история диалога, требований и принятых решений | Изолированный поток (agent thread), сфокусированный строго на своей задаче. Логи и детали остаются внутри |
| Модель / Глубина рассуждений | Задается для общей сессии | Настраивается индивидуально: быстрая модель для поиска, мощная — для проверки (раздел 05) |
| Системные инструкции | Логика работы Codex по умолчанию | Специализированный промпт (developer_instructions), например: «выполнять только чтение, запись запрещена» |
| Права песочницы | Общие настройки сессии | Наследуются от родителя, но могут быть переопределены (например, принудительный режим read-only) |
Главная ценность субагентов — фильтрация промежуточных технических логов из основного диалога. Субагенты самостоятельно разбираются в деталях, запускают утилиты и читают файлы, а в основную сессию возвращают только готовые резюме без лишнего мусора.
Это свойство определяет границы применимости инструмента.
Схема показывает логику работы: основная сессия разбивает задачу на части и распределяет их между субагентами. Каждый из них работает в изолированном контексте (поиск информации, запуск тестов, чтение документации). По завершении они возвращают в основной чат лаконичные сводные отчеты, оставляя детали внутри своих потоков.
💡 Резюме одной фразой: субагент — это изолированный поток со своей моделью и уровнем прав для решения конкретной задачи. Субагенты работают параллельно и возвращают в основной диалог только резюме результатов, что защищает чат от переполнения логами.
02 Решаемые проблемы и ограничения применимости
Выделение подзадач в фоновые потоки решает две основные проблемы работы с контекстом больших языковых моделей.
Context pollution (засорение контекста)
Аналогия: стопка важных документов, перемешанная с чеками на обед. В чате должна храниться только полезная информация: требования, архитектура, утвержденные правки. Если вы просите модель запустить тесты, в чат выводится огромный лог выполнения. Критически важные детали требований оказываются погребены под сотнями строк технического вывода. Это и есть засорение контекста.
Официальное определение:
Context pollution（上下文污染）：有用的信息被吵闹的中间输出埋没。
Практический пример: при отладке стороннего API мне приходилось отправлять запросы и анализировать ответы JSON. Спустя десять шагов мне потребовалось уточнить исходные требования к полям. Чтобы найти нужное сообщение, пришлось прокручивать чат на двадцать экранов вверх сквозь логи JSON. Вся эта промежуточная информация должна была обрабатываться в фоновом потоке.
Context rot (деградация контекста)
Аналогия: затянувшаяся планерка. В первый час обсуждения все сфокусированы на задаче. К третьему часу из-за накопления мелких деталей и посторонних тем качество принимаемых решений падает. Модели ведут себя схожим образом: по мере роста нерелевантной информации в контексте сессии качество ответов снижается.
Официальное определение:
Context rot（上下文腐烂）：随着对话被越来越多不那么相关的细节填满，表现逐渐变差。
Решение очевидно: вынести технические задачи в фоновые потоки субагентов, возвращая в основной чат только короткие выводы. Это позволяет разбивать даже объемную документацию на части для параллельного анализа группой субагентов.
Граница применимости: какие задачи не стоит разделять
Использование субагентов влечет за собой финансовые затраты. Каждая сессия субагента расходует системные лимиты (tokens) независимо от родительской. Чем больше агентов запущено, тем выше стоимость. Также параллельная запись в файлы несет риски по сравнению с чтением:
起步时，把并行 agent 用在偏读的任务上，比如探路、跑测试、分流、做摘要。偏写的并行工作流要更小心，因为多个 agent 同时改代码会撞车、还会增加协调成本。
Сводная таблица выбора тактики работы:
| Тип задачи | Стоит ли использовать субагентов | Причина |
|---|---|---|
| Поиск информации, тесты, логи, суммаризация (чтение, много вывода) | ✅ Да, рекомендуется | Убирает шум из основного чата. Идеальный сценарий |
| Независимые исследования (проверка API, БД, авторизации) | ✅ Да, рекомендуется | Параллельный запуск экономит время ожидания |
| Точечные мелкие правки в пределах видимости | ❌ Нет | Избыточный расход токенов на создание и запуск агента |
| Одновременная запись в один файл несколькими агентами | ⚠️ Не рекомендуется | Высокий риск конфликтов версий и ошибок слияния |
| Задачи с жесткой последовательностью шагов (A → B → C) | ⚠️ Не рекомендуется | Параллельный запуск не даст выигрыша в скорости |
Практический совет: не запускайте субагентов для простых точечных правок (например, изменения имени функции). Время на инициализацию потоков и расход токенов превысят выгоду. Выполняйте такие изменения в основном потоке.
💡 Резюме одной фразой: субагенты устраняют проблемы засорения и деградации контекста, вынося служебную информацию за рамки основного диалога. Избегайте параллельного запуска для мелких правок, зависимых шагов и записи в файлы. Избыточное количество агентов увеличивает расходы и замедляет работу.
Связь выбора тактики и запуска процессов показана на схеме:
Схема иллюстрирует логику принятия решений: простые задачи остаются в основном потоке. Сложные независимые блоки перенаправляются в параллельные потоки субагентов (при условии явного требования в промпте), результаты которых объединяются перед выводом пользователю.
03 Встроенные агенты по умолчанию и способы вызова
В Codex доступны три предустановленных агента:
| Встроенный агент | Назначение | Область применения |
|---|---|---|
default | Универсальный агент | Используется по умолчанию при отсутствии явных требований |
worker | Исполнитель (запись, правки) | Создание кода, исправление багов и другие активные задачи |
explorer | Исследователь (только чтение) | Изучение кодовой базы, поиск файлов и аудит |
Помните главное правило: запуск субагентов выполняется строго по текстовому запросу в чате. Агент не разделит задачу сам.
Codex 不会自动派生子代理，只有在你明确要求子代理或并行 agent 工作时才会用。
Для вызова используйте промпты вида «spawn two agents», «delegate this work in parallel» или «use one agent per point». Хороший промпт запуска содержит:
- Логику разделения подзадач;
- Условие ожидания выполнения всех потоков;
- Формат итоговой сводки.
Пример запроса в чате:
用并行子代理审一下这个分支（当前分支 vs main）。开一个 agent 专盯安全风险、一个专盯测试缺口、一个专盯可维护性。三个都等齐，再按类别把发现汇总，带上文件位置。Codex самостоятельно возьмет на себя управление жизненным циклом потоков: создание, передачу инструкций, контроль выполнения и завершение процессов. Сводный ответ будет выведен только после завершения работы всех запущенных субагентов.
Ограничение визуализации: работа субагентов отображается в CLI и десктопном приложении. Поддержка вывода статуса потоков в расширениях IDE запланирована к выходу в будущих версиях.
💡 Резюме одной фразой: три встроенных агента (
default,worker,explorer) активны сразу. Однако Codex никогда не разделяет задачи сам. Чтобы запустить их, укажите в промпте требования параллельности и формат сводного ответа.
04 Управление активными агентами: команда /agent и текстовые команды
Вы можете контролировать работу запущенных агентов и менять их задачи на лету с помощью двух инструментов.
Инструмент 1: Переключение через команду /agent
Для просмотра логов и статуса конкретного фонового потока используйте команду /agent (в единственном числе) в консоли:
/agentЭта команда выводит список активных потоков и позволяет переключаться между ними для прямого диалога с субагентом или анализа промежуточных логов.
Инструмент 2: Управление текстовыми командами
Вы можете отдавать прямые команды на управление субагентами на естественном языке, например: «останови работу третьего субагента». Codex самостоятельно завершит соответствующий поток.
Аналогия: диспетчерский пульт с рацией. Вы можете переключаться на каналы отдельных сотрудников для сбора информации (команда /agent) или отдавать общие команды на завершение или перенаправление задач («канал 3, прекратить поиск»). Вы полностью контролируете процесс.
Особенности согласования прав в параллельном режиме: Если фоновый поток сталкивается с операцией, требующей согласования (например, запись файла за пределами рабочей области), в интерактивном CLI появится уведомление. Нажмите клавишу o для перехода в контекст вызвавшего запрос субагента, оцените риски и примите решение. В неинтерактивных сценариях (запуск скриптов) такой запрос приведет к завершению потока с ошибкой.
💡 Резюме одной фразой: для контроля используйте
/agent(переключение и просмотр логов потока) или отдавайте прямые команды на остановку или перенаправление агентов текстом в чате. При появлении запросов согласования из фоновых потоков используйте клавишуoдля быстрого перехода.
05 Создание пользовательских агентов: файлы конфигурации TOML
Если для решения задач вам регулярно требуются специфичные правила (например, постоянный аудит кода на предмет безопасности с определенным поведением), вы можете зафиксировать эти настройки в пользовательском субагенте.
Для создания агента опишите файл конфигурации TOML и разместите его в одном из каталогов:
| Каталог | Область действия | Сфера применения |
|---|---|---|
~/.codex/agents/ | Во всех ваших проектах | Универсальные агенты вашей рабочей среды |
.codex/agents/ проекта | Только в текущем репозитории | Специфичные проектные агенты (фиксируются в Git) |
Аналогия: личное дело специалиста. Встроенные агенты — это сотрудники общего профиля. Создавая TOML-файл, вы нанимаете узкого специалиста: даете ему имя, определяете круг задач, снабжаете инструкциями по работе и выделяете бюджет на инструменты.
Минимальный файл конфигурации агента содержит всего три обязательных параметра:
name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
"""Описание полей конфигурации:
| Параметр | Обязательный | Назначение | Описание |
|---|---|---|---|
name | Да | Уникальное имя агента для вызова | Основной идентификатор. Рекомендуется называть файл по этому имени |
description | Да | Текстовое описание назначения агента | Облегчает выбор инструмента разработчиками |
developer_instructions | Да | Базовые системные инструкции поведения | Роль и правила работы агента |
nickname_candidates | Нет | Пул имен для отображения в интерфейсе | Используется для визуального отличия при параллельном запуске нескольких копий |
Остальные параметры (модель, лимиты, доступы песочницы) наследуются от родительской сессии, если они не переопределены явно. Файлы конфигурации агентов накладываются поверх общих настроек, а совпадающие имена переопределяют встроенных агентов (ваш локальный explorer заменит системный).
Выбор моделей и глубины рассуждений для субагентов
Переопределение параметров позволяет оптимизировать расходы и качество выполнения задач:
model(используемая модель). Назначайте легкие модели для рутинных операций и тяжелые — для сложного анализа. Имена моделей меняются, используйте актуальные для вашей системы;model_reasoning_effort(глубина рассуждений).
Режимы глубины рассуждений:
| Глубина рассуждений | Сфера применения | Издержки |
|---|---|---|
high | Анализ сложной логики, поиск скрытых уязвимостей, проверка верстки | Медленная работа, высокий расход лимитов. Максимальное качество |
medium | Сбалансированный режим для большинства задач | Средние параметры |
low | Простые рутинные операции | Быстрое выполнение, минимальный расход |
Пример конфигурации субагента-исследователя в файле TOML:
# .codex/agents/scout.toml
name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes."
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Stay in exploration mode.
Trace the real execution path, cite files and symbols, and avoid proposing fixes unless asked.
"""Обратите внимание на строку sandbox_mode = "read-only": мы принудительно запретили агенту вносить изменения в файлы, сделав его работу безопасной независимо от общих настроек родительской сессии.
Изменения настроек в интерактивном CLI (например, флаг глобального доступа
--yolo) переопределяют статические параметры файлов конфигурации субагентов.
Глобальные параметры субагентов настраиваются в основном файле config.toml (секция [agents]):
| Глобальный ключ | Назначение | Значение по умолчанию |
|---|---|---|
agents.max_threads | Лимит параллельно запущенных потоков агентов | 6 по умолчанию |
agents.max_depth | Глубина вложенности вызовов агентов (от корня 0) | 1 по умолчанию (запуск дочерних разрешен, внучатых — запрещен) |
agents.job_max_runtime_seconds | Лимит времени выполнения для пакетов CSV | 1800 секунд по умолчанию |
Рекомендуется сохранять значение max_depth = 1 для исключения неконтролируемого рекурсивного размножения агентов, которое ведет к мгновенному расходу лимитов и перегрузке процессора.
💡 Резюме одной фразой: пользовательский агент описывается в файле TOML в каталогах
~/.codex/agents/или.codex/agents/проекта. Ключевые поля:name,descriptionиdeveloper_instructions. Вы можете переопределять модели (model), глубину рассуждений (model_reasoning_effort) и принудительно ограничивать права черезsandbox_mode.
06 Практика: создание и запуск локального субагента в режиме «только чтение»
Проверим работу субагентов на практике. Создадим локального агента безопасности, поручим ему выполнить анализ файлов и убедимся, что он возвращает краткую сводку и не может вносить изменения на диск.
Шаг 1. Создаем структуру каталогов проекта (в Unix-терминале)
mkdir sub-demo
cd sub-demo
mkdir -p .codex/agentsВ Windows PowerShell используйте:
mkdir sub-demo; cd sub-demo; mkdir .codex\agents -Force.
Шаг 2. Создаем файл конфигурации субагента
В папке .codex/agents/ создайте файл scout.toml со следующим текстом:
name = "scout"
description = "只读的项目侦察兵，读指定文件、回报结构与潜在问题，不动手改。"
sandbox_mode = "read-only"
model_reasoning_effort = "low"
developer_instructions = """
你是一个只读的代码侦察兵，只探路、不改代码。
被派来时：
1. 读用户指定的文件
2. 按可读性、命名、潜在 bug 三类列出问题
3. 每条给一句改进方向，但绝不修改任何文件
最后只回一份精炼摘要，别把原始代码整段贴回来。
"""Параметр модели наследуется от родительской сессии, песочница заблокирована в режиме read-only, глубина рассуждений снижена для скорости.
Шаг 3. Создаем тестовый файл кода
echo 'def f(a, b):
return a / b' > calc.pyФункция содержит неочевидные имена переменных и риск деления на ноль, что станет отличной целью для проверки.
Шаг 4. Запускаем сессию и вызываем субагента
codexВнутри чата явно потребуем запустить субагента:
派 scout 这个子代理去侦察 calc.py，按它的守则只回一份问题摘要，别动文件。Ожидаемый результат: Codex запустит дочерний поток с именем scout (статус выполнения отобразится в CLI). Агент проанализирует файл в режиме чтения и вернет в чат сводку проблем (неинформативные имена аргументов, риск ZeroDivisionError). При этом исходный файл изменен не будет. Для проверки фоновых логов можно использовать команду /agent.
Шаг 5. Проверка файлов диска
Выйдите из сессии и откройте файл кода:
cat calc.pyОжидаемый результат: содержимое файла calc.py осталось без изменений. Ограничение прав песочницы субагента сработало корректно.
Если субагент не запустился, проверьте правильность формулировки промпта (требование параллельности должно быть явным) и отсутствие ошибок синтаксиса в TOML-файле.
💡 Резюме одной фразой: выполните на практике последовательность «создание scout.toml с флагом read-only → создание calc.py → вызов субагента scout в чате → проверка сохранности calc.py после завершения».
07 Дополнительно: пакетная обработка файлов CSV (экспериментально)
⚠️ Данная функция является экспериментальной и может менять синтаксис в новых версиях.
При наличии большого числа однотипных операций (аудит множества независимых файлов или пулл-реквестов) Codex поддерживает пакетный запуск субагентов через команду spawn_agents_on_csv. Система считывает файл CSV и запускает для каждой строки свой поток субагента-исполнителя, экспортируя итоговую таблицу после завершения всех процессов.
Каждый субагент в пакете обязан вернуть результат через функцию report_agent_job_result, иначе соответствующая строка в таблице пометится как ошибочная.
Сферы применения пакетного режима приведены в таблице:
| Сценарий | Применимость spawn_agents_on_csv | Причина |
|---|---|---|
| Аудит десятков пулл-реквестов одинаковой структуры | ✅ Рекомендуется | Одинаковые действия для множества объектов. Высокая скорость |
| Перевод комментариев в множестве файлов | ✅ Рекомендуется | Независимые строки, идеальный сценарий для пакетов |
| Задачи с зависимостями этапов выполнения | ❌ Не подходит | Строки обрабатываются параллельно, последовательность не гарантируется |
| Мелкие правки для 3-4 файлов | ❌ Не подходит | Затраты на подготовку пакета превышают время обычного запроса |
| Параллельная запись в общие файлы | ⚠️ Не рекомендуется | Высокий риск конфликтов записи, аналогичный описанному в разделе 02 |
💡 Резюме одной фразой: метод
spawn_agents_on_csvпредназначен для циклического выполнения одинаковых операций над большими списками независимых объектов. При наличии зависимостей шагов или малом объеме файлов используйте обычных агентов.
08 Итоги
Мы разобрали интеграцию субагентов в Codex, правила разделения задач и настройки безопасности фоновых потоков.
Повторим ключевые выводы:
| Вопрос | Ответ | Ключевой нюанс |
|---|---|---|
| Что такое субагенты | Набор изолированных потоков со своими моделями и правами | Работают параллельно, возвращая только сводные отчеты |
| Какие проблемы решают | Засорение и деградацию общего контекста сессии | Выносят служебные логи за рамки основного диалога |
| Ограничения | Мелкие задачи, зависимости шагов и запись | Избыточное деление замедляет работу и увеличивает расходы |
| Как вызывать | Только явной текстовой командой | Codex не разделяет задачи сам. Укажите логику слияния в промпте |
| Встроенные / Свои | Три предустановленных агента; свои файлы TOML | Обязательные поля: name, description, developer_instructions |
| Выбор моделей | Ключи model и model_reasoning_effort | Легкие быстрые модели для поиска, тяжелые глубокие — для аудита |
Теперь вы умеете: определять границы применимости субагентов, задействовать предустановленных агентов, создавать собственные файлы конфигурации в ~/.codex/agents/ или каталоге проекта с гибкой настройкой моделей и песочницы. Вы понимаете, что Codex запускает параллельные процессы только по вашему явному указанию, возвращая в основной чат лишь готовые отчеты. Навык эффективного распределения задач помогает экономить время и токены.
В следующей статье — [22 · Умения агента (Agent Skills)]. Мы выстроили развитую систему окружения Codex: правила в AGENTS.md, команды быстрого вызова, внешние серверы MCP и субагенты. Однако вы наверняка заметили, что описание роли в developer_instructions субагента получается объемным. В следующей главе мы научимся упаковывать правила поведения в повторно используемые модули умений (Agent Skills) для быстрого вызова при необходимости.