n8n-nodes-orbital

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

v3.5.0 — Adjuntos en Ejecutar Agente (binarios del item, URLs y base64) y nodo usable como tool de AI Agent. Historial en CHANGELOG.md.

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.
Generar Schema (IA)	POST /public/api/schema/generate	Genera un JSON Schema desde una descripción en lenguaje natural (útil como outputSchema).
Generar Imagen (IA)	POST /public/api/image/generate	Genera o edita imágenes con IA (nano-banana, imagen-4).

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.

Adjuntos (binarios, URLs, base64)

La operación Ejecutar Agente puede adjuntar ficheros (PDF, imágenes, documentos…) a la llamada. Hay tres fuentes, combinables entre sí:

Campo	Qué hace
Adjuntar binarios del item + Propiedades binarias	Lee los binarios del item de entrada (data por defecto; varias separadas por coma; * = todas). Solo en modo workflow normal.
URLs de ficheros	URLs http(s) separadas por coma / salto de línea, o un array JSON vía expresión. El nodo las descarga (timeout 60 s) y toma el MIME del content-type (o de la extensión) y el nombre de content-disposition (o de la ruta).
Ficheros en base64	Array JSON de data URLs (data:<mime>;base64,...) o de objetos { data | base64, mimeType, filename }. Si el base64 no lleva prefijo data:, mimeType es obligatorio.
Texto por defecto con adjuntos	Texto que acompaña a los ficheros si Mensaje está vacío (default: "Analiza los ficheros adjuntos.").

Con adjuntos, el nodo envía message como array de partes; sin adjuntos sigue enviando el string de siempre (retrocompatible):

{
  "message": [
    { "type": "text", "text": "Resume la factura" },
    { "type": "image_url", "image_url": "data:image/png;base64,iVBOR..." },
    { "type": "file", "data": "data:application/pdf;base64,JVBERi0x...", "filename": "factura.pdf" }
  ]
}

Las imágenes png/jpeg/gif/webp van como image_url; el resto (incluidas svg/tiff) como file con su filename.

Límites (los valida el nodo antes de llamar)

• Máx. 5 imágenes y 5 ficheros por llamada (máx. 20 partes en total, siempre con al menos un texto).
• Máx. 20 MB por fichero (≈ 27,9 M caracteres de base64).
• Si se supera un límite, el nodo falla con un error que indica el item y el fichero culpable.
• Hoy la API no acepta URLs directamente: por eso las descarga el nodo y las manda en base64.

Ejemplos

URLs desde una expresión:

URLs de ficheros: {{ $json.adjuntos.map(a => a.url) }}

Base64 desde un nodo anterior:

[
  "data:image/jpeg;base64,/9j/4AAQ...",
  { "base64": "JVBERi0x...", "mimeType": "application/pdf", "filename": "contrato.pdf" }
]

Salida

El output añade attachments (sin el base64) y, si aplica, attachmentWarnings:

{
  "attachments": [
    { "filename": "factura.pdf", "mimeType": "application/pdf", "sizeBytes": 183422, "source": "binary" }
  ],
  "attachmentWarnings": ["Modo async con 3.40 MB de adjuntos: ..."]
}

En modo async con más de 2 MB de adjuntos se avisa (sin bloquear): la petición, con el base64, se persiste en Orbital hasta que la ejecución termina.

Soporte por proveedor del agente

Proveedor	Imágenes	PDF	Otros ficheros (texto, DOCX, XLSX…)
OpenAI	Sí	Sí	Sí
Anthropic	Sí	Sí	Texto plano sí; DOCX/XLSX no
Google	Solo en modo unified (en modo direct se pierden)	Se pierde sin error	Se pierde sin error

Para trabajar con documentos, usa agentes con proveedor OpenAI o Anthropic. Con Google hoy los PDF/ficheros (y en modo direct también las imágenes) se descartan sin avisar.

Uso como tool de un AI Agent

El nodo es usableAsTool: puede conectarse como herramienta de un nodo AI Agent de n8n. En ese modo el agente rellena los campos con $fromAI, p. ej.:

URLs de ficheros:   {{ $fromAI('urls', 'URLs de los ficheros a analizar, separadas por coma', 'string') }}
Ficheros en base64: {{ $fromAI('ficheros', 'Array JSON de data URLs', 'string') }}

Los binarios del item solo se leen en modo workflow normal: como tool, el item no trae binarios, así que usa URLs o base64.

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