Cómo crear un agente de IA en 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, de forma opcional, memoria. Se indica un objetivo en lenguaje natural y el modelo decide qué herramientas debe invocar y en qué orden hasta poder responder. Todo lo que sigue es la configuración relacionada con esa idea.

Una cadena funciona al revés. En una Basic LLM Chain, usted define los pasos y el modelo sólo genera el texto. En un agente, el modelo decide los pasos. Por eso, una misma pregunta puede requerir una llamada al modelo hoy y nueve mañana. Esta diferencia determina todos los ajustes de esta guía. Si este bucle es nuevo para usted como concepto y no sólo como función de n8n, conviene escribirlo manualmente una vez antes de montarlo con nodos, porque el nodo oculta precisamente la parte sobre la que tendrá que razonar durante el resto de la guía.

Se da por hecho que n8n ya está ejecutándose detrás de HTTPS en una máquina que usted controla. Si no es así, empiece por alojar n8n en Docker con un certificado real, porque la API key que está a punto de guardar necesita la copia de seguridad de la encryption key que esa guía exige. Para los patrones sin agentes, como los resumidores mediante webhook y los clasificadores programados, consulte patrones de workflows de Claude y n8n.

Compruebe la versión antes de confiar en cualquier nombre de campo de esta guía, porque n8n modifica 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 se ejecutan como Tools Agent, por lo que el menú desplegable del tipo de agente antiguo ya no existe.

Paso 1: elija el disparador

Para un agente conversacional, añada un nodo Chat Trigger. Mantenga desactivada la opción Make Chat Publicly Available mientras realiza la configuración, para que sólo el panel de chat del editor pueda acceder a él. Actívela cuando el agente esté terminado y haya 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 la causa más frecuente del primer fallo.

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

Paso 2: la credencial del modelo

Añada un nodo AI Agent al 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, mediante Settings y después 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 a Claude.ai, por lo que la cuenta debe tener configurada la facturación 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 notifica funciona bien con Haiku, que en julio de 2026 figura con un precio de $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 su uso, cambie a Sonnet. El problema que debe evitar es que un modelo barato llame cuatro veces a la herramienta incorrecta y cueste más que un modelo caro que 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 produce el modelo. Si se deja un valor predeterminado alto, una ejecución con errores puede generar una respuesta muy larga y facturar ese consumo.

Hay una particularidad 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 prompt que recibe el agente

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

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

Con un nodo Webhook delante, el cuerpo de la petición POST se encuentra en $json.body, por lo que el campo del prompt queda así.

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 sola 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 como configuraría 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 en 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 desde 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 cuando decide si esta herramienta es relevante. Escríbalo como una afirmación directa 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 petición, use la expresión $fromAI(). Sólo 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 usar letras, dígitos, guiones bajos y guiones. El tipo debe ser uno de string, number, boolean o json, y de forma predeterminada 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 un campo llamado service desde ningún sitio. 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.

La búsqueda web es la segunda herramienta habitual. Como es simplemente otro endpoint HTTP, puede dirigir este mismo nodo a su propia instancia de SearXNG en lugar de una API de búsqueda de pago, siempre que trate cada página que devuelva como texto no fiable que ahora forma parte de su prompt.

Paso 5: memoria y por qué el agente olvida

Sin un subnodo de memoria, cada mensaje comienza desde cero. Añada 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 coste, no sólo la calidad, porque cada turno recordado se vuelve a enviar como tokens de entrada en cada llamada posterior. Una ventana de 20 en un agente conversacional implica pagar veinte veces por los mismos primeros mensajes.

Simple Memory no funciona en un flujo de trabajo de producción activo cuando n8n se ejecuta en modo de cola, porque el historial se almacena en los datos del propio flujo de trabajo y no en un almacén compartido. En una instancia en modo de cola, use el subnodo Postgres Chat Memory y configúrelo para acceder a una base de datos que puedan alcanzar tanto el proceso principal como los workers.

Paso 6: el mensaje del sistema

Abra las Options del agente y añada un System Message. Aquí se incluye la descripción del trabajo y es 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. En cuanto cambie la infraestructura, esa respuesta será incorrecta, aunque se presente con seguridad.

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

En Options también está Max Iterations, cuyo valor predeterminado es 10. Una iteración es una llamada al modelo más un resultado de herramienta que se devuelve al contexto. Por tanto, una ejecución del agente no es una sola llamada a la API. Puede incluir hasta diez llamadas, y cada una recibe como entrada toda la conversación acumulada.

Redúzcalo. La mayoría de los agentes que usan una sola herramienta terminan en dos iteraciones. Un límite de 3 o 4 turnos convierte un bucle descontrolado en un error limpio que puede ver en la lista de ejecuciones.

Mientras depura, active Return Intermediate Steps. La salida final incluye entonces 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 consuma recursos silenciosamente

Un agente detrás de un Chat Trigger tiene a una persona supervisándolo, y esa persona lo detiene cuando la respuesta parece incorrecta. Un agente detrás de un Schedule Trigger no tiene a nadie supervisándolo. Lo que se controla aquí es el gasto en modelos, no el coste de las licencias, porque los nodos de agente, herramientas y memoria funcionan en la edición gratuita autoalojada, y las funciones que requieren una clave de pago son principalmente las relacionadas con equipos y gobernanza. El tratamiento completo se encuentra en Control de costes de agentes de IA en un VPS siempre activo. Cuatro ajustes hacen la mayor parte del trabajo.

• Establezca un límite para Maximum Number of Tokens en el subnodo del modelo. Así, ninguna respuesta individual podrá prolongarse demasiado.
• Establezca Max Iterations en el número mínimo que permita completar la tarea.
• Mantenga pequeñas las respuestas de las herramientas. Una herramienta que devuelve un bloque JSON de 4,000 líneas introduce todo ese contenido en la siguiente llamada al modelo y, después, en todas las llamadas posteriores de la misma ejecución.
• Pregúntese si el agente necesita realmente una programación. Un trabajo que se ejecuta cada cinco minutos se inicia 288 veces al día. Multiplique el coste de una ejecución por esa cifra.

Desactive el flujo de trabajo mientras realiza las iteraciones. Un flujo de trabajo activo con un Schedule Trigger sigue ejecutándose con la versión que n8n ha guardado. Esa versión no siempre coincide con la 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. Añada una herramienta, aunque sea trivial, y vuelva a ejecutarlo.

El agente responde, pero nunca llama a mi herramienta. ¿Qué ocurre?

Casi siempre, el problema está en el campo Description de la herramienta. El modelo elige las herramientas leyendo esas descripciones, por lo que una descripción como "HTTP Request" no le indica cuándo se aplica la herramienta. Reescríbala para indicar qué datos devuelve y en qué situación resulta útil. Después, añada una línea al System Message para indicar al agente que llame 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 llamada individual. Max Iterations establece el límite máximo, y Return Intermediate Steps muestra cuántos pasos utilizó realmente una ejecución concreta.

Mi memoria funciona en el editor, pero no en producción. ¿Qué ha cambiado?

Compruebe si la instancia se ejecuta en modo de cola. Simple Memory almacena el historial en los datos de ejecución del propio workflow. Estos datos no sobreviven cuando la ejecución se entrega 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 compartida por todos los procesos de trabajo.