Saltar al contenido principal
Los subagentes permiten que el agente principal cree trabajadores independientes para encargarse de subtareas. Un subagente comparte herramientas y el contexto de la base de código con el agente principal, pero opera en su propia cadena de conversación — no hereda el historial de conversación del agente principal. Esto resulta útil para tareas que se benefician de un trabajo específico e independiente — como explorar una base de código, ejecutar pruebas o implementar una funcionalidad en paralelo. Puedes pedirle al agente que use subagentes de forma explícita (p. ej., “investiga cómo funciona la autenticación en un subagente”), o el agente puede decidir delegar por su cuenta cuando determine que una tarea se beneficiaría de un trabajo independiente. Según nuestras mediciones, los subagentes mejoran el rendimiento general de programación y reducen el costo.

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.
Como el costo aumenta con la cantidad de subagentes, las tareas que se distribuyen entre muchos subagentes (o los anidan) cuestan más. Usa subagentes de forma deliberada cuando el paralelismo o un contexto más enfocado justifiquen el gasto adicional.

¿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:
subagent_general hereda el modelo del agente principal. Si estás ejecutando un modelo prémium, cada subagente general también se ejecuta en ese modelo prémium, con su propia ventana de contexto y sus propias llamadas de inferencia; por lo tanto, una tarea que se reparte entre varios subagentes generales multiplica tu gasto. Pide un subagente de exploración (o un subagente personalizado con un model: más económico fijado) cuando el trabajo sea de investigación y no de cambios de código.
El modelo predeterminado del subagente no es un nombre de modelo fijo: se resuelve mediante un router al crearse, y un Admin puede aplicar una anulación (consulta más abajo). Con la configuración predeterminada del router de subagentes, se resuelve como SWE-1.6 (una variante más rápida o más lenta de SWE-1.6 según el nivel de tu plan).
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 herramienta run_subagent acepta un perfil, no un modelo. Tienes dos opciones:
  1. 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 más barato para subagentes. Pedir cambios de código hace que se use subagent_general, que se ejecuta con el modelo que hayas seleccionado.
  2. Fija un modelo en el perfil de un subagente personalizado. model: en AGENT.md 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 establecer model: en su frontmatter para reemplazar el modelo del perfil.

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 de subagent_explore y de los subagentes personalizados que no fijan un model:; no cambia subagent_general, que siempre sigue el modelo del agente principal.
Configuración del modelo de subagente predeterminado
Tiene tres opciones:

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.
También puedes definir tus propios perfiles de subagente personalizados; consulta Subagentes personalizados más abajo.

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.
  • 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.
Si un subagente en segundo plano falla porque se rechazó una herramienta necesaria, puedes reanudarlo en primer plano para aprobar los permisos necesarios. Consulta Reanudar subagentes más abajo.

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.

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.

Cancelar subagentes

Puedes cancelar un subagente en ejecución de dos formas:
  1. Desde el panel de subagentes: Abre el panel y pulsa x sobre un subagente en ejecución.
  2. Subagente en primer plano: Pulsa Ctrl+C o Esc para cancelar el subagente en primer plano que se está ejecutando en ese momento.

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:
Los subagentes anidados pueden incrementar significativamente el costo. Cada nivel de anidamiento genera agentes adicionales con sus propias ventanas de contexto y llamadas de inferencia. Use esta función con criterio.

Subagentes personalizados

Los subagentes personalizados son experimentales. El formato, el comportamiento y las opciones de configuración pueden cambiar en versiones futuras.
Además de los perfiles predefinidos subagent_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, anulaciones del modelo y permisos, 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 AGENT.md en un directorio con nombre propio dentro de agents/. El nombre del directorio pasa a ser el identificador del perfil.
También se admite:

Formato de AGENT.md

Un archivo AGENT.md 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.

Importación desde otras herramientas

Los subagentes personalizados también se pueden importar desde el formato de agente de Claude Code:
Los archivos de agente de Claude Code usan tools en lugar de allowed-tools en el frontmatter. Ambos formatos se admiten automáticamente.

Ejemplos

Agente de investigación de solo lectura

Agente de ejecución de pruebas