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

Una cadena funciona al contrario. En una Basic LLM Chain, usted decide los pasos y el modelo sólo completa 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. Esa diferencia determina todos los ajustes de esta guía. Si este bucle es una idea nueva para usted, no sólo una función de n8n, conviene escribirlo manualmente una vez antes de ensamblarlo con nodos, porque el nodo oculta la parte exacta cuyo comportamiento tendrá que analizar durante el resto de esta guía.

Se presupone que n8n ya se está ejecutando detrás de HTTPS en una máquina bajo su control. Si no es así, empiece por alojar n8n en Docker con un certificado válido, porque la clave de API que está a punto de guardar necesita la copia de seguridad de la clave de cifrado que exige esa guía. 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 su versión antes de confiar en cualquier nombre de campo de este documento, porque n8n modifica los nodos de IA con frecuencia.

docker compose exec n8n n8n --version

La versión 1.82.0 dejó obsoleto el ajuste del tipo de agente en favor de Tools Agent. Los nodos heredados v1 todavía incluyen ese ajuste; la documentación de n8n prevé eliminar esa versión del nodo en n8n 3.0.

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 Claude Console, en platform.claude.com, mediante Settings y después API keys. La clave se muestra una sola vez. Console también le pide que elija una fecha de expiración al crear la clave. Un agente sin supervisión deja de funcionar el día en que expira su clave. Guarde esa fecha en un lugar visible. Para un agente sin supervisión, use una clave de cuenta de servicio con alcance limitado a un workspace. Así, las solicitudes no necesitan una cabecera de workspace independiente.

El uso de la API se factura por token. La forma de pago depende del plan de Claude vigente el 31 de octubre de 2026. Los planes Max, Ultra y Team incluyen créditos mensuales para la API: $100 en Max, $200 en Ultra y hasta $500 compartidos en Team. Puede reclamarlos vinculando una organización de Console al plan desde Settings > Billing en Max o Ultra, o desde Organization settings > Billing en Team. No es necesario añadir un método de pago en Console. Los suscriptores nuevos pueden reclamarlos después de 7 días en el plan. Los créditos no utilizados caducan al final de cada ciclo de facturación, o mensualmente en los planes anuales. Cuando se agotan los créditos incluidos, las solicitudes siguen consumiendo créditos comprados. La recarga automática puede comprar más créditos y las organizaciones facturadas reciben una factura por el uso excedente. Las solicitudes se detienen cuando una organización prepaga no tiene créditos. El uso de la API nunca se carga al plan de Claude. Los planes Free, Pro y Enterprise no incluyen créditos mensuales para la API. En estos planes, la API se factura por separado de la suscripció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. La versión actual, Haiku 5.5, tiene un precio de $0.10 por millón de tokens de entrada y $0.50 por millón de tokens de salida a fecha de 12 de octubre de 2026. El precio aumenta a $0.50 y $2.50 para cualquier solicitud cuyo prompt supere los 100,000 tokens. Una ventana de memoria extensa y resultados grandes de las herramientas pueden superar ese límite. Cuando el agente tenga varias herramientas y deba planificar su uso, cambie a Sonnet. El problema que debe evitar es un modelo barato que llame cuatro veces a la herramienta incorrecta. Eso cuesta 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 genera el modelo. Si mantiene un valor predeterminado alto, una ejecución confusa puede generar una respuesta muy larga y aumentar el coste.

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 que dependan 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 Source for Prompt (User Message) tiene dos opciones.

• Connected Chat Trigger Node espera un campo de entrada llamado chatInput. Esta es la opción adecuada cuando se usa 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 adecuada cuando se usa un Schedule Trigger o un Webhook node.

Cuando hay un Webhook node delante, el cuerpo de la solicitud 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

La documentación de n8n indica que debe conectar al menos un subnodo de herramienta a un nodo AI Agent, aunque el código actual del nodo (versión 3.1) sólo impide la ejecución cuando falta un modelo de chat. Empiece con una sola herramienta de todos modos, porque una herramienta que funciona le enseña más que cuatro configuradas a medias, y un agente sin herramientas no es más que una cadena con un coste mayor.

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 fallo parecerá un problema del modelo, aunque en realidad será un problema de URL o de 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. El modelo lo lee junto con el nombre de la herramienta y el esquema de parámetros para decidir si la herramienta es relevante. Escríbalo como una afirmació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 petición, use la expresión $fromAI(). Sólo funciona en herramientas conectadas a un nodo AI Agent y no funciona en la herramienta Code.

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

Los argumentos son key, seguidos de description, type y defaultValue opcionales. 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 su valor predeterminado es string. Esta es una llamada más completa.

{{ $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 de ninguna ubicación. Indica al modelo que "produzca un valor y lo llame service", y el modelo busca uno en la conversación, los datos de entrada y los resultados de otras herramientas. En un flujo de chat, puede limitarse a preguntárselo al usuario.

La búsqueda web suele ser la segunda herramienta. Como es 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 confiable que ahora forma parte de su prompt.

Paso 5: memoria y por qué el agente olvida

Sin un subnodo de memoria, cada mensaje parte de cero. Conecte un subnodo Simple Memory para conservar la conversación reciente.

Tiene dos parámetros. Session Key determina de qué conversación se trata, de modo que dos usuarios con claves diferentes obtienen historiales independientes. 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 reenvía como tokens de entrada en todas las llamadas posteriores. Una ventana de 20 en un agente con mucha actividad implica pagar veinte veces por los mismos mensajes iniciales.

Simple Memory no funciona en un flujo de producción activo cuando n8n se ejecuta en modo de cola, porque almacena el historial en un Map singleton local al proceso, indexado por los ID del flujo de trabajo y de la sesión, y los workers no comparten esa memoria. En una instancia en modo de cola, use el subnodo Postgres Chat Memory y configúrelo para conectarse a una base de datos accesible tanto desde el proceso principal como desde 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é se repite el ciclo del agente y qué lo detiene

En Options también está Max Iterations, cuyo valor predeterminado es 10. Una iteración es una llamada al modelo. La llamada solicita herramientas o devuelve la respuesta final. Los resultados de las herramientas se incorporan a la siguiente llamada. Por tanto, una ejecución del agente no consiste en una sola llamada a la API. Puede incluir hasta diez llamadas. Cada una envía como entrada toda la conversación acumulada.

Reduzca este valor. La mayoría de los agentes que usan una sola herramienta terminan en dos iteraciones. Un límite de 3 o 4 convierte un ciclo descontrolado en un fallo 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ó información útil». Desactívela antes de pasar a producción. Esos pasos no son útiles para el usuario final.

Observe una ejecución desde el shell.

docker compose logs -f n8n

Evitar que un agente desatendido consuma recursos en segundo plano

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 supervisión. Aquí se controla el consumo del modelo, no el coste de las licencias, porque los nodos del agente, las herramientas y la memoria funcionan en la edición self-hosted gratuita, y las funciones que sí necesitan una clave de pago son principalmente las relacionadas con equipos y gobierno. El tratamiento completo está en Controlar los costes de un agente de IA en un VPS siempre activo. Cuatro ajustes cubren la mayor parte del trabajo.

• Limite Maximum Number of Tokens en el subnodo del modelo para que ninguna respuesta se prolongue 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 ese número por el coste de una ejecución.

Deje de publicar el workflow mientras lo itera o, como mínimo, recuerde qué versión está activa. Un workflow publicado con un Schedule Trigger sigue ejecutando la última versión publicada, no el borrador que aparece en pantalla, porque n8n mantiene los cambios como borrador hasta que vuelve a publicarlos.

FAQ

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

Compruebe primero los conectores. El nodo AI Agent necesita un subnodo de modelo de chat. Sin uno, se detiene con el mensaje "Please connect a model to the Chat Model input" antes de realizar cualquier llamada a la API. La documentación de n8n también indica que se necesita al menos un subnodo de herramienta. Si el modelo está conectado y el nodo sigue rechazando la ejecución, 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 tanto, 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 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 que tarda cuatro iteraciones factura los tokens de entrada y salida de las cuatro llamadas. Max Iterations establece el límite máximo. 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 un Map singleton local al proceso, indexado por los IDs del flujo de trabajo y de la sesión. Los procesos worker independientes no comparten ese Map. Sustitúyalo por el subnodo Postgres Chat Memory, que almacena el historial en la base de datos que comparten todos los workers.