Cómo crear un agente de IA n8n en tu VPS

Qué es un agente de IA de n8n y en qué se diferencia de una cadena

Un agente de IA de n8n es un único nodo AI Agent con subnodos conectados: un modelo de chat, una o más herramientas y memoria opcional. Se indica un objetivo en lenguaje natural y el modelo decide qué herramientas llamar y en qué orden hasta que puede responder. Todo lo que sigue describe la configuración relacionada con esa idea.

Una cadena funciona al contrario. En una Basic LLM Chain, usted define los pasos y el modelo solo genera el texto. En un agente, el modelo decide los pasos. Por eso, una misma pregunta puede costar una llamada al modelo hoy y nueve mañana. Esta diferencia determina todas las opciones de esta guía.

Se presupone que n8n ya se ejecuta detrás de HTTPS en una máquina bajo su control. Si no es así, empiece por alojar n8n en Docker con un certificado real, porque la clave de API que va a almacenar necesita la copia de seguridad de la clave de cifrado que esa guía exige. Para los patrones sin agentes, como los resumidores mediante webhook y los clasificadores programados, consulte patrones de flujos de trabajo con Claude y n8n.

Compruebe la versión antes de confiar en cualquier nombre de campo de esta guía, porque n8n cambia con frecuencia los nodos de IA.

docker compose exec n8n n8n --version

Los nombres de esta guía coinciden con la versión estable actual de n8n a fecha de julio de 2026. Desde la versión 1.82.0, todos los nodos AI Agent de n8n se ejecutan como Tools Agent, por lo que el menú desplegable del tipo de agente anterior ya no existe.

Paso 1: elegir el activador

Para un agente conversacional, añade un nodo Chat Trigger. Mantén desactivada la opción Make Chat Publicly Available mientras lo configuras para que solo el panel de chat del editor pueda acceder a él. Actívala cuando el agente esté terminado y hayas decidido el método de autenticación.

Chat Trigger proporciona al agente un campo llamado chatInput. Ese nombre es importante en el paso 3. Escribirlo mal es el error inicial más frecuente.

Para un agente desatendido, utiliza un nodo Schedule Trigger o Webhook. Ninguno genera chatInput, por lo que tendrás que escribir el prompt manualmente.

Paso 2: la credencial del modelo

Coloque un nodo AI Agent en el lienzo. n8n muestra inmediatamente un conector Chat Model vacío debajo de él. Conecte allí un subnodo Anthropic Chat Model.

Cree la credencial desde Anthropic Console en platform.claude.com, en Settings y después en API Keys. La clave se muestra una sola vez. El uso de la API se factura por token y es independiente de cualquier suscripción de Claude.ai, por lo que la cuenta debe tener la facturación configurada antes de la primera ejecución.

Elija el modelo para cada agente, no para toda la empresa. Un agente con una sola herramienta que busca un dato y lo informa funciona correctamente con Haiku, que en julio de 2026 figura a $1 por millón de tokens de entrada y $5 por millón de tokens de salida. Cuando el agente tenga varias herramientas y deba planificar entre ellas, cambie a Sonnet. El problema que debe evitar es que un modelo económico llame cuatro veces a la herramienta incorrecta, con un coste superior al de que el modelo más caro llame una vez a la herramienta correcta.

Configure Maximum Number of Tokens en las opciones del subnodo. Este valor limita la longitud de cada respuesta que genera el modelo. Si se deja un valor predeterminado alto, una ejecución confusa puede generar una respuesta muy larga y facturar ese consumo.

Hay una salvedad de la documentación de n8n que suele causar problemas: las expresiones dentro de un subnodo siempre se resuelven con respecto al primer elemento de entrada, nunca por elemento. Coloque las expresiones específicas de cada elemento en los campos de prompt del nodo raíz.

Paso 3: el mensaje que recibe el agente

Abra el nodo AI Agent. El parámetro Prompt tiene dos opciones.

• Take from previous node automatically espera un campo de entrada llamado chatInput. Esta es la opción correcta detrás de un Chat Trigger.
• Define below muestra un campo Prompt (User Message) donde puede escribir texto estático o una expresión. Esta es la opción correcta detrás de un Schedule Trigger o un Webhook node.

Con un Webhook node delante, el cuerpo de una solicitud POST queda en $json.body, por lo que el campo de mensaje tiene este aspecto.

Check the current status of {{ $json.body.service }} and tell me
whether it is up. If it is down, say for how long. No preamble.

Paso 4: proporcione al agente una herramienta

Un nodo AI Agent sin un subnodo de herramienta se niega a ejecutarse. Empiece con una herramienta, porque una herramienta funcional le enseña más que cuatro herramientas configuradas a medias.

Conecte un nodo HTTP Request al conector Tool del agente. Configúrelo exactamente igual que un nodo HTTP Request normal y pruebe primero ese endpoint desde un shell.

curl -s -H 'Accept: application/json' \
  https://status.example.com/api/status/database | head -c 400

Si ese curl devuelve un error o una página de inicio de sesión HTML, el agente también fallará. El error parecerá un problema del modelo, aunque en realidad será un problema de URL o autenticación. Corríjalo en el shell, no en el nodo.

El campo Description de la herramienta no es documentación para sus compañeros. Es lo único que lee el modelo para decidir si esta herramienta es relevante. Escriba una descripción sencilla de lo que devuelve: "Devuelve el estado actual, activo o inactivo, y la duración de la interrupción de un servicio monitorizado, en formato JSON."

Para permitir que el modelo complete parte de la solicitud, use la expresión $fromAI(). Solo funciona en herramientas conectadas a un nodo AI Agent. No funciona en la herramienta Code.

{{ $fromAI('service', 'The name of the service to look up', 'string') }}

Los argumentos son key, seguidos opcionalmente de description, type y defaultValue. La clave debe tener entre 1 y 64 caracteres y solo puede usar letras, dígitos, guiones bajos y guiones. El tipo debe ser uno de string, number, boolean o json, y el valor predeterminado es string. Una llamada más completa tiene este aspecto.

{{ $fromAI('limit', 'How many records to return', 'number', 20) }}

La clave es una indicación, no una referencia a datos existentes. $fromAI('service') no lee en ningún sitio un campo llamado service. Indica al modelo que "produzca un valor y lo llame service". El modelo busca ese valor en la conversación, los datos de entrada y los resultados de otras herramientas. En un flujo de trabajo de chat, puede simplemente preguntárselo al usuario.

Paso 5: memoria y por qué el agente olvida

Sin un subnodo de memoria, cada mensaje comienza sin contexto. Conecta un subnodo Simple Memory para conservar la conversación reciente.

Tiene dos parámetros. Session Key determina de qué conversación se trata, por lo que dos usuarios con claves diferentes obtienen historiales separados. Context Window Length indica cuántas interacciones anteriores se vuelven a incluir en el prompt.

Context Window Length también controla el costo, no solo la calidad, porque cada turno conservado se vuelve a enviar como tokens de entrada en cada llamada posterior. Una ventana de 20 en un agente con mucha actividad significa que pagas veinte veces por los mismos mensajes iniciales.

Simple Memory no funciona en un workflow de producción activo cuando n8n se ejecuta en modo de cola, porque el historial se almacena en los datos del propio workflow y no en un almacenamiento compartido. En una instancia en modo de cola, usa el subnodo Postgres Chat Memory y configúralo para conectarse a una base de datos accesible tanto para el proceso principal como para los workers.

Paso 6: el mensaje del sistema

Abra Options del agente y añada un System Message. Aquí se define la descripción del trabajo y se incluye el texto con mayor impacto del flujo de trabajo.

You are an infrastructure status assistant. Always call the status
tool before answering a question about whether something is running.
Never guess. If the tool returns an error, say so and stop.

«Always call the status tool before answering» cumple una función importante. Sin esta instrucción, un modelo que cree conocer la respuesta omitirá la herramienta y responderá de memoria. La respuesta será incorrecta con seguridad en cuanto cambie la infraestructura.

Por qué el agente entra en un bucle y qué lo detiene

También está Max Iterations en Options, con un valor predeterminado de 10. Una iteración es una llamada al modelo más un resultado de herramienta que se vuelve a incluir en el contexto. Por tanto, una ejecución del agente no es una sola llamada a la API, sino hasta diez. Cada llamada incluye como entrada toda la conversación acumulada.

Reduzca este valor. La mayoría de los agentes de una sola herramienta terminan en dos iteraciones. Un límite de 3 o 4 convierte un bucle que no termina en un error claro que puede ver en la lista de ejecuciones.

Mientras depura, active Return Intermediate Steps. La salida final incluirá las llamadas a herramientas que realizó el agente. Así puede distinguir entre «el modelo nunca llamó a la herramienta» y «la herramienta no devolvió nada útil». Desactívelo antes de pasar a producción, porque esos pasos son ruido para el usuario final.

Observe una ejecución desde el shell.

docker compose logs -f n8n

Evitar que un agente desatendido gaste recursos sin control

Un agente conectado a un Chat Trigger tiene a una persona supervisándolo, y esa persona lo detiene cuando la respuesta parece incorrecta. Un agente conectado a un Schedule Trigger no tiene supervisión. El tratamiento completo está en Controlar los costes de un agente de IA en un VPS siempre activo. Cuatro ajustes cubren la mayor parte de este problema.

• Limita Maximum Number of Tokens en el subnodo del modelo para que ninguna respuesta individual se prolongue demasiado.
• Establece Max Iterations en el número mínimo que permita completar la tarea.
• Mantén pequeñas las respuestas de las herramientas. Una herramienta que devuelve un bloque JSON de 4,000 líneas introduce todo su contenido en la siguiente llamada al modelo y, después, en todas las llamadas posteriores de la misma ejecución.
• Comprueba si el agente necesita realmente una programación. Un trabajo que se ejecuta cada cinco minutos se activa 288 veces al día. Multiplica el coste de una ejecución por ese número.

Desactiva el flujo de trabajo mientras haces pruebas. Un flujo de trabajo activo con un Schedule Trigger sigue ejecutándose con la versión que n8n ha guardado, que no siempre coincide con la versión que aparece en pantalla.

FAQ

¿Por qué mi nodo AI Agent se niega a ejecutarse?

El nodo AI Agent requiere un subnodo de modelo de chat y al menos un subnodo de herramienta. Un nodo con un modelo, pero sin ninguna herramienta, falla antes de realizar llamadas a la API. Conecte una herramienta, aunque sea trivial, y vuelva a ejecutarlo.

El agente responde, pero nunca llama a mi herramienta. ¿Cuál es el problema?

Casi siempre se debe al campo Description de la herramienta. El modelo elige las herramientas leyendo esas descripciones. Por eso, una descripción como "HTTP Request" no indica cuándo se aplica la herramienta. Reescríbala para explicar qué datos devuelve y en qué situación resulta útil. Después, añada una línea al System Message que indique al agente que debe llamar a esa herramienta antes de responder.

¿Por qué la misma pregunta cuesta una cantidad diferente en cada ejecución?

Porque el modelo elige el número de pasos. Cada iteración vuelve a enviar toda la conversación acumulada, incluida la salida anterior de la herramienta. Por eso, una ejecución de cuatro iteraciones cuesta mucho más que cuatro veces una sola llamada. Max Iterations establece el límite máximo y Return Intermediate Steps muestra cuántos pasos utilizó realmente una ejecución determinada.

La memoria funciona en el editor, pero no en producción. ¿Qué cambió?

Compruebe si la instancia se ejecuta en modo de cola. Simple Memory almacena el historial en los datos de ejecución del propio workflow. Esos datos no sobreviven cuando se entregan a un proceso de trabajo independiente, por lo que un workflow de producción activo pierde el historial. Sustituya el subnodo por Postgres Chat Memory, que conserva el historial en la base de datos que comparten todos los workers.