Nota del autor: Guía paso a paso para activar y utilizar la función de colaboración multi-agente Claude 4.6 Agent Teams, dominando la arquitectura Lead + Teammate, la asignación de tareas, la comunicación por mensajes y trucos prácticos.
Con el lanzamiento de Claude Opus 4.6, se introdujo simultáneamente la función Agent Teams (Equipos de Agentes), que permite que múltiples instancias de Claude colaboren en paralelo como si fueran un equipo de desarrollo real. Muchos desarrolladores tienen curiosidad: ¿Cómo se activa Agent Teams? ¿Cómo se dispara? ¿En qué se diferencia de un Subagent? ¿Para qué escenarios es adecuado?
Valor principal: Al terminar de leer este artículo, dominarás el flujo completo de uso de Agent Teams: desde la configuración inicial hasta los comandos de activación, pasando por la asignación de tareas y la colaboración en equipo, para que puedas empezar a programar con multi-agentes de inmediato.
Qué es Claude Agent Teams
Agent Teams es una función experimental de Claude Code (en fase de vista previa de investigación) que te permite ejecutar múltiples instancias independientes de Claude Code simultáneamente en un proyecto, las cuales colaboran a través de una lista de tareas compartida y un sistema de mensajería.
Para entenderlo rápido: Agent Teams = un Lead (líder del equipo) + varios Teammates (compañeros), cada uno trabajando de forma independiente, comunicándose entre sí y completando tareas complejas juntos.
| Dimensión de comparación | Subagent (Subagente) | Agent Teams (Equipo) |
|---|---|---|
| Forma de comunicación | Solo reporta resultados al Agente principal | Los compañeros pueden comunicarse directamente |
| Forma de coordinación | El Agente principal gestiona todo | Lista de tareas compartida + reclamo autónomo |
| Contexto | Contexto independiente, el resultado vuelve al llamador | Contexto independiente, autonomía total |
| Escenario ideal | Tareas enfocadas que solo requieren un resultado | Tareas complejas que requieren discusión y colaboración |
| Consumo de Tokens | Bajo (los resultados se resumen en el contexto principal) | Alto (cada compañero es una instancia independiente de Claude) |
Arquitectura central de Claude Agent Teams
Agent Teams se compone de 4 componentes principales:
| Componente | Responsabilidad | Descripción |
|---|---|---|
| Lead Agent | Líder del equipo | Tu sesión principal de Claude Code, responsable de crear el equipo, asignar tareas y consolidar resultados. |
| Teammate | Compañero | Instancias independientes de Claude Code que ejecutan las tareas asignadas. |
| Task List | Lista de tareas compartida | Un tablero de tareas visible para todos, con soporte para reclamos, dependencias y seguimiento de estado. |
| Mailbox | Sistema de mensajería | Canal de comunicación entre compañeros, soporta mensajes privados y difusión (broadcast). |
💡 Diferencia clave: Un Subagent sigue un modelo de "reporte al superior", mientras que Agent Teams sigue un modelo de "colaboración en equipo". Si tu tarea requiere que varias personas discutan, desafíen puntos de vista o procesen diferentes módulos en paralelo, Agent Teams es la mejor opción.
Cómo activar Claude Agent Teams
Agent Teams está desactivado por defecto y debe activarse manualmente. Aquí tienes 3 formas de hacerlo:
Paso 1: Activar la función experimental
Opción A — Archivo de configuración (recomendado)
En el archivo settings.json de Claude Code, añade lo siguiente:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
Opción B — Variables de entorno
# Añade esto a tu .bashrc o .zshrc
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
Opción C — Sesión única
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude
Paso 2: Activar Agent Teams con lenguaje natural
No existe un comando de barra como /agent-teams. Una vez activada la función, solo necesitas describir el equipo que deseas usando lenguaje natural:
Crea un equipo de agentes para revisar el PR #142. Genera tres revisores:
- Uno enfocado en riesgos de seguridad.
- Uno que verifique el impacto en el rendimiento.
- Uno que valide la cobertura de pruebas.
Haz que cada uno informe de sus hallazgos tras la revisión.
O algo más sencillo:
Create a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.
Claude creará automáticamente el equipo, generará a los compañeros y asignará las tareas. También es posible que Claude sugiera proactivamente la creación de un equipo si determina que tu tarea es apta para el procesamiento en paralelo, aunque siempre te pedirá confirmación primero.
Paso 3: Seleccionar el modo de visualización
| Modo de visualización | Descripción | Entorno aplicable |
|---|---|---|
| in-process (por defecto) | Todos los compañeros se ejecutan en la terminal principal | Cualquier terminal, incluyendo VS Code |
| tmux | Cada compañero en un panel independiente | Requiere tmux o iTerm2 |
| auto | Decisión automática | Si ya estás en tmux, divide la pantalla; de lo contrario, usa in-process |
# Especificar en la línea de comandos
claude --teammate-mode tmux
# O configurarlo en settings.json
{
"teammateMode": "tmux"
}
Sugerencia: Para el primer uso, se recomienda el modo in-process. Una vez familiarizado, puedes probar el modo de división de pantalla con tmux. Puedes obtener saldo para la API de Claude a través de APIYI para probar a fondo todas las configuraciones de Agent Teams en local.
Guía de operación de Claude Agent Teams
Referencia rápida de atajos de teclado
Mientras Agent Teams está en ejecución, puedes usar los siguientes atajos:
| Atajo | Función |
|---|---|
| Shift+Up/Down | Cambiar/seleccionar diferentes compañeros |
| Enter | Ver detalles de la sesión del compañero seleccionado |
| Escape | Interrumpir la operación actual del compañero |
| Ctrl+T | Cambiar a la vista de lista de tareas |
| Shift+Tab | Cambiar modo de delegación (el Líder solo coordina, no programa) |
Mecanismo de asignación y reclamo de tareas
El sistema de tareas de Agent Teams admite 3 estados y relaciones de dependencia:
Estados de las tareas: pending (pendiente) → in_progress (en progreso) → completed (completado)
Mecanismo de dependencia: Las tareas pueden configurar dependencias blockedBy. Una vez que la tarea de la que depende se completa, la tarea dependiente se desbloquea automáticamente, sin necesidad de intervención manual.
Formas de reclamar tareas:
- Asignación designada por el Líder: Dile explícitamente al Líder que asigne una tarea específica a un compañero determinado.
- Reclamo autónomo del compañero: Al terminar la tarea actual, el compañero reclama automáticamente la siguiente tarea disponible no asignada.
- Bloqueo de archivos para evitar conflictos: Si varios compañeros intentan tomar la misma tarea al mismo tiempo, el sistema utiliza bloqueos de archivos para evitar conflictos.
Sugerencia de tamaño de tarea: La mejor práctica es asignar 5-6 tareas por compañero. Si las tareas son demasiado pequeñas, el costo de coordinación superará los beneficios; si son demasiado grandes, el compañero pasará mucho tiempo sin informar sobre su progreso.
Formas de comunicación entre compañeros
| Tipo de comunicación | Descripción | Escenario de uso |
|---|---|---|
| write (mensaje privado) | Envía un mensaje a un compañero específico | Coordinar problemas específicos |
| broadcast (difusión) | Envía un mensaje a todos los compañeros | Avisos importantes (usar con precaución, el costo aumenta con el tamaño del equipo) |
La comunicación es punto a punto, no necesita pasar por el Líder. Cualquier compañero puede enviar mensajes directamente a otros.
Colaboración en Git y cómo evitar conflictos de archivos
La regla más importante en Agent Teams: si dos compañeros editan el mismo archivo, se producirán sobreescrituras.
Estrategia recomendada de división de archivos:
# Ejemplo de desarrollo de funcionalidad Full-stack
Compañero de Backend → Responsable de src/api/ y src/migrations/
Compañero de Frontend → Responsable de src/components/
Compañero de Tests → Responsable de tests/
⚠️ Importante: Los compañeros de Agent Teams comparten el mismo directorio de trabajo y no utilizan git worktree automáticamente. Asegurarse de que cada compañero se encargue de un conjunto diferente de archivos es clave para evitar conflictos.
5 Escenarios reales de Claude Agent Teams
Escenario 1: Revisión de código multidimensional
Crea un equipo de agentes para revisar este PR:
- Revisor de seguridad: busca inyecciones, XSS, problemas de permisos, etc.
- Revisor de rendimiento: analiza consultas N+1, fugas de memoria, estrategias de caché.
- Revisor de pruebas: verifica la cobertura de pruebas y casos borde.
Haz que cada uno revise por su cuenta e informe sus hallazgos.
¿Por qué es ideal para Agent Teams?: Las tres dimensiones de revisión son completamente independientes, no generan conflictos de archivos y pueden ejecutarse en paralelo.
Escenario 2: Desarrollo en paralelo de nuevos módulos
Crea un equipo para construir el sistema de notificaciones de usuario:
- Compañero 1: Construye la API del backend (src/api/notifications/)
- Compañero 2: Construye los componentes del frontend (src/components/notifications/)
- Compañero 3: Escribe las pruebas de integración (tests/notifications/)
¿Por qué es ideal?: Cada compañero se encarga de un directorio diferente, lo que proporciona un aislamiento natural. Al terminar, solo hay que integrar.
Escenario 3: Depuración de hipótesis competitivas
Hay un bug intermitente. Crea un equipo para depurarlo usando diferentes hipótesis:
- Compañero A: Investiga si es una condición de carrera (race condition).
- Compañero B: Investiga si es una fuga de memoria.
- Compañero C: Investiga si es un timeout de una API de terceros.
Cada uno debe validar su hipótesis de forma independiente e informar.
¿Por qué es ideal?: Depuración adversarial; se investigan múltiples pistas en paralelo. El primero que encuentre la causa raíz, gana.
Escenario 4: Coordinación de cambios multi-capa
Cuando un cambio abarca el frontend, el backend y la base de datos, Agent Teams permite que los expertos de cada capa cumplan con su función, coordinando las definiciones de las interfaces a través del sistema de mensajes.
Escenario 5: Investigación exploratoria
Estoy diseñando una herramienta de CLI para rastrear comentarios TODO en el código.
Crea un equipo para explorar desde diferentes ángulos:
- Un compañero se encarga del diseño de la experiencia de usuario (UX).
- Un compañero se encarga de la arquitectura técnica.
- Un compañero actúa como el "abogado del diablo" (devil's advocate).
¿Por qué es ideal?: Choque de múltiples perspectivas, desafiando mutuamente las hipótesis y conclusiones de los demás.
Guía de selección entre Claude Agent Teams y Subagents
| Dimensión de decisión | Elegir Subagent | Elegir Agent Teams |
|---|---|---|
| ¿Los compañeros necesitan comunicarse? | ❌ No | ✅ Sí |
| ¿Las tareas se pueden paralelizar? | Parcialmente | ✅ Altamente paralelo |
| ¿Implica edición de múltiples archivos? | ✅ Seguro para el mismo archivo | ⚠️ Requiere división para evitar conflictos |
| ¿Complejidad de la tarea? | Enfocado en un solo objetivo | Múltiples ángulos, múltiples módulos |
| ¿Presupuesto de tokens? | 💰 Más económico | 💸 Aprox. 3-7 veces el consumo |
| ¿Se requiere discusión o cuestionamiento? | ❌ No | ✅ Sí |
Referencia de costes: Un equipo de 3 Agent Teams funcionando durante 30 minutos consume aproximadamente entre 3 y 4 veces los tokens de una sesión individual. En modo Plan, el consumo es de unas 7 veces. Se recomienda gestionar el presupuesto de tokens de forma flexible a través de APIYI (apiyi.com).
Trucos avanzados para Claude Agent Teams
Truco 1: Modelos mixtos para reducir costes
Crea un equipo donde el Lead use Opus y 4 compañeros usen Sonnet.
El Lead se encarga de las decisiones estratégicas con Opus 4.6 para asegurar la calidad, mientras que los compañeros ejecutan tareas específicas con Sonnet para controlar los costes.
Truco 2: Flujo de trabajo con aprobación de planes (Plan)
Genera un compañero arquitecto para refactorizar el módulo de autenticación.
Exige que envíe una propuesta para aprobación antes de realizar cualquier modificación.
El compañero entrará primero en modo Plan de solo lectura y, tras completar la propuesta, enviará una solicitud de aprobación al Lead. El compañero solo empezará la implementación una vez que el Lead lo apruebe.
Truco 3: Modo delegación para evitar que el Lead se involucre directamente
Presiona Shift+Tab para activar el modo delegación. De esta forma, el Lead solo se encarga de coordinar y asignar tareas, sin escribir código él mismo. Esto evita que el Lead "robe el trabajo" de los demás y se mantenga en un nivel de supervisión.
Truco 4: Hooks de control de calidad (Quality Gate Hooks)
A través del mecanismo de Hooks, puedes controlar la calidad automáticamente:
TeammateIdle: Se activa cuando un compañero está a punto de quedar inactivo. Usar el código de salida 2 permite enviar feedback para que el compañero siga trabajando.TaskCompleted: Se activa cuando una tarea se marca como completada. El código de salida 2 puede detener la finalización y exigir modificaciones adicionales.
Consideraciones sobre Claude Agent Teams
Limitaciones conocidas
- No admite la reanudación de sesiones:
/resumey/rewindno restaurarán a los compañeros de equipo que ya hayan sido cerrados. - Un equipo por sesión: El Lead solo puede gestionar un equipo a la vez.
- No admite equipos anidados: Los compañeros de equipo no pueden crear sus propios equipos.
- Herencia de permisos: Los compañeros heredan el modo de permisos del Lead, aunque estos se pueden ajustar individualmente después de su creación.
- Limitaciones del modo de pantalla dividida: La división de pantalla mediante tmux no es compatible con el terminal integrado de VS Code, Windows Terminal ni Ghostty.
- Caída de compañeros: Si un compañero falla, se activará un tiempo de espera de latido (heartbeat) de 5 minutos; sus tareas podrán ser reclamadas por otros integrantes del equipo.
Mejores prácticas
- Tamaño del equipo: Se recomiendan entre 2 y 5 compañeros; un equipo de 3 suele funcionar mejor que uno de 6.
- La división de tareas es más importante que el número de personas: Un equipo de 3 personas con tareas bien divididas es más eficiente que uno de 6 con una mala organización.
- Tareas intensivas en lectura (revisión de código, investigación) son el escenario ideal para Agent Teams.
- La edición concurrente intensiva en escritura sigue siendo un desafío y requiere una división de archivos muy estricta.
Preguntas frecuentes
P1: ¿Qué suscripción se necesita para usar Agent Teams?
Agent Teams es una función experimental de Claude Code y requiere una suscripción Claude Max ($100-200/mes) para obtener suficiente cuota de uso de Opus 4.6. Los usuarios de la API pagan según las tarifas estándar de Opus 4.6 ($5/$25 por millón de tokens). También puedes obtener planes de facturación más flexibles a través de la plataforma APIYI (apiyi.com).
P2: ¿Agent Teams solo funciona con Opus 4.6?
No. Aunque Agent Teams se lanzó junto con Opus 4.6, puedes combinar modelos. El patrón recomendado es usar Opus 4.6 para que el Lead tome decisiones estratégicas y Sonnet para que los compañeros ejecuten tareas específicas; de esta forma, puedes controlar los costes manteniendo la calidad de la coordinación.
P3: ¿Se puede usar Agent Teams en VS Code?
Sí, pero con limitaciones. El terminal integrado de VS Code admite el modo "in-process" (donde todos los compañeros se ejecutan en la misma terminal). Sin embargo, el modo de pantalla dividida de tmux no está disponible en VS Code, por lo que para esa función necesitarás usar una terminal externa.
Resumen
Puntos clave de Claude 4.6 Agent Teams:
- Cómo activarlo: Configura la variable de entorno
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1y luego describe el equipo usando lenguaje natural. - Patrón de arquitectura: Coordinación del Lead Agent (Agente Líder) + trabajo en paralelo de los Teammate Agents (Agentes Compañeros), colaborando a través de una lista de tareas compartida y un sistema de mensajes.
- Mejores escenarios: Revisión de código, desarrollo en paralelo de nuevos módulos, depuración de hipótesis competitivas, coordinación entre capas e investigación exploratoria.
- Principio fundamental: La división de tareas es más importante que el número de integrantes; 3 compañeros suelen funcionar mejor que 6.
- Control de costos: El modelo híbrido (Opus para el Lead + Sonnet para los compañeros) es la opción con mejor relación calidad-precio.
Agent Teams lleva la programación con IA de la "lucha en solitario" a la era de la "colaboración en equipo". Aunque todavía está en fase de vista previa de investigación, ya ha demostrado una potente capacidad de desarrollo en paralelo.
Te recomendamos obtener saldo para la API de Claude a través de APIYI (apiyi.com). La plataforma ofrece facturación flexible y soporte para múltiples modelos, lo que facilita probar las diversas configuraciones de Agent Teams.
📚 Referencias
⚠️ Nota sobre el formato de los enlaces: Todos los enlaces externos utilizan el formato
Nombre del recurso: domain.compara que sean fáciles de copiar pero no clicables, evitando así la pérdida de autoridad SEO.
-
Documentación oficial de Claude Code Agent Teams: Guía completa de uso de Agent Teams.
- Enlace:
code.claude.com/docs/en/agent-teams - Descripción: Documentación oficial que incluye métodos de activación, explicación de la arquitectura y mejores prácticas.
- Enlace:
-
Blog de ingeniería de Anthropic — Caso del compilador de C: 16 Claudes construyendo un compilador de C en paralelo.
- Enlace:
anthropic.com/engineering/building-c-compiler - Descripción: Caso real de Agent Teams a gran escala, con más de 2000 sesiones que produjeron 100,000 líneas de código.
- Enlace:
-
Addy Osmani — Claude Code Swarms: Análisis profundo de Agent Teams por el responsable de ingeniería de Google.
- Enlace:
addyosmani.com/blog/claude-code-agent-teams - Descripción: Análisis de arquitectura y recomendaciones de mejores prácticas.
- Enlace:
-
Anuncio del lanzamiento de Claude Opus 4.6: Nota oficial de lanzamiento.
- Enlace:
anthropic.com/news/claude-opus-4-6 - Descripción: Presentación oficial de la función Agent Teams.
- Enlace:
Autor: Equipo de APIYI
Intercambio técnico: Te invitamos a discutir tu experiencia con Claude Agent Teams en la sección de comentarios. Para más recursos, visita la comunidad técnica de APIYI (apiyi.com).
