Sub-agents: Tareas en segundo plano sin interrupciones

¿Te ha pasado que pides a tu agent que analice un log enorme y te toca esperar minutos sin poder hacer nada más? Es un cuello de botella común cuando intentas que una IA haga tareas complejas. La solución es delegar ese trabajo pesado a procesos que corran de fondo para que tú puedas seguir interactuando con el chat principal.

Requisitos previos

• Un agent configurado y listo para recibir instrucciones.
• Acceso al Gateway para la gestión de sesiones.

Inicio rápido

La forma más sencilla de usar sub-agents es pedirlo de forma natural en el chat:

“Spawn a sub-agent to research the latest Node.js release notes”

El agent ejecutará la herramienta sessions_spawn internamente. Cuando el sub-agent termine, publicará sus hallazgos directamente en tu chat.

También puedes definir opciones específicas si lo necesitas:

“Spawn a sub-agent to analyze the server logs from today. Use gpt-5.2 and set a 5-minute timeout.”

Cómo funciona

1. El agent principal inicia el proceso: Llama a sessions_spawn con la descripción de la tarea. Esta llamada es non-blocking, por lo que recibes un { status: "accepted", runId, childSessionKey } de inmediato.
2. Ejecución en segundo plano: Se crea una sesión aislada (agent:<agentId>:subagent:<uuid>) en una cola dedicada llamada subagent.
3. Anuncio de resultados: Al finalizar, el sub-agent envía sus conclusiones al chat original y el agent principal muestra un resumen.
4. Auto-archivado: La sesión del sub-agent se archiva automáticamente tras 60 minutos (puedes cambiar este valor).

Configuración

Los sub-agents funcionan sin configuración previa, pero te recomiendo ajustar el modelo para optimizar costes. Cada sub-agent consume sus propios tokens y tiene su propio contexto.

Definir un modelo por defecto

Usa un modelo más económico para los sub-agents y así ahorrar tokens:

{
  agents: {
    defaults: {
      subagents: {
        model: "minimax/MiniMax-M2.1",
      },
    },
  },
}

Configurar el nivel de Thinking

Puedes ajustar la intensidad del razonamiento:

{
  agents: {
    defaults: {
      subagents: {
        thinking: "low",
      },
    },
  },
}

Control de concurrencia

Si necesitas limitar cuántos sub-agents se ejecutan al mismo tiempo (el valor por defecto es 8):

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 4,
      },
    },
  },
}

Auto-archivado personalizado

Si quieres que las sesiones duren más tiempo antes de archivarse:

{
  agents: {
    defaults: {
      subagents: {
        archiveAfterMinutes: 120,
      },
    },
  },
}

Solución de problemas

• Los archivos de sesión no se borran: El sistema no elimina los transcripts, solo los renombra a *.deleted.<timestamp> en la misma carpeta para preservarlos.
• El temporizador de archivado falló: Ten en cuenta que los timers de auto-archive funcionan bajo el principio de “best-effort”. Si el Gateway se reinicia, los temporizadores pendientes se pierden.

¿Necesitas ayuda para configurar tus sub-agents? Prueba nuestro AI Setup Assistant.

Próximos pasos

• Setting a Default Model
• Multi-agent setups

Seguro que te ha pasado: intentas que un solo agent gestione un flujo de trabajo complejo y todo se vuelve un caos. El contexto se satura, las instrucciones se mezclan y el rendimiento cae. La mejor forma de solucionar esto es dividir el trabajo.

Delegar tareas a sub-agents especializados no es solo una opción, es la mejor estrategia para mantener la claridad. Con sessions_spawn, puedes estructurar tu lógica de forma jerárquica y eficiente.

Requisitos previos

• Configuración de agents activa en tu entorno.
• Permisos para ejecutar herramientas de sistema.

Inicio rápido

La herramienta sessions_spawn es lo que un agent utiliza para crear sub-agents. Aquí tienes los parámetros que acepta:

Parameter	Type	Default	Description
task	string	(required)	Qué debe hacer el sub-agent
label	string	—	Etiqueta corta para identificación
agentId	string	(caller’s agent)	Crear bajo un agent id diferente (debe estar permitido)
model	string	(optional)	Sobrescribir el modelo para este sub-agent
thinking	string	(optional)	Sobrescribir el nivel de thinking (off, low, medium, high, etc.)
runTimeoutSeconds	number	0 (no limit)	Abortar el sub-agent tras N segundos
cleanup	"delete" | "keep"	"keep"	"delete" archiva inmediatamente después del anuncio

Cómo se resuelve el modelo y el thinking

El sistema decide qué model usar siguiendo este orden de prioridad:

1. Parámetro model explícito en la llamada a sessions_spawn.
2. Configuración por agent: agents.list[].subagents.model.
3. Valor por defecto global: agents.defaults.subagents.model.
4. Resolución normal del modelo del agent de destino.

Para el nivel de thinking, el orden es similar:

1. Parámetro thinking explícito en la llamada a sessions_spawn.
2. Configuración por agent: agents.list[].subagents.thinking.
3. Valor por defecto global: agents.defaults.subagents.thinking.
4. Si no hay ninguno, no se aplica ninguna sobrescritura específica.

Cross-Agent Spawning

Normalmente, los sub-agents solo pueden crearse bajo su propio agentId. Si necesitas que un agent cree sub-agents usando otras identidades, debes configurar allowAgents:

{
  agents: {
    list: [
      {
        id: "orchestrator",
        subagents: {
          allowAgents: ["researcher", "coder"], // o ["*"] para permitir todos
        },
      },
    ],
  },
}

Te recomiendo usar la herramienta agents_list para descubrir qué IDs de agent están permitidos actualmente para sessions_spawn.

Solución de problemas

Valores de modelo inválidos Si envías un valor de model que no es válido, el sistema lo ignorará en silencio. El sub-agent se ejecutará usando el siguiente valor por defecto que sea válido y recibirás un warning en el resultado de la herramienta.

El sub-agent tarda demasiado Si una tarea se queda colgada, asegúrate de haber configurado runTimeoutSeconds. Si el valor es 0, el sub-agent no tiene límite de tiempo y podría consumir recursos innecesarios.

¿Necesitas ayuda para configurar tus agents? Prueba nuestro AI Setup Assistant.

Próximos pasos

• Uso de la herramienta agents_list
• Configuración avanzada de sub-agents

¿Alguna vez has lanzado varios procesos en segundo plano y has sentido que perdías el rastro de lo que ocurre? Es frustrante no saber si una tarea sigue ejecutándose, si se ha quedado bloqueada o cuánto presupuesto está consumiendo realmente. Gestionar múltiples sub-agents requiere visibilidad clara para mantener el control de tu flujo de trabajo.

Para solucionar esto, puedes usar el comando /subagents. Esta herramienta te permite auditar y manipular las ejecuciones de los sub-agents en tu sesión actual sin complicaciones.

Requisitos previos

• Una sesión activa donde se estén ejecutando sub-agents.
• Acceso a la interfaz de comandos de la plataforma.

Inicio rápido

Si necesitas tomar el control ahora mismo, sigue estos pasos:

1. Escribe /subagents list para ver todas las tareas activas y terminadas.
2. Identifica el ID o el índice de la tarea (por ejemplo, 1 o i9j0k1l2).
3. Si una tarea no responde, usa /subagents stop <id> para finalizarla de inmediato.

Comandos disponibles

Puedes referenciar a los sub-agents por su índice en la lista (1, 2), el prefijo de su ID de ejecución, la clave de sesión completa o usando la palabra last.

Command	Description
/subagents list	Lista todas las ejecuciones (activas y completadas)
/subagents stop <id|#|all>	Detiene un sub-agent en ejecución
/subagents log <id|#> [limit] [tools]	Muestra el transcript del sub-agent
/subagents info <id|#>	Muestra metadatos detallados de la ejecución
/subagents send <id|#> <message>	Envía un mensaje a un sub-agent en ejecución

Ejemplos de uso

Listar y detener tareas Usa este flujo para limpiar procesos innecesarios:

/subagents list

🧭 Subagents (current session)
Active: 1 · Done: 2
1) ✅ · research logs · 2m31s · run a1b2c3d4 · agent:main:subagent:...
2) ✅ · check deps · 45s · run e5f6g7h8 · agent:main:subagent:...
3) 🔄 · deploy staging · 1m12s · run i9j0k1l2 · agent:main:subagent:...

/subagents stop 3

⚙️ Stop requested for deploy staging.

Inspeccionar detalles Para entender qué está haciendo un sub-agent específico:

/subagents info 1

ℹ️ Subagent info
Status: ✅
Label: research logs
Task: Research the latest server error logs and summarize findings
Run: a1b2c3d4-...
Session: agent:main:subagent:...
Runtime: 2m31s
Cleanup: keep
Outcome: ok

Ver logs de ejecución Si necesitas ver los últimos 10 mensajes e incluir las llamadas a herramientas (tools):

/subagents log 1 10 tools

Enviar mensajes de seguimiento Puedes interactuar con un sub-agent que ya está corriendo. El sistema esperará hasta 30 segundos por una respuesta:

/subagents send 3 "Also check the staging environment"

Announce: Cómo regresan los resultados

Cuando un sub-agent termina su tarea, pasa por un paso de announce:

1. Se captura la respuesta final del sub-agent.
2. Se envía un mensaje de resumen a la sesión del agente principal con el resultado, estado y estadísticas.
3. El agente principal publica un resumen en lenguaje natural en tu chat.

Las respuestas de tipo announce mantienen el ruteo por hilos o temas (Slack threads, Telegram topics, Matrix threads) si están disponibles.

Estadísticas de Announce

Cada aviso incluye una línea de estadísticas con:

• Duración del tiempo de ejecución (runtime).
• Uso de tokens (input, output y total).
• Coste estimado (si configuraste los precios en models.providers.*.models[].cost).
• Clave de sesión, ID de sesión y ruta del transcript.

Estados de Announce

El estado que verás en el mensaje de announce proviene del resultado del runtime, no de lo que diga el modelo:

• successful completion (ok): La tarea terminó normalmente.
• error: La tarea falló (revisa los detalles del error en las notas).
• timeout: La tarea superó el tiempo definido en runTimeoutSeconds.
• unknown: No se pudo determinar el estado.

Si no necesitas un anuncio para el usuario, el paso de resumen del agente principal puede devolver NO_REPLY y no se publicará nada. Esto es distinto a ANNOUNCE_SKIP, que se usa específicamente en flujos de anuncio entre agentes (sessions_send).

Solución de problemas

Si encuentras problemas con tus sub-agents, revisa estos estados comunes:

• La tarea tarda demasiado: Verifica si el sub-agent ha entrado en un estado de timeout. Puedes ajustar el parámetro runTimeoutSeconds si la tarea es compleja.
• Estado unknown: Esto ocurre cuando el proceso se interrumpe de forma inesperada y el runtime no puede confirmar el resultado. Intenta ejecutar de nuevo o revisa los logs con /subagents log.
• Error en la ejecución: Si el estado es error, usa /subagents info para ver las notas adjuntas que explican el fallo técnico.

¿Necesitas ayuda para configurar tus agentes? Prueba nuestro AI Setup Assistant.

Próximos pasos

• Envío de mensajes entre sesiones (sessions_send)
• Configuración de costes de modelos

Seguro te ha pasado: le das una tarea a un sub-agent y termina intentando gestionar sesiones o tocar configuraciones del Gateway que no debería. Es frustrante cuando un proceso secundario se sale de su carril o intenta ejecutar acciones que solo el agente principal tiene permitido coordinar.

Para evitar este caos y mantener la seguridad, necesitas definir límites claros. La mejor forma de trabajar es restringir los permisos de los sub-agents para que se enfoquen exclusivamente en la tarea asignada sin comprometer el sistema.

Requisitos previos

• Un agente principal configurado y operativo.
• Archivos de configuración en formato JSON5.
• Acceso al agentDir para la gestión de perfiles de auth.
• Conocimiento de las herramientas (tools) disponibles en tu entorno.

Quick Start: Restricción de herramientas en 5 minutos

Por defecto, los sub-agents reciben todas las herramientas excepto un conjunto de herramientas denegadas. Estas se bloquean porque son inseguras o innecesarias para tareas en segundo plano:

Denied tool	Reason
sessions_list	Gestión de sesiones — el agente principal las orquestas
sessions_history	Gestión de sesiones — el agente principal las orquesta
sessions_send	Gestión de sesiones — el agente principal las orquesta
sessions_spawn	No se permite fan-out anidado (sub-agents no crean sub-agents)
gateway	Admin del sistema — peligroso desde un sub-agent
agents_list	Admin del sistema
whatsapp_login	Configuración interactiva — no es una tarea
session_status	Estado/programación — el agente principal coordina
cron	Estado/programación — el agente principal coordina
memory_search	Es mejor pasar info relevante en el prompt de spawn
memory_get	Es mejor pasar info relevante en el prompt de spawn

Personaliza las herramientas de tus sub-agents

Si necesitas que un sub-agent sea aún más restrictivo, puedes editar su configuración. Por ejemplo, para bloquear el acceso a la navegación web:

{
  tools: {
    subagents: {
      tools: {
        // deny siempre gana sobre allow
        deny: ["browser", "firecrawl"],
      },
    },
  },
}

Si prefieres un enfoque de “lista blanca” donde el sub-agent solo tenga acceso a lo estrictamente necesario para editar código, usa allow:

{
  tools: {
    subagents: {
      tools: {
        allow: ["read", "exec", "process", "write", "edit", "apply_patch"],
        // deny sigue ganando si se configura
      },
    },
  },
}

Nota: Las entradas personalizadas en deny se suman a la lista de denegación por defecto. Si usas allow, solo esas herramientas estarán disponibles, pero la lista de denegación por defecto se seguirá aplicando por encima.

Authentication y Contexto

La autenticación de los sub-agents se resuelve mediante el agent id, no por el tipo de sesión. Esto es lo que debes saber:

1. El almacén de auth se carga desde el agentDir del agente objetivo.
2. Los perfiles de auth del agente principal se mezclan como un fallback. Si hay conflictos, ganan los perfiles del agente objetivo.
3. Esta mezcla es aditiva; los perfiles principales siempre están disponibles si los específicos fallan.

En cuanto al contexto, los sub-agents operan con un sistema de prompts reducido para evitar que se confundan con el agente principal. Incluyen secciones de Tooling, Workspace y Runtime, además de AGENTS.md y TOOLS.md. Sin embargo, se omiten archivos de identidad como SOUL.md, IDENTITY.md o USER.md.

Solución de problemas

• El sub-agent intenta usar una herramienta prohibida: Revisa la lista de “Default denied tools”. No puedes habilitar herramientas como gateway o sessions_spawn para sub-agents por diseño de seguridad.
• Conflictos de autenticación: Recuerda que los perfiles del agente objetivo en su agentDir tienen prioridad. Si el sub-agent no usa las credenciales correctas, verifica los archivos en su directorio específico.
• Aislamiento de auth: Actualmente no se soporta el aislamiento total de auth por sub-agent. El fallback hacia el agente principal siempre está activo.
• El sub-agent actúa como el agente principal: Esto suele pasar si intentas pasarle demasiada información de identidad. El sistema está diseñado para que reciban un prompt enfocado en tareas; asegúrate de no incluir manualmente archivos como SOUL.md en su contexto.

¿Necesitas ayuda configurando tus políticas? Prueba nuestro AI Setup Assistant.

Próximos pasos

• AGENTS.md
• TOOLS.md

Seguro que te ha pasado: lanzas un proceso y, de repente, te das cuenta de que algo no va como esperabas. Quizás el agente entró en un bucle innecesario o simplemente ya no necesitas esa respuesta. Detener estas ejecuciones a tiempo es fundamental para no quemar créditos de API ni saturar tu Gateway.

Gestionar el ciclo de vida de tus Sub-Agents no tiene por qué ser un caos. Aquí te explico cómo mantener el control total sobre lo que se está ejecutando en tu sistema.

Requisitos previos

• Un Gateway configurado y en funcionamiento.
• Sub-Agents definidos en tu archivo de configuración.

Inicio rápido

Si necesitas detener procesos ahora mismo, tienes estas opciones principales. Te recomiendo usar los comandos manuales para control inmediato y los límites de tiempo para automatizar la seguridad:

1. Detención total: Escribe /stop en el chat. Esto aborta la sesión principal y, de paso, mata todas las ejecuciones de Sub-Agents activos que dependan de ella.
2. Detención selectiva: Usa /subagents stop <id>. Es ideal si solo quieres frenar un Sub-Agent específico sin cerrar tu sesión de chat principal.
3. Límites automáticos: Configura runTimeoutSeconds. El Sub-Agent se detendrá automáticamente cuando pase el tiempo que hayas definido.
4. Gestión de sesiones: Ten en cuenta que runTimeoutSeconds no archiva la sesión. La sesión se queda ahí hasta que salte el temporizador de archivo normal.

Full Configuration Example

Aquí tienes cómo integrar estas opciones en tu configuración de agentes. Fíjate especialmente en cómo limitamos la concurrencia y definimos los modelos para cada nivel:

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-sonnet-4" },
      subagents: {
        model: "minimax/MiniMax-M2.1",
        thinking: "low",
        maxConcurrent: 4,
        archiveAfterMinutes: 30,
      },
    },
    list: [
      {
        id: "main",
        default: true,
        name: "Personal Assistant",
      },
      {
        id: "ops",
        name: "Ops Agent",
        subagents: {
          model: "anthropic/claude-sonnet-4",
          allowAgents: ["main"], // ops puede generar sub-agents bajo "main"
        },
      },
    ],
  },
  tools: {
    subagents: {
      tools: {
        deny: ["browser"], // los sub-agents no pueden usar el browser
      },
    },
  },
}

Solución de problemas

Si algo no funciona como esperas al detener agentes, revisa estas limitaciones del sistema:

• Anuncios “Best-effort”: Si el Gateway se reinicia, cualquier aviso de anuncio pendiente se pierde.
• Sin anidamiento: Los Sub-Agents no pueden generar sus propios Sub-Agents. Si intentas forzar esto, fallará.
• Recursos compartidos: Todos los Sub-Agents corren en el proceso del Gateway. Usa siempre maxConcurrent como válvula de seguridad para no tumbar el servicio.
• Auto-archivo volátil: Los temporizadores de archivo pendientes se pierden si reinicias el Gateway.

¿Necesitas ayuda para configurar tus agentes o depurar un flujo complejo? Prueba el AI Setup Assistant.

Próximos pasos

• Session Tools — detalles sobre sessions_spawn y otras herramientas de sesión.
• Multi-Agent Sandbox and Tools — restricciones de herramientas por agente y sandboxing.
• Configuration — referencia completa de agents.defaults.subagents.
• Queue — cómo funciona el carril de subagent.