Custom agent в Codex - это отдельная роль со своей моделью, конфигурацией и, что особенно важно, более узким sandbox. Встроенные типы уже покрывают частые случаи: general-purpose по умолчанию, implementation-oriented worker для правок и read-heavy explorer для исследования. Свои агенты задаются отдельными TOML-файлами в ~/.codex/agents/ или проектном .codex/agents/. Смысл роли не в новом имени, а в том, чтобы закрепить за задачей устойчивый набор полномочий и поведения.

Полезно один раз увидеть определение агента целиком. Ниже - security-reviewer: имя, описание, модель, высокий effort, sandbox read-only и собственные developer_instructions. Читается он как явная роль: read-only ревьюер для auth, границ доверия, секретов и рисков зависимостей. Ключевое здесь - связка более глубокого рассуждения и суженного доступа: агенту, который только смотрит, не нужна запись, и профиль это фиксирует, а не оставляет на усмотрение сессии.

Настройки уровня агентов задают рамки для всей многоагентной работы. Полезно один раз увидеть и их. Ниже - секция [agents] с ограничением числа одновременных потоков на сессию и моделью и effort по умолчанию для субагентов. Это не про конкретную роль, а про общий бюджет параллельности: сколько агентов может работать разом и на какой модели по умолчанию. Ограничение потоков - это защита и от расхода, и от хаоса, а не косметическая настройка.

Главное правило про custom agents - не заводить роль ради другого имени. Отдельный агент оправдан, когда действительно нужны стабильный scope, другая модель или effort, суженный sandbox или собственные инструкции - то есть когда роль несёт содержательное отличие в полномочиях и поведении. Если единственное отличие - как агента зовут, это не роль, а лишняя сущность, которую придётся поддерживать. Роль создают под функцию, а не под название.

Суженный sandbox - это, пожалуй, самая ценная причина завести роль. Агент-ревьюер с read-only не может ничего сломать, даже если ошибётся или поддастся инъекции: у него физически нет записи. Это принцип наименьших полномочий, выраженный в конфигурации: каждая роль получает ровно тот доступ, что нужен её функции, и ни каплей больше. Read-only explorer, write-worker в своём каталоге, security-reviewer без сети - у каждого своя узкая граница.