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 Agents Studio 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:
   • Agents Studio 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

| Nodo | Event key | Cuándo se dispara | | --- | --- | --- | | Agents Studio Call Started Trigger | call.callStarted | Una llamada (entrante o saliente) inicia | | Agents Studio Call Analyzed Trigger | call.callAnalyzed | El análisis post-llamada está disponible | | Agents Studio Transfer Bridged Trigger | call.transferBridged | Una transferencia se conecta con el destino |

Próximamente: trigger para call.callEnded y otros eventos del catálogo.

Acciones disponibles

| Nodo | Qué hace | | --- | --- | | Agents Studio Start Call | Lanza una llamada saliente desde un agente de voz |

Agents Studio 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).
• Campaign ID: UUID de la campaña a la que pertenece esta llamada (requerido por Agents Studio).
• Variables (opcional): pares clave-valor enviados al proveedor para personalizar la llamada (firstName, plan, etc.).
• 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.

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.
• HTTP Request estándar de n8n para llamar acciones puntuales como startCall (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: [email protected].
• 📚 Documentación de Agents Studio: https://docs.getsupervisor.ai.