Índice
Cuando quieres que varias IA se repartan el trabajo en Claude Code, hay dos mecanismos parecidos pero distintos: los subagents y los Agent Teams. Los nombres confunden, pero sus funciones y modos de coordinación son fundamentalmente diferentes. Este artículo aclara qué es cada uno, la diferencia decisiva, cuál usar y cómo, basándose en la documentación oficial.
Tres puntos cruciales de entrada. (1) Los subagents son una función integrada: el agente principal delega una subtarea acotada a un "ayudante de contexto fresco" y solo recibe de vuelta un resumen (jerárquico, efímero). (2) Los Agent Teams son una función experimental opt-in, desactivada por defecto. Solo funcionan una vez que defines CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1: varias sesiones independientes se coordinan como pares mediante una shared task list (entre pares, persistente). (3) "Anidamiento de 5 niveles" es una función de los subagents; los Agent Teams no pueden anidarse (son planos); no confundas ambas cosas.
¿Jerarquía o pares?
— delegar y recibir un resumen, o coordinarse como iguales
Subagents: el agente principal pasa una tarea a un ayudante y recibe el resultado. Agent Teams: pares iguales se coordinan mediante una shared task list.
Los Teams son una función experimental desactivada por defecto: se requiere CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
1. Qué son los subagents
Los subagents son agentes especializados que manejan tipos concretos de trabajo dentro de una sola sesión. Según la documentación oficial, "cada subagent se ejecuta en su propia ventana de contexto, con un system prompt personalizado y permisos de herramientas específicos." El agente principal delega automáticamente en función del description de cada subagent, y el subagent trabaja de forma independiente y devuelve solo un resumen a la conversación principal.
La clave es que "cada subagent se ejecuta en un contexto fresco y separado": no ve tu historial de conversación ni los archivos que ya hayas leído. Así puedes hacer que realice búsquedas pesadas "fuera" y recibir solo la conclusión, sin inundar tu contexto principal con logs o salida de tests. Gestiónalos con /agents (pestañas Running / Library). Defínelos en .claude/agents/<name>.md con frontmatter YAML (name / description / tools / model). Entre los integrados están Explore (Haiku, solo lectura), Plan y general-purpose. Los subagents pueden anidarse, hasta 5 niveles de profundidad (en el nivel 5 no se pasa el Agent tool, así que no pueden generar más). Para el panorama general, consulta Qué es un sistema multiagente.
2. Qué son los Agent Teams (experimental, tras un flag)
Los Agent Teams te permiten coordinar varias sesiones de Claude Code como un "equipo." Una es el team lead (coordina, asigna, sintetiza); las demás son teammates, cada una su propia sesión y contexto independientes, que se comunican directamente entre sí mediante una shared task list y un mailbox. A diferencia de los subagents, puedes hablar con teammates concretos directamente.
Importante: Agent Teams es una función experimental, desactivada por defecto
La documentación oficial afirma con claridad que "los agent teams son experimentales y están desactivados por defecto." Para usarlos, define la variable de entorno CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 (o a través del env de settings.json). Sin ella, no se crea ningún equipo al arrancar y Claude no propondrá ni generará teammates.
Ten en cuenta que el cambio de v2.1.178 solo "eliminó el paso de configuración TeamCreate/TeamDelete, de modo que con el flag activado cada sesión tiene un equipo implícito"; no "activó los equipos por defecto." El flag sigue siendo obligatorio.
3. La diferencia decisiva
Puestos lado a lado, los dos tienen formas de coordinarse completamente distintas.
| Subagents | Agent Teams | |
|---|---|---|
| Coordinación | Jerárquica (el principal delega y agrega resultados) | Entre pares (se autocoordinan mediante una shared task list) |
| Comunicación | Solo informan al llamante (nunca se hablan entre sí) | Los teammates se mensajean directamente entre sí por el mailbox |
| Persistencia | Efímeros (devuelven un resumen tras la tarea) | Sesiones independientes persistentes (las diriges directamente) |
| Contexto | Su propio contexto fresco; el resumen vuelve al principal | Totalmente independiente (nada se resume de vuelta automáticamente) |
| Coste en tokens | Relativamente bajo | Alto (cada teammate es una instancia de Claude aparte) |
| Estado | Integrado, siempre disponible | Experimental, tras un flag, desactivado por defecto |
| Anidamiento | Los subagents se anidan hasta 5 niveles | Sin anidamiento (los teammates no pueden generar teammates) |
En una línea: Subagents = "el agente principal pasa una tarea acotada a un ayudante de contexto fresco y recibe de vuelta la conclusión (jerárquico, efímero, solo resumen)." Agent Teams = "varias sesiones persistentes se coordinan mediante una shared task list y mensajería, y puedes dirigir a cada una (pares, independientes)." Un error común: "el anidamiento de 5 niveles" es una función de los subagents, mientras que los Teams son planos (sin anidamiento).
4. Cuál deberías usar
Elige según el propósito y no te agobiarás. La mayoría del trabajo del día a día va bien con subagents (o una sola sesión).
Elige según el propósito
· el trabajo es autocontenido y solo importa el resultado
· quieres límites de herramientas o un modelo más barato
· los trabajadores no necesitan hablar
· la exploración en paralelo compensa (revisión paralela / depuración de hipótesis rivales / multimódulo)
· quieres dirigir a cada trabajador
(aceptas mayor coste + el flag)
· necesitas idas y vueltas frecuentes
· toca los mismos archivos
· es un cambio local rápido
Por defecto, "ante la duda, una sola sesión o subagents."
Recurre a los Agent Teams solo para trabajo en paralelo que realmente necesite coordinación entre pares.
5. Chuleta de uso
Una referencia rápida de comandos y configuración.
# --- Subagents (built-in) ---
/agents # gestor (Running / Library)
.claude/agents/<name>.md # definición de proyecto (name/description/tools/model)
~/.claude/agents/<name>.md # definición de usuario (todos los proyectos)
claude --agent code-reviewer # ejecuta toda la sesión como un subagent concreto
@agent-<name> # @-mención para invocarlo explícitamente
# --- Agent Teams (experimental, tras un flag) ---
# Actívalo vía env (o el env de settings.json); DESACTIVADO por defecto
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
# Luego descríbelo en lenguaje natural, p. ej.: "Genera tres teammates para revisar la PR #142:
# uno para seguridad, uno para rendimiento, uno para cobertura de tests."
# Visualización vía teammateMode (por defecto in-process; los paneles divididos necesitan tmux/iTerm2)En un archivo de definición de subagent, puedes restringir herramientas con tools o enrutar a un modelo más ligero como haiku con model. Para construir y diseñar agentes, consulta Cómo construir un sistema multiagente y Cómo construir un agente de IA.
6. Advertencias sobre Agent Teams
Los Agent Teams son potentes, pero vienen con límites y coste propios de su fase experimental. Conócelos antes de adoptarlos.
(1) Un equipo por sesión, sin anidamiento: los teammates no pueden generar teammates, y el lead es fijo. (2) Alto consumo de tokens (cada teammate es una instancia de Claude aparte); la recomendación es de 3 a 5 teammates. (3) Los teammates no están aislados en worktrees, así que si tocan los mismos archivos se sobrescriben entre sí: reparte los archivos manualmente. (4) Al ser una función experimental, hay límites como que /resume y /rewind no restauran teammates in-process. (5) La visualización en paneles divididos necesita tmux o iTerm2 (algunas terminales como la de VS Code no son compatibles). En resumen, úsalo solo cuando el beneficio de la coordinación en paralelo supere el coste y el esfuerzo.
Resumen
Los subagents y los Agent Teams de Claude Code "reparten el trabajo entre varias IA", pero sus modelos de coordinación difieren. Los subagents son integrados: el agente principal delega una tarea acotada a un ayudante de contexto fresco y solo recibe de vuelta un resumen (jerárquicos, efímeros, no se hablan entre sí, se anidan hasta 5 niveles). Los Agent Teams son un opt-in experimental, desactivado por defecto (necesita CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1): varias sesiones independientes se coordinan como pares mediante una shared task list y mensajería (persistentes, diriges a cada una, sin anidamiento).
Cómo elegir: "solo quiero el resultado / no quiero contaminar el contexto → subagents", "trabajo en paralelo donde los trabajadores deben compartir y coordinarse → Agent Teams", "secuencial / mismos archivos / arreglo rápido → una sola sesión." Una confusión habitual: "el anidamiento de 5 niveles" es una función de los subagents; los Teams son planos. Y ten en cuenta que v2.1.178 agilizó el arranque de equipos, no "los activó por defecto." Los Teams son costosos y experimentales, así que limítalos a casos donde la coordinación compense. Relacionado: Qué es un sistema multiagente, cómo construir uno, Observabilidad de IA.
FAQ
Q. ¿En qué se diferencian los subagents y los Agent Teams?
A. Su coordinación es fundamentalmente distinta. Los subagents son jerárquicos: el agente principal delega una tarea acotada a un ayudante de contexto fresco y solo recibe de vuelta un resumen (los ayudantes no se hablan entre sí; efímeros). Los Agent Teams son entre pares: varias sesiones independientes se coordinan mediante una shared task list y un mailbox, y puedes dirigir a cada una (persistentes). Los subagents son integrados; los Agent Teams son experimentales y requieren un flag.
Q. ¿Puedo usar los Agent Teams de inmediato?
A. No: están desactivados por defecto. Debes definir CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 en env (o en el env de settings.json). v2.1.178 solo agilizó el arranque ("eliminó el paso de configuración TeamCreate, de modo que con el flag activado cada sesión tiene un equipo implícito"); no "activó los equipos por defecto." El flag sigue siendo obligatorio.
Q. ¿A cuál se refiere "se anida hasta 5 niveles"?
A. A los subagents. Un subagent puede generar sus propios subagents, hasta 5 niveles de profundidad (en el nivel 5 no puede ir más allá). Los Agent Teams no pueden anidarse: los teammates no pueden generar teammates, y solo el lead gestiona el equipo. No confundas ambas cosas.
Q. No sé cuál usar.
A. La mayoría de las veces basta con una sola sesión o subagents. Si solo quieres el resultado y no quieres que salida pesada inunde tu contexto principal, usa subagents. Si los trabajadores deben compartir hallazgos, contrastarse y autocoordinarse en trabajo en paralelo (revisión paralela, depuración de hipótesis rivales, desarrollo multimódulo) y quieres dirigir a cada uno, usa Agent Teams. Para trabajo secuencial, idas y vueltas frecuentes o tocar los mismos archivos, encaja una sola sesión.
Q. ¿Qué debo vigilar con los Agent Teams?
A. Alto consumo de tokens (cada teammate es una instancia aparte; se recomiendan de 3 a 5), un equipo por sesión sin anidamiento, los teammates no aislados en worktrees por lo que entran en conflicto sobre los mismos archivos (repártelos manualmente), límites experimentales en /resume y /rewind, y los paneles divididos que necesitan tmux/iTerm2. Úsalo solo para trabajo en paralelo donde la coordinación supere el coste.
