Agentes Encadenados (Parent-Child)

Configura workflows donde un agente puede llamar a otro agente y esperar a que termine antes de continuar.

Conceptos Clave

JERARQUIA DE AGENTES

Accion trigger_agent

Configuracion Basica

{
  "actionType": "trigger_agent",
  "parameters": {
    "targetAgentId": 5,
    "waitForCompletion": true,
    "passVariables": ["postulantId", "applicationId"]
  }
}

Parametros

Comportamiento segun waitForCompletion

waitForCompletion: false (default)

El padre continua inmediatamente despues de disparar al hijo.

Flujo:

1. Padre ejecuta accion 1
2. Padre dispara trigger_agent
3. Hijo inicia en paralelo
4. Padre continua a accion 3 (sin esperar)
5. Hijo continua independientemente

Caso de uso: Tareas independientes que no dependen del resultado.

waitForCompletion: true

El padre espera hasta que el hijo termine completamente.

Flujo:

1. Padre ejecuta accion 1
2. Padre dispara trigger_agent con waitForCompletion=true
3. Hijo inicia y ejecuta sus acciones
4. Si hijo tiene wait_for_response, padre tambien espera
5. Cuando hijo termina, padre continua a accion 3

Caso de uso: Flujos secuenciales donde el siguiente paso depende del anterior.

Sincronizacion de Estados

Cuando el Hijo tiene Acciones de Espera

Si el hijo ejecuta acciones que requieren esperar (como wait_for_response):

Variables Disponibles Post-Ejecucion

Cuando el hijo termina, el padre recibe estas variables:

{
  "triggeredExecutionId": 123,      // ID de ejecucion del hijo
  "childExecutionStatus": "completed", // Estado final
  "childExecutionSuccess": true,     // Si fue exitoso
  // ... todas las variables del hijo
}

Cadenas de Agentes (Nesting)

El sistema soporta cadenas ilimitadas de agentes.

Ejemplo: Cadena de 3 Niveles

Coordinador (A)
├── Accion: Enviar bienvenida
├── Accion: trigger_agent (waitForCompletion=true)
│   └── Recolector de Docs (B)
│       ├── Accion: Solicitar documentos
│       ├── Accion: wait_for_response
│       └── Accion: trigger_agent (waitForCompletion=true)
│           └── Validador (C)
│               ├── Accion: Validar documentos
│               └── Accion: Enviar resultado
└── Accion: Continuar onboarding

Como se Desenrolla la Cadena

1. C termina - Emite evento AGENT_COMPLETED
2. B se reanuda - Recibe resultado de C, continua
3. B termina - Emite evento AGENT_COMPLETED
4. A se reanuda - Recibe resultado de B, continua
5. A termina - Flujo completo

Importante: Cada nivel solo conoce a su padre inmediato. La propagacion es automatica.

Herencia de Bloqueo de Thread

Cuando waitForCompletion=true, el hijo puede heredar el bloqueo del thread del padre.

Sin Herencia (waitForCompletion=false)

Padre tiene bloqueo del thread
↓
Hijo intenta enviar mensaje
↓
ERROR: Thread bloqueado por otra ejecucion
↓
Mensaje se encola para despues

Con Herencia (waitForCompletion=true)

Padre tiene bloqueo del thread
↓
Hijo hereda el bloqueo (canInheritLock=true)
↓
Hijo envia mensaje exitosamente
↓
Conversacion fluida

Ejemplo Practico: Onboarding Multi-Agente

Agente Coordinador

{
  "name": "Coordinador Onboarding",
  "actions": [
    {
      "actionType": "send_message",
      "parameters": {
        "message": "Bienvenido! Iniciemos tu proceso de ingreso."
      }
    },
    {
      "actionType": "trigger_agent",
      "parameters": {
        "targetAgentName": "Recolector Documentos",
        "waitForCompletion": true
      }
    },
    {
      "actionType": "trigger_agent",
      "parameters": {
        "targetAgentName": "Asignador Tests",
        "waitForCompletion": true
      }
    },
    {
      "actionType": "send_message",
      "parameters": {
        "message": "Excelente! Has completado todos los pasos."
      }
    }
  ]
}

Agente Recolector de Documentos

{
  "name": "Recolector Documentos",
  "actions": [
    {
      "actionType": "request_document",
      "parameters": {
        "documentTypes": ["ine", "curp", "comprobante_domicilio"]
      }
    },
    {
      "actionType": "wait_for_response",
      "parameters": {
        "waitFor": "document_completion",
        "timeout": "7 days"
      }
    }
  ]
}

Flujo Resultante

1. Coordinador envia bienvenida
2. Coordinador dispara Recolector y espera
3. Recolector solicita documentos
4. Recolector espera a que usuario suba docs
5. Usuario sube documentos
6. Recolector termina
7. Coordinador continua, dispara Asignador Tests
8. (similar para tests)
9. Coordinador envia mensaje de finalizacion

Debugging

Logs Importantes

[AgentExecution] Triggered agent 5 (Recolector), new execution 123
[AgentExecution] Awaiting child execution 123 to complete...
[AgentExecution] Child execution 123 is waiting, parent will also wait...
[AgentGraph] Emitting AGENT_COMPLETED event for execution 123
[AgentQueue] Received AGENT_COMPLETED event for execution 123
[AgentQueue] Parent 122 resumed immediately (bypassed polling)

Problemas Comunes

Proximos Pasos

• Bloqueo de Threads - Control de concurrencia
• Mensajes de Agente - Atribucion y notificaciones
• Logs de Ejecuciones - Monitoreo