n8n-nodes-orbital

Nodo de n8n para ejecutar agentes IA y llamadas LLM directas en Orbital (Fractalia) desde cualquier workflow.

v3.0.3 — URL base hardcoded (zero-config). Fix envelope en getExecution y endpoint correcto en getJob. Auto-emit de steps en modelo plano con ai.tools[] inline (breaking change respecto a v2.x — ver Migración).

Instalación

npm install n8n-nodes-orbital

O desde la UI de n8n: Settings → Community Nodes → Install → n8n-nodes-orbital.

Concepto

Este es el nodo "de entrada" a Orbital como cliente: desde n8n invocas agentes IA (sync o async), consultas jobs pendientes, lanzas llamadas compact al LLM y descubres agentes disponibles en el proyecto.

Dirección del flujo: n8n → Orbital. Usa API Key (oapi_) para clientes B2B autónomos, o JWT (eyJ) cuando el flujo está ejecutando como Action de Orbital.

Zero-config (v3.0.3)

El nodo no requiere configurar URL base. Apunta a producción de Orbital internamente (api.orbital.fractaliacyber.com). El técnico solo configura:

1. Autenticación — API Key / JWT manual, o Credential guardado.
2. Campos de la operación (Agent ID, mensaje, etc.).

Complementario con n8n-nodes-orbital-actions

| Paquete | Dirección | Uso | |---|---|---| | n8n-nodes-orbital (este) | n8n → Orbital | Invocar agentes IA / compact / polling | | n8n-nodes-orbital-actions | n8n → Orbital (callbacks) | Reportar progreso/steps en flujos lanzados por Orbital |

Cuando se combinan, el nodo Orbital Process puede emitir automáticamente un step en el job padre tras ejecutar el agente (ver sección Auto-emit de steps).

Operaciones disponibles

| Operación | Endpoint | Uso | |---|---|---| | Ejecutar Agente (Sync) | POST /public/api/agents/:id/process | Ejecuta un agente, espera respuesta completa. | | Ejecutar Agente (Async) | POST /public/api/agents/:id/process con async:true | Devuelve executionId + pollingUrl inmediatamente. | | Consultar Ejecución (Process Async) | GET /public/api/process/executions/:executionId | Polling de ejecución async del agente (devuelta por processAsync). | | Consultar Job (Workflow Async) | GET /public/api/actions/jobs/:jobId | Polling de workflow_jobs creados por tools async DENTRO del agente. | | Compact (LLM Directo) | POST /public/api/compact | Llamada directa al LLM sin agente. Ideal para clasificación, extracción. | | Listar Agentes | GET /public/api/agents | Discovery — lista agentes disponibles del proyecto. |

IMPORTANTE: todos los endpoints son /public/api/* (B2B público). Nunca /api/* (Zero Trust interno).

Diferencia entre "Consultar Ejecución" y "Consultar Job"

Dos tipos de async diferentes — NO confundir:

| | Consultar Ejecución | Consultar Job | |---|---|---| | ID usado | executionId (exec_...) | jobId (job_...) | | Endpoint | /public/api/process/executions/:id | /public/api/actions/jobs/:id | | Cuándo | Después de Ejecutar Agente (Async) | Cuando el agente usó una MCP tool async internamente | | Origen | Tabla process_executions | Tabla workflow_jobs | | Auth | API Key oapi_ o JWT | API Key oapi_ o JWT | | Ejemplo | Agente entero tarda 30s → polling del execution | Agente usó gen_video tool → polling del job dentro de la ejecución |

Cuando ejecutas un agente con async: true y ese agente internamente usa un tool async, pueden existir ambos tipos:

• Un executionId del agente completo
• N jobIds de los tools async que lanzó

Usa la operación correspondiente según qué ID tengas.

Auth

2 modos:

Autenticación: [API Key / JWT ▾]
  Token: [oapi_xxx]      → API Key (B2B clients)
  Token: [eyJ...]        → JWT (cuando viene como Action de Orbital)

Autenticación: [Credential guardado ▾]
  → usa un Header Auth configurado en n8n

La URL base del endpoint es constante interna del nodo — el técnico no la configura. Apunta a producción (api.orbital.fractaliacyber.com).

Auto-emit de steps

Al activar Emitir Step tras ejecutar en operaciones process/processAsync, el nodo automáticamente emite un step enriquecido al job del JWT:

• Funciona solo con JWT (empezando por eyJ). Con API Key (oapi_) se ignora silenciosamente (no hay jobId al que asociar).
• Genera 1 solo step kind=ai con ai.tools[] inline como metadata (modelo plano v3.0.0).
• El coste de IA va con costSource: 'ai_gateway' (ya registrado por Gateway sync → rollups NO duplican).

Ejemplo

[Webhook Trigger (Orbital Action)]
    ↓
[Orbital Actions: Declarar Pipeline]  CyberSOC NIST
    ↓
[Orbital Actions: Reportar Progreso]  fase=detection
    ↓
[Orbital Process: Ejecutar Agente "clasificador"]
   [X] Emitir Step
   Fase: detection
   Incluir assistantMessage: [X]
    ↓
   (auto-emite POST a /public/wh/events con:)
   {
     status: 'running',
     step: {
       kind: 'ai',
       title: 'Clasificador de Incidentes',
       phaseRef: 'detection',
       status: 'success',
       ai: {
         model: 'gpt-4o',
         provider: 'openai',
         tokensIn: 1250,
         tokensOut: 340,
         costSource: 'ai_gateway',     ← no duplica coste
         tools: [                       ← tools INLINE, no substeps
           { name: 'get_logs', type: 'rag', status: 'success', input, output },
           { name: 'classify', type: 'code', status: 'success', input, output },
           { name: 'score', status: 'success', ... }
         ]
       },
       content: { type: 'markdown', body: assistantMessage },
       metrics: { duration, tool_success_rate, tools_count }
     }
   }

Dashboard del job tras el emit:

Detection (1 step, 2.1s)
  [ok] Clasificador de Incidentes              ai, 2.1s
       gpt-4o, 1590 tokens total, 3 tools
       (expandir: ver prompt, output, detalle de cada tool)

Campos del auto-emit

| Campo | Tipo | Default | Efecto | |---|---|---|---| | Emitir Step tras ejecutar | boolean | false | Switch maestro | | Fase del Pipeline | dropdown (loadOptions) | '' | Fase asociada (auto-asigna a currentPhaseRef si vacío) | | Incluir assistantMessage como content | boolean | true | Añade texto del agente como content.type=markdown | | Incluir structured output como content | boolean | true | Si el agente tiene outputSchema, añade JSON como content | | Progreso del Job (%) | number 0-100 | 0 | 0=no tocar. Si >0, actualiza progress global. |

Caso async

Si Ejecutar Agente (Async), el step se emite con status='started' + metrics.async_job_id. El técnico después consulta el job y cierra el step con OrbitalActions: Actualizar Step Abierto (async).

Output estándar (sin emit)

La respuesta del process va en el json del output:

{
  "operation": "process",
  "success": true,
  "executionId": "exec_...",
  "agentId": "agent_...",
  "agentName": "Clasificador",
  "toolsExecuted": [
    { "name": "get_logs", "type": "rag", "status": "success", "input": {...}, "output": {...} }
  ],
  "output": { ... structured output si hay outputSchema ... },
  "assistantMessage": "Texto generado",
  "metrics": {
    "totalExecutionTimeMs": 2100,
    "tokensUsed": { "input": 1250, "output": 340 },
    "toolSuccessRate": 1.0,
    "modelUsed": "gpt-4o",
    "providerUsed": "openai"
  }
}

Migración

Desde v3.0.2 → v3.0.3:

• Campo URL Base eliminado (hardcoded interno).
• Modo auth auto eliminado — solo "API Key / JWT" o "Credential guardado".
• Fix: getExecution extrae correctamente envelope.data (antes retornaba campos vacíos).
• Fix: getJob apunta al endpoint público /public/api/actions/jobs/:jobId (antes apuntaba a ruta interna Zero Trust).

Workflows guardados en v3.0.2 siguen funcionando — el campo URL que existiera en el workflow se ignora silenciosamente.

Desde v2.x (breaking change en v3.0.0):

| Cambio | v2.x | v3.0.x | |---|---|---| | Auto-emit de tools | N+1 steps (1 AI + N substeps por tool) | 1 solo step con ai.tools[] inline | | Campo "Es Substep De" (emitParentStepId) | Sí | Eliminado | | Campo emitPhaseRef | String libre | Dropdown dinámico (loadOptions desde staticData) |

El campo emitPhaseRef es dropdown dinámico — las fases se populan desde workflowStaticData.orbitalPipelinePhases, persistido por OrbitalActions.declarePipeline en ejecuciones anteriores. En la 1ª ejecución, escribe el ref directamente (ej: detection).

Build local

pnpm install
pnpm run build

Para testing local:

npm link
cd ~/.n8n/custom
npm link n8n-nodes-orbital
# reiniciar n8n

Licencia

MIT