Un subagente de Codex sirve para sacar del hilo principal una tarea acotada y devolver solo el resultado que permite decidir. No convierte automáticamente un encargo ambiguo en trabajo rápido. Si varias ramas dependen de la misma decisión o editan los mismos archivos, el paralelismo añade conflictos, consumo y coordinación.
En las versiones locales actuales de Codex, el workflow de subagentes está habilitado por defecto en la aplicación, la CLI y la extensión de IDE. Puedes pedir la delegación de forma directa; también puede activarse por instrucciones aplicables de AGENTS.md o de una skill. Cada subagente ejecuta su propio trabajo de modelo y herramientas, así que consume más tokens que una ejecución comparable con un solo agente. La documentación oficial de OpenAI sobre Subagents aconseja empezar con exploración, pruebas, triage y resúmenes, y ser más prudente con escrituras paralelas.
Separa resultados, no solo perfiles
Poner nombres como “especialista en seguridad” o “experto en rendimiento” no garantiza una división útil. Cada encargo debería tener entrada, límite, condición de finalización y formato de retorno propios.
Antes de delegar, comprueba lo siguiente:
- Independencia: ¿puede terminar sin esperar una decisión pendiente de otro agent?
- Superficie de escritura: ¿trabajará en modo lectura o tendrá archivos que nadie más modifica?
- Salida: ¿puede devolver hallazgos, referencias, comandos e incertidumbres en vez de un transcript completo?
- Responsabilidad: ¿sabe el hilo principal cómo resolver contradicciones y qué evidencia necesita para seguir?
Una investigación de regresión puede dividirse entre quien reproduce el fallo, quien traza la ruta de ejecución y quien verifica la API externa utilizada. La corrección, en cambio, suele funcionar mejor después: un solo worker recibe la causa ya delimitada, un grupo pequeño de archivos y una prueba observable.
El prompt también debe decir cuándo esperar
Un encargo operativo puede adoptar esta forma:
textRevisa esta rama frente a main con tres subagentes. - explorer: traza las rutas de ejecución afectadas, solo lectura; - reviewer: busca riesgos de corrección, seguridad y pruebas ausentes; - test_agent: ejecuta únicamente los targets relacionados y clasifica los fallos. Espera a que terminen los tres. No modifiques archivos. Devuelve un único informe con hechos confirmados, hipótesis, referencias a archivos, comandos ejecutados, áreas no revisadas y discrepancias entre agentes.
El valor de este prompt no está en el número tres. Define responsabilidades no equivalentes, una frontera de escritura, una condición de espera y un contrato de pruebas. Además, obliga al hilo principal a consolidar, no a pegar tres respuestas consecutivas.
Los permisos proceden del flujo principal
Los subagentes locales heredan el sandbox o permission mode actual. En la app y el IDE conviene seleccionar el modo bajo el composer antes de pedir la delegación. En una sesión CLI interactiva, una aprobación puede aparecer desde un agent thread que no estás viendo; el overlay identifica el origen y la tecla o abre ese hilo antes de aprobar o rechazar. Si una ejecución no interactiva no puede mostrar una aprobación nueva, la acción restringida falla y el error vuelve al padre.
Las opciones activas del turno principal también se reaplican al crear el hijo. Por eso, un valor por defecto dentro de un custom agent no sustituye la comprobación del permiso real con el que se inició el workflow.
Una política sencilla reduce sorpresas:
- exploradores, revisores y lectores de documentación trabajan en read-only;
- un writer se inicia cuando la causa y los archivos ya están definidos;
- dos writers activos no comparten ownership de archivos;
- envíos externos, credenciales, borrados e instalaciones conservan una aprobación específica;
- una petición de permiso inesperada se revisa desde su thread de origen.
App, CLI e IDE no muestran lo mismo
- En Codex App, abre un subagent thread desde la actividad del chat principal. También puedes pedir a Codex que redirija o detenga un agente en curso y que cierre threads terminados.
- En Codex CLI,
/agentpermite cambiar entre agent threads para inspeccionar trabajo y resultados. - En la extensión de IDE, cuando el panel de background agents está disponible, muestra estado, permite detener agentes y abrir un hilo concreto.
No esperes al resumen final si un agente sale de su ámbito, modifica archivos que no le pertenecen o descubre una dependencia que invalida la división. Corregir la dirección pronto evita que varias ramas sigan construyendo sobre una hipótesis falsa.
Crea un custom agent solo si la responsabilidad se repite
Codex incluye default, worker y explorer. Un custom agent tiene sentido cuando un trabajo recurrente necesita instrucciones, modelo, reasoning effort, sandbox o herramientas estables. Los agentes personales viven en ~/.codex/agents/ y los del proyecto en .codex/agents/. Cada TOML independiente exige name, description y developer_instructions.
tomlname = "contract_reader" description = "Agente de solo lectura para verificar contratos de API y su uso real." model = "gpt-5.6-terra" model_reasoning_effort = "high" sandbox_mode = "read-only" developer_instructions = """ Comprueba la fuente oficial y traza los call paths relevantes. Devuelve archivos, evidencia, incertidumbres y decisiones pendientes. No modifiques el repositorio. """
La guía oficial actual propone gpt-5.6 para agentes exigentes y ambiguos, gpt-5.6-terra para apoyo rápido y read-heavy, y gpt-5.6-luna para tareas estrechas y repetibles. Son recomendaciones actuales, no constantes: la disponibilidad depende de cuenta, autenticación y cliente.
Los controles globales están bajo [agents], incluidos la activación, el máximo de threads simultáneos y el modelo o reasoning effort por defecto. Para resolver precedencia entre configuración personal, de proyecto, profile y CLI, consulta la guía de config.toml de Codex en lugar de copiar una configuración completa.
Un informe consolidado todavía necesita verificación
El hilo principal debe eliminar duplicados, separar observaciones, inferencias y recomendaciones, y volver a abrir la evidencia importante. Si un agente dice que las pruebas pasan, confirma qué targets ejecutó. Si señala una vulnerabilidad, sigue una ruta alcanzable. Si no encontró referencias, revisa si la búsqueda cubrió el espacio adecuado.
El workflow sano mantiene requisitos, decisiones y responsabilidad final en el hilo principal. Los subagentes absorben trabajo intermedio con límites claros y devuelven evidencia comprimida. Pueden reducir tiempo transcurrido cuando las ramas son independientes, pero no sustituyen la validación de la respuesta combinada.
Si todavía estás decidiendo qué coding agent encaja con tu forma de trabajar, en vez de cómo delegar dentro de Codex, continúa con la comparación entre Claude Code y Codex.
