Agents Studio para n8n

Conecta n8n con Agents Studio sin escribir un solo HTTP Request. Arrastra un trigger, pega tu API Key y empieza a recibir eventos de tus llamadas en tiempo real.

¿Qué hace este paquete?

Cuando arrastras un nodo trigger de Agents Studio a un workflow y lo activas, n8n:

1. Crea automáticamente un webhook en tu workspace de Agents Studio.
2. Lo suscribe al evento que el nodo representa (call.callStarted, call.callEnded, etc.).
3. Empieza a entregarte cada evento como input del workflow.

Cuando borras el nodo o desactivas el workflow, el webhook y su suscripción se eliminan solos. Sin huérfanos, sin pasos manuales.

Requisitos

• n8n 1.0+ (Cloud, Desktop o Self-Hosted).
• Una API Key de Agents Studio con scope webhooks:write.
• Tu instancia de n8n debe ser accesible desde internet (URL pública). Esto es obligatorio: Agents Studio rechaza webhooks que apunten a localhost o IPs privadas.
  • n8n Cloud y Desktop ya cumplen esto.
  • Para self-hosted: despliega detrás de un dominio público o usa un túnel mientras desarrollas (ngrok, cloudflared, VS Code dev tunnels).

Instalación

1. En n8n ve a Settings → Community nodes → Install.
2. Escribe n8n-nodes-agents-studio y confirma.
3. Espera a que n8n descargue el paquete desde npm.

Self-hosted detrás de proxy: asegúrate de permitir @getsupervisor/agents-studio-sdk en tu allowlist de paquetes externos.

Configuración inicial (una sola vez)

1. Crea la credencial

1. Settings → Credentials → New y busca Leracom API.
2. Pega tu API Key (se identifica con el workspace automáticamente, no necesitas configurar workspace ID).
3. Click Save.

Por defecto la credencial siempre apunta a Production (https://api-prod.studio.getsupervisor.ai/v1). El selector de Environment con opciones Sandbox/Custom queda oculto y solo aparece si levantas n8n con AGENTS_STUDIO_DEV_MODE=true (ver sección Modo desarrollador).

2. Verifica que tu n8n tiene URL pública

Si vas a usar n8n self-hosted, define la variable de entorno antes de levantar n8n:

WEBHOOK_URL=https://tu-dominio-publico.com n8n start

Para desarrollo con VS Code dev tunnels:

WEBHOOK_URL=https://tu-tunnel-id-5678.use2.devtunnels.ms n8n start

n8n Cloud y Desktop lo gestionan solos.

Uso

1. Crea un workflow nuevo y arrastra el trigger que necesites:
   • Leracom Call Started Trigger — se dispara cuando una llamada inicia (call.callStarted).
2. En el panel del nodo, selecciona la credencial que creaste.
3. Click Execute workflow (modo prueba) o activa el workflow para producción.
4. n8n registra el webhook en Agents Studio en segundo plano y queda escuchando.
5. Cuando ocurra el evento, el payload llega al primer output del workflow como un item JSON normal.

Troubleshooting

"API Key inválida o expirada en Agents Studio"

La API Key no es válida o fue revocada. Genera una nueva desde Agents Studio → Workspace Settings → API Keys y reemplázala en la credencial de n8n.

"API Key sin permisos para gestionar webhooks (403 Forbidden)"

La API Key existe pero no tiene el scope webhooks:write. Genera una nueva marcando ese permiso al crearla y reemplázala en la credencial.

"Agents Studio no acepta la URL de webhook generada por n8n (no es pública)"

Tu instancia de n8n está corriendo en una URL no alcanzable desde internet (típicamente localhost). Soluciones:

• Despliega n8n en un dominio público (recomendado para producción).
• Para desarrollo local, levanta un túnel y arranca n8n con WEBHOOK_URL=https://tu-tunel.dominio/.
• Si usas n8n Cloud o Desktop, este error no debería aparecer.

El webhook no llega al workflow

1. Confirma que el evento ocurrió en tu workspace de Agents Studio (revisa el log de llamadas).
2. En Agents Studio → Webhooks, busca uno cuya descripción contenga n8n trigger · <evento> · workflow:<id>. Si no existe, n8n no logró registrarlo (revisa errores en el editor).
3. Revisa el panel Webhook Deliveries del webhook: ahí ves los reintentos y respuestas del endpoint de n8n.

Triggers disponibles

Próximamente: triggers para call.callEnded, whatsapp.messageDelivered y otros eventos del catálogo.

Acciones disponibles

Leracom Start Call

Configura los siguientes campos:

• Agent: dropdown que lista tus agentes de voz activos en el workspace. También puedes pegar un UUID directo en modo "By ID" o usar una expresión n8n.
• To: número destinatario en formato E.164 (+525538808448).
• Variables: se prellenan automáticamente desde el blueprint del agente — n8n muestra un campo por cada variable que espera el prompt ({{...}}) y solo rellenas los valores. Las variables se leen siempre de la versión actual del agente (la publicada o el último borrador, resuelta vía GET /agents/:id); no necesitas elegir versión. Se envían como args.variables. Requiere que la API Key porte los scopes agents:read y agent-blueprints:read. Si el agente no tiene variables, no se muestra ninguna.
• Additional Options → Campaign (opcional): dropdown que carga dinámicamente las campañas del agente seleccionado (requiere scope campaigns:read en la API Key). La campaña es opcional; si no eliges ninguna, la llamada se lanza sin asociarse a una campaña. Solo aparece cuando abres Additional Options, así que no estorba si no la necesitas.
• Additional Options → Idempotency Key (opcional): si lo proporcionas, evita llamadas duplicadas si el workflow se reintenta. Si lo dejas vacío, se genera un UUID v4 nuevo por ejecución.

El nodo retorna el response crudo del API: { status, result: { callId, status }, metadata, toolId, toolAgentConnectionId, toolExecutionId }. Procesa los campos que necesites con un Set node siguiente.

Leracom Send WhatsApp

Envía un mensaje de WhatsApp saliente a través del tool chatbot.chat (proveedor Kapso). Configura:

• Agent: dropdown que lista tus agentes de chat activos en el workspace. También puedes pegar un UUID directo en modo "By ID" o usar una expresión n8n.
• To: número del destinatario en formato E.164 (+525538808448).
• Message (opcional): texto libre. Solo se entrega si la conversación está dentro de la ventana de 24h de WhatsApp; fuera de ella debes usar una plantilla. Máximo 4000 caracteres.
• Template Name (opcional): nombre de la plantilla HSM aprobada. Si lo defines, el envío se hace por plantilla (obligatorio fuera de la ventana de 24h).
• Variables (opcional): pares clave-valor que rellenan los placeholders {{...}} de la plantilla.
• Additional Options → Idempotency Key (opcional): evita mensajes duplicados si el workflow se reintenta. Si lo dejas vacío, se genera un UUID v4 nuevo por ejecución.

Debes proporcionar Message o Template Name (al menos uno). El nodo retorna el response crudo del API igual que Start Call.

Compatibilidad y breaking changes

v2.0.0 rediseña el paquete por completo. Si vienes de v1.x, los nodos Agents Studio, Agents Studio Agents, Agents Studio Tools y Agents Studio Webhooks desaparecieron. Reemplázalos por:

• Triggers (este paquete) para escuchar eventos.
• Nodos de acción de este paquete (Leracom Start Call, Leracom Send WhatsApp) para ejecutar acciones puntuales.
• HTTP Request estándar de n8n solo para endpoints del API que aún no tengan nodo dedicado (puedes ver la doc del API en Agents Studio).

Las credenciales agentsStudioApi siguen llamándose igual, pero el campo Workspace ID fue removido (la API Key ya identifica el workspace).

Modo desarrollador

Por defecto la credencial siempre apunta a Production y el campo Environment queda oculto. Esto evita que un usuario final apunte por accidente a Sandbox o a una URL ajena.

Si necesitas que aparezca el selector con Sandbox y Custom (para QA, staging o desarrollo interno), levanta n8n con la variable AGENTS_STUDIO_DEV_MODE=true:

AGENTS_STUDIO_DEV_MODE=true \
  WEBHOOK_URL=https://tu-dominio-publico.com \
  n8n start

El cambio se aplica al cargar n8n; reinicia el proceso después de cambiar el valor.

Soporte

• 🐛 Bugs / feature requests: abre un issue en https://github.com/julio-supervisor/agents-studio-be (carpeta apps/public-api/integrations/n8n-code).
• 💬 Soporte comercial: hola@getsupervisor.ai.
• 📚 Documentación de Agents Studio: https://docs.getsupervisor.ai.