Agent Teams - Orquestación de equipos de sesiones de Claude Code

• Función experimental para organizar varias instancias de Claude Code como un solo equipo y distribuir y coordinar trabajo en paralelo; la sesión líder crea a los miembros, asigna tareas y sintetiza los resultados
• A diferencia de los subagentes existentes, permite intercambio directo de mensajes entre miembros del equipo, y el usuario también puede comunicarse directamente con miembros individuales sin pasar por el líder
• Es eficaz para revisión de código, exploración paralela de hipótesis de depuración y trabajo entre capas como frontend, backend y pruebas; para trabajo secuencial o edición del mismo archivo, una sola sesión sigue siendo más adecuada
• Como cada miembro tiene su propia ventana de contexto independiente, el uso de tokens aumenta considerablemente y el costo puede crecer en proporción al número de integrantes
• Soporta modo de pantalla dividida mediante tmux o iTerm2, y ayuda a mejorar la productividad y calidad en tareas de desarrollo complejas mediante exploración paralela y automatización de la colaboración

---

Resumen de Agent Teams

• Coordina varias sesiones de Claude Code como un equipo único para ejecutar trabajo en paralelo
  • El líder del equipo distribuye las tareas y sintetiza los resultados
  • Cada integrante se ejecuta de forma independiente en su propia ventana de contexto
• A diferencia de Subagent, los integrantes pueden enviarse mensajes directamente
• Es una función experimental y viene desactivada por defecto; se activa configurando la variable de entorno CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

Cuándo conviene usar Agent Teams

• Investigación y revisión: varios integrantes examinan al mismo tiempo distintos aspectos de un problema, luego comparten resultados y se validan entre sí
• Desarrollo de un nuevo módulo o funcionalidad: cada integrante se encarga de archivos o módulos distintos para trabajar en paralelo sin conflictos
• Depuración basada en hipótesis en competencia: se prueban distintas hipótesis al mismo tiempo para encontrar la causa más rápido
• Coordinación entre capas: se asignan integrantes por capa, como frontend, backend y pruebas, para hacer cambios simultáneos
• Para trabajo secuencial, edición del mismo archivo o tareas con muchas dependencias, una sola sesión o los subagentes suelen ser más eficientes

Subagent vs. Agent Team

• Subagente: tiene su propia ventana de contexto, pero solo devuelve resultados al llamador; el agente principal administra todo el trabajo y el costo en tokens es relativamente bajo
• Equipo de agentes: tiene ventanas de contexto completamente independientes, permite mensajería directa entre integrantes y se coordina por sí mismo con una lista de tareas compartida; como cada integrante es una instancia separada de Claude, el costo en tokens es mayor
• Para trabajo enfocado donde solo se necesita el resultado, convienen los subagentes; para trabajo complejo que requiere discusión y colaboración entre integrantes, conviene un equipo de agentes

Primer inicio de un equipo de agentes

• Por defecto está desactivado; se activa configurando la variable de entorno CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS en 1 o agregando esa variable en settings.json
• Después de activarlo, describe en lenguaje natural la estructura del equipo y el trabajo, y Claude creará el equipo y lanzará a los integrantes mientras coordina la ejecución

  • I'm designing a CLI tool that helps developers track TODO comments across their codebase. Create an agent team to explore this from different angles: one teammate on UX, one on technical architecture, one playing devil's advocate.

  • Diseñar una herramienta CLI para rastrear TODOs, haciendo que tres integrantes exploren de forma independiente UX, arquitectura técnica y una postura crítica, y luego sintetizar los resultados
  • Con esto, Claude intentará crear la lista de tareas compartida, generar a los integrantes, hacer que exploren cada problema, sintetizar los resultados y limpiar el equipo al terminar
• En la terminal del líder se muestra la lista completa de integrantes y el estado de las tareas, y puedes seleccionar integrantes con Shift+Up/Down para enviar mensajes directos

Control del equipo de agentes

• Elegir modo de visualización

  • Modo in-process: todos los integrantes se ejecutan dentro de la terminal principal; se puede seleccionar integrantes con Shift+Up/Down y enviar mensajes, sin configuración adicional
  • Modo split panes: cada integrante aparece en un panel separado y se puede ver la salida al mismo tiempo; requiere tmux o iTerm2
  • El valor predeterminado "auto" usa split pane si se está ejecutando dentro de una sesión de tmux; en caso contrario, usa in-process
  • La configuración "tmux" activa el modo split-pane y detecta automáticamente tmux e iTerm2
  • Puede sobrescribirse con teammateMode en settings.json o usar la bandera claude --teammate-mode in-process para forzar una sola sesión

• Especificar integrantes y modelo

  • Claude decide automáticamente cuántos integrantes necesita según la tarea, pero se puede indicar la cantidad exacta y el modelo (por ejemplo, Sonnet) con instrucciones como "Create a team with 4 teammates"

• Exigir aprobación del plan

  • En tareas complejas o riesgosas, se puede aplicar a los integrantes un modo de plan solo lectura para bloquear la implementación hasta que el líder apruebe
  • Cuando un integrante termina el plan, envía una solicitud de aprobación al líder; si el líder aprueba, comienza la implementación, y si la rechaza, vuelve a enviar una versión con los comentarios incorporados
  • Los criterios del líder pueden condicionarse desde el prompt (por ejemplo, "approve only plans that include test coverage")

• Modo delegate

  • En vez de implementar directamente, el líder queda restringido a usar solo herramientas de coordinación (crear integrantes, enviar mensajes, finalizar, administrar tareas)
  • Después de iniciar el equipo, presiona Shift+Tab para cambiar al modo delegate

• Conversación directa con integrantes

  • Como cada integrante es una sesión completamente independiente de Claude Code, se le pueden enviar directamente instrucciones adicionales, preguntas de seguimiento o cambios de enfoque
  • En modo in-process, se seleccionan con Shift+Up/Down y se envían mensajes; Enter permite ver la sesión, Escape interrumpe el turno actual y Ctrl+T alterna la lista de tareas
  • En modo split-pane, basta con hacer clic en el panel correspondiente para interactuar directamente

• Asignación y toma de tareas

  • Todo el equipo se coordina mediante una lista de tareas compartida, con estados pending, in progress y completed
  • Se pueden establecer dependencias entre tareas, y una tarea con dependencias no resueltas no puede ser tomada
  • El líder puede asignar tareas explícitamente, o un integrante puede tomar automáticamente la siguiente tarea no asignada y no bloqueada al terminar la suya
  • Para evitar que varios integrantes tomen la misma tarea al mismo tiempo, se usan bloqueos de archivos

• Finalizar integrantes y limpiar el equipo

  • Si se pide al líder finalizar a un integrante específico, ese integrante puede aprobar o rechazar la solicitud explicando el motivo
  • Al limpiar el equipo, el líder elimina los recursos compartidos; si quedan integrantes activos, la limpieza falla, así que primero hay que cerrarlos

Cómo funciona internamente el equipo de agentes

• Rutas para iniciar un equipo

  • El usuario solicita el equipo: describe una tarea adecuada para trabajo paralelo y pide explícitamente crear un equipo de agentes
  • Claude propone el equipo: si Claude considera que la tarea se beneficia del procesamiento paralelo, propone crear el equipo y continúa solo tras la confirmación del usuario
  • En ambos casos, el equipo no se crea sin aprobación del usuario

• Componentes de la arquitectura

  • Team lead: la sesión principal de Claude Code, encargada de crear el equipo, lanzar integrantes y coordinar el trabajo
  • Teammates: instancias separadas de Claude Code que ejecutan las tareas que se les asignan
  • Task list: lista compartida de tareas que los integrantes toman y completan
  • Mailbox: sistema de mensajería para comunicación entre agentes
  • Las dependencias de tareas se administran automáticamente; cuando un integrante completa una tarea, las tareas bloqueadas se desbloquean sin intervención manual
  • La configuración del equipo se guarda localmente en ~/.claude/teams/{team-name}/config.json, y la lista de tareas en ~/.claude/tasks/{team-name}/
  • La configuración incluye un arreglo members con el nombre, ID de agente y tipo de agente de cada integrante

• Permisos

  • Los integrantes inician heredando la configuración de permisos del líder; si el líder se ejecuta con --dangerously-skip-permissions, todos los integrantes reciben la misma configuración
  • Se puede cambiar el modo de un integrante después de lanzarlo, pero no se pueden definir permisos individuales al momento de crearlo

• Contexto y comunicación

  • Cada integrante tiene su propia ventana de contexto independiente y, al lanzarse, carga el mismo contexto del proyecto que una sesión normal, incluyendo CLAUDE.md, servidor MCP y skills
  • El historial de conversación del líder no se transmite a los integrantes; solo se les pasa el prompt de creación
  • Entrega automática de mensajes: los mensajes enviados por un integrante se entregan automáticamente al destinatario, sin que el líder tenga que hacer polling
  • Notificación de inactividad: cuando un integrante termina su trabajo y se detiene, el líder recibe una notificación automática
  • Lista de tareas compartida: todos los agentes pueden ver el estado de las tareas y tomar trabajo disponible
  • Existen dos formas de mensajería: message (a un integrante específico) y broadcast (a todo el equipo, con un costo proporcional al tamaño del equipo, por lo que conviene usarlo con moderación)

• Uso de tokens

  • Los equipos de agentes aumentan considerablemente el uso de tokens frente a una sola sesión, y ese costo crece en proporción al número de integrantes activos
  • En investigación, revisión y desarrollo de nuevas funciones, ese costo adicional suele justificarse; para tareas rutinarias, una sola sesión es más rentable

Casos de uso

• Revisión de código en paralelo

  • Un solo revisor tiende a concentrarse en un solo tipo de problema a la vez, por lo que conviene dividir los criterios de revisión en dominios independientes como seguridad, rendimiento y cobertura de pruebas
  • Cada revisor aplica un filtro distinto al mismo PR y, al finalizar, el líder sintetiza el resultado completo

• Investigación basada en hipótesis en competencia

  • Un solo agente tiende a dejar de explorar en cuanto encuentra una explicación, por eso conviene estructurar explícitamente al equipo de forma adversarial
  • Cada integrante investiga su propia hipótesis mientras intenta refutar las teorías de los demás, en una dinámica de debate científico
  • Esto ayuda a evitar el sesgo de anclaje que aparece en investigaciones secuenciales y aumenta la probabilidad de que la teoría sobreviviente sea la causa raíz real

Buenas prácticas

• Dar suficiente contexto a los integrantes: el contexto del proyecto se carga automáticamente, pero el historial del líder no se comparte, así que el prompt de creación debe incluir detalles relevantes de la tarea
• Ajustar bien el tamaño de las tareas: si son demasiado pequeñas, la sobrecarga de coordinación supera la ventaja; si son demasiado grandes, se corre el riesgo de desperdiciar tiempo por trabajar mucho sin puntos de control; convienen unidades autocontenidas que produzcan entregables claros, como funciones, archivos de prueba o revisiones
• Si el líder empieza a implementar directamente en lugar de esperar a los integrantes, se le indica: Wait for your teammates to complete their tasks before proceeding
• Al usarlo por primera vez, conviene empezar con tareas de investigación y revisión de límites claros y sin escritura de código, como revisión de PR, investigación de librerías o investigación de bugs
• Evitar conflictos de archivos: si dos integrantes editan el mismo archivo, pueden sobrescribirse entre sí, por lo que conviene dividir el trabajo para que cada uno se encargue de conjuntos de archivos distintos
• Revisar periódicamente el progreso de los integrantes, redirigir enfoques que no estén funcionando y sintetizar resultados apenas vayan apareciendo

Solución de problemas

• Si no aparecen integrantes: en modo in-process usa Shift+Down para recorrer los integrantes activos, verifica que la tarea sea lo bastante compleja para justificar un equipo y, si pediste split pane, confirma que tmux esté instalado y en PATH; en iTerm2, verifica que esté instalado el CLI it2 y habilitada la Python API
• Demasiados prompts de permisos: las solicitudes de permisos de los integrantes escalan al líder, así que conviene preaprobar tareas comunes en la configuración de permisos antes de lanzarlos
• Un integrante se detiene tras un error: revisa su salida y dale instrucciones adicionales directamente, o lanza un integrante de reemplazo para continuar la tarea
• El líder termina antes de que acabe el trabajo: indícale que continúe o configúralo para esperar a que los integrantes terminen antes de delegar
• Sesiones tmux huérfanas: si quedan sesiones de tmux tras cerrar el equipo, verifícalas con tmux ls y elimínalas con tmux kill-session -t <session-name>

Restricciones

• No se pueden restaurar integrantes in-process: /resume y /rewind no restauran integrantes in-process, y después de restaurar el líder podría intentar enviar mensajes a integrantes que ya no existen, por lo que habrá que lanzar nuevos
• Retraso en el estado de tareas: si un integrante no marca su tarea como completada, una tarea dependiente puede quedar bloqueada; se puede actualizar el estado manualmente o pedir al líder que le recuerde hacerlo
• Demora al finalizar: un integrante solo se cierra después de terminar la solicitud actual o la llamada de herramienta en curso
• Solo se permite un equipo por sesión: para iniciar uno nuevo, primero hay que limpiar el equipo actual
• No se permiten equipos anidados: los integrantes no pueden crear su propio equipo ni lanzar otros integrantes; solo el líder puede administrarlo
• Líder fijo: la sesión que crea el equipo es el líder permanente de ese equipo; no se puede promover a un integrante a líder ni transferir el liderazgo
• Permisos unificados al crear integrantes: todos los integrantes empiezan con el mismo modo de permisos del líder y no se pueden configurar permisos por integrante en el momento del lanzamiento
• Split pane requiere tmux o iTerm2: el modo split-pane no es compatible con la terminal integrada de VS Code, Windows Terminal ni Ghostty

[kuthia]

Parece que, para la orquestación de múltiples agentes, va a ser importante cómo se preservan los resultados semánticos durante el proceso de compresión del contexto. Se siente como ciencia cognitiva.

[GN⁺]

Opiniones de Hacker News

• Es interesante que la innovación del último año haya estado enfocada principalmente en la ingeniería
  Han aparecido muchos conceptos nuevos como MCP, agent y skill, pero los problemas fundamentales como las alucinaciones, la inexactitud y el colapso de contexto siguen sin resolverse
  Parece que este tipo de problemas solo se podrá resolver con investigación básica, no solo con ingeniería
  Las mejoras y anuncios actuales se sienten como parte de un ciclo de hype para mantener las expectativas de los inversionistas
  Sinceramente, ya me cansó la narrativa de la IA y quisiera que pasáramos rápido al punto en que quede claro para qué sirve realmente esta tecnología

• Aunque estas funciones se ven geniales, me pregunto cuánta gente puede realmente tener agents corriendo todo el día
  Usando Cursor, el consumo de tokens era tan alto que terminé cambiándome a Ultra, pero siento que el uso no escala de manera proporcional
  Por suerte, el ecosistema de los LLM de código abierto está avanzando rápido, así que hay motivos para tener esperanza

  • Yo ni siquiera agoto el límite mensual de 200 usos de Claude Max. Programo todos los días y hago tareas bastante pesadas, y aun así no llego
  • En realidad esto sigue estando en fase experimental, así que podría fracasar como Gas Town
  • Muchas empresas pueden contratar a un ingeniero junior de 150 mil dólares al año. Si la suscripción de IA cuesta más que eso, hay un problema
    Además, aquí no estamos hablando de Cursor sino de Claude Code. Yo más bien recomendaría probar Claude Max
  • Los únicos que probablemente puedan tener esto corriendo todo el día son las startups de dos personas financiadas por VC
  • Claude Code Max ofrece 30 veces más valor por token, así que si no lo aprovechas es problema tuyo. Incluso podría salir más barato que la luz

• Hace tiempo Steve Yegge le había propuesto a empresas como Anthropic la idea de un agent orchestrator
  (Welcome to Gas Town)
  Viendo que Anthropic ahora lanzó Agent Teams, parece que ya venían preparándolo desde entonces o llegaron a la misma conclusión
  De cualquier forma, es interesante porque la visión de Steve quedó validada. Tal vez pronto llegue la temporada de “domar al polecat”

  • Yo tampoco conocía GasTown ni Beeds, pero construí algo parecido. Era el siguiente paso natural
    claude-code-orchestrator
  • Yo también armé una estructura simple de equipo de agents antes de todo el furor por GasTown. Corría varias instancias de Claude en sesiones de tmux y las sincronizaba con .claude.lock
    Funcionaba bastante bien, pero todavía no es eficiente. Los cuellos de botella son la velocidad para redactar especificaciones y la calidad del QA
  • En realidad, este tipo de estructura ya existía en los frameworks de actores. Comparado con sistemas como Akka, no hay nada nuevo
    Ver que los proveedores de LLM apenas estén aprendiendo esto da la impresión de que siguen creciendo en tiempo real
    Decir que es Kubernetes for agents tampoco es una exageración. Yo también lo conecto así en local
  • No creo que los ingenieros de Anthropic no conocieran estas ideas. Desde los primeros tiempos de ChatGPT ya se hablaba mucho de esto
  • En realidad, este tipo de sistemas multi-agent ya abundaban en arXiv y GitHub desde 2023
    En ese momento los modelos eran menos inteligentes y la ventana de contexto era más pequeña; ahora simplemente ya es viable

• Yo ya venía usando un flujo de trabajo en el que varias instancias de Claude Code colaboran como CLI agents basados en tmux
  Esta función de orchestration es mucho más útil porque comparte una lista común de tareas y el agent principal coordina todo
  Con la herramienta tmux-cli se puede automatizar la colaboración entre agents

• No lo había aprendido hasta ahora porque era obvio que en algún momento esto iba a venir integrado por defecto, pero parece que ya llegó la hora de probarlo

• Me preocupa que mi suscripción de $20 al mes no vaya a durar ni 10 minutos

  • Si lo vas a pagar de tu bolsillo, tiene más sentido usar Kimi o GLM
  • Pienso lo mismo. Tengo dudas de si esta estructura realmente puede generar valor
  • En ciertas tareas, Haiku me ha dado resultados bastante buenos

• Esto se parece a Gas Town

  • Si un proyecto se vuelve demasiado extraño o juguetón, al final es muy probable que aparezca un clon menos ridículo y gane
  • Pero entonces, ¿qué pasó con el polecat? Me intriga el sentido del humor del mercado
  • No sé qué es Gas Town, pero yo ya venía usando una estructura parecida a Claude Code Agent Teams
    Si generas subagents desde la conversación principal y divides el trabajo, puedes trabajar por mucho tiempo sin perder contexto
  • El diseño se ve más simple. Un agent líder y varios workers; es más limpio que el sistema de roles complejo de Gas Town
  • Pero sí da pena que no haya polecat

• Yo no puedo dejarle a Claude Code trabajos grandes de forma autónoma
  Para mantener la calidad del código, tengo que intervenir directamente en el proceso de diseño
  Un equipo de agents más bien parece que solo aumentaría la carga de revisión y refactorización

  • Si codificas como skills la estructura del codebase y las reglas de uso de patrones, puedes hacer que los subagents sean supervisados con eso
    Justamente esa es la esencia de esta función: dividir y hacer colaborar a agents de planeación, diseño, QA y revisión
  • También hay una forma de mejorar la calidad creando un modelo adversarial dentro de Claude. Un agent hace cambios y otro los valida
  • Así como los humanos dividimos los trabajos grandes, también es eficiente hacer que Claude establezca planes y criterios de prueba
  • En la práctica, una de cada 3 o 4 veces hace falta ajustar o detener el proceso. Solo alguien con experiencia se da cuenta de eso
  • También hay investigación en curso sobre cómo los LLM dividen tareas y combinan resultados
    Artículo relacionado

• Estoy buscando una orquestación multi-LLM donde use Opus como principal y Gemini o Codex como subagents

  • Hay herramientas que soportan esta estructura, como Coder-Codex-Gemini, ccg-workflow, claude_code_bridge
    Todos son proyectos hechos por desarrolladores chinos, pero por lo que probé están bastante bien
  • Con AgentWorkforce/relay puedes elegir el LLM que quieras como líder/orquestador
    Resumí mi experiencia en este post de Twitter
  • Yo programo con Opus y hago review con Codex. En cada tarea llamo una review skill para ejecutar Codex
    Código de la review skill, y también uso el analizador de PR de Greptile
  • Sería muy útil si en el futuro Cursor soporta este tipo de colaboración entre múltiples modelos
  • Como en este ejemplo de Pied-Piper,
    también se puede usar GPT-5.2 Codex Max para planear, Opus 4.5 para implementar y Gemini para revisar

• Mientras construía una alternativa a Beads, terminé completando un sistema de agents sincronizado con proyectos de GitHub usando una estructura similar
  Pienso liberarlo como open source pronto, y a largo plazo creo que será más útil si se integra con un sistema de tickets
  Es deseable que aparezcan más alternativas agnósticas que no dependan de un agent específico