Subagentes: un agente que trabaja aparte y te devuelve solo el resultado
Un subagente es un asistente con su propia ventana de contexto: atiende una tarea y devuelve solo el resultado. Cómo se define, qué ve y cuándo usarlo.
¿Por qué existen?
Un agente que hace todo en una sola ventana de contexto acumula material: archivos leídos, comandos ejecutados, resultados intermedios. Cuando la sesión es larga, esa acumulación empieza a ocupar espacio que hace falta para razonar. Cada herramienta que se ejecuta agrega su resultado al contexto, y ese contexto se mide en tokens. Cuando se acerca al límite, el agente tiene que resumir lo anterior y puede perder detalles.
Un subagente resuelve esa presión. Anthropic lo describe así: los subagentes usan ventanas de contexto aisladas y le envían al orquestador solo la información relevante. La tarea de explorar cincuenta archivos ocurre en su contexto. Al principal regresa un párrafo con la conclusión. El resto se queda donde nació. Es el mismo principio que una persona aplica al delegar una investigación: quien investiga lee mucho, quien decide recibe el resumen.
¿Cómo se define?
En Claude Code, un subagente es un archivo Markdown con frontmatter YAML. El frontmatter tiene la configuración y el cuerpo es su system prompt:
---
name: revisor-de-accesibilidad
description: Revisa pantallas contra la guía de accesibilidad. Úsalo cuando se pida revisar contraste, foco o etiquetas.
tools: Read, Glob, Grep
model: sonnet
---
Eres un revisor de accesibilidad. Lee la pantalla indicada y devuelve
una lista de hallazgos con severidad y criterio WCAG.
Los campos principales son name y description, que son obligatorios. La descripción es la pista que usa el agente principal para decidir cuándo delegar. tools limita qué herramientas puede usar, y model elige el modelo. Los archivos pueden vivir en el proyecto (.claude/agents/) o en el perfil del usuario.
¿Qué ve y qué devuelve?
Según la documentación de Claude Code, cada subagente “runs in its own context window with a custom system prompt, specific tool access, and independent permissions”: corre en su propia ventana de contexto, con un system prompt a medida, acceso específico a herramientas y permisos independientes. No ve el historial del principal ni lo que este ya leyó. Lo que sabe es lo que está en su system prompt y en el mensaje con el que se le delegó la tarea, más detalles básicos del entorno. Por eso ese mensaje tiene que ser autosuficiente: si falta un dato, el subagente no tiene cómo adivinarlo.
Al terminar, devuelve su mensaje final al principal, no sus llamadas a herramientas ni su razonamiento intermedio. Por dentro, el subagente ejecuta su propio loop de agente: piensa, usa una herramienta, observa y repite hasta terminar. Si el subagente explora mucho, el principal solo recibe la conclusión. Un subagente también puede correr en segundo plano: el principal sigue trabajando y recibe el resultado cuando termina. Claude Code además trae subagentes integrados, como Explore, pensado para buscar y analizar código sin modificarlo.
¿Por qué le importa a un diseñador?
Porque la delegación cambia cómo se organiza un flujo de trabajo, y eso tiene consecuencias de diseño. Un equipo puede separar responsabilidades: un subagente revisa accesibilidad, otro revisa tokens, otro redacta microcopy, y el agente principal integra los resultados. Cada uno tiene permisos y criterios propios, y es más fácil revisar qué hizo cada uno.
El mismo cuidado que aplicas a las interfaces de agente aplica aquí: cada subagente debe tener un nombre claro, una descripción que diga cuándo usarlo y solo las herramientas que necesita.
¿Cuándo NO conviene?
- Cuando la tarea es corta y se resuelve en dos o tres pasos. El costo de delegar supera el beneficio.
- Cuando el subagente necesita casi todo el historial del principal. Al no verlo, puede trabajar con información incompleta.
- Cuando el resultado intermedio es necesario para decidir en el momento. Esperar al resumen agrega latencia.
- Cuando cada subagente tiene permisos amplios sin revisión. Más agentes con más permisos aumentan el riesgo.
Ejemplo
Ejemplo ilustrativo: un equipo quiere saber qué componentes del sistema usan colores fuera de los tokens. Hacerlo en la sesión principal llenaría el contexto con decenas de archivos. El agente principal delega en un subagente de solo lectura, con herramientas Read, Glob y Grep. El subagente recorre la biblioteca y devuelve una tabla de nueve componentes con el archivo y la línea. La sesión principal sigue limpia, y el equipo corrige los nueve casos en la siguiente tarea.
¿Qué permisos debe tener un subagente?
Un subagente hereda la idea de permisos independientes, y eso es útil: puedes darle solo lectura para explorar y dejar la escritura al agente principal, con revisión. Según la documentación, el campo tools limita las herramientas disponibles y disallowedTools funciona como lista de denegación (todo lo que no esté en esa lista queda permitido). El principio de mínimo privilegio aplica como en cualquier sistema: un subagente que explora no necesita editar, y uno que redacta no necesita ejecutar comandos. Al delegar, escribe en el mensaje qué debe devolver y en qué formato, para que el resultado sea fácil de revisar y de comparar con otros.
Qué puedes hacer mañana
Escribe el mensaje de delegación de tu próxima tarea larga antes de lanzarla. Incluye tres cosas: qué debe investigar, qué debe devolver y en qué formato. Si no puedes escribirlo en tres líneas, la tarea todavía no está lista para delegar. Cuando el subagente devuelva el resultado, compara una muestra con lo que tú revisas a mano. Si coinciden en la muestra, confía en el resto con un poco más de tranquilidad.
Errores comunes
- Dar a cada subagente todas las herramientas. Limita a lo que necesita.
- Escribir descripciones vagas que impiden que el principal sepa cuándo delegar.
- Esperar que el subagente conozca decisiones tomadas en la sesión principal. No las ve.
- Usar subagentes para todo. Multiplican la coordinación.
- No revisar el resultado del subagente antes de actuar sobre él.