Agente vs subagente en Claude Code: qué los diferencia

Un agente es el sistema que trabaja para ti: un modelo que decide, unas herramientas que ejecuta y un bucle que repite hasta terminar. Un subagente es un agente que otro agente lanza para delegarle una subtarea, con su propia ventana de contexto, y que solo le devuelve un resumen. En Claude Code, tu conversación principal es el agente, y los subagentes son los ayudantes a los que les pasa trabajo.

Para seguir el resto necesitas dos ideas. La primera es qué es un agente, que explico desde cero en qué es un agente de IA y en qué se diferencia de un chatbot. La segunda es la ventana de contexto: todo el texto que el modelo tiene delante en cada momento, es decir, tus mensajes, sus respuestas, los archivos que ha leído y la salida de cada comando que ha ejecutado. Tiene un tamaño limitado, y cuando se llena de ruido el modelo trabaja peor. Si quieres profundizar, lo cuento en ventana de contexto y buenas prácticas.

Agente vs subagente, lado a lado

	Agente (tu conversación principal)	Subagente
Qué es	El sistema con el que hablas: modelo, herramientas, bucle y condición de parada	Un agente que el principal lanza para una tarea concreta
Quién lo pone en marcha	Tú, al abrir Claude Code	El agente principal, porque la tarea encaja con la descripción del subagente o porque tú se lo pides
Qué ve al empezar	Toda tu conversación	Una ventana nueva con el encargo que le escribe Claude, su propio system prompt y tus CLAUDE.md. Tu historial no
Qué devuelve	Respuestas y cambios, turno a turno	Un resumen final al agente principal
Herramientas	Las de tu sesión	Las que le permitas en su definición (si no limitas nada, hereda las disponibles)
De dónde sale	Viene de serie	Integrados (Explore, Plan, general-purpose) o un archivo Markdown tuyo en .claude/agents/

La fila que importa es la de qué ve al empezar. Piensa en pedirle a un compañero que se lea cuarenta archivos de log y te diga solo qué test ha fallado. No quieres los cuarenta archivos encima de tu mesa, quieres la conclusión. Pero tu compañero tampoco estaba en la reunión de esta mañana, así que solo sabe lo que le cuentes en el encargo.

Ese intercambio es todo el mecanismo: ganas una conversación principal limpia y pagas con un ayudante que empieza sin saber nada de lo que habéis hablado.

Qué es un subagente en Claude Code

Un subagente de Claude Code (subagent, en la documentación en inglés) es un asistente especializado que trabaja en su propia ventana de contexto, con su propio system prompt (las instrucciones fijas que definen su papel), sus propias herramientas y sus propios permisos ^[1]. Claude lee la descripción de cada subagente disponible y, cuando una tarea encaja, se la delega. El subagente hace el trabajo por su cuenta y devuelve el resultado.

Si usas Claude Code, seguramente ya has visto alguno trabajar sin pedirlo, porque trae varios integrados y Claude recurre a ellos cuando lo ve oportuno ^[1]:

• Explore y Plan son de solo lectura. Explore busca y entiende código sin tocar nada; Plan hace esa misma investigación cuando estás en modo plan, el modo en el que Claude estudia el código y te propone un plan antes de cambiar nada.
• general-purpose es para tareas de varios pasos que necesitan explorar y además modificar archivos.

Y luego están los tuyos.

Ejemplo: un subagente propio, en un archivo

Un subagente personalizado es un archivo Markdown con una cabecera en YAML. Si lo guardas en .claude/agents/ dentro del proyecto, lo puedes subir al repositorio y lo usa todo el equipo; si lo guardas en ~/.claude/agents/, lo tienes en todos tus proyectos ^[1]. Este revisa los tests y no puede arreglar nada:

---
name: test-runner
description: Ejecuta los tests y resume solo los que fallan. Úsalo después de cambiar código.
tools: Read, Grep, Glob, Bash
model: haiku
---

Ejecuta la suite de tests del proyecto. Devuelve solo los tests que fallan,
con su mensaje de error y el archivo afectado. No intentes arreglar nada.

Línea a línea: name es su identificador y description le dice a Claude cuándo delegar en él. Son los dos únicos campos obligatorios ^[1]. tools es la lista de herramientas que puede usar; si la omites, hereda todas las disponibles. model elige el modelo con el que trabaja, y aquí uno más barato basta para leer la salida de unos tests. El texto de debajo de la cabecera es su system prompt.

Fíjate en la diferencia entre la última frase del prompt y la línea tools. “No intentes arreglar nada” es una petición que el modelo casi siempre respetará. La lista de herramientas es un límite: sin Edit ni Write, aunque quisiera editar un archivo no tendría con qué.

Para usarlo, Claude puede delegar en él solo, o se lo pides tú: basta con nombrarlo (“usa el subagente test-runner para revisar los tests”) o mencionarlo con @ (eligiéndolo en la lista que aparece, o escribiendo @agent-test-runner), que garantiza que se ejecute ese subagente y no otro ^[1]. Si lees tutoriales antiguos que hablan de la herramienta Task, es la misma: en la versión 2.1.63 pasó a llamarse Agent, y las referencias antiguas siguen funcionando como alias ^[1].

Cuándo usar un subagente y cuándo quedarte en la conversación principal

Un subagente compensa cuando el trabajo genera mucho ruido y a ti solo te interesa la conclusión. La documentación oficial lo resume en tres casos: salida voluminosa que no necesitas en tu contexto, herramientas o permisos que quieres restringir, y trabajo autocontenido que cabe en un resumen ^[1]. Llevado a ejemplos concretos:

Situación	Mejor opción
Ejecutar los tests y quedarte solo con los que fallan	Un subagente: la salida es larga y te basta con el resumen
Investigar varios módulos que no dependen entre sí	Varios subagentes en paralelo, uno por módulo
Una revisión de código que no debe poder tocar archivos	Un subagente con tools de solo lectura
Iterar un diseño contigo, con muchas idas y vueltas	La conversación principal
Un cambio pequeño en un archivo que ya estáis mirando	La conversación principal. Un subagente empieza de cero y tardaría en ponerse al día
Un procedimiento que repites y que debe ver tu conversación	Una skill, que se carga en la conversación principal en vez de aislarse

El precio de delegar está en el traspaso. Como el subagente no ve tu historial, lo único que sabe de la tarea es el mensaje que le escribe Claude al delegar. Tus CLAUDE.md sí le llegan, pero lo que hayáis acordado en la conversación no: si le dijiste a Claude hace veinte mensajes que no tocara la carpeta vendor/, repíteselo al pedirle que delegue, porque el subagente nunca lo leyó. Y hay un segundo coste que se olvida: cada subagente gasta sus propios tokens (los fragmentos de texto que el modelo lee y escribe, y con los que se mide el uso), y todos esos resultados vuelven a tu conversación principal, así que lanzar muchos que devuelvan informes largos acaba llenando justo la ventana que querías proteger ^[1].

Cuándo compensa de verdad repartir una tarea entre varios agentes en paralelo, y cuándo acaban tomando decisiones que chocan entre sí, es un debate con datos en los dos bandos que analizo en context engineering.

Delegar en un subagente es un caso concreto de un patrón más general: un agente que coordina y reparte trabajo entre otros especializados. Ese patrón, y los que lo rodean, los trabajo con ejercicios en el curso Patrones de Diseño para Agentes de IA.

Mi regla práctica es sencilla: si la respuesta que necesito cabe en un párrafo pero el trabajo para conseguirla llena pantallas de salida, se lo paso a un subagente. Si voy a tener que corregirle el rumbo cada dos mensajes, me lo quedo yo en la conversación principal.

Fuentes

1. Create custom subagents, documentación oficial de Claude Code (Anthropic): definición de subagente, contexto aislado al arrancar, subagentes integrados, formato de archivo y campos, formas de invocarlos, cuándo usar subagentes o la conversación principal, anidamiento y renombrado de Task a Agent.

Preguntas Frecuentes

¿Qué diferencia hay entre un agente y un subagente?

Un agente es el sistema completo que trabaja para ti: un modelo de lenguaje que decide qué hacer, unas herramientas para hacerlo, un bucle que repite y una condición de parada que le dice cuándo ha terminado. Un subagente es un agente que otro agente lanza para delegarle una parte del trabajo. Arranca con su propia ventana de contexto, sin ver la conversación de quien lo lanzó, y al terminar solo devuelve un resumen del resultado.

¿Un subagente de Claude Code ve lo que he hablado en la conversación?

No. Un subagente normal empieza con un contexto nuevo: recibe el encargo que le escribe Claude, su propio system prompt y, salvo Explore y Plan, tus archivos CLAUDE.md, pero no tu historial ni los archivos que Claude ya ha leído. La excepción es el fork, un tipo de subagente que hereda la conversación completa precisamente para no tener que explicarle nada.

¿Un subagente puede lanzar sus propios subagentes?

Sí, en las versiones actuales de Claude Code, hasta tres niveles por debajo de la conversación principal por defecto, y el límite se cambia con la variable de entorno CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH. Este comportamiento ha cambiado varias veces entre versiones, así que si depende de él, compruébalo en la documentación de la versión que usas.

¿Qué diferencia hay entre un subagente y una skill?

Una skill es un conjunto de instrucciones reutilizables que se carga dentro de tu conversación principal y trabaja con todo lo que ya hay en ella. Un subagente trabaja aparte, en su propia ventana de contexto, y solo te devuelve el resultado. Si quieres que el procedimiento vea lo que estás haciendo, usa una skill; si quieres que el ruido del trabajo se quede fuera, un subagente.

¿Usar subagentes (o sub-agentes) gasta más?

Cada subagente hace sus propias peticiones al modelo, y esas peticiones cuentan contra los mismos límites de uso que tu conversación principal. Lo que ganas es una conversación principal más limpia, no un trabajo gratis.