Sub-Agentes

Los sub-agentes son ejecuciones de agente en segundo plano generadas desde una ejecución de agente existente. Se ejecutan en su propia sesión (''agent:<agentId>:subagent:<uuid>'') y, cuando terminan, ''anuncian'' su resultado de vuelta al canal de chat del solicitante.

Usa ''/subagents'' para inspeccionar o controlar ejecuciones de sub-agente para la ''sesión actual'':

- ''/subagents list''

- ''/subagents stop <id|#|all>''

- ''/subagents log <id|#> [limit] [tools]''

- ''/subagents info <id|#>''

- ''/subagents send <id|#> <message>''

''/subagents info'' muestra metadatos de ejecución (estado, marcas de tiempo, id de sesión, ruta de transcripción, limpieza).

Objetivos principales:

- Paralelizar trabajo de "investigación / tarea larga / herramienta lenta" sin bloquear la ejecución principal.

- Mantener sub-agentes aislados por defecto (separación de sesión + sandboxing opcional).

- Mantener la superficie de herramientas difícil de usar incorrectamente: los sub-agentes no obtienen herramientas de sesión por defecto.

- Evitar fan-out anidado: los sub-agentes no pueden generar sub-agentes.

Nota de costo: cada sub-agente tiene su <strong>propio</strong> contexto y uso de tokens. Para tareas pesadas o repetitivas,

establece un modelo más económico para sub-agentes y mantén tu agente principal en un modelo de mayor calidad.

Puedes configurar esto via ''agents.defaults.subagents.model'' o anulaciones por agente.

Usa ''sessions_spawn'':

- Inicia una ejecución de sub-agente (''deliver: false'', carril global: ''subagent'')

- Luego ejecuta un paso de anuncio y publica la respuesta de anuncio al canal de chat del solicitante

- Modelo predeterminado: hereda del llamador a menos que establezcas ''agents.defaults.subagents.model'' (o por agente ''agents.list[].subagents.model''); un ''sessions_spawn.model'' explícito todavía gana.

Parámetros de herramienta:

- ''task'' (requerido)

- ''label?'' (opcional)

- ''agentId?'' (opcional; genera bajo otro id de agente si está permitido)

- ''model?'' (opcional; anula el modelo del sub-agente; valores inválidos se saltan y el sub-agente se ejecuta en el modelo predeterminado con una advertencia en el resultado de la herramienta)

- ''thinking?'' (opcional; anula el nivel de pensamiento para la ejecución del sub-agente)

- ''runTimeoutSeconds?'' (predeterminado ''0''; cuando está establecido, la ejecución del sub-agente se aborta después de N segundos)

- ''cleanup?'' (''delete|keep'', predeterminado ''keep'')

Lista permitida:

- ''agents.list[].subagents.allowAgents'': lista de ids de agente que pueden ser objetivo via ''agentId'' (''["*"]'' para permitir cualquiera). Predeterminado: solo el agente solicitante.

Descubrimiento:

- Usa ''agents_list'' para ver qué ids de agente están actualmente permitidos para ''sessions_spawn''.

Auto-archivado:

- Las sesiones de sub-agente se archivan automáticamente después de ''agents.defaults.subagents.archiveAfterMinutes'' (predeterminado: 60).

- El archivado usa ''sessions.delete'' y renombra la transcripción a ''*.deleted.<timestamp>'' (misma carpeta).

- ''cleanup: "delete"'' archiva inmediatamente después del anuncio (todavía mantiene la transcripción via renombrado).

- El auto-archivado es de mejor esfuerzo; los temporizadores pendientes se pierden si el gateway se reinicia.

- ''runTimeoutSeconds'' ''no'' auto-archiva; solo detiene la ejecución. La sesión permanece hasta el auto-archivado.

La autenticación del sub-agente se resuelve por id de agente, no por tipo de sesión:

- La clave de sesión del sub-agente es ''agent:<agentId>:subagent:<uuid>''.

- El almacén de autenticación se carga desde el ''agentDir'' de ese agente.

- Los perfiles de autenticación del agente principal se fusionan como un fallback; los perfiles del agente anulan los perfiles principales en conflictos.

Nota: la fusión es aditiva, así que los perfiles principales siempre están disponibles como fallbacks. Autenticación completamente aislada por agente no está soportada todavía.

Los sub-agentes reportan de vuelta via un paso de anuncio:

- El paso de anuncio se ejecuta dentro de la sesión del sub-agente (no la sesión del solicitante).

- Si el sub-agente responde exactamente ''ANNOUNCE_SKIP'', no se publica nada.

- De lo contrario la respuesta de anuncio se publica al canal de chat del solicitante via una llamada ''agent'' de seguimiento (''deliver=true'').

- Las respuestas de anuncio preservan el enrutamiento de hilo/tema cuando está disponible (hilos Slack, temas Telegram, hilos Matrix).

- Los mensajes de anuncio se normalizan a una plantilla estable:

- ''Status:'' derivado del resultado de la ejecución (''success'', ''error'', ''timeout'', o ''unknown'').

- ''Result:'' el contenido resumen del paso de anuncio (o ''(not available)'' si falta).

- ''Notes:'' detalles de error y otro contexto útil.

- ''Status'' no se infiere de la salida del modelo; viene de señales de resultado de runtime.

Las cargas útiles de anuncio incluyen una línea de estadísticas al final (incluso cuando están envueltas):

- Runtime (ej., ''runtime 5m12s'')

- Uso de tokens (entrada/salida/total)

- Costo estimado cuando el precio del modelo está configurado (''models.providers.*.models[].cost'')

- ''sessionKey'', ''sessionId'', y ruta de transcripción (para que el agente principal pueda obtener historial via ''sessions_history'' o inspeccionar el archivo en disco)

Por defecto, los sub-agentes obtienen todas las herramientas excepto herramientas de sesión:

- ''sessions_list''

- ''sessions_history''

- ''sessions_send''

- ''sessions_spawn''

Anular via config:

'{'
  agents: '{'
    defaults: '{'
      subagents: '{'
        maxConcurrent: 1,
      '}',
    '}',
  '}',
  tools: '{'
    subagents: '{'
      tools: '{'
        // deny wins
        deny: ["gateway", "cron"],
        // if allow is set, it becomes allow-only (deny still wins)
        // allow: ["read", "exec", "process"]
      '}',
    '}',
  '}',
'}'

Los sub-agentes usan un carril de cola dedicado en proceso:

- Nombre del carril: ''subagent''

- Concurrencia: ''agents.defaults.subagents.maxConcurrent'' (predeterminado ''8'')

- Enviar ''/stop'' en el chat del solicitante aborta la sesión del solicitante y detiene cualquier ejecución de sub-agente activa generada desde ella.

- El anuncio de sub-agente es de mejor esfuerzo. Si el gateway se reinicia, el trabajo pendiente de "anunciar de vuelta" se pierde.

- Los sub-agentes todavía comparten los mismos recursos de proceso del gateway; trata ''maxConcurrent'' como una válvula de seguridad.

- ''sessions_spawn'' siempre es no bloqueante: retorna '''{' status: "accepted", runId, childSessionKey '}''' inmediatamente.

- El contexto del sub-agente solo inyecta ''AGENTS.md'' + ''TOOLS.md'' (sin ''SOUL.md'', ''IDENTITY.md'', ''USER.md'', ''HEARTBEAT.md'', o ''BOOTSTRAP.md'').