Codex и Agents SDK: как собрать рабочий маршрут из ролей, handoff и кода

Иногда задача слишком сложная для одного запроса в Codex. Не потому, что Codex не справится с кодом, а потому, что вокруг кода есть роли, входы, проверки и решения: кто формулирует задание, кто превращает его в техническую работу, кто продолжает уже начатую сессию, кто смотрит результат и где остается ответственность человека.

В таких случаях полезно думать не о «большом промпте», а о рабочем маршруте. Один агент может собрать краткое задание. Другой агент может вызвать Codex только на ограниченную часть работы. Третий шаг может проверить артефакт и trace. Человек принимает решение, можно ли применять результат. Именно такой мост между оркестрацией и работой с кодом описывает документация OpenAI про использование Codex вместе с Agents SDK.

Почему одного большого промпта недостаточно

Большой промпт удобен, когда задача разовая: прочитать файл, исправить ошибку, подготовить PR, написать скрипт, проверить гипотезу. Но бизнес-процесс редко состоит из одного действия. В нем есть повторяемый вход, несколько участников, правила остановки, разные уровни доступа и итоговый артефакт, который должен быть понятен не только разработчику.

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

Agents SDK помогает разложить такую работу на роли и handoff. Codex в этой схеме не становится главным начальником процесса. Он становится инструментом для той части, где нужно работать с кодом, файлами и локальным контекстом.

Что документация говорит о Codex и Agents SDK

Официальная документация OpenAI описывает способ запустить Codex как MCP-сервер и подключить его из другого MCP-клиента, например из агента, построенного на OpenAI Agents SDK. Команда запуска сервера выглядит просто: codex mcp-server.

После запуска MCP-клиент может запросить список инструментов и увидеть два основных инструмента. codex начинает новую сессию Codex по начальному prompt. codex-reply продолжает уже созданную сессию по threadId и новому prompt.

У инструмента codex есть обязательный prompt, а также настройки, которые важны для рабочей рамки: approval policy, base instructions, config overrides, рабочая папка cwd, включение plan tool, model, profile и sandbox. Это не декоративные параметры. Через них команда задает, насколько свободно Codex может действовать и где именно он работает.

У codex-reply обязательны prompt и threadId. Документация отдельно показывает, что threadId приходит в structuredContent.threadId в ответе tool call. Это важная деталь: если процесс должен продолжать задачу, он не должен каждый раз начинать Codex с нуля. Он должен сохранить идентификатор сессии и понимать, когда продолжение уместно.

Главная мысль документации не в том, что можно устроить эффектную многоагентную демонстрацию. Практическая мысль в другом: Codex CLI можно превратить в инструмент внутри детерминированного, просматриваемого workflow, где есть роли, handoff, ограничения и trace.

Когда нужен такой рабочий маршрут

Связка Agents SDK и Codex MCP нужна не для каждой задачи. Если человеку нужно быстро попросить Codex починить тест, проще открыть Codex напрямую. Если нужно разово получить объяснение по файлу, тоже не обязательно строить оркестрацию.

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

Плохой кандидат: «пусть агенты сами решают, что делать с проектом». Это не workflow, а передача ответственности в туман. Хороший кандидат звучит иначе: «у нас есть вход, есть роли, есть ограниченная работа Codex, есть результат и есть проверка».

Что дать Codex перед проектированием связки

Перед тем как просить Codex собрать такую схему, нужно дать не только техническое желание, но и рамку процесса.

Во-первых, нужен вход: откуда приходит задача и как выглядит нормальная заявка. Это может быть форма, issue, сообщение в Slack, строка в таблице или документ. Важно не название канала, а структура: что известно заранее, что нужно уточнить, какие поля нельзя считать надежными.

Во-вторых, нужны роли. Например: intake agent готовит краткое задание, planner agent превращает его в план, coder agent вызывает Codex MCP, reviewer agent проверяет результат. Названия не так важны, как границы: кто принимает вход, кто вызывает Codex, кто не имеет права менять файлы, кто только проверяет.

В-третьих, нужен контур Codex. Надо указать рабочую папку, sandbox, approval policy, профиль, допустимые команды, ожидаемый артефакт и правило продолжения сессии через threadId. Если этого не сделать, Codex может формально выполнить задачу, но процесс будет трудно повторить и проверить.

В-четвертых, нужно описать приемку. Где появляется результат: файл, diff, отчет, ссылка, structured output, комментарий? Кто его смотрит? Что считается достаточным? Что происходит, если Codex сообщает, что не может безопасно продолжить?

Как разделить роли, handoff и вызов Codex

Самая простая схема состоит из трех частей.

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

Вторая часть — вызов Codex. Здесь агент вызывает MCP-инструмент codex с ограниченным prompt. В prompt не нужно помещать весь бизнес-контекст. Туда идет только то, что нужно для работы с кодом: папка, цель, ограничения, ожидаемый артефакт, проверка, запрет на лишние изменения. Параметры sandbox и approval policy должны соответствовать риску задачи.

Третья часть — продолжение и проверка. Если Codex начал сессию и вернул threadId, workflow может продолжить ее через codex-reply. Но продолжение должно быть осознанным: не каждый следующий шаг обязан идти в ту же сессию. Если меняется цель, контекст или уровень доступа, лучше начать новую задачу.

Такой handoff полезен именно потому, что он делает границы видимыми. Агент-координатор отвечает за качество задания. Codex отвечает за работу с кодом внутри ограничений. Ревью отвечает за приемку. Человек отвечает за решение, можно ли применять результат.

Как должен выглядеть результат

Хороший результат такой связки — не просто «агент что-то сделал». Нужен пакет, который можно проверить.

Минимальный пакет включает карту ролей, описание входа, prompt для Codex MCP, параметры вызова, ожидаемый артефакт, правило сохранения threadId, список проверок и список человеческих решений. Для технической команды туда можно добавить пример кода. Для руководителя достаточно схемы: кто что делает, где Codex включается, где останавливается автоматизация.

Пример артефакта:

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

Как проверить маршрут без программирования

Непрограммисту не нужно читать весь код Agents SDK. Достаточно проверить маршрут по вопросам.

Первый вопрос: кто формулирует задачу для Codex? Если ответ «любой предыдущий агент как получится», маршрут сырой. Должен быть явный слой brief.

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

Третий вопрос: где результат? Если результат виден только в логах, его трудно принять. Он должен быть файлом, отчетом, diff, structured output или другим артефактом, который можно открыть.

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

Пятый вопрос: кто принимает решение? Если решение спрятано внутри автоматизации, это риск. Если решение явно остается за человеком или за заранее утвержденной политикой, процесс становится управляемым.

Где остается человеческое решение

Agents SDK может организовать роли. Codex может выполнить работу с кодом. MCP может связать эти части. Но человеческое решение остается в нескольких местах.

Человек решает, какой процесс вообще стоит автоматизировать. Не каждая повторяемая задача должна становиться агентной цепочкой. Иногда дешевле и безопаснее оставить одну ручную проверку.

Человек решает, какой доступ дать Codex. Sandbox и approval policy — это не техническая мелочь, а управленческое решение о риске.

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

Человек решает, какой trace считается достаточным. Если workflow нельзя объяснить после выполнения, он не готов к серьезному использованию.

Связка Codex и Agents SDK сильна не тем, что обещает полностью автономную разработку. Она сильна тем, что позволяет встроить Codex в понятный маршрут: роль подготовила задачу, Codex выполнил ограниченную работу, trace сохранился, человек увидел артефакт и принял решение.

Шаблон запроса

Можно дать Codex такой запрос:

Помоги спроектировать workflow, где OpenAI Agents SDK оркестрирует роли, а Codex вызывается как MCP-инструмент только для работы с кодом.

Процесс:
[какая повторяемая задача автоматизируется]

Вход:
[откуда приходит задача: issue, форма, Slack, документ, таблица]

Роли:
- intake agent: что проверяет и уточняет;
- planner agent: как превращает вход в brief;
- coder agent: когда вызывает Codex MCP;
- reviewer agent: как проверяет результат.

Codex MCP boundary:
- команда сервера: codex mcp-server;
- рабочая папка cwd;
- sandbox;
- approval policy;
- профиль или config overrides;
- что входит в prompt;
- какой артефакт должен появиться.

Continuation:
- когда сохраняем threadId;
- когда используем codex-reply;
- когда начинаем новую сессию.

Review:
- где лежит результат;
- какие проверки обязательны;
- кто принимает решение;
- что делать, если Codex блокируется или просит расширить доступ.

Результат:
1. дай карту ролей;
2. опиши handoff между ролями;
3. предложи prompt для вызова Codex MCP;
4. перечисли риски доступа;
5. назови человеческие решения перед запуском.

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