Субагенты Codex — это вложенные агенты, которые оркестратор запускает параллельно, каждый со своим изолированным контекстом, задачей и инструментами. Если коротко: один агент-начальник раздаёт задания нескольким агентам-исполнителям, получает ответы и собирает результат.

3–5×дороже субагент vs tool use на простых задачах
5 шаговдо рабочей production-схемы с субагентами

Схема оркестратора с тремя параллельными субагентами Codex

Что такое субагент и чем он отличается от инструмента

Путаница здесь частая, поэтому сразу по делу.

Инструмент (tool use) — это функция, которую агент вызывает синхронно. Агент остановился, вызвал функцию, получил результат, пошёл дальше. Один контекст, одна нить выполнения.

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

Параллельная сессия — то же, что субагент, но в контексте Claude Code: несколько окон/сессий работают одновременно над разными частями задачи. По данным документации Claude Code, параллельные сессии поддерживаются нативно.

Что Когда брать Стоимость
Tool use Простой вызов, один шаг, предсказуемый вывод Дешево: только токены запроса и ответа
Субагент Многоходовая логика, нужна изоляция контекста Дороже: оркестратор + полный контекст субагента
Параллельные сессии Независимые большие задачи, можно разделить по репозиториям Дорого: каждая сессия — отдельный контекст с нуля

Я, Арина Михална, первое время путала субагентов с инструментами и гоняла целые агентные сессии там, где хватило бы простого fetch. Это как нанять отдельного подрядчика, чтобы он сходил за кофе.

Три архитектурных паттерна субагентов Codex

Разберём три паттерна, которых хватает для большинства задач.

Паттерн 1: Параллельные задачи, делегация и сбор результатов

Оркестратор создаёт N субагентов одновременно, каждый выполняет свой кусок независимо. Схема для задач, которые распараллеливаются без зависимостей между шагами.

Пример задачи: собрать данные из трёх API одновременно — погода, курсы валют, новости. Три субагента запускаются параллельно, возвращают результаты, оркестратор собирает их в один отчёт.

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

Опасность: если один субагент упал — оркестратор должен это отловить и продолжить с оставшимися. Без обработки ошибок всё ломается.

Паттерн 2: Каскадная делегация (cascading delegation)

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

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

Когда брать: задача многоуровневая, объём работы неизвестен заранее. Архитектура гибкая, но сложнее в отладке.

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

Паттерн 3: Конвейер с состоянием (stateful pipeline)

Субагенты передают результат по цепочке, каждый обогащает его. Первый субагент вытаскивает данные, второй нормализует, третий анализирует, четвёртый форматирует в отчёт.

Пример задачи: обработка резюме — парсинг PDF, извлечение структурированных данных, проверка компетенций по требованиям вакансии, генерация саммари.

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

Опасность: если один субагент в середине цепочки сломался — вся цепочка останавливается. Нужен механизм retry и fallback.

Три архитектурных паттерна субагентов Codex: параллельные задачи, каскад и конвейер

Архитектура — это ещё не production, дальше её надо запустить, залогировать и откатить при ошибке.

На курсе разбираем все три паттерна на живых задачах и сразу ставим мониторинг

забрать курс от 1490 ₽

Как создать субагента в Codex: системный промпт и изоляция контекста

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

Шаблон промпта оркестратора для спауна субагента:

Ты оркестратор. Если задача требует сбора данных из
нескольких источников параллельно,
создай субагента для каждого источника со следующими
параметрами:

Субагент "data_fetcher_1":
- Задача: получить данные из {{API_URL}}, вернуть в JSON
- Инструменты: http_request
- Таймаут: 30 сек
- Retry: 2 попытки

Собери результаты всех субагентов и объедини в единый отчёт.

Оркестратор видит этот промпт, понимает паттерн и спаунит субагентов. Каждый субагент работает независимо, возвращает результат.

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

Production-схема: логирование, трассировка, откат

Субагенты в production без мониторинга — это хаос. Ты не знаешь, кто упал, на каком шаге и почему. Вот что ставить обязательно.

Логирование идентификатора каждого субагента

Каждый субагент получает уникальный идентификатор при запуске. Логируй его в начале и в конце работы субагента. Это единственный способ понять, какой субагент сломался.

# Псевдокод логирования субагентов
import logging

def spawn_subagent(task, agent_id):
    logging.info(f"Запуск субагента {agent_id}, задача:
{task}")
    try:
        result = codex_api.run_subagent(task, agent_id)
        logging.info(f"Субагент {agent_id} завершён,
результат: {result}")
        return result
    except Exception as e:
        logging.error(f"Субагент {agent_id} упал: {e}")
        return None

Без логов ты не увидишь, что третий из пяти субагентов завис, а остальные работают.

Трейс входа и выхода: что передали, что вернули

Сохраняй полный трейс: входные данные субагента, его ответ, время выполнения. Это нужно для debugging и для подсчёта токенов.

trace = {
    "agent_id": agent_id,
    "input": task_data,
    "output": result,
    "duration_ms": end_time - start_time,
    "tokens_used": token_count
}
logging.info(f"Трейс субагента: {trace}")

Claude Code поддерживает параллельные сессии — их состояние можно отслеживать отдельно. Логи каждой сессии идут в свой файл или с тегом идентификатора.

Таймаут и retry: субагент не должен висеть вечно

Ставь таймаут на каждого субагента. Если он не вернул результат за N секунд — убиваешь его и пробуешь retry. Без таймаута один зависший субагент блокирует всю задачу.

timeout = 30  # секунд
retry_count = 2

for attempt in range(retry_count):
    try:
        result = run_with_timeout(spawn_subagent, timeout,
task, agent_id)
        break
    except TimeoutError:
        logging.warning(f"Субагент {agent_id} таймаут на
попытке {attempt + 1}")
        if attempt == retry_count - 1:
            logging.error(f"Субагент {agent_id} не выполнен
после {retry_count} попыток")
            result = None

Два retry хватает для большинства случаев. Больше — субагент делает что-то не то, надо смотреть задачу.

Graceful degradation: если субагент упал, оркестратор продолжает

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

results = []
for task in tasks:
    result = spawn_subagent(task, generate_agent_id())
    if result:
        results.append(result)
    else:
        logging.warning(f"Задача {task} не выполнена,
продолжаем с оставшимися")

Это называется graceful degradation — система деградирует, но не ломается полностью.

Схема мониторинга субагентов: идентификатор, трейс, таймаут, retry, graceful degradation

Anti-patterns: три ошибки, из-за которых субагенты ломаются

Anti-pattern 1: Субагент вместо инструмента на простой задаче

Я, Арина Михална, первые недели работы с субагентами гоняла их там, где хватило бы простого tool use. Запрос к API — субагент. Парсинг JSON — субагент. Проверка формата — субагент.

Результат: токены улетали в 3-5 раз быстрее, а задача не стала проще. Субагент дороже инструмента, потому что у него свой контекст и своя логика принятия решений.

Правило: если задача решается одним вызовом функции без условных веток — это tool use, не субагент. Субагент — только когда нужна многоходовая логика.

Anti-pattern 2: Субагенты дублируют контекст родителя

Оркестратор передаёт каждому субагенту весь свой контекст — «на всякий случай, вдруг пригодится». Субагентов пять, контекст по 10 тыс. токенов у каждого — итого 50 тыс. токенов на пустом месте.

Правило: субагенту передавай ТОЛЬКО то, что ему нужно для задачи. Входные данные, формат ответа, граничные условия. Всё остальное — лишнее.

Anti-pattern 3: Нет обработки ошибок — один субагент ломает всех

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

Правило: каждый субагент оборачивается в try-except, его ошибка логируется, но не останавливает оркестратора. Graceful degradation — обязательная часть архитектуры.

ROI субагентов: когда дешевле, когда дороже

Субагент не всегда выгоднее инструмента. Вот таблица, когда что брать.

Тип задачи Tool use Субагент Почему
Один вызов API ✅ ❌ Tool use — 50-100 токенов, субагент — 500+ токенов
Парсинг JSON ✅ ❌ Логика простая, своего контекста не нужно
Многоходовая обработка данных ❌ ✅ Несколько итераций, условные ветки, нужна изоляция
Параллельный сбор из 5 источников ❌ ✅ Tool use последовательный, субагенты параллельные
Генерация 10 вариантов текста ❌ ✅ Каждый вариант — независимая логика

Практическое правило: если задача умещается в 2-3 шага без ветвления — tool use. Если больше 3 шагов или есть условия — субагент.

По нашим замерам, субагент дешевле инструмента, когда задача требует больше 500 токенов контекста и 4+ шагов логики. Ниже этого порога tool use выгоднее.

Примеры Codex субагентов на практике

Пример 1: Параллельный сбор данных из трёх API

Задача: собрать данные о погоде, курсах валют и новостях одновременно. Три субагента запускаются параллельно, возвращают результаты, оркестратор собирает их в один отчёт.

Ты оркестратор. Запусти три субагента параллельно:

Субагент "weather": получить погоду из {{weather_api}},
вернуть JSON
Субагент "currency": получить курсы валют из
{{currency_api}}, вернуть JSON
Субагент "news": получить топ-3 новости из {{news_api}},
вернуть JSON

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

Результат: три субагента работают одновременно, время выполнения = время самого медленного субагента, а не сумма всех трёх.

Пример 2: Каскадная документация модулей

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

Ты оркестратор. Проанализируй код API, выдели все эндпоинты.
Для каждого эндпоинта создай субагента "doc_writer" с
задачей:
- Описать назначение эндпоинта
- Перечислить параметры и их типы
- Привести пример запроса и ответа

Собери результаты всех субагентов в единый
Markdown-документ.

Каждый субагент документации работает независимо, с изолированным контекстом — не перегружая оркестратора.

Пример 3: Конвейер обработки резюме

Задача: обработать PDF-резюме — парсинг, извлечение структурированных данных, проверка компетенций, генерация саммари.

Ты оркестратор. Обработай резюме через цепочку субагентов:

Субагент 1 "pdf_parser": извлечь текст из PDF, вернуть plain
text
Субагент 2 "data_extractor": из текста извлечь ФИО, опыт
работы, навыки в JSON
Субагент 3 "skill_matcher": сравнить навыки с требованиями
вакансии {{job_requirements}}, вернуть совпадения
Субагент 4 "summary_generator": создать саммари кандидата на
основе данных субагента 3

Вернуть итоговый JSON с саммари и процентом совпадения.

Каждый субагент обогащает результат предыдущего, передавая его дальше по цепочке.

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

По материалам: официальная документация OpenAI Codex, документация Claude Code, TLDR AI от 7 сентября 2026.

Читайте также

На курсе проходим все три паттерна на практике и сразу ставим CI/CD для агентов. Разбираем, как довести архитектуру до production с логами, retry и мониторингом — курс от 1490 ₽