Codex CLI — Subagentes · Agentes de IA para programar

Codex admite flujos de trabajo multiagente: el agente principal puede delegar trabajo en subagentes que corren en hilos separados. En las versiones actuales estos flujos vienen activados por defecto (agents.enabled = true, features.multi_agent = true). Codex delega cuando se lo pides directamente, o cuando lo piden las instrucciones de AGENTS.md o de una skill.

Agentes integrados

Agente	Rol
`default`	Uso general, es el de reserva
`worker`	Centrado en ejecutar
`explorer`	Exploración intensiva en lectura

Un agente propio con el mismo nombre que uno integrado tiene prioridad sobre él.

Agentes propios

Los agentes propios son archivos TOML independientes:

~/.codex/agents/ — agentes personales
.codex/agents/ — agentes del proyecto

Campos obligatorios en cada archivo: name, description y developer_instructions. Entre los opcionales están model, model_reasoning_effort, sandbox_mode, mcp_servers y skills.config.

# .codex/agents/security-reviewer.toml
name = "security-reviewer"
description = "Revisor de solo lectura que audita los cambios en busca de problemas de seguridad"
developer_instructions = """
Eres un revisor de código centrado en seguridad. Nunca modifiques archivos.
Reporta los hallazgos con referencias archivo:línea y su severidad.
"""
sandbox_mode = "read-only"
model_reasoning_effort = "high"

El archivo se carga como una capa de configuración para la sesión que se lanza; lo que no especifiques se hereda del padre. Orden de resolución del modelo y el esfuerzo: valor explícito al lanzarlo → valor por defecto de [agents] → valor del padre.

Lanzar y coordinar subagentes

Las herramientas multiagente disponibles para el agente padre:

Herramienta	Para qué sirve
`spawn_agent`	Arranca el hilo de un subagente
`send_input`	Le envía entrada a un subagente en marcha
`resume_agent`	Retoma el hilo de un subagente
`wait_agent`	Espera a que un subagente termine
`close_agent`	Cierra el hilo de un subagente

En la TUI, /agent (o /subagents) cambia el hilo activo para que puedas inspeccionar o continuar el trabajo de un subagente.

Ajustes globales

Bajo [agents] en config.toml:

Clave	Para qué sirve
`enabled`	Interruptor general (true por defecto)
`max_concurrent_threads_per_session`	Tope de concurrencia (alias antiguo `max_threads`)
`default_subagent_model`	Modelo por defecto de los agentes que se lanzan
`default_subagent_reasoning_effort`	Esfuerzo de razonamiento por defecto
`interrupt_message`	true por defecto
`agents.<nombre>.config_file` / `agents.<nombre>.description`	Declara roles en la configuración

Permisos

Los subagentes heredan el sandbox y el modo de permisos del padre; los agentes propios pueden sobrescribirlo (por ejemplo, forzando read-only en un agente revisor, como en el ejemplo de arriba).

Casos de uso y limitaciones

Encajan bien en:

Exploración paralela intensiva en lectura (mapear un código, encontrar todos los llamadores, auditar un patrón).
Aislar un rol especialista (revisión de seguridad, escritura de tests) con sus propias instrucciones y su propio sandbox.
Tareas largas en segundo plano mientras tú sigues trabajando en el hilo principal.

Cuidado con:

Los flujos multiagente consumen más tokens que las ejecuciones con un solo agente.
El trabajo paralelo intensivo en escritura — si varios agentes editan los mismos archivos, entran en conflicto.

Última verificación: 2026-09-07

Fuentes oficiales:

Las herramientas de IA para programar evolucionan rápido. Si encuentras información desactualizada, abre un issue o un pull request.