Субагенты: разделить работу и контекст

Чем дольше сессия, тем больше в контексте мусора: выводы команд, просмотренные файлы, стек-трейсы. Документация Codex называет это засорением контекста: важные решения тонут в промежуточном шуме, и агент работает хуже. Субагенты (subagents) переносят шумную работу в отдельные потоки, а основному агенту возвращают только выводы. Заодно независимые части задачи выполняются параллельно.

Как это работает

Основной агент запускает субагентов, каждый работает в своём потоке (agent thread) со своим контекстом, а основной собирает их результаты в один ответ. В текущих версиях Codex субагенты включены по умолчанию в десктопном приложении, CLI и IDE-расширении.

Запускаются они в двух случаях:

• вы прямо просите: «запусти двух агентов», «раздели это между агентами», «по агенту на каждый пункт»;
• так велит AGENTS.md или навык — например, навык ревью может требовать отдельного агента на безопасность.

Хорошая просьба объясняет три вещи: как поделить работу, ждать ли всех агентов и что вернуть.

Проверь ветку относительно main параллельными субагентами: один ищет проблемы
безопасности, второй — пробелы в тестах, третий — проблемы сопровождаемости.
Дождись всех троих и сведи находки по категориям со ссылками на файлы.

В CLI команда /subagents переключает между потоками агентов, пока они работают. Запросы на одобрение могут прийти из неактивного потока — в окне одобрения видно, из какого; клавиша o открывает этот поток, чтобы посмотреть контекст перед решением.

Что отдавать субагентам

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

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

Встроенные и свои агенты

В Codex есть три встроенных агента:

• default — универсальный;
• worker — для реализации и исправлений;
• explorer — для исследования кода с упором на чтение.

Свои агенты описываются отдельными TOML-файлами: личные — в ~/.codex/agents/, проектные — в .codex/agents/. Один файл — один агент. Обязательные поля:

• name — имя, по которому Codex запускает агента и на него ссылается;
• description — когда этого агента использовать;
• developer_instructions — его основные инструкции.

Дополнительно можно задать model, model_reasoning_effort, model_reasoning_summary, model_verbosity и отключить отдельные возможности. Если имя совпадает со встроенным, например explorer, ваш агент заменит встроенного.

Пример: ревью MR втроём

Набор для ревью merge request в веб-проекте. Модели указаны по состоянию на октябрь 2026 года — принцип важнее имён: быстрая модель для узких и массовых задач, сильная — для неоднозначных.

name = "code_mapper"
description = "Исследует код только на чтение: находит затронутые изменением пути выполнения до того, как кто-то начнёт править."
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
Только исследование, файлы не редактируй.
Проследи реальный путь выполнения: маршрут, контроллер или компонент OctoberCMS,
модель, миграции. Называй файлы и символы.
Не предлагай исправлений, если об этом не попросили.
"""

name = "reviewer"
description = "Ревьюер MR: корректность, безопасность, регрессии и недостающие тесты."
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
developer_instructions = """
Ревьюй как владелец кода. Файлы не редактируй.
Приоритет: корректность, безопасность (валидация ввода, SQL, права доступа),
регрессии поведения, отсутствующие тесты.
Начинай с конкретных находок со ссылками на строки. Замечания только о стиле —
лишь если за ними скрывается баг.
"""

name = "e2e_checker"
description = "Проверяет изменённые страницы на локальном стенде через браузер и сообщает, что реально видно."
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
Открой изменённые страницы на локальном стенде через Playwright MCP.
Опиши фактическое поведение: что отрисовалось, ошибки в консоли, упавшие запросы.
Код приложения не редактируй, на внешние сайты не ходи.
"""

[features]
apps = false

Запрос, который их использует:

Проверь ветку относительно main. Пусть code_mapper найдёт затронутые пути,
reviewer найдёт реальные риски, а e2e_checker пройдёт изменённые страницы
на http://localhost:8001. Сведи результат в один список по важности.

Права наследуются, а не настраиваются

Это главное, что нужно понять про субагентов. Субагент получает текущие песочницу и политику одобрений родительского хода, включая изменения через /permissions или --yolo. Файл агента их не переопределяет: ключи sandbox_mode, approval_policy, model_provider и mcp_servers в нём просто не действуют.

Следствия:

• «Не редактируй файлы» в инструкциях — просьба, а не песочница. Если нужен агент, который физически не может писать, запускайте родительскую сессию в режиме только для чтения. Как настроить права — в уроке про песочницу.
• MCP-серверы — от родителя. Агенту e2e_checker нужен Playwright MCP — значит, он должен быть подключён в основном config.toml. В файле агента его не объявить.
• Отключить возможности можно. Ключи features.shell_tool, features.apps, features.plugins, features.memories и features.request_permissions_tool со значением false убирают соответствующие инструменты. Навыки наследуются от родителя; лишние выключаются через [[skills.config]] в файле агента.

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

Модель и глобальные настройки

Если модель и уровень рассуждений не заданы, субагент берёт их у родителя. Порядок такой: явное значение в просьбе о запуске, затем значения по умолчанию из [agents], затем настройки родителя. Значения из файла агента применяются поверх.

[agents]
max_concurrent_threads_per_session = 4
default_subagent_model = "gpt-6-luna"
default_subagent_reasoning_effort = "high"

max_concurrent_threads_per_session ограничивает число одновременно открытых потоков субагентов, не считая основного; старое имя ключа — max_threads. Если не задано, Codex выбирает значение сам. Выключить субагентов совсем — enabled = false в той же таблице.

Для наблюдения за субагентами есть хуки SubagentStart и SubagentStop — например, чтобы подмешать субагенту правила тестов проекта при старте. Подробнее — в уроке про хуки.