Cómo funcionan los subagentes
Cuando el agente crea un subagente, selecciona uno de los perfiles de subagente disponibles y elige si el subagente debe ejecutarse en primer plano o en segundo plano. Los subagentes pueden ejecutarse en dos modos:Primer plano
Se ejecuta directamente en tu sesión. El agente principal se pausa y espera a que el subagente termine antes de continuar. Puedes aprobar o rechazar llamadas a herramientas a medida que aparecen.
Segundo plano
Se ejecuta en paralelo mientras el agente principal sigue trabajando. El agente principal recibe una notificación automáticamente cuando el subagente termina. Las herramientas no aprobadas se rechazan automáticamente.
No ves directamente la salida en bruto del subagente. Cuando un subagente termina, el agente principal lee el resultado y resume los hallazgos clave y las acciones para ti.
Costo de los subagentes
Los subagentes se ejecutan como sus propias sesiones de agente, cada una con su propia ventana de contexto y llamadas de inferencia, por lo que generan costos de forma independiente del agente principal. El gasto del agente principal cubre su propio trabajo; cada subagente que crea agrega su propio consumo además de eso.En los planes basados en prompts, cada subagente consume créditos adicionales, igual que un mensaje de usuario. La cantidad de créditos depende del modelo que utilice el subagente, por lo que las tareas que generan múltiples subagentes (o los anidan) consumen más créditos.
¿Qué modelo usa un subagente?
No todos los subagentes se ejecutan con el modelo que elegiste en el selector de modelos. Cada perfil determina de dónde obtiene su modelo:
El modelo predeterminado del subagente no es un nombre de modelo fijo: se resuelve mediante un router del lado del servidor al crearse, y un Admin puede aplicar una anulación (consulta más abajo). Con la configuración predeterminada del router de subagentes, el router elige el primer modelo apto de una lista ordenada, por lo que el modelo resultante puede variar según el nivel de tu plan, la disponibilidad de modelos y la política de modelos de tu organización. La lista de enrutamiento puede cambiar con el tiempo, así que no des por sentado que un subagente siempre usará un modelo concreto.
Actualmente, la CLI no indica qué modelo está usando un subagente en ejecución en el panel de subagentes.
Cómo influir en el modelo
No hay forma de indicar un modelo para un subagente en un prompt: la herramientarun_subagent acepta un perfil, no un modelo. Tienes tres opciones:
-
Pide un perfil en lenguaje natural. Pedir un subagente de exploración (“investiga cómo funciona la autenticación en un subagente de exploración”) mantiene el trabajo en el modelo predeterminado del subagente en lugar del modelo que hayas seleccionado. Pedir cambios de código hace que se use
subagent_general, que se ejecuta con el modelo que hayas seleccionado. -
Fija un modelo en el perfil de un subagente personalizado.
model:en el archivo de definición es la única forma de ejecutar un subagente con capacidad de escritura en un modelo distinto al del agente principal. Una skill que se ejecute en un subagente también puede establecermodel:en su frontmatter para reemplazar el modelo del perfil. -
Establece tu propio modelo predeterminado del subagente.
agent.subagent_modelen tu archivo de configuración reemplaza el modelo predeterminado del subagente en tus sesiones. Tiene prioridad tanto sobre el router de subagentes como sobre cualquier modelo que un admin haya fijado como predeterminado del equipo, pero no vuelve a habilitar los subagentes si la configuración del admin es None:Se aplica asubagent_explorey a los subagentes personalizados que no fijen unmodel:;subagent_generalsigue usando el modelo del agente principal. El modelo debe estar permitido por tu organización; de lo contrario, la configuración se ignora y se usa el predeterminado del equipo. El cambio se aplica a las sesiones nuevas.
Controles de Enterprise
Los administradores pueden controlar qué modelo usan los subagentes —y si pueden ejecutarse o no— mediante la configuración Modelo predeterminado del subagente en Settings de org/Enterprise. Esta configuración controla el modelo desubagent_explore y de los subagentes personalizados que no fijan un model:; no cambia subagent_general, que siempre sigue el modelo del agente principal.

Activar y desactivar subagentes
Los subagentes están activados de forma predeterminada. Configurasubagents_enabled como false en tu archivo de configuración para eliminar las herramientas run_subagent y read_subagent y que el agente haga todo por sí mismo:
La política de la organización tiene prioridad: si un Admin ha configurado modelo predeterminado del subagente como None, los subagentes permanecerán deshabilitados independientemente de lo que indique esta configuración.
Perfiles de subagente
Cada subagente se ejecuta con un perfil específico que determina sus capacidades. Hay dos perfiles predefinidos:El agente elige automáticamente el perfil adecuado según la tarea. Los subagentes de exploración son ideales para investigar y comprender, mientras que los subagentes generales pueden realizar cambios. Consulta ¿Qué modelo usa un subagente? para ver cómo cada perfil elige su modelo: los dos perfiles no se ejecutan con el mismo modelo.
Permisos de herramientas
El funcionamiento de los permisos de herramientas depende de si el subagente se ejecuta en primer plano o en segundo plano:- Los subagentes en primer plano se comportan como el agente principal: se te pedirá que apruebes o rechaces las llamadas a herramientas, como de costumbre. El mensaje indica el nombre del subagente que solicitó la acción, para que sepas quién la solicita.
- Los subagentes en segundo plano heredan los permisos de herramientas que ya hayas concedido durante la sesión actual. Cualquier herramienta que no se haya aprobado previamente se rechaza automáticamente. Los subagentes en segundo plano no pueden solicitarte permisos nuevos.
Supervisión de subagentes
Indicador de subagente
Cuando hay subagentes en segundo plano en ejecución, aparece un indicador debajo del área de entrada que muestra su estado. Puede ir al indicador pulsando ↓ desde el área de entrada y, a continuación, pulsar Enter para abrir el panel de subagentes. Cuando hay un subagente en primer plano en ejecución, el indicador giratorio muestra “Subagente en ejecución · Ctrl+B para ejecutar en segundo plano”.Panel de subagentes
El panel de subagentes te permite ver y gestionar todos los subagentes activos y finalizados. Muestra el perfil, el título, el estado, el tiempo transcurrido y el número de llamadas a herramientas de cada subagente. La actividad de los subagentes se conserva al recargar la sesión, por lo que el panel sigue mostrando tus subagentes después de reanudarla.Cambio entre primer plano y segundo plano
Puedes mover subagentes entre primer plano y segundo plano mientras se ejecutan:- Pasar un subagente en primer plano a segundo plano: Pulsa Ctrl+B mientras se está ejecutando un subagente en primer plano. El subagente seguirá trabajando en segundo plano y el agente principal se reanudará.
- Pasar un subagente en segundo plano a primer plano: Abre el panel de subagentes y pulsa f sobre un subagente en segundo plano que esté en ejecución. La salida del subagente se mostrará en línea.
Cuando mueves un subagente a segundo plano, la llamada a la herramienta del agente principal ya habrá finalizado, por lo que el agente principal continúa de forma independiente. El resultado del subagente no volverá a incorporarse al pipeline actual del agente principal, pero recibirás una notificación cuando termine.
Interrumpir un turno
Interrumpir al agente no finaliza sus subagentes. Los subagentes en ejecución quedan en pausa y conservan su estado; se reanudan con tu siguiente mensaje. Así, una interrupción para redirigir al agente principal no descarta el trabajo en curso.Cancelar subagentes
Puedes cancelar un subagente en ejecución de dos formas:- Desde el panel de subagentes: Abre el panel y pulsa x sobre un subagente en ejecución.
- Subagente en primer plano: Pulsa Ctrl+C con la entrada vacía, o Esc dos veces, para cancelar el subagente en primer plano que se está ejecutando en ese momento. Si el borrador contiene texto, Ctrl+C primero lo borra.
Reanudar subagentes
Los subagentes cancelados, que fallaron o que ya se completaron pueden reanudarse con un nuevo prompt. Puedes pedirle al agente que reanude un subagente, y continuará donde lo dejó. Los subagentes reanudados siempre se ejecutan en primer plano, por lo que puedes aprobar cualquier llamada a herramientas que se haya denegado anteriormente. Esto es especialmente útil cuando:- Un subagente en segundo plano falló porque se denegó una herramienta necesaria; reanúdalo en primer plano para conceder los permisos necesarios.
- Un subagente se completó, pero quieres que haga trabajo de seguimiento adicional en función de sus hallazgos.
- Un subagente se canceló antes de tiempo y quieres que continúe.
Profundidad de anidación
De forma predeterminada, los subagentes no pueden crear sus propios subagentes; solo el agente raíz puede hacerlo. Las herramientas de subagentes (run_subagent y read_subagent) están deshabilitadas dentro de un subagente para evitar una anidación sin límites.
Sin embargo, los perfiles personalizados de subagentes pueden habilitar la creación anidada configurando el campo max-nesting en su frontmatter. Este valor reemplaza la profundidad máxima predeterminada y permite que los subagentes creen subagentes secundarios siempre que el árbol se mantenga dentro de ese límite.
Por ejemplo, max-nesting: 3 permite la siguiente cadena:
Subagentes personalizados
Además de los perfiles predefinidossubagent_explore y subagent_general, puedes definir tus propios perfiles de subagentes personalizados. Los subagentes personalizados te permiten crear subagentes especializados con sus propios prompts de sistema, restricciones de herramientas y anulaciones del modelo, adaptados a tareas específicas de tu flujo de trabajo. Esta también es la forma de obtener un subagente con capacidad de escritura que no se ejecute en tu modelo principal (posiblemente costoso): asígnale un model: y las herramientas que necesite.
Crear un subagente personalizado
Los subagentes personalizados se definen como archivos Markdown enagents/, con cualquiera de estas estructuras:
- Archivo plano —
agents/<name>.md(la misma convención que usan Claude Code, Cursor y otras herramientas). El nombre del archivo (sin.md) pasa a ser el identificador del perfil. - Directorio —
agents/<name>/AGENT.md. El nombre del directorio pasa a ser el identificador del perfil.AGENTS.md,agent.mdyagents.mdtambién se aceptan como nombre de archivo (si hay varios presentes,AGENT.mdtiene prioridad, seguido deAGENTS.md,agent.mdyagents.md).
name: en el frontmatter anula el identificador derivado de la ruta.
- Específico del proyecto
- Global
Formato del archivo de definición
Un archivo de definición de subagente usa el mismo frontmatter YAML que las skills, seguido del prompt del sistema del subagente:Campos del frontmatter
Cómo se usan los subagentes personalizados
Una vez definidos, los perfiles de subagentes personalizados aparecen junto a los predefinidos. El agente ve una descripción de cada perfil disponible y elige el más adecuado al crear un subagente. También puedes pedirle al agente que use un perfil específico por su nombre (p. ej., “revisa este código con el subagente revisor”). Los perfiles de subagentes personalizados que entren en conflicto con el nombre de un perfil predefinido (p. ej.,subagent_explore, subagent_general) se omiten y se muestra una advertencia.

