Sub-agentes

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

Comando slash

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

  • /subagents list
  • /subagents kill <id|#|all>
  • /subagents log <id|#> [limit] [tools]
  • /subagents info <id|#>
  • /subagents send <id|#> <message>
  • /subagents steer <id|#> <message>
  • /subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]

Controles de vinculación a hilos:

Estos comandos funcionan en canales que admiten vinculaciones persistentes de hilos. Consulta Canales con soporte de hilos más abajo.

  • /focus <subagent-label|session-key|session-id|session-label>
  • /unfocus
  • /agents
  • /session idle <duration|off>
  • /session max-age <duration|off>

/subagents info muestra metadatos de la ejecución (estado, timestamps, id de sesión, ruta de transcripción, limpieza).

Comportamiento de spawn

/subagents spawn inicia un sub-agente en segundo plano como comando de usuario, no como un relay interno, y envía una actualización final de completado de vuelta al chat solicitante cuando la ejecución termina.

  • El comando spawn es no bloqueante; devuelve un id de ejecución inmediatamente.
  • Al completarse, el sub-agente anuncia un mensaje de resumen/resultado de vuelta al canal de chat solicitante.
  • Para spawns manuales, la entrega es resiliente:
    • OpenClaw intenta la entrega directa agent primero con una clave de idempotencia estable.
    • Si la entrega directa falla, recurre al enrutamiento por cola.
    • Si el enrutamiento por cola tampoco está disponible, el anuncio se reintenta con un backoff exponencial corto antes de abandonar definitivamente.
  • El traspaso de completado a la sesión solicitante es contexto interno generado en runtime (no texto escrito por el usuario) e incluye:
    • Result (texto de respuesta del assistant, o último toolResult si la respuesta del asistente está vacía)
    • Status (completed successfully / failed / timed out / unknown)
    • estadísticas compactas de runtime/tokens
    • una instrucción de entrega indicando al agente solicitante reescribir en voz normal de asistente (no reenviar metadatos internos crudos)
  • --model y --thinking sobreescriben los valores por defecto para esa ejecución específica.
  • Usa info/log para inspeccionar detalles y salida después del completado.
  • /subagents spawn es modo one-shot (mode: "run"). Para sesiones persistentes vinculadas a hilos, usa sessions_spawn con thread: true y mode: "session".
  • Para sesiones harness ACP (Codex, Claude Code, Gemini CLI), usa sessions_spawn con runtime: "acp" y consulta Agentes ACP.

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 sesiones + sandboxing opcional).
  • Mantener la superficie de herramientas difícil de mal usar: los sub-agentes no obtienen herramientas de sesión por defecto.
  • Admitir profundidad de anidamiento configurable para patrones de orquestador.

Nota de costos: cada sub-agente tiene su propio contexto y uso de tokens. Para tareas pesadas o repetitivas, configura un modelo más económico para sub-agentes y mantén tu agente principal en un modelo de mayor calidad. Puedes configurar esto con agents.defaults.subagents.model o sobreescrituras por agente.

Herramienta

Usa sessions_spawn:

  • Inicia una ejecución de sub-agente (deliver: false, lane global: subagent)
  • Luego ejecuta un paso de anuncio y publica la respuesta de anuncio en el canal de chat solicitante
  • Modelo por defecto: hereda del llamador a menos que configures agents.defaults.subagents.model (o por agente agents.list[].subagents.model); un sessions_spawn.model explícito sigue ganando.
  • Thinking por defecto: hereda del llamador a menos que configures agents.defaults.subagents.thinking (o por agente agents.list[].subagents.thinking); un sessions_spawn.thinking explícito sigue ganando.
  • Timeout de ejecución por defecto: si se omite sessions_spawn.runTimeoutSeconds, OpenClaw usa agents.defaults.subagents.runTimeoutSeconds cuando está configurado; de lo contrario recurre a 0 (sin timeout).

Parámetros de la herramienta:

  • task (obligatorio)
  • label? (opcional)
  • agentId? (opcional; genera bajo otro id de agente si está permitido)
  • model? (opcional; sobreescribe el modelo del sub-agente; valores inválidos se omiten y el sub-agente se ejecuta con el modelo por defecto con una advertencia en el resultado de la herramienta)
  • thinking? (opcional; sobreescribe el nivel de thinking para la ejecución del sub-agente)
  • runTimeoutSeconds? (por defecto agents.defaults.subagents.runTimeoutSeconds cuando está configurado, de lo contrario 0; cuando se configura, la ejecución del sub-agente se aborta después de N segundos)
  • thread? (por defecto false; cuando es true, solicita vinculación a hilo del canal para esta sesión de sub-agente)
  • mode? (run|session)
    • por defecto es run
    • si thread: true y se omite mode, el valor por defecto pasa a session
    • mode: "session" requiere thread: true
  • cleanup? (delete|keep, por defecto keep)
  • sandbox? (inherit|require, por defecto inherit; require rechaza el spawn a menos que el runtime hijo destino esté en sandbox)
  • sessions_spawn no acepta parámetros de entrega de canal (target, channel, to, threadId, replyTo, transport). Para entrega, usa message/sessions_send desde la ejecución generada.

Sesiones vinculadas a hilos

Cuando las vinculaciones de hilos están habilitadas para un canal, un sub-agente puede permanecer vinculado a un hilo para que los mensajes de seguimiento del usuario en ese hilo sigan enrutándose a la misma sesión del sub-agente.

Canales con soporte de hilos

  • Discord (actualmente el único canal admitido): admite sesiones de subagente persistentes vinculadas a hilos (sessions_spawn con thread: true), controles manuales de hilos (/focus, /unfocus, /agents, /session idle, /session max-age), y claves de adaptador channels.discord.threadBindings.enabled, channels.discord.threadBindings.idleHours, channels.discord.threadBindings.maxAgeHours y channels.discord.threadBindings.spawnSubagentSessions.

Flujo rápido:

  1. Genera con sessions_spawn usando thread: true (y opcionalmente mode: "session").
  2. OpenClaw crea o vincula un hilo a ese destino de sesión en el canal activo.
  3. Las respuestas y mensajes de seguimiento en ese hilo se enrutan a la sesión vinculada.
  4. Usa /session idle para inspeccionar/actualizar auto-unfocus por inactividad y /session max-age para controlar el límite máximo.
  5. Usa /unfocus para desvincular manualmente.

Controles manuales:

  • /focus <target> vincula el hilo actual (o crea uno) a un destino de sub-agente/sesión.
  • /unfocus elimina la vinculación del hilo vinculado actual.
  • /agents lista las ejecuciones activas y el estado de vinculación (thread:<id> o unbound).
  • /session idle y /session max-age solo funcionan para hilos vinculados enfocados.

Switches de configuración:

  • Valor global por defecto: session.threadBindings.enabled, session.threadBindings.idleHours, session.threadBindings.maxAgeHours
  • Las claves de sobreescritura de canal y auto-vinculación de spawn son específicas del adaptador. Consulta Canales con soporte de hilos más arriba.

Consulta Referencia de configuración y Comandos slash para detalles actuales del adaptador.

Lista de permitidos:

  • agents.list[].subagents.allowAgents: lista de ids de agente que pueden ser apuntados con agentId (["*"] para permitir cualquiera). Por defecto: solo el agente solicitante.
  • Protección de herencia de sandbox: si la sesión solicitante está en sandbox, sessions_spawn rechaza destinos que se ejecutarían sin sandbox.

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 (por defecto: 60).
  • El archivado usa sessions.delete y renombra la transcripción a *.deleted.<timestamp> (misma carpeta).
  • cleanup: "delete" archiva inmediatamente después del anuncio (aún conserva la transcripción mediante renombrado).
  • El auto-archivado es best-effort; 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.
  • El auto-archivado se aplica igualmente a sesiones de profundidad 1 y profundidad 2.

Sub-agentes anidados

Por defecto, los sub-agentes no pueden generar sus propios sub-agentes (maxSpawnDepth: 1). Puedes habilitar un nivel de anidamiento configurando maxSpawnDepth: 2, lo que permite el patrón orquestador: principal -> sub-agente orquestador -> sub-sub-agentes trabajadores.

Cómo habilitarlo

{
  agents: {
    defaults: {
      subagents: {
        maxSpawnDepth: 2, // permitir que sub-agentes generen hijos (por defecto: 1)
        maxChildrenPerAgent: 5, // máx. hijos activos por sesión de agente (por defecto: 5)
        maxConcurrent: 8, // límite de concurrencia global de lane (por defecto: 8)
        runTimeoutSeconds: 900, // timeout por defecto para sessions_spawn cuando se omite (0 = sin timeout)
      },
    },
  },
}

Niveles de profundidad

ProfundidadForma de la clave de sesiónRol¿Puede generar?
0agent:<id>:mainAgente principalSiempre
1agent:<id>:subagent:<uuid>Sub-agente (orquestador cuando profundidad 2 permitida)Solo si maxSpawnDepth >= 2
2agent:<id>:subagent:<uuid>:subagent:<uuid>Sub-sub-agente (trabajador hoja)Nunca

Cadena de anuncios

Los resultados fluyen hacia arriba en la cadena:

  1. El trabajador de profundidad 2 termina -> anuncia a su padre (orquestador de profundidad 1)
  2. El orquestador de profundidad 1 recibe el anuncio, sintetiza resultados, termina -> anuncia al principal
  3. El agente principal recibe el anuncio y entrega al usuario

Cada nivel solo ve anuncios de sus hijos directos.

Política de herramientas por profundidad

  • El rol y el alcance de control se escriben en los metadatos de sesión al momento del spawn. Esto evita que claves de sesión planas o restauradas recuperen accidentalmente privilegios de orquestador.
  • Profundidad 1 (orquestador, cuando maxSpawnDepth >= 2): Obtiene sessions_spawn, subagents, sessions_list, sessions_history para poder gestionar sus hijos. Otras herramientas de sesión/sistema permanecen denegadas.
  • Profundidad 1 (hoja, cuando maxSpawnDepth == 1): Sin herramientas de sesión (comportamiento actual por defecto).
  • Profundidad 2 (trabajador hoja): Sin herramientas de sesión — sessions_spawn siempre se deniega en profundidad 2. No puede generar más hijos.

Límite de spawn por agente

Cada sesión de agente (a cualquier profundidad) puede tener como máximo maxChildrenPerAgent (por defecto: 5) hijos activos a la vez. Esto previene la expansión descontrolada desde un solo orquestador.

Detención en cascada

Detener un orquestador de profundidad 1 detiene automáticamente todos sus hijos de profundidad 2:

  • /stop en el chat principal detiene todos los agentes de profundidad 1 y propaga a sus hijos de profundidad 2.
  • /subagents kill <id> detiene un sub-agente específico y propaga a sus hijos.
  • /subagents kill all detiene todos los sub-agentes del solicitante y propaga.

Autenticación

La autenticación de sub-agentes 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 auth se carga desde el agentDir de ese agente.
  • Los perfiles de auth del agente principal se fusionan como fallback; los perfiles del agente sobreescriben los del principal en conflictos.

Nota: la fusión es aditiva, así que los perfiles del principal siempre están disponibles como fallbacks. La autenticación completamente aislada por agente aún no está admitida.

Anuncio

Los sub-agentes reportan mediante un paso de anuncio:

  • El paso de anuncio se ejecuta dentro de la sesión del sub-agente (no de la sesión solicitante).
  • Si el sub-agente responde exactamente ANNOUNCE_SKIP, no se publica nada.
  • De lo contrario la entrega depende de la profundidad del solicitante:
    • las sesiones solicitantes de nivel superior usan una llamada agent de seguimiento con entrega externa (deliver=true)
    • las sesiones de subagente solicitantes anidadas reciben una inyección de seguimiento interna (deliver=false) para que el orquestador pueda sintetizar resultados de hijos dentro de la sesión
    • si una sesión de subagente solicitante anidada ya no existe, OpenClaw recurre al solicitante de esa sesión cuando está disponible
  • La agregación de completados de hijos tiene alcance de la ejecución actual del solicitante al construir hallazgos de completado anidados, evitando que salidas de hijos de ejecuciones anteriores se filtren al anuncio actual.
  • Las respuestas de anuncio preservan el enrutamiento de hilo/tema cuando está disponible en los adaptadores de canal.
  • El contexto de anuncio se normaliza a un bloque de evento interno estable:
    • origen (subagent o cron)
    • clave/id de sesión del hijo
    • tipo de anuncio + etiqueta de tarea
    • línea de estado derivada del resultado del runtime (success, error, timeout, o unknown)
    • contenido del resultado del paso de anuncio (o (no output) si falta)
    • una instrucción de seguimiento describiendo cuándo responder vs. permanecer en silencio
  • Status no se infiere de la salida del modelo; viene de señales del resultado del runtime.

Los payloads de anuncio incluyen una línea de estadísticas al final (incluso cuando están envueltos):

  • Runtime (ej., runtime 5m12s)
  • Uso de tokens (entrada/salida/total)
  • Costo estimado cuando los precios del modelo están configurados (models.providers.*.models[].cost)
  • sessionKey, sessionId y ruta de transcripción (para que el agente principal pueda obtener historial con sessions_history o inspeccionar el archivo en disco)
  • Los metadatos internos son solo para orquestación; las respuestas al usuario deben reescribirse en voz normal de asistente.

Política de herramientas (herramientas de sub-agente)

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

  • sessions_list
  • sessions_history
  • sessions_send
  • sessions_spawn

Cuando maxSpawnDepth >= 2, los sub-agentes orquestadores de profundidad 1 reciben adicionalmente sessions_spawn, subagents, sessions_list y sessions_history para poder gestionar sus hijos.

Sobreescritura por configuración:

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 1,
      },
    },
  },
  tools: {
    subagents: {
      tools: {
        // deny tiene prioridad
        deny: ["gateway", "cron"],
        // si allow está configurado, se convierte en allow-only (deny sigue ganando)
        // allow: ["read", "exec", "process"]
      },
    },
  },
}

Concurrencia

Los sub-agentes usan una lane de cola dedicada en proceso:

  • Nombre de lane: subagent
  • Concurrencia: agents.defaults.subagents.maxConcurrent (por defecto 8)

Detención

  • Enviar /stop en el chat solicitante aborta la sesión solicitante y detiene cualquier ejecución activa de sub-agente generada desde ella, propagando a hijos anidados.
  • /subagents kill <id> detiene un sub-agente específico y propaga a sus hijos.

Limitaciones

  • El anuncio de sub-agente es best-effort. Si el gateway se reinicia, el trabajo pendiente de “anunciar de vuelta” se pierde.
  • Los sub-agentes comparten los mismos recursos de proceso del gateway; trata maxConcurrent como una válvula de seguridad.
  • sessions_spawn siempre es no bloqueante: devuelve { status: "accepted", runId, childSessionKey } inmediatamente.
  • El contexto de sub-agente solo inyecta AGENTS.md + TOOLS.md (sin SOUL.md, IDENTITY.md, USER.md, HEARTBEAT.md ni BOOTSTRAP.md).
  • La profundidad máxima de anidamiento es 5 (rango de maxSpawnDepth: 1-5). Profundidad 2 es recomendada para la mayoría de los casos de uso.
  • maxChildrenPerAgent limita hijos activos por sesión (por defecto: 5, rango: 1-20).
arrow_back
Anterior
Agent Send
Siguiente
ACP Agents
arrow_forward