Subagentes

ChatGPT Work y Codex pueden ejecutar flujos de trabajo con subagentes mediante la creación de agentes especializados en paralelo y la posterior recopilación de sus resultados en una sola respuesta. Esto puede ser especialmente útil para tareas complejas que permiten un alto grado de paralelización, como explorar una base de código o implementar un plan de funcionalidades de varios pasos.

En los clientes locales de Codex, también puedes definir agentes personalizados con distintas configuraciones de modelo e instrucciones para diferentes tareas.

Disponibilidad

ChatGPT Work en la web

ChatGPT Work muestra los flujos de trabajo y la actividad de los subagentes a las cuentas que cumplen los requisitos.

Clientes locales de Codex

Las versiones actuales de Codex habilitan los flujos de trabajo con subagentes de forma predeterminada. La actividad de los subagentes aparece en la aplicación de escritorio de ChatGPT, Codex CLI y la extensión para IDE.

Como cada subagente realiza su propio trabajo con el modelo y las herramientas, los flujos de trabajo con subagentes consumen más tokens que las ejecuciones equivalentes con un solo agente.

ChatGPT Work en la web

En ChatGPT Work, pide a ChatGPT que delegue trabajo independiente a subagentes. Los agentes se ejecutan en el entorno alojado de ChatGPT, y el chat muestra su actividad y sus resultados. En la mayoría de los niveles de inteligencia, solicita la delegación explícitamente. Con Ultra, ChatGPT puede delegar trabajo de forma proactiva cuando los agentes en paralelo mejorarían considerablemente la velocidad o la calidad.

Aplicación de escritorio de ChatGPT

Pide a Codex en un chat de la aplicación que delegue partes independientes del trabajo a subagentes. Las versiones locales actuales de Codex delegan cuando lo solicitas directamente o cuando las instrucciones aplicables de AGENTS.md o de una habilidad lo requieren. La aplicación muestra cada hilo de subagente para que puedas inspeccionar su trabajo y el resumen devuelto al chat principal.

Codex CLI

Pide a Codex en una sesión interactiva de CLI que use subagentes. Codex también puede seguir las instrucciones aplicables de AGENTS.md o de una habilidad que soliciten delegación. Usa /agent para inspeccionar los hilos de los agentes y cambiar entre ellos mientras se ejecutan. El hilo principal recopila los resultados de los subagentes en su respuesta final.

Extensión para IDE

Pide a Codex en un chat del IDE que delegue partes independientes del trabajo a subagentes. Codex también puede seguir las instrucciones aplicables de AGENTS.md o de una habilidad que soliciten delegación. Cuando la interfaz de agentes en segundo plano está disponible, los subagentes activos aparecen encima del cuadro de redacción. Expande el panel para ver su estado, detener todos los subagentes activos o abrir el hilo de un subagente concreto.

Por qué son útiles los flujos de trabajo con subagentes

Incluso con ventanas de contexto grandes, los modelos tienen límites. Si saturas el chat principal (donde defines requisitos, restricciones y decisiones) con resultados intermedios ruidosos, como notas de exploración, registros de pruebas, seguimientos de pila y resultados de comandos, la sesión puede volverse menos fiable con el tiempo.

Esto suele describirse como:

• Contaminación del contexto: la información útil queda sepultada bajo resultados intermedios ruidosos.
• Deterioro del contexto: el rendimiento disminuye a medida que el chat se llena de detalles menos relevantes.

Para obtener más contexto, consulta el artículo de Chroma sobre el deterioro del contexto.

Los flujos de trabajo con subagentes ayudan trasladando el trabajo ruidoso fuera del hilo principal:

• Mantén al agente principal centrado en los requisitos, las decisiones y los resultados finales.
• Ejecuta subagentes especializados en paralelo para tareas de exploración, pruebas o análisis de registros.
• Devuelve resúmenes de los subagentes en lugar de resultados intermedios sin procesar.

También pueden ahorrar tiempo cuando el trabajo puede ejecutarse de forma independiente y en paralelo, y hacen que las tareas de mayor envergadura sean más manejables al dividirlas en partes acotadas. Por ejemplo, Codex puede dividir el análisis de un documento de varios millones de tokens en problemas más pequeños y devolver conclusiones sintetizadas al hilo principal.

Como punto de partida, usa agentes en paralelo para tareas con mucha lectura, como exploración, pruebas, triaje y resumen. Ten más cuidado con los flujos de trabajo en paralelo que requieren mucha escritura, porque varios agentes editando código al mismo tiempo pueden generar conflictos y aumentar la sobrecarga de coordinación.

Términos principales

Codex usa varios términos relacionados en los flujos de trabajo con subagentes:

• Flujo de trabajo con subagentes: un flujo de trabajo en el que Codex ejecuta agentes en paralelo y combina sus resultados.
• Subagente: un agente delegado que Codex inicia para realizar una tarea específica.
• Hilo de agente: el hilo donde un subagente realiza su trabajo. Los clientes compatibles permiten abrir estos hilos para inspeccionar el progreso o los resultados.

Activar flujos de trabajo con subagentes

ChatGPT Work en la web

En la mayoría de los niveles de inteligencia, solicita directamente subagentes o trabajo con agentes en paralelo. Ultra permite la delegación proactiva, por lo que ChatGPT puede delegar trabajo independiente adecuado sin una solicitud adicional.

Clientes locales de Codex

Solicita directamente subagentes o trabajo con agentes en paralelo. Codex también puede delegar cuando lo soliciten las instrucciones aplicables del proyecto o de una habilidad.

En la práctica, la activación manual consiste en usar instrucciones directas como «crea dos agentes», «delega este trabajo en paralelo» o «usa un agente por cada punto». Los flujos de trabajo con subagentes consumen más tokens que las ejecuciones equivalentes con un solo agente porque cada subagente realiza su propio trabajo con el modelo y las herramientas.

Una buena instrucción para subagentes debe explicar cómo dividir el trabajo, si Codex debe esperar a todos los agentes antes de continuar y qué resumen o resultado debe devolver.

Review this branch with parallel subagents. Spawn one subagent for security risks, one for test gaps, and one for maintainability. Wait for all three, then summarize the findings by category with file references.

Elegir modelos y razonamiento

Los distintos agentes necesitan configuraciones diferentes de modelo y razonamiento.

ChatGPT Work en la web

En ChatGPT Work, elige un modelo y un nivel de inteligencia en el cuadro de redacción. Los niveles de inteligencia disponibles pueden incluir Light, Medium, High, Extra High y Max, según el modelo seleccionado. Ultra solo está disponible para cuentas que cumplen los requisitos y modelos compatibles. Usa el razonamiento máximo y permite que ChatGPT delegue de forma proactiva el trabajo adecuado a subagentes.

En los demás niveles de inteligencia, solicita subagentes explícitamente cuando quieras que el trabajo se delegue en paralelo.

Clientes locales de Codex

Si no fijas un modelo ni model_reasoning_effort, Codex puede elegir una configuración que equilibre inteligencia, velocidad y precio para la tarea. Puede dar prioridad a gpt-5.6-terra para análisis rápidos o a una configuración de gpt-5.6 con mayor esfuerzo para razonamientos más exigentes. Cuando quieras un control más preciso, orienta esa elección en tu instrucción o establece model y model_reasoning_effort directamente en el archivo del agente.

Elección del modelo

• gpt-5.6: comienza aquí para agentes exigentes. Es la opción más potente para trabajos ambiguos de varios pasos que requieren planificación, uso de herramientas, validación y seguimiento en un contexto más amplio.
• gpt-5.6-terra: úsalo para agentes que priorizan la velocidad y la eficiencia sobre la profundidad, como la exploración, los análisis con mucha lectura, la revisión de archivos grandes o el procesamiento de documentos complementarios. Funciona bien para trabajadores en paralelo que devuelven resultados sintetizados al agente principal.
• gpt-5.6-luna: úsalo para agentes rápidos y de alcance limitado que realizan trabajos claros, repetibles o de gran volumen.

Esfuerzo de razonamiento (model_reasoning_effort)

• ultra: úsalo para el razonamiento más profundo cuando el modelo seleccionado lo admita.
• max y xhigh: úsalos para razonamientos especialmente exigentes cuando el modelo seleccionado admita estos niveles.
• high: úsalo cuando un agente necesite rastrear lógica compleja, comprobar suposiciones o analizar casos límite (por ejemplo, agentes revisores o centrados en la seguridad).
• medium: una opción predeterminada equilibrada para la mayoría de los agentes.
• low: úsalo cuando la tarea sea sencilla y la velocidad sea la máxima prioridad.

Un mayor esfuerzo de razonamiento aumenta el tiempo de respuesta y el uso de tokens, pero puede mejorar la calidad de los trabajos complejos. Para obtener más información, consulta Modelos, Conceptos básicos de configuración y Referencia de configuración.

Orquestación y controles de hilos

ChatGPT o Codex gestiona la orquestación entre agentes, incluida la creación de nuevos subagentes, el envío de instrucciones de seguimiento, la espera de resultados y el cierre de hilos de agentes.

Cuando se ejecutan muchos agentes, Codex espera hasta que todos los resultados solicitados estén disponibles y luego devuelve una respuesta consolidada.

ChatGPT Work en la web

En la mayoría de los niveles de inteligencia, ChatGPT crea agentes tras una solicitud directa. Con Ultra, ChatGPT también puede delegar de forma proactiva cuando el trabajo en paralelo resulta útil.

Clientes locales de Codex

Las versiones locales actuales de Codex crean agentes tras una solicitud directa o una instrucción aplicable del proyecto o de una habilidad.

Para verlo en acción, prueba la siguiente instrucción en tu proyecto:

I would like to review the following points on the current PR (this branch vs main). Spawn one agent per point, wait for all of them, and summarize the result for each point.
1. Security issue
2. Code quality
3. Bugs
4. Race
5. Test flakiness
6. Maintainability of the code

Gestionar subagentes

ChatGPT Work en la web

Abre Subagentes para ver las listas de solo lectura Activos y Finalizados. Selecciona un subagente finalizado para inspeccionar sus detalles y su resultado. La barra lateral de la web muestra la actividad de los subagentes; no ofrece controles para detener u orientar a un subagente concreto.

Aplicación de escritorio de ChatGPT

• Abre un hilo de subagente desde la actividad que se muestra en el hilo principal para inspeccionar su trabajo.
• Pide directamente a Codex que oriente a un subagente en ejecución, que lo detenga o que cierre los hilos de subagentes finalizados.

Codex CLI

• Usa /agent en la CLI para cambiar entre los hilos de agentes activos e inspeccionar el hilo en curso.
• Pide directamente a Codex que oriente a un subagente en ejecución, que lo detenga o que cierre los hilos de agentes finalizados.

Extensión para IDE

• Cuando el panel de agentes en segundo plano esté disponible, expándelo para inspeccionar el estado, detener subagentes activos o abrir el hilo de un subagente.
• Pide directamente a Codex que oriente a un subagente en ejecución, que lo detenga o que cierre los hilos de agentes finalizados.

Controles de aprobación y entorno aislado

Clientes locales de Codex

Los subagentes heredan tu política actual de entorno aislado.

ChatGPT Work en la web

ChatGPT Work ejecuta los subagentes en su entorno alojado y no ofrece controles de entorno aislado local de Codex ni de modo de aprobación. Los subagentes usan las herramientas disponibles para el chat principal. Los permisos de sitios web y conectores siguen siendo específicos de cada herramienta.

Aplicación de escritorio de ChatGPT

Los subagentes heredan el modo de permisos seleccionado debajo del cuadro de redacción. Elige el modo de permisos para el turno principal antes de pedir a Codex que delegue trabajo.

Codex CLI

En sesiones interactivas de CLI, las solicitudes de aprobación pueden aparecer desde hilos de agentes inactivos incluso mientras consultas el hilo principal. La superposición de aprobación muestra la etiqueta del hilo de origen, y puedes presionar o para abrir ese hilo antes de aprobar, rechazar o responder a la solicitud.

En flujos no interactivos, o cuando una ejecución no puede mostrar una nueva solicitud de aprobación, una acción que necesita una nueva aprobación falla y Codex devuelve el error al flujo de trabajo principal.

Codex también vuelve a aplicar las sustituciones de configuración del entorno de ejecución en vivo del turno principal cuando crea un agente secundario. Esto incluye las opciones de entorno aislado y aprobación que estableciste de forma interactiva durante la sesión, como los cambios de /permissions o --yolo, incluso si el archivo del agente personalizado seleccionado establece valores predeterminados diferentes.

Extensión para IDE

Los subagentes heredan el modo de permisos seleccionado debajo del cuadro de redacción. Elige el modo de permisos para el turno principal antes de pedir a Codex que delegue trabajo.

También puedes sustituir la configuración del entorno aislado para agentes personalizados concretos, por ejemplo, marcar explícitamente uno para que trabaje en modo de solo lectura.

Agentes personalizados

Codex incluye agentes integrados:

• default: agente alternativo de propósito general.
• worker: agente centrado en la ejecución para implementaciones y correcciones.
• explorer: agente de exploración de bases de código con mucha lectura.

Para definir tus propios agentes personalizados, añade archivos TOML independientes en ~/.codex/agents/ para agentes personales o en .codex/agents/ para agentes del proyecto.

Cada archivo define un agente personalizado. Codex carga estos archivos como capas de configuración para las sesiones generadas, por lo que los agentes personalizados pueden sobrescribir los mismos ajustes que la configuración de una sesión normal de Codex. Esto puede resultar más complejo que un manifiesto de agente específico, y el formato puede evolucionar a medida que maduren la creación y el uso compartido.

Cada archivo independiente de agente personalizado debe definir:

• name
• description
• developer_instructions

Si un archivo de agente personalizado establece model o model_reasoning_effort, prevalece el valor del archivo. De lo contrario, Codex resuelve cada ajuste de forma independiente: un valor explícito al generar el agente, luego el valor predeterminado correspondiente de [agents] y, por último, el valor del agente principal. Si al generar un agente se selecciona un modelo diferente y no hay un esfuerzo explícito ni configurado, Codex usa el esfuerzo predeterminado de ese modelo. Otros ajustes de sesión, como sandbox_mode, mcp_servers y skills.config, se heredan del agente principal cuando el archivo del agente personalizado los omite.

Ajustes globales

Los ajustes globales de los subagentes siguen estando en [agents] dentro de tu configuración.

Notas:

• agents.enabled tiene como valor predeterminado true. Establécelo en false para desactivar las herramientas multiagente.
• Cuando dejas agents.max_concurrent_threads_per_session sin establecer, Codex elige el valor predeterminado. Las configuraciones existentes pueden seguir usando agents.max_threads como alias heredado.
• Los valores explícitos al generar el agente sobrescriben agents.default_subagent_model y agents.default_subagent_reasoning_effort.
• agents.interrupt_message tiene como valor predeterminado true. Establécelo en false para omitir del contexto del agente el mensaje de interrupción visible para el modelo.
• Si el nombre de un agente personalizado coincide con el de un agente integrado, como explorer, prevalece tu agente personalizado.

Esquema del archivo de agente personalizado

También puedes incluir otras claves config.toml compatibles en un archivo de agente personalizado, como model, model_reasoning_effort, sandbox_mode, mcp_servers y skills.config.

Codex identifica al agente personalizado mediante su campo name. Hacer coincidir el nombre del archivo con el nombre del agente es la convención más sencilla, pero el campo name es la fuente de verdad.

Ejemplos de agentes personalizados

Los mejores agentes personalizados son específicos y tienen criterios definidos. Asigna a cada uno una tarea clara, una superficie de herramientas que se corresponda con esa tarea e instrucciones que eviten que se desvíe hacia trabajos adyacentes.

Ejemplo 1: Revisión de PR

Este patrón divide la revisión entre tres agentes personalizados especializados:

• pr_explorer traza el mapa de la base de código y recopila evidencia.
• reviewer busca riesgos de corrección, seguridad y pruebas.
• docs_researcher consulta la documentación del framework o de la API mediante un servidor MCP dedicado.

Configuración del proyecto (.codex/config.toml):

[agents]
max_concurrent_threads_per_session = 8

.codex/agents/pr-explorer.toml:

name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes are proposed."
model = "gpt-5.3-codex-spark"
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 the parent agent asks for them.
Prefer fast search and targeted file reads over broad scans.
"""

.codex/agents/reviewer.toml:

name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
Lead with concrete findings, include reproduction steps when possible, and avoid style-only comments unless they hide a real bug.
"""

.codex/agents/docs-researcher.toml:

name = "docs_researcher"
description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."
model = "gpt-5.6-luna"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Use the docs MCP server to confirm APIs, options, and version-specific behavior.
Return concise answers with links or exact references when available.
Do not make code changes.
"""

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

Esta configuración funciona bien con instrucciones como:

Review this branch against main. Have pr_explorer map the affected code paths, reviewer find real risks, and docs_researcher verify the framework APIs that the patch relies on.

Ejemplo 2: Depuración de la integración del frontend

Este patrón resulta útil para regresiones de la interfaz de usuario, flujos inestables del navegador o errores de integración que afectan tanto al código de la aplicación como al producto en ejecución.

Configuración del proyecto (.codex/config.toml):

[agents]
max_concurrent_threads_per_session = 6

.codex/agents/code-mapper.toml:

name = "code_mapper"
description = "Read-only codebase explorer for locating the relevant frontend and backend code paths."
model = "gpt-5.6-luna"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Map the code that owns the failing UI flow.
Identify entry points, state transitions, and likely files before the worker starts editing.
"""

.codex/agents/browser-debugger.toml:

name = "browser_debugger"
description = "UI debugger that uses browser tooling to reproduce issues and capture evidence."
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
developer_instructions = """
Reproduce the issue in the browser, capture exact steps, and report what the UI actually does.
Use browser tooling for screenshots, console output, and network evidence.
Do not edit application code.
"""

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
startup_timeout_sec = 20

.codex/agents/ui-fixer.toml:

name = "ui_fixer"
description = "Implementation-focused agent for small, targeted fixes after the issue is understood."
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
developer_instructions = """
Own the fix once the issue is reproduced.
Make the smallest defensible change, keep unrelated files untouched, and validate only the behavior you changed.
"""

[[skills.config]]
path = "/Users/me/.agents/skills/docs-editor/SKILL.md"
enabled = false

Esta configuración funciona bien con instrucciones como:

Investigate why the settings modal fails to save. Have browser_debugger reproduce it, code_mapper trace the responsible code path, and ui_fixer implement the smallest fix once the failure mode is clear.