- OpenAI Codex ahora admite un flujo de trabajo con subagentes, que permite distribuir en paralelo tareas complejas entre varios agentes especializados y unificar los resultados en una sola respuesta
- Los subagentes solo se crean cuando el usuario lo solicita explícitamente, y como cada agente usa su propio modelo y herramientas, el consumo de tokens aumenta frente al uso de un solo agente
- Es posible definir agentes personalizados con archivos TOML para configurar de forma independiente por agente el modelo, el modo sandbox, los servidores MCP y más
- También incluye la función experimental spawn_agents_on_csv, que crea en lote agentes worker tomando cada fila de un archivo CSV como una unidad de trabajo
- La documentación oficial también muestra directamente patrones de combinación de agentes personalizados para escenarios reales como revisión de código y depuración de frontend
Resumen y disponibilidad de subagentes
- Codex admite flujos de trabajo con subagentes que lanza (spawn) en paralelo y luego recopila en una sola respuesta
- Resulta especialmente útil para tareas complejas con alto paralelismo, como explorar un codebase o planificar implementaciones de funciones de varios pasos
- En los flujos de trabajo con subagentes también se pueden definir agentes personalizados con distintas configuraciones de modelo e instrucciones según la tarea
- En la versión actual de Codex, el flujo de trabajo con subagentes está activado por defecto
- La actividad de los subagentes ya puede verse en la app de Codex y el CLI, y la visibilidad en la extensión para IDE llegará pronto
- Los subagentes solo se crean cuando el usuario lo pide explícitamente, y como cada subagente ejecuta su propio trabajo con modelo y herramientas, consumen más tokens que una ejecución con un solo agente
Flujo de trabajo general
- Codex se encarga de la orquestación entre agentes: crear nuevos subagentes, enrutar instrucciones posteriores, esperar resultados y cerrar los hilos de los agentes
- Cuando varios agentes están ejecutándose, Codex espera a que estén listos todos los resultados antes de devolver una respuesta consolidada
- Ejemplo de prompt: pedir que para el PR actual se cree un agente para cada aspecto: problemas de seguridad, calidad de código, bugs, race conditions, inestabilidad en pruebas y mantenibilidad, y luego resumir el resultado completo
Gestión de subagentes
- En el CLI, el comando
/agent permite cambiar entre hilos de agentes activos e inspeccionar hilos en curso
- También se le puede pedir directamente a Codex que controle, detenga o cierre hilos completados de subagentes en ejecución
Control de aprobaciones y sandbox
- Los subagentes heredan la política sandbox actual del usuario
- En sesiones interactivas del CLI, las solicitudes de aprobación de hilos de agentes inactivos pueden mostrarse incluso mientras se usa el hilo principal, y la superposición de aprobación muestra una etiqueta del hilo de origen
- Presiona
o para abrir ese hilo y poder aprobar, rechazar o responder
- En flujos no interactivos no se pueden mostrar nuevas aprobaciones, por lo que las tareas que requieran aprobación fallan y el error se propaga al flujo de trabajo superior
- Al crear agentes hijos, se vuelven a aplicar los overrides de runtime activos del turno del agente padre, incluidos cambios con
/approvals o configuraciones interactivas como --yolo
- Incluso si el archivo del agente personalizado seleccionado define otros valores por defecto, prevalecen los ajustes del padre
- También es posible sobrescribir por separado la configuración sandbox para cada agente personalizado individual (por ejemplo, poner un agente específico en modo solo lectura)
Agentes personalizados
- Codex incluye 3 agentes integrados por defecto
default: agente fallback de propósito generalworker: agente orientado a ejecución enfocado en implementar y corregirexplorer: agente orientado a lectura para explorar el codebase
- Para definir agentes personalizados, se agregan archivos TOML independientes en
~/.codex/agents/ (uso personal) o .codex/agents/ (alcance del proyecto)
- Cada archivo define un agente personalizado, y Codex lo carga como una capa de configuración para la sesión de creación
- Campos obligatorios que deben incluir todos los archivos de agentes personalizados:
name, description, developer_instructions
- Campos opcionales como
nickname_candidates, model, model_reasoning_effort, sandbox_mode, mcp_servers, skills.config y otros se heredan de la sesión padre si se omiten
Configuración global
- La configuración global de subagentes se define en la sección
[agents] del archivo de configuración
agents.max_threads: límite máximo de hilos de agentes abiertos en simultáneo (valor predeterminado: 6)agents.max_depth: profundidad de anidamiento de los agentes creados (valor predeterminado: 1, permite solo agentes hijos directos y evita anidamientos más profundos)agents.job_max_runtime_seconds: timeout predeterminado por worker para trabajos spawn_agents_on_csv (si no se configura, el valor por llamada es 1800 segundos)- Si un agente personalizado tiene el mismo nombre que un agente integrado como
explorer, el agente personalizado tiene prioridad
Esquema de archivos de agentes personalizados
name (string, obligatorio): nombre del agente que Codex usa al crearlo o referenciarlodescription (string, obligatorio): guía orientada a humanos sobre cuándo debe usarse este agentedeveloper_instructions (string, obligatorio): instrucciones centrales que definen el comportamiento del agentenickname_candidates (string[], opcional): conjunto de apodos visibles para el agente generado- También pueden incluirse otras claves compatibles de
config.toml: model, model_reasoning_effort, sandbox_mode, mcp_servers, skills.config, etc.
- Codex identifica a los agentes por el campo
name; aunque la convención más simple es hacer coincidir el nombre del archivo con el del agente, el campo name es la fuente de verdad
Apodos visibles
nickname_candidates sirve para mostrar en la UI etiquetas distinguibles cuando se ejecutan varias instancias del mismo agente personalizado- Los apodos son solo para visualización; Codex sigue identificando y creando al agente con
name
- Los candidatos a apodo deben ser una lista no vacía de nombres únicos, y pueden usar caracteres ASCII, números, espacios, guiones y guiones bajos
- Ejemplo: si al agente
reviewer se le asignan los apodos ["Atlas", "Delta", "Echo"], en la app y el CLI se mostrará el apodo, pero el tipo base del agente seguirá siendo reviewer
Ejemplo 1: patrón de revisión de PR
- Un patrón que divide la revisión en tres agentes personalizados especializados
pr_explorer: agente de solo lectura que mapea el codebase y reúne evidencia (modelo: gpt-5.3-codex-spark, reasoning effort: medium)reviewer: revisor de PR que busca problemas de corrección, seguridad y riesgo en pruebas (modelo: gpt-5.4, reasoning effort: high)docs_researcher: especialista en documentación que verifica documentación de frameworks o APIs mediante un servidor MCP dedicado (modelo: gpt-5.3-codex-spark, solo lectura)
- Configuración del proyecto:
max_threads = 6, max_depth = 1
- Instrucciones de
pr_explorer: mantenerse en modo exploración, rastrear rutas reales de ejecución, citar archivos y símbolos, y evitar sugerir cambios salvo que el agente padre lo pida
- Instrucciones de
reviewer: revisar desde la perspectiva del responsable, priorizar corrección, seguridad, regresiones de comportamiento y cobertura de pruebas faltante, e incluir pasos de reproducción cuando sea posible; evitar comentarios solo de estilo salvo que oculten un bug real
- Instrucciones de
docs_researcher: usar el servidor MCP de docs para verificar APIs, opciones y comportamiento por versión, y responder de forma concisa con enlaces o referencias exactas; no modificar código
- Prompt de ejemplo: "Revisa esta rama comparándola con main. Que
pr_explorer mapee las rutas de código afectadas, reviewer encuentre riesgos reales y docs_researcher valide las APIs del framework de las que depende el parche"
Procesamiento por lotes con CSV: spawn_agents_on_csv (experimental)
- Es una función experimental y puede cambiar en el futuro
- Cuando hay muchas tareas similares, crea en lote subagentes worker usando una fila del CSV como una unidad de trabajo
- Codex lee el CSV, crea un agente worker por fila, espera a que termine todo el lote y luego exporta los resultados a un CSV
- Casos de uso adecuados:
- Revisar un archivo, paquete o servicio por fila
- Inspeccionar una lista de incidentes, PR o objetivos de migración
- Generar resúmenes estructurados para muchas entradas similares
- Parámetros de entrada de la herramienta:
csv_path (CSV de origen), instruction (plantilla de prompt para workers, usando placeholders {column_name}), id_column (ID estable del elemento), output_schema (forma JSON fija), output_csv_path, max_concurrency, max_runtime_seconds
- Cada worker debe llamar a
report_agent_job_result exactamente una vez; si termina sin reportar resultados, esa fila se marca como error
- Al ejecutarse con
codex exec, durante el lote se muestra en stderr una actualización de progreso en una sola línea
- El CSV exportado incluye los datos originales de cada fila y metadatos como
job_id, item_id, status, last_error, result_json, entre otros
- Configuraciones de runtime relacionadas:
agents.max_threads (límite de concurrencia), agents.job_max_runtime_seconds (timeout por worker; max_runtime_seconds por llamada tiene prioridad), sqlite_home (ruta de persistencia de estado SQLite usada para trabajos de agentes y resultados exportados)
Ejemplo 2: patrón de depuración integral de frontend
- Un patrón útil para bugs de integración que cruzan regresiones de UI, flujos inestables en el navegador y tanto el código de la aplicación como el producto en ejecución
- Combinación de tres agentes personalizados:
code_mapper: agente explorador de solo lectura que encuentra rutas de código relevantes de frontend y backend (modelo: gpt-5.3-codex-spark, reasoning effort: medium)browser_debugger: depurador de UI que reproduce el problema y captura evidencia usando herramientas del navegador (modelo: gpt-5.4, reasoning effort: high, sandbox: workspace-write)
- Usa herramientas del navegador para capturas de pantalla, salida de consola y evidencia de red, pero no debe editar el código de la aplicación
- Conecta el servidor MCP de Chrome DevTools (
http://localhost:3000/mcp, startup_timeout_sec: 20)
ui_fixer: agente orientado a implementación que hace correcciones pequeñas y puntuales una vez identificado el problema (modelo: gpt-5.3-codex-spark, reasoning effort: medium)
- Debe hacer el cambio defendible más pequeño posible, no tocar archivos no relacionados y validar solo el comportamiento que cambió
- Prompt de ejemplo: "Investiga por qué el modal de configuración falla al guardar. Que
browser_debugger lo reproduzca, code_mapper rastree la ruta de código correspondiente y ui_fixer implemente la corrección mínima una vez identificado el modo de falla"
4 comentarios
Como el agente solo usa el modelo GPT-5.1-Codex-Mini,
en las Custom instructions de Codex App
si agregas el siguiente prompt, el agente funciona con GPT-5.3-Codex-Spark.
"- when it spawns agents, use models "GPT-5.3-Codex-Spark" or higher."
O también es bastante entretenido poder especificar el modelo al crear un agente,
y me gusta que en Codex App lo muestre con estructura de subcarpetas.
Lo aproveché cuando hicieron una promo súper agresiva en KakaoTalk y lo he estado usando muchísimo jajaja
Qué pena, ¿ya no van a hacer otro evento? T_T
¡Codex, por favor apúrense y hagan también un control remoto!