Subagentes (Subagents): delegando tareas en paralelo, pero solo si tú lo indicas
📚 Navegación de la serie: El artículo anterior 20 · Habilitar herramientas externas con MCP te enseñó cómo conectar herramientas externas a Codex para consultar documentación o enlazar servicios. En esta sección cambiaremos la estrategia: en lugar de añadir herramientas, aprenderás a delegar tareas en paralelo: subagentes (Subagents), un grupo de asistentes especializados con modelos, instrucciones y permisos independientes, que trabajan simultáneamente para recopilar sus conclusiones en un único informe.
Hoy hablaremos de una de las funciones más llamativas y que más a menudo se utiliza de forma incorrecta en Codex: los subagentes.
El concepto de "agentes en paralelo" suena sofisticado, como si estuvieras al mando de tu propio escuadrón. Al descubrir esta función por primera vez, intenté estructurar cada tarea delegando en cinco o seis agentes a la vez, pensando que era la forma "profesional" de trabajar.
Sin embargo, la realidad de los subagentes en Codex difiere de otros entornos; cuenta con una restricción contraintuitiva: el sistema nunca dividirá las tareas por su cuenta por defecto. La documentación oficial lo detalla con claridad: Codex creará subagentes únicamente cuando se lo solicites expresamente. Si no indicas "ejecuta varios agentes en paralelo", continuará operando de forma individual de inicio a fin. Esta regla define la manera y el momento de utilizarlos.
En este artículo no solo te enseñará cómo invocar subagentes, estructurar perfiles personalizados y asignar modelos diferentes, sino que te ayudaré a definir el límite: qué tareas conviene delegar en paralelo y cuáles solo añadirán complejidad y gastos innecesarios.
Al terminar este artículo, obtendrás:
- Qué son realmente los subagentes: delegar subtareas a agentes especializados en paralelo y consolidarlas frente a un único agente convencional.
- Los dos problemas de contexto que resuelve: la contaminación de contexto (context pollution) y la degradación de contexto (context rot), junto con el criterio para decidir cuándo no delegar.
- Los tres agentes predeterminados integrados en Codex (
default,workereexplorer), activos sin requerir configuración. - Cómo definir agentes personalizados guardando un archivo TOML bajo
~/.codex/agents/o.codex/agents/y los tres campos obligatorios que debe incluir. - Cómo asignar modelos y la intensidad de razonamiento a cada perfil, como modelos ligeros para exploración y avanzados para auditorías.
- Práctica paso a paso: definir un agente de exploración de solo lectura y verificar que recopila la información sin modificar los archivos.
01 Comprender primero: qué son los subagentes
Definamos el concepto de entrada: los subagentes son instancias especializadas que Codex genera temporalmente; operan en hilos independientes y devuelven una conclusión consolidada al agente principal, evitando volcar los datos intermedios de su investigación en tu pantalla.
Analogía: Dividir un caso complejo entre varios investigadores. Eres el inspector jefe (la conversación principal) y gestionas un caso complejo del tipo "auditar esta modificación de código a nivel de seguridad, rendimiento y pruebas". Estos tres enfoques son independientes y no conviene analizarlos uno a uno de forma secuencial. Así que asignas tres investigadores: uno centrado en vulnerabilidades de seguridad, otro en el rendimiento y un tercero en la cobertura de pruebas, operando en paralelo. Al terminar, en lugar de amontonar folios de documentación en tu mesa, te entregan un resumen específico: "seguridad detecta dos incidencias en X e Y". El resultado que obtienes es un informe unificado y clasificado.
Los investigadores disponen de recursos privados aislados del canal principal. La documentación oficial aclara los siguientes términos:
Subagent：Codex派生出来、用来处理某个具体任务的受托agent。 Subagent: agente secundario que Codex genera para ejecutar una subtarea específica.
Agent thread：某个agent的CLI线程，你能用
/agent进去查看、来回切换。 Agent thread: el hilo de ejecución CLI asociado a un agente, consultable y gestionable con/agent.
De este modo, cada subagente puede gestionar los siguientes parámetros de forma independiente:
| Dimensión | Canal principal (tu conversación) | Subagente (hilo secundario delegado) |
|---|---|---|
| Hilos y contexto | El chat principal que contiene directrices, decisiones e historial general | Un hilo independiente (agent thread) centrado en su subtarea, conservando allí sus registros |
| Modelos e intensidad | El modelo por defecto activo en el chat | Asignación personalizable; por ejemplo, modelos ligeros para exploración y avanzados para auditorías (ver sección 05) |
| Instrucciones (perfil) | Directrices de comportamiento por defecto de Codex | Definido mediante developer_instructions específicos (p. ej. "limítate a examinar el código, prohibido modificarlo") |
| Permisos de sandbox | La directiva activa en la sesión | Heredado de tu sesión por defecto, con opción de restringirse (p. ej. forzar read-only) |
La ventaja competitiva de los subagentes reside en eliminar los datos intermedios redundantes del chat principal. La documentación oficial destaca: permite al agente principal centrarse en las directrices, toma de decisiones y el informe final, delegando la recopilación de datos, pruebas o registros de consola a subagentes en paralelo, quienes devuelven únicamente resúmenes omitiendo los volcados de consola.
Esta característica define en qué escenarios conviene utilizarlos.
Este esquema ilustra el flujo: el agente principal divide la tarea general y distribuye subtareas en paralelo; cada subagente opera en su contexto independiente (evitando interferencias entre auditorías, pruebas o documentación) y devuelve únicamente un informe de síntesis al canal principal, conservando las trazas de consola en sus propios hilos.
💡 Resumen en una frase: Los subagentes son instancias secundarias con hilos independientes y asignación personalizable de modelos y permisos que operan en paralelo devolviendo solo resúmenes; su beneficio radica en limpiar la consola del chat principal.
02 Qué resuelven y el criterio para decidir cuándo no delegar
Entendido el concepto, analicemos su utilidad. La documentación oficial define dos problemas específicos que solucionan:
1. Contaminación de contexto (context pollution)
Analogía: Documentos de trabajo mezclados con folletos publicitarios. Tu chat principal debe conservar directrices esenciales: requerimientos, límites y decisiones. Si pides al modelo "ejecuta la suite de pruebas completa", la consola se llenará con cientos de líneas de registros redundantes. Los avisos importantes del tipo "estas pruebas han fallado" se pierden entre datos de depuración irrelevantes. Esto es la contaminación de contexto: el ruido oculta la señal útil.
Definición oficial:
Context pollution（上下文污染）：有用的信息被吵闹的中间输出埋没。 Context pollution (contaminación de contexto): la información útil queda sepultada por volcados de consola intermedios redundantes.
Caso real: al integrar una API de terceros, pedí a Codex realizar pruebas reiteradas que volcaban respuestas JSON extensas. Tras una decena de turnos, quise comprobar si "el campo A era obligatorio en las directrices iniciales"; tuve que revisar unas veinte páginas llenas de JSON para localizar la frase. Comprendí que las tareas que generan gran volumen de datos de depuración no deben ejecutarse en el canal principal.
2. Degradación de contexto (context rot)
Analogía: Una reunión interminable. Durante la primera hora, los asistentes debaten con rigor; tras tres horas de debate, la mesa se llena de detalles secundarios o desvíos temporales, y la calidad de las decisiones decae. Los modelos se comportan igual: a medida que el chat acumula datos secundarios y redundantes, su rendimiento empeora gradualmente al procesar información innecesaria.
Definición oficial:
Context rot（上下文腐烂）：随着对话被越来越多不那么相关的细节填满，表现逐渐变差。 Context rot (degradación de contexto): merma del rendimiento del modelo a medida que el historial se llena de detalles irrelevantes.
La solución es la misma: delegar subtareas complejas a subagentes en paralelo, devolviendo únicamente informes de síntesis. La documentación detalla un caso límite: ante un documento de millones de tokens, Codex puede dividirlo en bloques e invocar subagentes que extraigan las conclusiones clave de cada sección para presentárselas al canal principal de forma simplificada.
El criterio de decisión: cuándo no usar subagentes
Comprendidos los beneficios, evaluemos la regla de oro: ¿por qué es un error delegarlo todo?
Los subagentes consumen recursos. La documentación oficial detalla: cada subagente invoca modelos y consume herramientas de forma independiente, por lo que este flujo de trabajo requiere más tokens que una ejecución unitaria convencional. A mayor número de subagentes, mayor coste. Existe además el riesgo de colisión al modificar archivos simultáneamente en paralelo:
起步时，把并行 agent 用在偏读的任务上，比如探路、跑测试、分流、做摘要。偏写的并行工作流要更小心，因为多个 agent 同时改代码会撞车、还会增加协调成本。 Al comenzar, limita el uso de agentes en paralelo a tareas de lectura: exploración, suites de pruebas, clasificación o resúmenes. Los flujos de escritura en paralelo implican riesgos de colisión en el código y aumentan la complejidad de coordinación.
Sigue estos criterios para decidir:
| Tarea | ¿Conviene delegar en subagentes? | Motivo |
|---|---|---|
| Exploración, suites de pruebas, registros o resúmenes (lectura y gran volumen de datos) | ✅ Recomendado | Limpia la consola principal; es su propósito básico |
| Investigaciones independientes (analizar autenticación, bases de datos o API por separado) | ✅ Recomendado | Ejecución simultánea en paralelo para ahorrar tiempo |
| Ediciones menores que se resuelven con una sola instrucción | ❌ No recomendado | Invocar subagentes consume tokens innecesarios |
| Múltiples agentes modificando el mismo fichero | ⚠️ Evitar | Riesgo alto de colisión en el código y costes de coordinación |
| Procesos secuenciales donde B depende del resultado de A | ⚠️ Evitar | La ejecución en paralelo requiere independencia entre subtareas |
Caso real: en una ocasión quise delegar la simple tarea de "renombrar una función" a un subagente solo por usar la función. El resultado fue ineficiente: inicializar el agente, ejecutar el modelo y devolver el resultado tardó más que haber escrito "renombra esta función" en la sesión activa, consumiendo además tokens por duplicado. Mi regla desde entonces: evita delegar tareas sencillas que se resuelven directamente.
💡 Resumen en una frase: Los subagentes resuelven la contaminación y degradación de contexto aislando las tareas de lectura complejas; evita su uso para ediciones menores, tareas secuenciales o escritura simultánea para no incurrir en retardos o costes elevados.
Visualiza el flujo de decisión en este diagrama:
Esquema: Evalúa si conviene delegar. Si no, resuélvelo en el canal principal; si conviene y lo solicitas expresamente, Codex invocará agentes en paralelo para consolidar sus informes al finalizar. Nota que requiere tu solicitud para activarse.
03 Uso inmediato: tres agentes integrados y cómo invocarlos
Revisemos la práctica. Codex incorpora tres perfiles de subagentes listos para usar sin requerir configuración adicional:
Los tres agentes integrados son:
| Perfil integrado | Enfoque | Tareas idóneas |
|---|---|---|
default | Agente de propósito general | Opción por defecto ante tareas genéricas |
worker | Ejecución: desarrollo y corrección | Modificación de código o depuración de fallos |
explorer | Lectura: exploración y análisis | Inspección de la base de código, búsquedas o investigación |
Disponer de los perfiles no implica su activación. Recuerda la directriz básica: Codex nunca dividirá la tarea por su cuenta; requiere tu instrucción expresa en el chat. La documentación oficial detalla:
Codex 不会自动派生子代理，只有在你明确要求子代理或并行 agent 工作时才会用。 Codex no generará subagentes de forma automática, recurriendo a ellos únicamente cuando lo solicites de forma explícita.
Para invocarlos, simplemente redacta la instrucción con claridad indicando la distribución de tareas, si esperar a que finalicen y qué informe presentar. Ejemplos de directrices recomendados oficialmente: "spawn two agents", "delegate this work in parallel" o "use one agent per point". Un prompt de calidad para subagentes debe especificar tres aspectos: la distribución del trabajo, si la ejecución es asíncrona o requiere esperar a todos los agentes, y el formato de resumen de salida.
Puedes estructurar tus instrucciones siguiendo esta sintaxis:
Audita esta rama frente a main usando subagentes en paralelo. Asigna un agente para evaluar riesgos de seguridad, otro para la cobertura de pruebas y un tercero para la mantenibilidad del código. Espera a que los tres finalicen y consolida sus hallazgos clasificados por categoría indicando los ficheros y líneas.Analogía: El director de cine coordinando cámaras. Si no lo indicas, se grabará de forma secuencial; si ordenas "grabad estas tres escenas simultáneamente con las cámaras A, B y C y entregadme las tomas al terminar", el equipo se dividirá. Tu instrucción actúa como orden de rodaje: las cámaras (agentes) están disponibles, esperando tu orden de inicio.
Codex gestiona de forma automática la orquestación: inicializa las instancias, distribuye las instrucciones secundarias, recopila los resultados y cierra los hilos de ejecución al terminar. Si ejecutas múltiples agentes, esperará a consolidar todas las respuestas antes de mostrarte la conclusión.
Caso real: al auditar una PR, definí un prompt de tipo "spawn one agent per point" para evaluar seis incidencias simultáneamente. En lugar de retrasar la sesión, la ejecución en paralelo completó la tarea mucho más rápido que consultarlas una a una, entregando un resumen estructurado. Allí asimilé el valor del paralelismo: ahorra los tiempos de espera acumulados de la ejecución secuencial.
⚠️ Diferencias de visualización: las actividades de los subagentes son visibles actualmente en la CLI y la app de escritorio de Codex, figurando como "próximamente disponible" para extensiones de IDE en la documentación oficial. Usa la CLI o la app para auditar la actividad en tiempo real.
💡 Resumen en una frase: Dispones de tres perfiles integrados (
default,worker,explorer); ten en cuenta que Codex nunca los invocará de forma autónoma, requiriendo solicitar en tu instrucción "ejecutar agentes en paralelo, esperar a todos y consolidar los resultados".
04 Gestionar agentes activos: el comando /agent o comandos por chat
Si ejecutas múltiples agentes simultáneamente, requieres herramientas para consultar su estado o modificar sus tareas. Codex ofrece dos métodos:
Método 1: Alternar hilos con /agent
El comando oficial es /agent (en singular); utilízalo en la CLI para alternar entre hilos de ejecución activos y auditar la actividad de cada uno:
/agentNota la diferencia con otras utilidades: no sirve para "arrancar un agente", sino para "inspeccionar y alternar entre hilos". Inicializas los agentes mediante prompts y los auditas con /agent.
Método 2: Controlar mediante instrucciones por chat
Puedes gestionar las instancias directamente desde la conversación. La documentación oficial señala: puedes ordenar directamente a Codex interactuar con un subagente activo, detener su ejecución o cerrar hilos finalizados. Usa lenguaje natural sin comandos específicos (p. ej. "cancela la tarea del agente de exploración activo").
Analogía: La centralita de radio. Con múltiples unidades móviles en el exterior, puedes sintonizar una frecuencia para escuchar el estado de un vehículo (/agent) o usar la radio general para ordenar "unidad 3, aborta la tarea y regresa" (instrucciones por chat). Los vehículos operan de forma autónoma, pero tú conservas el control en todo momento.
Una consideración sobre las aprobaciones de permisos detallada oficialmente: en la CLI interactiva, las solicitudes de aprobación pueden provenir de hilos secundarios ejecutándose en segundo plano. Si un agente secundario requiere autorización, la alerta especificará su origen; puedes pulsar o para acceder a su hilo e inspeccionar el contexto antes de aprobar, denegar o responder. En flujos no interactivos (como scripts de automatización), cualquier solicitud de autorización no atendida provocará el fallo del subproceso devolviendo el error al canal principal.
💡 Resumen en una frase: Controla agentes activos con
/agent(singular) para alternar e inspeccionar hilos, o mediante chat para cancelarlos o reestructurarlos; pulsaosi un hilo secundario solicita confirmación para revisar su contexto antes de decidir.
05 Agentes personalizados: definir perfiles en archivos TOML
Los tres agentes integrados cubren necesidades generales, pero si repites directrices específicas con frecuencia (como "audita este código buscando riesgos de seguridad y cobertura de pruebas"), conviene consolidar el comportamiento en un agente personalizado para invocarlo fácilmente en el futuro.
Cómo definirlos: guarda un archivo TOML (un formato de configuración simple, fácil de leer y escribir) por cada agente en los siguientes directorios:
| Ruta de guardado | Alcance | Casos de uso |
|---|---|---|
~/.codex/agents/ | Todos tus proyectos de forma global | Perfiles genéricos de uso habitual en cualquier repositorio |
.codex/agents/ | Limitado al repositorio activo | Perfiles específicos que se añaden a Git para compartirse en equipo |
Analogía: La ficha del investigador especialista. Los tres perfiles integrados son recursos generales de la oficina; tu archivo TOML define la ficha de un especialista: nombre, especialidad, directrices de actuación y herramientas asignadas (modelo). Al registrar su ficha, podrás invocarlo en cualquier consulta.
Un archivo de agente personalizado básico requiere incluir estos tres campos obligatorios:
name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
"""Detalles de los campos (según la especificación oficial):
| Campo | Requerido | Propósito | Noción clave |
|---|---|---|---|
name | Sí | Nombre identificativo para invocar al agente | Es el identificador oficial; se recomienda nombrarlo igual que el archivo |
description | Sí | Descripción de uso para el usuario | Útil para aclarar su función al equipo |
developer_instructions | Sí | Directrices que rigen el comportamiento del agente | Define su perfil y reglas de actuación |
nickname_candidates | No | Lista de nombres alternativos para visualización | Útil para distinguir visualmente múltiples instancias activas del mismo agente en la UI |
Los demás parámetros opcionales se heredan de la sesión principal al omitirse: model, model_reasoning_effort, sandbox_mode, mcp_servers y skills.config. La documentación oficial detalla: los archivos de agente actúan como capas de configuración secundarias, admitiendo cualquier variable compatible con config.toml. Si tu agente personalizado coincide en nombre con uno integrado (p. ej. explorer), el tuyo tiene prioridad de carga.
Asignar modelos e intensidad de razonamiento por agente
Esta flexibilidad es el principal valor de los perfiles: asignar el recurso adecuado a cada tarea mediante estos interruptores:
model: el modelo a usar. El criterio recomendado es "modelos rápidos para exploración y robustos para auditorías": tareas de lectura extensas o paralelismo masivo usan modelos ligeros (gpt-5.4-mini); la lógica compleja o auditoría de seguridad requiere modelos avanzados (gpt-5.4ogpt-5.5, siendogpt-5.5la base para agentes exigentes, mientras que el ejemplo oficial de auditoría usagpt-5.4). Los nombres específicos varían según actualizaciones; adáptate a las directrices de rendimiento.model_reasoning_effort: intensidad de razonamiento del modelo, con tres niveles:
| Intensidad | Casos de uso | Contrapartida |
|---|---|---|
high | Lógica compleja, análisis de suposiciones o límites de código (auditoría o seguridad) | Mayor retardo y consumo de tokens, idóneo para tareas complejas |
medium | Valor por defecto equilibrado | Intermedio |
low | Tareas directas y sencillas | Mayor velocidad |
Configura un agente de exploración rápido de solo lectura y un auditor avanzado en sus respectivos archivos:
Nota sobre modelos: el ejemplo oficial usa gpt-5.3-codex-spark (ChatGPT Pro); usamos gpt-5.4-mini en esta plantilla, que puedes sustituir si tienes acceso Pro.
# .codex/agents/explorer.toml —— Explorador de solo lectura: rápido, económico, sin permisos de escritura
name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes."
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Stay in exploration mode.
Trace the real execution path, cite files and symbols, and avoid proposing fixes unless asked.
"""Nota la línea sandbox_mode = "read-only": sirve para restringir permisos por agente. Aunque los subagentes heredan la política general de la sesión por defecto, puedes delimitar perfiles específicos a solo lectura, personalizando al explorador para que no realice modificaciones de código.
⚠️ Prioridad en tiempo de ejecución: las modificaciones de permisos realizadas durante la sesión activa (como cambiar con
/permissionso iniciar con--yolo) se aplican a los subagentes heredados por encima de los parámetros estáticos declarados en sus archivos TOML.
Existe además una sección global [agents] en config.toml para definir los límites de todos los subagentes:
| Clave global | Propósito | Valor por defecto |
|---|---|---|
agents.max_threads | Límite máximo de hilos de agentes activos en paralelo | 6 |
agents.max_depth | Límite de anidamiento de subagentes (la sesión principal es 0) | 1 (permite subagentes pero impide que estos generen más niveles) |
agents.job_max_runtime_seconds | Tiempo de espera máximo para subprocesos en lotes CSV | 1800 segundos |
La recomendación oficial para max_depth es clara: mantenlo en 1 salvo que requieras recursividad expresamente. Incrementar el anidamiento convierte tareas complejas en cascadas de procesos en abanico (fan-out), disparando el consumo de tokens y recursos. Configurar max_threads limita los hilos simultáneos pero no controla la complejidad de la recursión.
💡 Resumen en una frase: Un agente personalizado es un archivo TOML bajo
~/.codex/agents/o.codex/agents/que requierename,descriptionydeveloper_instructions; hereda del chat principal por defecto y permite asignar modelos (model), razonamiento (model_reasoning_effort) y restringir permisos (sandbox_mode).
06 Manos a la obra: definir un agente de exploración de solo lectura y ejecutarlo
La teoría sin práctica no sirve. Definiremos un agente personalizado mínimo de exploración para verificar su aislamiento y la restricción de solo lectura (sandbox_mode = "read-only").
Crearemos un "explorador de código" de solo lectura, centrado en analizar ficheros e informar sobre la estructura del código sin realizar modificaciones.
Primer paso: Crear el directorio del proyecto y de agentes (en Mac / Linux)
mkdir sub-demo
cd sub-demo
mkdir -p .codex/agentsResultado esperado: se crea la estructura de directorios en sub-demo. Ejecutar ls .codex lista la carpeta agents.
En Windows PowerShell usa:
mkdir sub-demo; cd sub-demo; mkdir .codex\agents -Force. Sustituyeechoycatpor los equivalentes de PowerShell.
Segundo paso: Escribir el archivo del agente personalizado
Crea el archivo sub-demo/.codex/agents/scout.toml y añade:
name = "scout"
description = "Explorador de solo lectura, analiza ficheros e informa sobre estructuras y fallos sin modificar archivos."
sandbox_mode = "read-only"
model_reasoning_effort = "low"
developer_instructions = """
Actúa como un explorador de código de solo lectura: analiza el código sin modificarlo.
Tareas a realizar:
1. Leer los archivos indicados por el usuario.
2. Identificar problemas estructurados por: legibilidad, nomenclatura y fallos potenciales.
3. Proporcionar recomendaciones de mejora para cada punto sin alterar ningún archivo.
Devuelve únicamente una síntesis simplificada sin volcar código fuente redundante.
"""Nota que hemos omitido la clave model para heredar la opción por defecto de la sesión. Declarar sandbox_mode = "read-only" restringe su ejecución a solo lectura impidiendo modificaciones, y model_reasoning_effort = "low" acelera las búsquedas sencillas.
Tercer paso: Crear un archivo de código con fallos sencillos
echo 'def f(a, b):
return a / b' > calc.pyLa función f y los parámetros a y b carecen de descriptividad, y falta validar la división por cero; es idóneo para la prueba.
Resultado esperado: se crea el archivo calc.py en sub-demo.
Cuarto paso: Iniciar Codex e invocar al agente personalizado
codexAl entrar, recuerda solicitar expresamente el uso de subagentes (sección 03):
Delega en el subagente scout el análisis de calc.py; devuelve únicamente un resumen de hallazgos según sus directrices sin modificar el archivo.Resultado esperado: Codex inicializa el subagente scout (mostrándolo en la UI o CLI, habitualmente con un alias asignado). El agente lee calc.py en su hilo aislado y devuelve solo un informe consolidado al canal principal: identificará la nomenclatura ambigua de f, a y b, y la falta de control para división por cero recomendando mejoras. Solo informará sin alterar el fichero al carecer de permisos de escritura (read-only). Escribe /agent para inspeccionar su hilo de ejecución durante la sesión.
Quinto paso: Verificar que el archivo permanece intacto
Sal de Codex y comprueba en la terminal:
cat calc.py(En Windows PowerShell usa type calc.py).
Resultado esperado: calc.py permanece intacto. Esto demuestra el control de permisos: al restringir el subagente a solo lectura, se garantiza que no altere los archivos.
Completar este flujo verifica el ciclo completo: "escribir TOML → invocar subagente → ejecución en hilo aislado → consolidación y seguridad". Cualquier agente personalizado posterior utilizará los mismos principios.
⚠️ Si Codex realiza el análisis directamente sin inicializar al subagente, asegúrate de redactar la instrucción con mayor claridad (sección 03) indicando explícitamente "delega en el subagente scout..." para evitar que el modelo principal resuelva la consulta.
💡 Resumen en una frase: Configura un TOML de exploración con
read-only→ solicita "delega en scout..." en el chat → comprueba concatque el fichero no ha variado; probar este flujo consolida el aprendizaje de permisos y paralelismo.
07 Procesamiento de lotes en CSV (experimental)
⚠️ Este función está etiquetada como experimental y sujeta a cambios; la presentamos de forma introductoria.
Si requieres procesar grandes volúmenes de tareas análogas (un fichero o PR por cada línea de un archivo), Codex ofrece spawn_agents_on_csv: lee una plantilla CSV e inicializa un subagente worker por cada línea, exportando un CSV consolidado con las respuestas al finalizar.
Analogía: La cadena de montaje. Cada línea del CSV representa una pieza de trabajo y se asignan operarios (agentes worker) en paralelo para etiquetarla. Cada agente worker debe invocar exactamente una vez report_agent_job_result para reportar el estado, o esa fila se marcará como fallida en la salida. Revisa la documentación oficial para la sintaxis detallada.
Criterios de uso para lotes CSV:
| Escenario | ¿Conviene usar lotes CSV? | Motivo |
|---|---|---|
| Auditar decenas de PR de estructura similar | ✅ Recomendado | Tareas idénticas sobre múltiples objetos; beneficio alto |
| Traducir comentarios en decenas de ficheros | ✅ Recomendado | Tareas independientes y aisladas; escenario ideal |
| Procesos secuenciales dependientes | ❌ No recomendado | Los hilos se inician en paralelo sin orden de ejecución |
| Pocas tareas u objetos sencillos | ❌ No recomendado | El coste de inicialización del lote supera la resolución directa |
| Modificaciones simultáneas en los mismos archivos | ⚠️ Evitar | Mismo riesgo de colisión de código de la sección 02 |
💡 Resumen en una frase: La función experimental para procesar CSV automatiza tareas repetitivas sobre grandes lotes de objetos independientes; evítala ante flujos secuenciales o modificaciones concurrentes sobre el mismo archivo.
08 Resumen
En este artículo hemos revisado los subagentes: su idoneidad, inicialización, perfiles y auditoría; comprendiendo el límite entre delegar o resolver en el canal principal, y recordando que requiere tu orden expresa para activarse.
Repasemos las pautas consolidadas:
| Aspecto | Conclusión | Noción clave |
|---|---|---|
| Qué son los subagentes | Instancias secundarias con hilos y configuración independiente | Operan en paralelo y devuelven solo resúmenes |
| Qué resuelven | Contaminación y degradación de contexto | Aisla las tareas de lectura pesadas del chat principal |
| Cuándo no usarlos | Ediciones menores, secuenciales o escritura concurrente | Evita sobrecargar tokens o causar conflictos en el código |
| Cómo invocarlos | Requiere tu instrucción expresa en el chat | Define la tarea, si esperar y el informe deseado |
| Integrados y personalizados | Tres perfiles integrados; personalizados con TOML | Campo name, description y developer_instructions obligatorios |
| Selección de modelos | model y model_reasoning_effort | Modelos ligeros para búsquedas; avanzados para auditorías |
Ahora deberías ser capaz de: evaluar cuándo conviene delegar en subagentes; usar los tres perfiles integrados o definir agentes personalizados en ~/.codex/agents/ asignando modelos y limitando permisos; y recordar que requiere tu instrucción expresa para arrancar, devolviendo un informe consolidado. Esta distinción entre paralelismo y ejecución directa es el verdadero criterio de uso.
Conserva la pauta: los subagentes de Codex son muy útiles, pero tú mantienes el control de decidir cuándo y cómo dividirlos.
El próximo artículo 22 · Habilidades de los agentes (Skills): tu arquitectura de desarrollo con Codex se consolida con AGENTS.md, comandos, MCP y subagentes. Sin embargo, configurar las directrices de actuación de los subagentes en cada ocasión puede ser tedioso. ¿Y si pudieras encapsular estas instrucciones en habilidades reutilizables (Skills) listas para invocar? En el próximo capítulo explicaremos cómo consolidar estas aptitudes en Codex.