Agentes, Subagentes y Agent Teams en Claude Code
La confusión que frena a los equipos
Cuando los desarrolladores empiezan a explorar Claude Code en serio, aparece rápidamente una pregunta que parece simple pero no lo es: ¿qué diferencia hay entre un agente, un subagente y un Agent Team? Los tres conceptos conviven en la documentación, en los foros y en las conversaciones técnicas, pero rara vez se explican en conjunto y con ejemplos concretos.
Entender esta distinción no es un detalle académico. Es lo que separa un uso básico de Claude Code —donde todo el trabajo recae en una única sesión lineal— de un uso avanzado donde las tareas se distribuyen, paralelizan y especializan para lograr resultados imposibles de conseguir con un solo hilo de ejecución.
¿Qué es un Agente en Claude Code?
En el contexto de Claude Code, un agente es cualquier instancia del modelo que opera con autonomía: recibe un objetivo, puede usar herramientas (leer archivos, ejecutar comandos, buscar en la web, llamar a APIs) y toma decisiones iterativas hasta completar la tarea o pedir intervención humana.
Cuando abres Claude Code y describes una tarea como "refactoriza este módulo para que use el patrón repositorio", estás activando el agente principal. Él decide qué herramientas invocar, en qué orden, y cuándo ha terminado. Esta autonomía es la esencia del concepto.
Lo que distingue a Claude Code de un chatbot convencional es precisamente esta capacidad de agencia: el modelo no solo responde, sino que actúa. Puede modificar ficheros, ejecutar tests, corregir errores en tiempo real y entregar un resultado completo sin que tengas que guiar cada paso.
El agente principal y su ciclo de trabajo
El agente principal de Claude Code sigue un bucle interno:
- Observa el estado actual (archivos, contexto, instrucciones)
- Razona sobre qué acción ejecutar a continuación
- Actúa invocando una herramienta
- Evalúa el resultado y decide si continuar o terminar
Este ciclo puede repetirse decenas de veces en una sola tarea. Y aquí es donde aparece la necesidad de los subagentes.
Subagentes: Delegar para Escalar
Un subagente es una instancia secundaria del modelo lanzada por el agente principal para resolver una subtarea de forma independiente. En la práctica, Claude Code los crea usando la herramienta Agent disponible en su conjunto de herramientas nativas.
La idea central es esta: en lugar de que el agente principal haga todo de forma secuencial, delega partes del trabajo a subagentes que pueden ejecutarse en paralelo o en contextos aislados.
// Así es como el agente principal lanza un subagente (Claude Agent SDK)
{
"type": "tool_use",
"name": "Agent",
"input": {
"description": "Analiza el rendimiento del módulo de autenticación",
"prompt": "Lee los archivos src/auth/*.ts y genera un informe con los cuellos de botella de rendimiento. Devuelve solo el informe, sin modificar nada.",
"subagent_type": "general-purpose"
}
}
El subagente tiene su propio contexto, sus propias herramientas y trabaja de forma encapsulada. El agente principal recibe el resultado cuando termina y continúa con su lógica.
¿Cuándo lanzar un subagente?
Los subagentes son especialmente útiles cuando:
- La búsqueda es abierta: necesitas explorar múltiples rutas antes de saber cuál es la correcta. En lugar de contaminar el contexto principal, el subagente explora y resume.
- El trabajo es paralelo: tienes cuatro módulos independientes que analizar. Lanzas cuatro subagentes en paralelo y obtienes los cuatro resultados al mismo tiempo.
- El contexto debe protegerse: una operación larga podría llenar el contexto del agente principal. El subagente trabaja en su propio espacio y entrega solo el resultado relevante.
- La especialización importa: puedes configurar subagentes con tipos específicos (
Explore,Plan,claude-code-guide) que tienen capacidades distintas.
// Subagentes en paralelo: el agente lanza los dos a la vez
// Mensaje único con múltiples tool_use de tipo Agent
[
{
"name": "Agent",
"input": {
"description": "Auditoría de accesibilidad",
"prompt": "Revisa src/components/**/*.tsx buscando problemas de accesibilidad WCAG 2.1 AA",
"subagent_type": "Explore"
}
},
{
"name": "Agent",
"input": {
"description": "Auditoría de rendimiento",
"prompt": "Revisa src/components/**/*.tsx buscando re-renders innecesarios y optimizaciones posibles",
"subagent_type": "Explore"
}
}
]
La clave del paralelismo: ambos subagentes se ejecutan simultáneamente. El tiempo total es el del más lento, no la suma de ambos.
Agent Teams: Coordinación Estructurada a Gran Escala
Un Agent Team es un paso más allá: no es simplemente lanzar varios subagentes de forma puntual, sino diseñar un sistema de agentes con roles definidos, flujo de trabajo estructurado y división de responsabilidades estable.
En un Agent Team, cada agente tiene:
- Un rol fijo (orquestador, investigador, escritor, revisor, validador...)
- Un conjunto de herramientas adecuado a ese rol
- Un protocolo de comunicación con los otros agentes del equipo
Mientras que un agente con subagentes es una relación dinámica y ad-hoc (el agente decide en tiempo de ejecución si lanza o no subagentes), un Agent Team es una arquitectura prediseñada donde la distribución de trabajo está planificada desde el principio.
Ejemplo real: pipeline de publicación de contenido
En uno de nuestros proyectos de integración IA, usamos un Agent Team para automatizar la generación y publicación de contenido técnico:
| Agente | Rol | Herramientas |
|---|---|---|
| Orquestador | Coordina el flujo y toma decisiones de routing | Gestión de estado, lanzamiento de subagentes |
| Investigador | Busca información actualizada sobre el tema | WebSearch, WebFetch, Grep |
| Redactor | Escribe el contenido siguiendo la guía de estilo | Read, Write, historial de artículos |
| Revisor | Verifica calidad, SEO y coherencia | Read, Grep, checklist estructurado |
| Publicador | Formatea y ejecuta el commit/push | Bash, Git tools |
El orquestador no hace el trabajo directamente: dirige. Recibe el objetivo, asigna tareas a cada agente especializado según el progreso y gestiona los resultados intermedios.
// Configuración esquemática de un Agent Team con el Claude Agent SDK
const contentTeam = {
orchestrator: {
role: "Coordina el pipeline completo de generación de contenido",
tools: ["Agent", "TodoWrite"],
instructions: "Nunca escribas contenido directamente. Siempre delega al Redactor."
},
researcher: {
role: "Investiga el tema dado y devuelve datos estructurados",
tools: ["WebSearch", "WebFetch", "Grep"],
subagent_type: "general-purpose"
},
writer: {
role: "Redacta el artículo siguiendo las guías del blog",
tools: ["Read", "Write"],
subagent_type: "general-purpose"
},
reviewer: {
role: "Revisa calidad, SEO y coherencia del artículo",
tools: ["Read", "Grep"],
subagent_type: "Explore"
}
};
Comparativa: Agente, Subagente o Agent Team
Esta tabla resume cuándo usar cada enfoque:
| Criterio | Agente único | Subagentes | Agent Team |
|---|---|---|---|
| Complejidad de la tarea | Simple o mediana | Mediana, paralelizable | Alta, multifase |
| Paralelismo | No | Sí (ad-hoc) | Sí (estructurado) |
| Especialización | No | Parcial | Total |
| Diseño previo | No necesario | Mínimo | Imprescindible |
| Casos típicos | Refactoring, debugging | Auditorías, análisis múltiples | Pipelines, automatización continua |
| Overhead | Ninguno | Bajo | Medio-alto |
La regla práctica es sencilla: empieza siempre con el agente único. Si la tarea crece y necesitas paralelismo puntual, añade subagentes. Si el sistema va a ejecutarse de forma recurrente con un flujo complejo y definido, diseña un Agent Team desde el principio.
El error más común
El error típico es el opuesto: diseñar un Agent Team complejo para tareas que un agente único con dos subagentes resolvería en menos tiempo y con menos superficie de fallo. La complejidad arquitectónica tiene un coste: más configuración, más puntos de fallo, más difícil de depurar.
Los Agent Teams brillan cuando la tarea es recurrente, predecible en su estructura y suficientemente compleja como para justificar el diseño. No son la solución por defecto; son la herramienta para cuando las otras se quedan cortas.
Conclusión
Los tres conceptos forman una jerarquía coherente dentro de Claude Code:
- El agente es la unidad base: autónomo, con herramientas, capaz de completar tareas completas por sí solo.
- Los subagentes son extensiones dinámicas del agente principal para paralelizar o aislar subtareas sin diseño previo.
- Los Agent Teams son arquitecturas planificadas donde varios agentes especializados colaboran en flujos de trabajo complejos y recurrentes.
Dominar esta distinción es lo que permite escalar el uso de inteligencia artificial en proyectos reales: no como una herramienta de asistencia puntual, sino como una infraestructura que trabaja de forma autónoma y coordinada.
Si estás explorando cómo implementar agentes o Agent Teams en tu empresa y quieres un punto de partida sólido, podemos ayudarte a diseñar la arquitectura correcta para tu caso: