Lo esencial
Un subagente es un freelancer: recibe el encargo, lo hace, lo entrega y se va. Un equipo de agentes es un departamento: todos trabajan al mismo tiempo, se comunican entre sí, ven la tarea común y pueden pasarle trabajo a un colega. No solo es más rápido: es otro nivel de complejidad en las tareas que puedes resolver.
Conceptos clave
- La diferencia clave entre un equipo y los subagentes: los integrantes se comunican directamente entre sí (la herramienta
SendMessage) - Estado: agent teams es una función experimental, desactivada por defecto; se activa con la variable
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 - Ejemplo de equipo para desarrollar una landing page: Frontend + Backend + QA en paralelo
- Herencia de permisos: el equipo recibe los permisos de la sesión principal
- 4 trampas del trabajo en equipo y cómo evitarlas
- Cuándo usar equipos y cuándo subagentes
Teoría
Subagentes vs. equipos: la diferencia clave
Subagentes (lección Subagentes):
- Trabajan de forma independiente entre sí
- Normalmente no saben de los otros subagentes (los subagentes con nombre pueden escribirse entre sí, pero es más bien la excepción)
- Se comunican sobre todo con el agente principal (arriba/abajo)
- Recibieron la tarea → la hicieron → devolvieron el resultado → fin
Equipos:
- Saben quiénes son sus compañeros de equipo
- Pueden enviarse mensajes entre sí (la herramienta
SendMessage) - Ven una lista común de tareas
- Pueden delegar tareas dentro del equipo
- Trabajan en paralelo y se coordinan por su cuenta
Subagentes:
Agente principal
↕ ↕ ↕
Agente A Agente B Agente C
(aislados entre sí)
Equipo:
Agente principal
↕
Agente A ←→ Agente B ←→ Agente C
(se comunican directamente)Ejemplo en vivo: un equipo para desarrollar una landing page
Tarea: crear la landing page de un producto nuevo en un día.
Sin equipo (en secuencia):
1. Frontend Dev hace la UI → 4 horas
2. Backend Dev hace la API → 3 horas
3. QA prueba → 2 horas
Total: 9 horasCon equipo (en paralelo):
En paralelo:
├── Frontend Dev: maqueta los componentes de UI → 4 horas
├── Backend Dev: escribe los endpoints de la API → 3 horas
└── QA: prepara los casos de prueba y prueba las partes que ya están listas → 2 horas
QA encuentra un bug → le envía un mensaje a Frontend Dev → este lo corrige
sin esperar a que termine todo el proceso
Total: ~4.5 horas (contando la comunicación)Casi el doble de rápido, con la misma calidad.
Cómo crear un equipo
Primero activa la función. Agent teams es experimental y está desactivado por defecto. Agrega a settings.json:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}Sin esta variable, Claude no crea ni propone equipos. Solo funciona en una sesión interactiva (no en modo -p). La función es experimental; su comportamiento y sus limitaciones pueden cambiar: consulta la documentación.
Un equipo sencillo se crea con un solo prompt:
Crea un equipo de 3 agentes para desarrollar una landing page: - Agente 1 (Frontend Dev): maqueta componentes de React, trabaja con CSS/Tailwind - Agente 2 (Backend Dev): escribe endpoints de FastAPI, trabaja con PostgreSQL - Agente 3 (QA): prueba la funcionalidad, usa Playwright para pruebas automáticas Usa Sonnet para cada integrante. Los agentes pueden comunicarse directamente entre sí.
El modelo de cada integrante se toma en este orden: primero el que nombres en tu prompt, luego el modelo de la definición del subagente, luego CLAUDE_CODE_SUBAGENT_MODEL y, por último, el modelo del líder. El modelo y el fast mode quedan fijos en el momento en que se crea el integrante.
Claude Code creará el equipo y le dará a cada integrante:
Lo que recibe cada agente:
1. La descripción de su rol y su tarea 2. La lista de compañeros de equipo (nombres + qué hacen) 3. La lista común de tareas del proyecto 4. Instrucciones paso a paso para su parte 5. Acceso a SendMessage para comunicarse
El historial de la conversación del líder no pasa a los integrantes: ellos cargan CLAUDE.md, los servidores MCP y los skills del proyecto, y reciben solo la tarea del líder. Por eso, escribe todo lo necesario en la tarea.
Cómo se comunican los agentes: SendMessage
Ejemplo de diálogo dentro del equipo:
QA Agent → Frontend Dev:
"Encontré un bug: el botón Submit del formulario de pedido se activa dos veces si lo presionas rápido.
Eso crea pedidos duplicados en la base. Prioridad: alta.
Caso de prueba: test_double_click_submit.py en la carpeta tests/"
Frontend Dev → QA Agent:
"Recibido. Agrego debounce al botón Submit. La corrección estará lista en 15 minutos.
Puedes volver a correr el caso de prueba después del commit #a3f2c."
QA Agent → Backend Dev:
"Necesito ayuda para probar el endpoint POST /orders.
¿Cómo reproduzco la idempotencia con solicitudes duplicadas?"El agente principal no controla cada mensaje: el equipo se coordina solo. Él ve el panorama general e interviene solo si hace falta.
Herencia de permisos
Los integrantes del equipo arrancan con el modo de permisos del líder (salvo el modo dontAsk, que no heredan). Las solicitudes de permiso de los integrantes aparecen en la sesión del líder y las apruebas ahí:
- Los integrantes toman los servidores MCP y los skills de la configuración del proyecto y del usuario, como una sesión normal
- Si están permitidos los comandos bash → los integrantes pueden ejecutar bash
- Si está permitido editar archivos → los integrantes pueden editar
- Si el líder se lanzó con
--dangerously-skip-permissions, todos los integrantes trabajan así también
Es cómodo: no tienes que configurar a cada agente por separado. Pero debes entender que, si un agente recibe instrucciones equivocadas, tiene permisos completos para romper algo.
Importante: antes de lanzar el equipo, asegúrate de que los permisos estén bien configurados. No le des al equipo permisos que no necesita.
4 trampas del trabajo en equipo
Trampa 1: los agentes piden permisos
Situación: creaste el equipo, empezó a trabajar y cada 2 minutos un agente pregunta "¿Puedo ejecutar un comando bash?"
Solución: preautoriza las operaciones necesarias antes de lanzar el equipo: agrégalas a las permitidas con /permissions o en settings.json (ver la lección Permisos y seguridad).
Los permisos no se otorgan solo con un prompt: la frase "no pidas confirmación" no elimina las solicitudes de permiso. Con el prompt puedes describir los límites del trabajo ("trabajen solo en la carpeta /src, hagan los commits en su propia rama"), pero los permisos en sí se definen en la configuración.
Trampa 2: conflictos al escribir archivos
Situación: Frontend Dev y Backend Dev editan config.json al mismo tiempo → uno sobrescribe los cambios del otro.
Solución: usar archivos temporales con nombres únicos:
Frontend Dev escribe en: frontend-config-temp.json Backend Dev escribe en: backend-config-temp.json El agente principal los une en: config.json
O repartir explícitamente las zonas de responsabilidad en el prompt: "Frontend trabaja solo en /src/components/, Backend solo en /api/; no tocan los archivos del otro sin permiso explícito."
Trampa 3: confusión con los permisos de acceso
Situación: QA Agent intenta usar una herramienta que no estaba permitida → error → el agente se "atora".
Solución: en la etapa de aprendizaje, da permisos completos y observa qué se usa. Después restringe según el uso real. Adivinar los permisos de antemano no es productivo.
Trampa 4: un equipo para tareas secuenciales
Situación: creaste un equipo de 3 agentes para tareas que deben hacerse estrictamente una tras otra (el agente B no puede empezar hasta que el agente A termine).
Resultado: los agentes B y C se quedan esperando, no hay ningún paralelismo. El equipo gastó el doble de recursos sin ganar velocidad.
Solución: para tareas secuenciales usa subagentes, no un equipo. Un equipo solo es eficaz cuando las tareas son paralelas.
Ejemplo práctico: un equipo para investigación de mercado
Tarea: investigar el mercado de educación en línea para lanzar un curso nuevo
Crea un equipo de 3 agentes para una investigación de mercado: Agente 1 (Industry Analyst): - Analiza el tamaño del mercado de educación en línea en español - Estudia las tendencias de los últimos 2 años - Encuentra nichos en crecimiento Agente 2 (Competitor Researcher): - Investiga los 10 cursos principales del nicho elegido - Analiza precios, formatos y reseñas - Encuentra necesidades sin cubrir Agente 3 (Audience Researcher): - Estudia al público objetivo (foros, Reddit, grupos de Facebook, YouTube) - Identifica sus problemas y deseos - Encuentra dónde pasa el tiempo ese público Usa Sonnet para cada integrante. Al terminar, cada agente comparte sus resultados con los demás. El Agente 1 coordina el reporte final con base en todos los datos.
Mientras Industry Analyst estudia las tendencias, Competitor Researcher ya investiga a la competencia y Audience Researcher lee los foros. Todo en paralelo, así que la investigación sale bastante más rápido que en secuencia (a costa de un mayor consumo de tokens: cada integrante es una sesión aparte de Claude).
Patrones de comunicación entre agentes
| Patrón | Cómo funciona | Cuándo usarlo | Ejemplo |
|---|---|---|---|
| Orchestrator-Worker | Un coordinador reparte tareas a los demás | Roles bien separados, necesitas control | Landing page: coordinador + Frontend + Backend + QA |
| Pipeline | El resultado del agente A es la entrada del agente B | Pasos secuenciales con transformación de datos | Recolectar datos → Análisis → Reporte → PDF |
| Parallel (Fan-out / Fan-in) | Todos los agentes trabajan a la vez y los resultados se juntan | Tareas independientes, necesitas velocidad | Investigación de mercado: 3 analistas en paralelo |
| Peer-to-peer | Los agentes se comunican directamente con SendMessage |
Hace falta coordinación sin control central | Frontend + QA: encontré un bug → corrígelo |
El patrón más común para empezar: Orchestrator-Worker. Un agente coordinador maneja de 3 a 5 agentes trabajadores (la documentación recomienda empezar con 3-5 integrantes y no inflar el equipo: tres integrantes enfocados suelen funcionar mejor que cinco dispersos). Simple, predecible, eficaz.
Cuándo usar equipos vs. subagentes
Usa un equipo cuando:
- Las tareas son paralelas e independientes entre sí
- Hace falta comunicación entre agentes durante el trabajo
- La tarea es lo bastante grande para justificar el costo de coordinación y el consumo de tokens (un equipo cuesta bastante más que una sola sesión)
- Distintas partes de la tarea requieren distintas especializaciones
Usa subagentes cuando:
- Las tareas son secuenciales (una depende de otra)
- Basta con una delegación sencilla sin comunicación
- Las tareas son cortas (menos de 10 minutos cada una)
- Solo necesitas aislar el contexto
No uses ni uno ni otro cuando:
- La tarea toma menos de 5 minutos
- No hace falta especialización
- La tarea requiere todo el contexto de la sesión actual
Práctica
Tarea: crear un equipo de 3 agentes para investigar un mercado
- Elige un nicho que quieras investigar (por ejemplo: SaaS para pequeños negocios, cursos en línea de finanzas personales, apps de fitness)
- Crea un equipo de 3 agentes:
- Industry Analyst: tendencias generales del mercado
- Competitor Researcher: los 5 competidores principales con precios y reseñas
- Audience Researcher: problemas y deseos del público objetivo
- Dale al equipo la tarea: investigar el nicho elegido
- Observa a los agentes en el panel debajo del campo de entrada: las flechas arriba y abajo eligen a un integrante, Enter abre su conversación, Ctrl+T muestra la lista de tareas
- Evalúa el resultado: ¿en qué se diferencia del enfoque secuencial (en calidad y en tiempo)?
- Extra: agrega un cuarto agente, "Report Writer", que arme el reporte final con los datos de los otros tres
Herramientas y recursos
SendMessage: herramienta integrada para comunicarse dentro del equipo- Modos de visualización: in-process (por defecto, funciona en cualquier terminal) y split panes (cada integrante en su propio panel; requiere tmux o iTerm2); se cambia con el ajuste
teammateMode - Hooks para equipos:
TeammateIdle,TaskCreated,TaskCompleted(el código de salida 2 devuelve retroalimentación) - Documentación de agent teams: guía oficial y lista de limitaciones
- Documentación de subagentes
/permissions: manejo de permisos antes de lanzar el equipo- Git branches / worktrees: para trabajar en paralelo sobre el código sin conflictos
Ideas clave
La diferencia clave entre un equipo y los subagentes: los agentes del equipo HABLAN entre sí. QA encuentra un bug → se lo dice directamente a Frontend Dev, sin intermediario.
Un equipo para tareas paralelas puede acelerar bastante el trabajo. Un equipo para tareas secuenciales = el doble de gasto sin beneficio. Aprende cuándo usarlo.
Preautoriza las herramientas antes de lanzar el equipo; si no, los agentes pedirán permiso todo el tiempo y romperán el ritmo de trabajo.
Lecciones relacionadas
- ← Subagentes: los subagentes trabajan aislados; los equipos agregan comunicación
- → Git y worktrees: worktrees para que los agentes trabajen en paralelo sobre el código sin conflictos
- ← MCP a fondo: los integrantes del equipo cargan los servidores MCP desde la configuración del proyecto y del usuario
Qué sigue
La marca se guarda solo en este navegador y no se envía a ningún sitio. Mi progreso