Codex Subagents: cómo delegar tareas a agentes especializados
Aprende
cómo funcionan los subagentes de Codex,
cuándo conviene dividir
una tarea,
cómo ejecutar
agentes especializados
en paralelo,
configurar roles personalizados
con archivos
.toml,
asignar modelos,
razonamiento,
sandbox,
Skills
y MCP,
y cómo coordinar
exploración,
seguridad,
testing,
documentación
e implementación
desde un agente principal.
¿Qué es un subagente de Codex?
Un subagente de Codex es un agente adicional al que el agente principal delega una tarea concreta. Cada subagente puede investigar, utilizar herramientas, ejecutar verificaciones y devolver un resultado al agente coordinador. Esto permite dividir trabajos complejos en problemas independientes y ejecutarlos simultáneamente, por ejemplo usando un agente para seguridad, otro para tests y otro para documentación.
Qué aporta un workflow con subagentes
Paralelismo
Varias investigaciones pueden ejecutarse al mismo tiempo.
Especialización
Cada agente puede tener un objetivo diferente.
Contexto focalizado
Cada subagente trabaja sobre un problema más pequeño.
Modelos distintos
Puedes equilibrar profundidad, velocidad y costo.
Permisos diferentes
Un reviewer puede ser solo lectura.
Síntesis
El agente principal reúne los resultados en una respuesta.
El agente principal coordina y los subagentes especializan
Divide
Detecta subtareas independientes.
Delega
Asigna cada problema al agente apropiado.
Trabajan
Los subagentes avanzan en paralelo.
Integra
El coordinador reúne los resultados.
Los subagentes funcionan mejor con tareas independientes
Explorar distintas partes de un repositorio.
Revisar seguridad, calidad y tests por separado.
Investigar documentación mientras otro agente analiza código.
Ejecutar verificaciones independientes.
Clasificar múltiples bugs o incidencias.
Analizar grandes cantidades de información por partes.
No todo problema necesita varios agentes
Tareas independientes
Cada agente puede completar su trabajo sin bloquear a los demás.
Trabajo muy acoplado
Todos necesitan modificar simultáneamente las mismas funciones y archivos.
Cada uno utiliza modelo, contexto y herramientas de forma independiente, por lo que un workflow multiagente normalmente consume más tokens que una ejecución equivalente con un solo agente.
Pide directamente a Codex que trabaje en paralelo
Revisa esta rama
usando tres subagentes.
Agente 1:
busca problemas de seguridad.
Agente 2:
busca bugs y regresiones.
Agente 3:
revisa cobertura de tests.
Ejecuta las tres revisiones
en paralelo.
Espera los tres resultados
antes de responder.
Después entrégame
una sola lista consolidada
ordenada por severidad,
con archivo y línea.Indica qué debe hacer cada subagente, si Codex debe esperar a todos y cómo debe integrar los resultados.
Empieza paralelizando tareas principalmente de lectura
Exploración
Mapear distintos módulos del repositorio.
Review
Buscar diferentes categorías de problemas.
Testing
Investigar tests faltantes o fallos.
Implementación
Varios agentes escribiendo sobre el mismo código.
Codex incluye agentes predeterminados
| Agente | Enfoque |
|---|---|
default |
Agente general utilizado como fallback |
worker |
Implementación, cambios y correcciones |
explorer |
Exploración intensiva en lectura del repositorio |
Para muchos workflows, los roles integrados son suficientes. Los agentes personalizados tienen sentido cuando quieres comportamiento más especializado.
Crear un subagente personalizado
Los agentes personalizados se definen mediante archivos TOML independientes.
.codex/
└── agents/
├── reviewer.toml
├── security.toml
├── test-reviewer.toml
└── docs-researcher.tomlAgentes personales vs agentes del proyecto
~/.codex/agents/
Agentes que quieres reutilizar entre distintos proyectos.
.codex/agents/
Roles específicos del repositorio y compartibles con el equipo.
Tres campos son fundamentales
| Campo | Función |
|---|---|
name |
Identifica el agente |
description |
Explica cuándo debería utilizarse |
developer_instructions |
Define cómo debe comportarse |
Crear un agente reviewer
name = "reviewer"
description = "Code reviewer focused on correctness, security, regressions and missing tests."
model = "gpt-5.6"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
Review code like a repository owner.
Prioritize:
- correctness bugs
- security issues
- behavior regressions
- data-loss risks
- missing authorization
- missing regression tests
Return concrete findings
with file and line references.
Avoid style-only comments
unless they hide a real problem.
Do not modify code.
"""
Si el objetivo
del agente
es únicamente
revisar,
darle
workspace-write
normalmente
no aporta
ninguna ventaja.
Agente especializado en seguridad
name = "security_reviewer"
description = "Security specialist for reviewing authentication, authorization, input validation, secrets, database access and externally reachable attack surfaces."
model = "gpt-5.6"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
Perform a security-focused review.
Prioritize realistic vulnerabilities involving:
- authentication bypass
- authorization failures
- injection
- unsafe file operations
- exposed secrets
- session handling
- CSRF
- SSRF
- unsafe deserialization
- privilege escalation
Do not report speculative issues
without a plausible attack path.
Do not modify code.
"""Agente especializado en cobertura de tests
name = "test_reviewer"
description = "Testing specialist that identifies important missing regression, integration and edge-case coverage."
model = "gpt-5.6-terra"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Review the changed behavior
and existing test coverage.
Find:
- untested regressions
- missing edge cases
- incorrect assertions
- flaky tests
- important error paths
- behavior changes without coverage
Do not ask for tests
that merely duplicate
implementation details.
Return the minimum set
of high-value tests.
"""Un subagente puede tener su propio servidor MCP
name = "docs_researcher"
description = "Documentation specialist that verifies APIs and version-specific behavior using the documentation MCP server."
model = "gpt-5.6-luna"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Verify APIs,
configuration options
and version-specific behavior
using official documentation.
Return concise findings
with exact references.
Do not modify code.
"""
[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"No todos los subagentes necesitan el mismo modelo
| Trabajo | Perfil recomendado |
|---|---|
| Arquitectura compleja | Modelo de mayor capacidad |
| Security review | Modelo potente + reasoning alto |
| Exploración del repositorio | Modelo rápido y eficiente |
| Clasificación repetitiva | Modelo ligero |
| Documentación focalizada | Modelo rápido + MCP |
Un sistema con varios agentes funciona mejor cuando reservas los modelos más costosos para tareas que realmente necesitan razonamiento profundo.
Cada agente puede utilizar un nivel de razonamiento distinto
model_reasoning_effort = "high"Tareas claras y repetitivas.
Buen equilibrio para la mayoría.
Review, seguridad y lógica compleja.
Problemas especialmente difíciles cuando el modelo lo soporte.
Los subagentes heredan configuración del agente principal
Si un agente personalizado no especifica ciertos ajustes, puede heredar valores de la sesión principal.
Modelo y razonamiento.
Sandbox y permisos.
Servidores MCP.
Configuración de Skills.
Puedes mantener una configuración común y sobrescribir únicamente lo necesario para cada rol.
Configura los permisos antes de iniciar la delegación
Los subagentes heredan el modo de permisos seleccionado para el turno del agente principal. Por eso conviene decidir el nivel de acceso antes de solicitar la delegación.
Un reviewer,
explorer
o researcher
normalmente
puede configurarse
con
sandbox_mode = "read-only"
aunque otros agentes
necesiten
escribir
en el workspace.
Configuración global del sistema multiagente
[agents]
enabled = true
max_concurrent_threads_per_session = 6
default_subagent_model = "gpt-5.6-terra"
default_subagent_reasoning_effort = "medium"
interrupt_message = true| Ajuste | Función |
|---|---|
agents.enabled |
Activa o desactiva las herramientas multiagente |
agents.max_concurrent_threads_per_session |
Limita los subagentes abiertos simultáneamente |
agents.default_subagent_model |
Modelo predeterminado de los subagentes |
agents.default_subagent_reasoning_effort |
Razonamiento predeterminado |
agents.interrupt_message |
Controla el mensaje visible al modelo cuando se interrumpe un agente |
Controla cuántos subagentes pueden estar abiertos
[agents]
max_concurrent_threads_per_session = 8El objetivo no es llenar todos los slots, sino encontrar partes del problema que realmente puedan avanzar de forma independiente.
Instalaciones
previas
pueden seguir
utilizando
agents.max_threads
como alias heredado.
Para nuevas configuraciones
conviene utilizar
max_concurrent_threads_per_session.
Configuración multiagente versionada en el repositorio
mi-proyecto/
├── AGENTS.md
│
├── .codex/
│ ├── config.toml
│ │
│ └── agents/
│ ├── reviewer.toml
│ ├── security-reviewer.toml
│ ├── test-reviewer.toml
│ └── docs-researcher.toml
│
├── .agents/
│ └── skills/
│
├── src/
└── tests/El repositorio puede definir sus propios reviewers, explorers, investigadores y workers junto con AGENTS.md y Skills.
Un agente personalizado puede tener configuración de Skills
name = "reviewer"
description = "Reviewer for security and correctness."
sandbox_mode = "read-only"
[[skills.config]]
path = "/home/user/.agents/skills/security-review/SKILL.md"
enabled = trueLos mejores agentes son estrechos y especializados
super_agent
Revisa, desarrolla, diseña, testea, documenta y despliega cualquier cosa.
security_reviewer
Busca vulnerabilidades concretas y no modifica código.
El agente principal no debería repetir el trabajo delegado
Si un subagente está investigando seguridad, el agente principal debería aprovechar ese tiempo realizando trabajo diferente, en lugar de volver a ejecutar la misma auditoría.
Audita seguridad.
Revisa arquitectura.
Analiza cobertura.
Prepara integración.
Espera únicamente cuando el resultado sea necesario
Mientras un subagente trabaja, el agente principal puede continuar realizando tareas independientes. Solo debería bloquearse cuando necesite el resultado para avanzar en el camino crítico.
Inspeccionar subagentes desde Codex CLI
En una sesión interactiva puedes utilizar:
/agentEsto permite cambiar entre threads de agentes y revisar qué está haciendo cada uno.
Puedes redirigir un subagente mientras trabaja
Si un agente está explorando una dirección poco útil, puedes pedir al agente principal que cambie su foco.
El agente de seguridad
no necesita revisar
el frontend.
Redirígelo únicamente
a:
- autenticación
- autorización
- sesiones
- endpoints REST
- consultas SQL.También puedes detener trabajos que ya no aportan valor
Detén el agente
de documentación.
Ya tenemos
la información necesaria.
Continúa esperando
únicamente
security_reviewer
y test_reviewer.Revisión de Pull Request con agentes especializados
Revisa esta rama contra main.
Usa estos agentes:
explorer:
mapea los code paths modificados
y dependencias relacionadas.
reviewer:
busca bugs,
regresiones
y problemas de seguridad.
test_reviewer:
busca comportamiento nuevo
sin cobertura suficiente.
docs_researcher:
verifica APIs externas
o comportamiento dependiente
de versiones.
Ejecuta las investigaciones
en paralelo cuando sea posible.
Espera todos los resultados.
Después elimina duplicados
y entrégame únicamente
hallazgos accionables
ordenados por severidad.Subagentes para un plugin WordPress
Analiza este plugin WordPress
usando cuatro subagentes.
Agente 1 · architecture
Mapea:
- bootstrap
- clases
- hooks
- shortcodes
- AJAX
- REST
- cron
- tablas
Agente 2 · security
Revisa:
- nonces
- capabilities
- sanitización
- escaping
- SQL
- uploads
- REST permissions
Agente 3 · compatibility
Revisa:
- PHP 8.2+
- WordPress
- WooCommerce
- APIs obsoletas
Agente 4 · testing
Identifica:
- flujos críticos
- tests faltantes
- posibles regresiones
Todos deben trabajar
en modo lectura.
Espera los cuatro resultados
y genera
un único informe consolidado.Debugging con exploración y reproducción separadas
Investiga por qué
el formulario
no guarda los cambios.
Usa tres roles.
code_mapper:
encuentra el flujo completo
desde UI hasta base de datos.
runtime_debugger:
reproduce el error
y reúne logs,
network
y mensajes reales.
docs_researcher:
verifica cualquier API
o comportamiento
del framework
del que dependa el flujo.
No modifiques código todavía.
Primero reúne
los tres resultados
y propón
la causa raíz
más probable.
Después
de encontrar
la causa raíz
puedes delegar
la implementación
a un
worker
o agente
especializado.
Cuando varios agentes escriben código, divide bien el alcance
Dos agentes que editan exactamente los mismos archivos pueden crear conflictos o duplicar trabajo. La implementación paralela funciona mejor cuando cada agente posee una parte claramente separada del código.
Alcances separados
Agente A: backend.
Agente B: frontend.
Agente C: tests.
Mismo archivo
Tres agentes refactorizando simultáneamente la misma clase.
Subagentes y Worktrees resuelven problemas diferentes
| Subagents | Worktrees |
|---|---|
| Delegación lógica | Aislamiento Git |
| Especialización de agentes | Separación de checkouts |
| Paraleliza razonamiento | Paraleliza modificaciones |
| Puede ser solo lectura | Especialmente útil para escritura |
| Devuelve resultados al coordinador | Produce cambios aislados en Git |
Subagent vs Skill
Procedimiento
Define cómo realizar un workflow especializado.
Ejecutor
Ejecuta una tarea delegada como agente independiente.
Un subagente especializado puede tener acceso a una Skill diseñada específicamente para su trabajo.
Cómo encajan todas las capas de personalización de Codex
Delegación débil vs delegación útil
| Débil | Mejor |
|---|---|
| Revisa el proyecto | Mapea autenticación y devuelve entry points, llamadas y archivos relevantes |
| Busca errores | Busca regresiones introducidas por esta rama comparándola contra main |
| Revisa seguridad | Busca bypass de autorización, inyección y exposición de credenciales |
| Haz tests | Identifica comportamiento modificado sin cobertura de regresión |
| Devuelve todo | Resume hallazgos accionables con archivo, línea e impacto |
Cómo diseñar workflows multiagente efectivos
Una responsabilidad clara por agente.
Paraleliza únicamente tareas independientes.
Usa read-only cuando el agente no necesita escribir.
Utiliza modelos más rápidos para exploración.
Reserva razonamiento alto para problemas difíciles.
No dupliques en el agente principal el trabajo delegado.
Espera todos los resultados requeridos antes de sintetizar.
Devuelve resúmenes, no enormes volcados de contexto.
Equipo de agentes para revisar un proyecto
Configuración:
[agents]
enabled = true
max_concurrent_threads_per_session = 6
default_subagent_model = "gpt-5.6-terra"
default_subagent_reasoning_effort = "medium"Estructura:
.codex/
├── config.toml
│
└── agents/
├── architecture.toml
├── reviewer.toml
├── security-reviewer.toml
├── test-reviewer.toml
└── docs-researcher.tomlPrompt:
Haz una revisión completa
de esta rama.
architecture:
mapea el impacto.
reviewer:
busca bugs y regresiones.
security_reviewer:
busca vulnerabilidades reales.
test_reviewer:
revisa cobertura.
docs_researcher:
verifica APIs externas
cuando sea necesario.
Ejecuta en paralelo
las partes independientes.
Espera todos los resultados.
Después:
1. elimina duplicados
2. resuelve contradicciones
3. ordena por severidad
4. devuelve archivo y línea
5. propone la corrección mínimaGuías relacionadas
FAQ sobre Codex Subagents
Es un agente que Codex inicia para realizar una tarea específica delegada por un agente principal. Varios subagentes pueden trabajar en paralelo y sus resultados pueden consolidarse posteriormente.
Sí. Las versiones actuales de Codex habilitan workflows con subagentes, y su actividad puede verse en superficies compatibles como la app de escritorio, Codex CLI y la extensión IDE.
Codex incluye actualmente los roles default, worker y explorer. Default funciona como agente general, worker está orientado a implementación y explorer a exploración intensiva en lectura.
Los agentes personales pueden guardarse en ~/.codex/agents/, mientras los agentes específicos de un proyecto pueden almacenarse en .codex/agents/ dentro del repositorio.
Cada agente se define mediante un archivo TOML que debe incluir name, description y developer_instructions. También puede configurar modelo, razonamiento, sandbox, MCP y Skills.
Sí. Un agente personalizado puede establecer su propio modelo y model_reasoning_effort. Esto permite utilizar modelos rápidos para exploración y configuraciones más potentes para seguridad, revisión o razonamiento complejo.
La concurrencia puede limitarse mediante agents.max_concurrent_threads_per_session. Si no estableces un valor, Codex utiliza su configuración predeterminada. El antiguo agents.max_threads continúa disponible como alias heredado.
Sí. Los subagentes heredan el modo de permisos seleccionado para el turno del agente padre. Un agente personalizado también puede definir configuraciones como sandbox de solo lectura.
Sí. La configuración de un agente personalizado puede incluir skills.config. Esto permite combinar un rol especializado con workflows reutilizables definidos mediante Skills.
Sí. Un agente personalizado puede configurar servidores MCP propios, por ejemplo para consultar documentación, herramientas de navegador u otros sistemas externos.
Los subagentes resuelven la delegación de trabajo entre agentes. Los worktrees resuelven el aislamiento de cambios mediante diferentes checkouts Git. Pueden utilizarse juntos en workflows de programación paralela.
Una Skill define un procedimiento reutilizable. Un subagente es un agente independiente al que se delega trabajo. Un subagente puede utilizar una o varias Skills durante su tarea.
En una sesión interactiva de Codex CLI puedes usar /agent para cambiar entre threads de agentes activos e inspeccionar el trabajo que están realizando.
Codex MCP: conecta agentes con herramientas y sistemas externos
Ya sabes cómo delegar trabajos a agentes especializados. Ahora veremos cómo ampliar sus capacidades mediante Model Context Protocol, conectando Codex con documentación, herramientas, APIs y servicios externos, además de combinar MCP con Skills y Subagents.
Aprender Codex MCP →