Agentes en n8n
del nodo al sistema autónomo

¿Qué es n8n?

n8n es una plataforma de automatización de workflows que conecta tus apps, datos y servicios — todo en un editor visual con código cuando lo necesitás.

Pensalo como un pegamento entre herramientas: conectás tu CRM, tu sistema de facturación, tu email, Slack, una base de datos, lo que uses, y n8n ejecuta secuencias enteras cuando se dispara un evento. Tiene más de 400 integraciones nativas y nodos para hacer requests HTTP a cualquier API que no esté en la lista.

A diferencia de Zapier o Make, n8n es fair-code: podés correrlo en tu propio servidor sin pagar licencia para la edición Community, y la Cloud cuenta ejecuciones completas en lugar de pasos individuales — termina siendo más previsible y barato a escala.

La interfaz: el editor visual

El editor es donde construís todo. Tiene tres áreas: panel izquierdo, canvas central y panel de nodos a la derecha.

Workflow: el lienzo de la automatización

Un workflow es un conjunto de nodos conectados que ejecutan una automatización. Es la unidad principal de trabajo en n8n.

Cada workflow tiene un punto de entrada (el trigger) y desde ahí los datos fluyen de nodo en nodo hasta el final. Podés tener workflows simples de dos nodos o complejos con decenas de ramas, sub-workflows y lógica condicional.

Los workflows se pueden activar (modo producción, corren solos al dispararse) o ejecutar manualmente desde el canvas. También podés guardar versiones en History, compartirlos como JSON, convertir partes en sub-workflows, e incluso controlarlos con Git en planes Business y Enterprise.

Los cuatro tipos de nodos

Un nodo es un paso individual del workflow: carga, procesa o envía datos. n8n los clasifica en cuatro tipos según su función.

Triggers y conexiones

Todo workflow necesita arrancar con un trigger. Hay tres familias según cómo detectan el evento.

Credenciales: cómo conectás tus apps

Para que n8n hable con tus servicios, necesita autenticarse. Las credenciales guardan API keys, tokens OAuth, usuarios y contraseñas — cifradas y reutilizables.

Cada integración define qué tipo de credencial necesita. Las más comunes son:

• API Key — un string largo que pegás en n8n (Gmail, OpenAI, Anthropic, SerpAPI, la mayoría de servicios SaaS modernos).
• OAuth 2.0 — flujo de autorización por navegador. n8n te redirige al servicio, autorizás, vuelve con el token. Lo usan Google, Microsoft, Slack, GitHub, etc.
• Basic Auth — usuario + contraseña. Servicios viejos o internos.
• Bearer / Header auth — token en el header de la request. Común en APIs custom.

Construí tu primer workflow

El "Hello World" oficial: un workflow de dos nodos que trae artículos de Hacker News con un trigger manual.

1. Crear un workflow vacío. Desde Overview, click en "Create Workflow". Vas a ver el canvas vacío con "Add first step".
2. Agregar el Manual Trigger. Click en "Add first step", buscá "Manual Trigger" y seleccionalo. Te permite correr el workflow apretando un botón.
3. Conectar el nodo de Hacker News. Click en el + a la derecha del Manual Trigger, buscá "Hacker News" y seleccionalo.
4. Configurar el nodo. Resource: "All", Operation: "Get many", Tags: "story", Keywords: "automation", Limit: 10.
5. Ejecutar. Click en "Execute step" o "Execute workflow". Debajo del nodo aparecen los 10 artículos como output JSON.
6. Guardar. Click en Save (o Ctrl+S). Si no lo guardás, se pierde al cerrar.

Ejecuciones: la historia de tu workflow

Cada vez que un workflow corre, n8n guarda un registro: input, output de cada nodo, errores, duración. Eso es una execution.

Las ejecuciones se ven en la pestaña Executions dentro del workflow, o en la global desde el panel izquierdo. Podés filtrar por estado (Failed, Running, Success, Waiting), por fecha o por custom data.

• Re-ejecutar: si una ejecución falla, podés reintentarla con el workflow actual o con el original.
• Debug en editor: abrís una ejecución pasada y la cargás en el canvas para inspeccionar nodo por nodo.
• Limpieza automática: n8n puede borrar ejecuciones viejas automáticamente. Configurable con variables de entorno en self-host.

Cómo viajan los datos: items

Toda la data que pasa entre nodos en n8n es un array de objetos. Cada objeto envuelve otro objeto con la key json.

// El formato base que n8n espera entre nodos
[
  {
    "json": {
      "name": "Diego",
      "role": "profesor"
    }
  },
  {
    "json": {
      "name": "Alumna",
      "role": "estudiante"
    }
  }
]

Cada elemento del array es un item. Los nodos suelen procesar todos los items en paralelo. Si tu nodo recibe 5 items, ejecuta 5 veces — una por cada uno.

Pueden tener objetos anidados (nested), arrays adentro, valores numéricos, strings, booleans. La key json es fija; lo que va adentro es libre. También puede haber una key binary para archivos.

Expressions: código en los campos

Las expressions son piezas chicas de código JavaScript que ponés directamente dentro de los parámetros de un nodo usando la sintaxis {{ ... }}.

Ejemplo concreto: si querés mandar un email con el nombre del cliente que viene del nodo anterior, ponés en el campo Body: {{ "Hola " + $json.name + ", gracias por tu compra" }}.

IF y Switch: decisiones en el flow

A veces necesitás que el workflow tome caminos distintos según los datos. Ahí entran IF (dos ramas) y Switch (múltiples ramas).

IF node

Divide el flow en dos: true y false según una condición. Soporta comparaciones para string, number, date & time, boolean, array y object. Operadores disponibles: equals, contains, starts/ends with, regex match, is greater/less than, is after/before, length, etc.

Switch node

Como IF pero con múltiples salidas. Tiene dos modos:

• Rules: creás reglas y cada una tiene su salida con nombre.
• Expression: escribís una expression que devuelve un número (el índice del output al que va el item).

Transformar datos sin escribir código

n8n incluye nodos especializados para manipular datos tabulares sin tocar JavaScript. Cubren la mayoría de los casos.

Code node: cuando lo visual no alcanza

El Code node ejecuta JavaScript (o Python vía Pyodide) como un paso del workflow. Te da acceso a los inputs, podés transformar items, agregar, sacar, hacer cualquier lógica custom.

// Modo: Run Once for All Items
// Recibo todos los items y los devuelvo modificados

const items = $input.all();

return items.map(item => {
  return {
    json: {
      ...item.json,
      fullName: item.json.firstName + " " + item.json.lastName,
      processedAt: new Date().toISOString()
    }
  };
});

# Misma idea en Python (Pyodide)
items = _input.all()

result = []
for item in items:
    data = item["json"]
    data["fullName"] = f"{data['firstName']} {data['lastName']}"
    result.append({"json": data})

return result

• Dos modos: Run Once for All Items (procesás el array completo) o Run Once for Each Item (n8n itera por vos).
• Variables built-in: $input, $json, $execution, $workflow, $binary, $itemIndex.
• Libraries externas: solo en self-host con la variable NODE_FUNCTION_ALLOW_EXTERNAL. En Cloud no se pueden agregar paquetes npm custom.
• Python: nuevo native runner reemplazó a Pyodide; podés usar JS y Python con misma API.

Manejar errores con elegancia

Toda automatización productiva eventualmente falla: APIs caídas, datos inesperados, rate limits. La doc recomienda diseñar pensando en el error desde el inicio.

Error Workflow

Es un workflow separado que se dispara solo cuando falla otro workflow. Empieza con un Error Trigger y desde ahí podés mandar un Slack, un email, registrar en una base, lo que necesites.

1. Creá un workflow nuevo con el Error Trigger como primer nodo. Llamalo, por ejemplo, "Error Handler".
2. Conectá los nodos de notificación (Slack, Telegram, Send Email, etc.) al Error Trigger.
3. Guardalo. No hace falta activarlo: corre cuando otro workflow falla.
4. En el workflow que querés monitorear: Settings → Error workflow → seleccionás el handler.
5. El mismo handler sirve para muchos workflows. No hace falta crear uno por cada uno.

Stop and Error node

Fuerza un error en un punto específico del workflow. Útil cuando querés cortar la ejecución bajo cierta condición (ej: si el monto es negativo, lanzar error y notificar). Solo se puede usar como último nodo de una rama.

Sub-workflows: modularidad

Podés llamar un workflow desde otro. Permite armar arquitecturas modulares, tipo microservicios, y reutilizar lógica entre flows.

Se implementa con dos nodos: Execute Workflow en el workflow padre, y Execute Sub-workflow Trigger (también llamado "When Executed by Another Workflow") en el hijo.

• No cuentan al límite mensual de ejecuciones ni al de active workflows del plan.
• Heredan la ejecución: si el padre se ejecuta manualmente, el hijo también.
• Pasan data en ambas direcciones: padre → hijo (input) y hijo → padre (output).
• Útil contra memory issues: si tu workflow crece mucho, partirlo en sub-workflows reduce el footprint en RAM por ejecución.

LLM vs AI Agent: la diferencia clave

Antes de armar tu primer agente, hay que entender qué distingue a un Large Language Model de un Agent.

Un LLM genera texto prediciendo la próxima palabra. Puede simular decisiones en el texto que genera, pero no puede actuar sobre el mundo: no llama APIs, no manda emails, no consulta bases de datos. Solo escribe.

Un AI Agent, en cambio, usa un LLM como cerebro pero le agrega capacidad de acción: puede usar tools, ejecutar tareas multi-paso, decidir qué hacer y cuándo. Es goal-oriented.

Tu primer agente: tres nodos

El tutorial oficial arma un chatbot básico con Chat Trigger + AI Agent + OpenAI Chat Model. Esa es la mínima expresión de un agente conversacional.

1. Crear el workflow vacío. Desde la pantalla principal de n8n.
2. Sumar el Chat Trigger. Provee la UI de chat lista. Output: el mensaje del usuario.
3. Conectar el AI Agent. Click en "Add node" sobre el Chat Trigger. Buscar "AI Agent".
4. Adjuntar un Chat Model. El tutorial usa OpenAI Chat Model. Soporta también Anthropic, Groq, Mistral, Azure OpenAI, Google Gemini, DeepSeek.
5. Configurar credenciales. El Chat Model necesita una API key. Las credenciales se cargan una sola vez y se reutilizan.
6. Probar el nodo. Click en "Chat" abajo del canvas. Escribir un mensaje, ver la respuesta y el log.
7. Ajustar el system prompt. Por defecto es "You are a helpful assistant". Cambialo para definir personalidad y restricciones.

Hasta acá tenés un agente que responde, pero todavía no recuerda. Eso lo arregla la memoria.

Memoria: que el agente recuerde

Sin memoria, cada mensaje al agente es una conversación nueva — perdés todo el contexto. La memoria mantiene el historial de mensajes anteriores.

Tools: las manos del agente

Un agente sin tools sólo puede hablar. Con tools, puede consultar APIs, leer hojas de cálculo, mandar emails, calcular, buscar en la web — actuar sobre el mundo.

Chains vs Agents: la decisión arquitectónica

Esta es la decisión más importante al diseñar un workflow de IA. Determina costo, predictibilidad y capacidad.

n8n provee tres chain nodes:

• Basic LLM Chain — interactúa con un LLM sin componentes adicionales. Ideal para tareas one-shot: clasificar, traducir, resumir.
• Question and Answer Chain — puede conectar a un vector store usando un retriever. Para Q&A determinístico sobre tu data.
• Summarization Chain — toma input y devuelve un resumen.

Y dos chains complementarias:

• Sentiment Analysis — clasifica texto en positivo/negativo/neutral.
• Text Classifier — clasifica texto en categorías que definís.

RAG: el patrón de dos workflows

RAG combina un LLM con datos externos indexados en un vector store. Tu agente responde sobre tus PDFs, emails o wiki — sin reentrenar nada.

Workflow A — Ingesta (corre una vez, o cuando los documentos cambian):

Workflow B — Consulta (cada vez que el usuario pregunta):

1. Fetch. Traés los archivos: Google Drive, S3, Read Binary Files, lo que aplique.
2. Insert Documents. Agregás un Vector Store node en modo "Insert Documents".
3. Embedding model. Conectás un modelo de embeddings (OpenAI, Cohere, Ollama local, etc).
4. Default Data Loader. Sub-nodo que parte tu contenido en chunks. Tres estrategias: Character Text Splitter, Recursive (recomendada para la mayoría), Token Splitter.
5. Metadata opcional. Agregás metadata a cada chunk para filtrar mejor después (autor, fecha, tipo, etc.).
6. Workflow B: el agente. Chat Trigger → AI Agent con Vector Store Tool como tool. El agente decide cuándo consultar la base.

Vector stores: la base semántica

Un vector store es una base de datos diseñada para guardar vectores — representaciones numéricas multidimensionales — y buscar por similitud semántica en lugar de keywords.

Embeddings y text splitters

Antes de guardar texto en un vector store, hay que (1) cortarlo en pedazos del tamaño correcto, y (2) convertir cada pedazo en un vector numérico.

Text splitters

• Character Text Splitter — corta por longitud de caracteres. Simple y rápido.
• Recursive Character Text Splitter — corta respetando estructura (Markdown, HTML, code blocks, párrafos). Recomendado para la mayoría de los casos.
• Token Text Splitter — corta por número de tokens. Útil cuando el límite de tu modelo es por tokens.

Embedding models

• Embeddings OpenAI — el más común, alta calidad.
• Embeddings Cohere — alternativa managed, soporta múltiples idiomas.
• Embeddings Hugging Face — accedés a miles de modelos vía Hugging Face Inference.
• Embeddings Ollama — modelos locales (all-minilm, nomic-embed-text). Privacidad total, costo cero.
• Embeddings Google Gemini, AWS Bedrock, Azure OpenAI, Mistral — para stacks específicos.

Document Loaders

• Default Document Loader — el más flexible, soporta texto, PDFs, JSON, CSV.
• GitHub Document Loader — carga archivos directamente desde un repo.

Output parsers: forzar formato

Los LLMs devuelven texto libre. Si necesitás JSON estructurado para procesar después, usás un output parser.

// Ejemplo de schema para Structured Output Parser
{
  "type": "object",
  "properties": {
    "sentiment": {
      "type": "string",
      "enum": ["positivo", "negativo", "neutral"]
    },
    "confidence": { "type": "number" },
    "reasoning": { "type": "string" }
  },
  "required": ["sentiment", "confidence"]
}

Multi-agent con AI Agent Tool

El nodo AI Agent Tool permite que un agente "supervisor" delegue partes de la tarea en agentes especializados — como un equipo real con un líder y especialistas.

Es ideal para sistemas complejos que funcionan como equipos del mundo real: un agente líder asigna partes de la tarea a especialistas. Incluso podés tener varias capas de agentes dirigiendo otros agentes, como en una organización multi-nivel.

También ayuda con la gestión del prompt: en lugar de instrucciones largas y complejas en un solo agente, las dividís en tareas más chicas y enfocadas en varios agentes.

1. Agregar el AI Agent principal al canvas.
2. Click en + para crear una conexión Tools.
3. Buscar y seleccionar AI Agent Tool en el panel de nodos.
4. Nombrar claramente el sub-agente — el supervisor lo va a referenciar por nombre.
5. Agregar una descripción y un prompt que explique qué tipo de tareas resuelve.
6. Conectar al sub-agente sus propios LLMs, memoria y tools.
7. En el system prompt del supervisor: instruirlo sobre cuándo usar cada sub-agente y qué contexto pasarle.

MCP: tu agente como ciudadano del ecosistema

MCP — Model Context Protocol — estandariza cómo los LLMs interactúan con tools externas. n8n puede actuar como servidor MCP o como cliente.

Cada vez más proveedores (Claude Desktop, Cursor, ChatGPT) adoptan MCP como estándar. n8n introduce tres nodos para integrarse.

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "<MCP_URL>",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": { "AUTH_TOKEN": "<MCP_BEARER_TOKEN>" }
    }
  }
}

↑ Config de Claude Desktop para usar tu MCP Server Trigger de n8n.

Queue mode: escalado horizontal

Cuando tu instancia self-host crece, el modo regular se queda corto. Queue mode te permite separar el frontend de la ejecución, escalando con workers independientes.

Cómo funciona:

1. Una instancia main recibe los triggers (webhooks, schedule) y genera el job — sin ejecutarlo.
2. Pasa el job a un broker (Redis) que mantiene la cola de ejecuciones pendientes.
3. Un worker de la pool toma el job de Redis y ejecuta el workflow.
4. El worker escribe los resultados a la base de datos.
5. Notifica a Redis que terminó.
6. Redis notifica al main.

Lo que necesitás:

• Redis como broker de mensajes.
• Postgres 13+ como base de datos (SQLite no se soporta en queue mode).
• Misma N8N_ENCRYPTION_KEY en main y todos los workers, para acceder a credenciales.
• Variable EXECUTIONS_MODE=queue en main y workers.
• Workers iniciados con n8n worker (o el comando Docker equivalente).

Human-in-the-loop: cuando el agente pide ayuda

Para acciones críticas — borrar datos, enviar comunicaciones masivas, hacer pagos — querés que un humano revise antes de que el agente actúe.

n8n soporta human review steps en las tools del agente. La AI especifica los parámetros (incluso con $fromAI()), pero antes de ejecutar la tool, n8n pausa la ejecución y notifica a un humano para que apruebe o deniegue.

Variables disponibles en el mensaje de review

• $tool.name — el nombre del nodo de la tool que el agente quiere ejecutar.
• $tool.parameters — los parámetros que el agente quiere pasarle, incluyendo los campos $fromAI().

El AI quiere usar {{ $tool.name }} con los siguientes parámetros:
{{ JSON.stringify($tool.parameters, null, 2) }}

¿Aprobás esta acción?

También podés implementar fallback humano de otra forma: el agente tiene una tool especial "escalar a humano" que dispara un Slack/email/Telegram con el contexto, y el workflow espera la respuesta antes de seguir.

Evaluations: medir antes de escalar

Cuando llevás un agente a producción, necesitás saber si "anda bien". Las evaluations de n8n te permiten correr tu workflow contra un dataset y medir resultados sistemáticamente.

Dos modos de evaluations

• Light evaluations — análisis cualitativo sobre un sample chico de casos. Para Community Edition registrada hay análisis limitado de una evaluación en la pestaña Evaluations.
• Metric-based evaluations — scoring numérico con métricas sobre datasets grandes. Para Pro y Enterprise, evaluaciones ilimitadas.

Métricas built-in

n8n incluye varias métricas pre-construidas para comparar respuestas del agente contra ground truth, y permite definir custom metrics.

El archivo llms-full.txt

Una sola URL con toda la documentación oficial en texto plano. ~2.5MB. Apto para context window de cualquier modelo moderno.

El estándar llms.txt propone que cada sitio técnico publique su documentación de forma consumible por LLMs. n8n lo implementa con dos archivos: llms.txt (índice) y llms-full.txt (contenido completo).

Casos de uso típicos:

• Pegale la URL a Claude o ChatGPT y consultá sobre nodos, parámetros o configuración como si charlaras con un experto.
• Pasásela a Cursor, Continue o Cody para autocompletar mientras armás workflows en code.
• Construí tu propio chatbot interno con RAG sobre el archivo — ideal si tu equipo usa n8n masivamente.
• Usalo como ground truth en evaluations para validar que las respuestas de tu agente sobre n8n sean correctas.

AI Console: preguntale a un LLM

Escribí tu pregunta. Apretás el botón. Se abre Claude o ChatGPT con tu consulta y la doc oficial ya enganchada como referencia.

No usa API keys ni backend — simplemente arma el prompt correcto, codifica la URL y abre el modelo en una pestaña nueva. Funciona con cualquier LLM que acepte parámetros vía URL.

Las dos opciones principales

La elección depende de presupuesto, privacidad y skills del equipo.

Planes n8n Cloud

Desde fines de 2025, todos los planes incluyen workflows y usuarios ilimitados. El precio escala únicamente con el volumen de ejecuciones.

Una ejecución = una corrida completa de un workflow, sin importar cuántos pasos tenga. Mucho más predecible que pagar por step como en Zapier o Make.

Self-host sin volverte sysadmin

Pikapods es hosting managed para apps open source. Elegís n8n del catálogo, configurás CPU/RAM/storage con sliders, y en menos de un minuto tenés tu instancia corriendo con HTTPS automático.

Qué te dan

• Deploy de n8n en ~60 segundos con un click
• SSL/HTTPS automático y subdominio gratis
• Custom domain con SSL automático (configurás CNAME y listo)
• Dos regiones: EU (Hetzner Falkenstein DE + Finlandia) y US (Evocative BOS1 Boston + Cyber WURX Atlanta)
• Updates semanales testeados (manuales si los preferís)
• Backups diarios gestionados + opción de backups externos a S3
• Acceso por SFTP para copiar archivos manualmente
• Catálogo de 60+ apps open source además de n8n
• $5 de crédito inicial gratis (sin tarjeta de crédito)

Self-hosted AI Starter Kit

Un docker-compose template curado oficialmente por n8n que bootstrappea un entorno completo de IA local y low-code.

Combina n8n self-hosted con componentes compatibles para construir workflows de IA privados desde cero: