Subagentes
Usa subagentes en ChatGPT y Codex, y configura agentes personalizados de Codex
- Aplicación de escritorio de ChatGPT Proyectos, archivos y tareas más largas en el escritorio.
- ChatGPT web Chats, proyectos y Work en tu navegador.
- Codex CLI Codex en tu terminal.
- Extensión de Codex para IDE Codex en tu editor.
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 muestra los flujos de trabajo y la actividad de los subagentes a las cuentas que cumplen los requisitos.
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.
En ChatGPT Work, pide a ChatGPT que delegue tareas independientes 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, pide la delegación de forma explícita. Con Ultra, ChatGPT puede delegar tareas de forma proactiva cuando los agentes en paralelo mejoren considerablemente la velocidad o la calidad.
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.
Pide a Codex en una sesión interactiva de la CLI que utilice subagentes. Codex también puede seguir
las instrucciones aplicables de AGENTS.md o de habilidades que soliciten delegación. Utiliza
/subagents para inspeccionar los hilos de los agentes y alternar entre ellos mientras se ejecutan. El hilo
principal reúne los resultados de los subagentes en su respuesta final.
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
En la mayoría de los niveles de inteligencia, solicita subagentes o trabajo con agentes en paralelo directamente. Ultra permite la delegación proactiva, por lo que ChatGPT puede delegar tareas independientes adecuadas sin una solicitud adicional.
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.
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.
Si no configuras un modelo de subagente o model_reasoning_effort, el
subagente hereda el modelo y el esfuerzo de razonamiento del agente principal. Si una solicitud explícita
de creación o un valor predeterminado de [agents] selecciona un modelo sin un
esfuerzo de razonamiento explícito o configurado, el subagente usa el esfuerzo de razonamiento
predeterminado de ese modelo. Para equilibrar la inteligencia, la velocidad y el precio de cada tarea,
solicita un modelo o un esfuerzo de razonamiento específico en tu prompt,
configura los valores predeterminados de [agents] en config.toml, o establece model y
model_reasoning_effort directamente en el archivo del agente personalizado.
Por ejemplo, usa gpt-6-luna para exploraciones rápidas o una configuración de gpt-6.1-sol con mayor esfuerzo para razonamientos más exigentes.
Elección del modelo
gpt-6.1-sol: Empieza aquí para agentes con tareas exigentes. Úsalo para trabajos ambiguos de varios pasos que requieran planificación, uso de herramientas, validación y seguimiento en un contexto más amplio.gpt-6-luna: Úsalo para agentes rápidos con un alcance limitado que realicen tareas claras, repetibles o de gran volumen.
Esfuerzo de razonamiento (model_reasoning_effort)
Para GPT-6.1 Sol, usa un esfuerzo de razonamiento compatible con tu cliente y el modelo
seleccionado. Para configuraciones explícitas del modelo, empieza con high para GPT-6 Luna o low
para GPT-6 Astra. Ajústalo a la tarea con un nivel que admita el modelo seleccionado.
ultra: Úsalo para el razonamiento más profundo cuando el modelo seleccionado lo admita.maxyxhigh: Úsalos para razonamientos especialmente exigentes cuando el modelo seleccionado admita estos niveles.high: Úsalo cuando un agente necesite seguir una lógica compleja, comprobar supuestos o resolver casos límite (por ejemplo, agentes revisores o centrados en la seguridad).medium: Equilibra la velocidad y la profundidad.low: Úsalo cuando la tarea sea sencilla y la velocidad sea lo más importante.
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.
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.
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 codeGestionar subagentes
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.
- 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.
- Utiliza
/subagentsen la CLI para alternar entre los hilos de agentes activos e inspeccionar el hilo en curso. - Pide directamente a Codex que dé nuevas indicaciones a un subagente en ejecución, lo detenga o cierre los hilos de agentes completados.
- 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 dé nuevas indicaciones a un subagente en ejecución, lo detenga o cierre los hilos de subagentes completados.
Controles de aprobación y entorno aislado
Los subagentes heredan tu política actual de entorno aislado.
ChatGPT Work ejecuta subagentes en su entorno alojado y no ofrece un entorno aislado local de Codex ni un control del 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.
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.
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.
Los subagentes heredan los ajustes actuales de aislamiento y aprobación del turno del agente principal,
incluidos los cambios realizados con /permissions o --yolo. Un archivo de agente personalizado
no puede sustituir esos ajustes.
Los subagentes heredan el modo de permisos seleccionado debajo del cuadro de redacción. Elige el modo de permisos del turno principal antes de pedir a Codex que delegue tareas.
Configura los controles de aislamiento y aprobación en la sesión principal. Las instrucciones de los agentes personalizados pueden pedir a un agente que evite las modificaciones, pero no crean un entorno aislado independiente 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. Los agentes personalizados pueden cambiar la configuración del modelo y las instrucciones o desactivar las capacidades compatibles. Heredan los permisos, el proveedor y los MCP servers del agente principal; un archivo de agente personalizado no puede sobrescribir esa configuración.
Cada archivo independiente de agente personalizado debe definir:
namedescriptiondeveloper_instructions
Si un archivo de agente personalizado establece model o model_reasoning_effort, el valor del
archivo tiene prioridad. Antes de aplicar el archivo, Codex determina cada ajuste
a partir de un valor explícito de creación, después del valor predeterminado correspondiente de [agents] y, por último,
del valor del agente principal. Si una solicitud explícita de creación o un valor predeterminado de [agents]
selecciona un modelo y ninguno especifica un esfuerzo de razonamiento, Codex utiliza
el esfuerzo predeterminado de ese modelo. Un archivo de agente personalizado que solo establece model
conserva este esfuerzo determinado previamente. Establece también model_reasoning_effort en el
archivo si el modelo seleccionado no admite ese esfuerzo o si quieres
uno diferente. Las habilidades se heredan del agente principal, y un agente personalizado puede desactivar
habilidades individuales con skills.config.
Ajustes globales
Los ajustes globales de los subagentes siguen estando en [agents] dentro de tu configuración.
| Campo | Tipo | Obligatorio | Finalidad |
|---|---|---|---|
agents.enabled |
boolean | No | Activar o desactivar las herramientas multiagente. |
agents.max_concurrent_threads_per_session |
number | No | Limitar los hilos de agentes generados abiertos simultáneamente, sin contar el principal. |
agents.default_subagent_model |
string | No | Establecer el modelo predeterminado para los agentes generados. |
agents.default_subagent_reasoning_effort |
string | No | Establecer el esfuerzo de razonamiento predeterminado para los agentes generados. |
agents.interrupt_message |
boolean | No | Registrar un mensaje visible para el modelo cuando se interrumpe el turno de un agente. |
Notas:
agents.enabledtiene como valor predeterminadotrue. Establécelo enfalsepara desactivar las herramientas multiagente.- Cuando dejas
agents.max_concurrent_threads_per_sessionsin establecer, Codex elige el valor predeterminado. Las configuraciones existentes pueden seguir usandoagents.max_threadscomo alias heredado. - Los valores explícitos al generar el agente sobrescriben
agents.default_subagent_modelyagents.default_subagent_reasoning_effort. agents.interrupt_messagetiene como valor predeterminadotrue. Establécelo enfalsepara 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
| Campo | Tipo | Obligatorio | Finalidad |
|---|---|---|---|
name |
string | Sí | Nombre que Codex usa al generar este agente o hacer referencia a él. |
description |
string | Sí | Orientación para las personas sobre cuándo debe usar Codex este agente. |
developer_instructions |
string | Sí | Instrucciones principales que definen el comportamiento del agente. |
Usa model, model_reasoning_effort, model_reasoning_summary y
model_verbosity para personalizar el comportamiento del modelo.
Consulta la referencia de configuración para conocer sus
valores admitidos.
Para reducir las capacidades de un agente personalizado, establece las claves de funciones compatibles en false:
features.shell_tool, features.apps, features.plugins,
features.memories o features.request_permissions_tool. Desactiva habilidades
individuales con skills.config o las habilidades incluidas con
skills.bundled.enabled = false. Establece skills.include_instructions = false para
omitir el bloque automático de instrucciones de habilidades. Los requisitos administrados siguen siendo aplicables.
Otros ajustes de sesión, incluidos sandbox_mode, approval_policy,
model_provider y mcp_servers, no sobrescriben la configuración principal
cuando se incluyen en un archivo de agente personalizado. El nivel de servicio también sigue la preferencia de la sesión
raíz. Configura los MCP servers en la sesión principal para que el agente
pueda usarlos.
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.
Los ejemplos usan GPT-6.1 Sol cuando la cuenta con la que iniciaste sesión o tu espacio de trabajo tiene acceso. Si no está disponible, elige un modelo que puedas usar.
Ejemplo 1: Revisión de PR
Este patrón divide la revisión entre tres agentes personalizados especializados:
pr_explorertraza el mapa de la base de código y recopila evidencia.reviewerbusca riesgos de corrección, seguridad y pruebas.docs_researcherconsulta la documentación del framework o de la API mediante un MCP server dedicado.
Configuración del proyecto (.codex/config.toml):
[agents]
max_concurrent_threads_per_session = 8
[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp".codex/agents/pr-explorer.toml:
name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes are proposed."
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
Stay in exploration mode.
Do not edit files.
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-6.1-sol"
model_reasoning_effort = "medium"
developer_instructions = """
Review code like an owner.
Do not edit files.
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-6-luna"
model_reasoning_effort = "high"
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.
"""
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
[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
startup_timeout_sec = 20.codex/agents/code-mapper.toml:
name = "code_mapper"
description = "Read-only codebase explorer for locating the relevant frontend and backend code paths."
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
Map the code that owns the failing UI flow.
Do not edit files.
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-6.1-sol"
model_reasoning_effort = "medium"
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.
""".codex/agents/ui-fixer.toml:
name = "ui_fixer"
description = "Implementation-focused agent for small, targeted fixes after the issue is understood."
model = "gpt-6-luna"
model_reasoning_effort = "high"
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 = falseEsta 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.