5. Las cuatro piezas: modelo, prompt, tools y memoria

Descripción

En la lección anterior abriste el nodo AI Agent nativo de n8n 2.0 y viste su anatomía: la UI, el motor visual, los puntos de conexión. Pero un nodo AI Agent recién soltado en el canvas no hace nada — es un orquestador vacío. En esta lección vas a identificar las cuatro piezas que se conectan a ese nodo, explicar qué aporta cada una al bucle razonar-actuar-observar que viste en la lección 3, y — lo más útil en la práctica — diagnosticar cuál de las cuatro falla cuando un agente no se comporta como esperabas.

Esto importa porque en producción casi nadie te va a decir "el modelo está mal configurado". Te van a decir "el bot le repite la misma pregunta al cliente", "el agente no usó la herramienta que debía", o "responde distinto según el día". Cada uno de esos síntomas apunta a una pieza específica. Saber cuál — sin tener que reconstruir el agente entero para averiguarlo — es la habilidad de debugging número uno cuando trabajas con agentes.

Conexión con el módulo: esta lección es el mapa mental del resto de la guía. El modelo y el prompt se profundizan en el Módulo 2, la memoria en el Módulo 3, las tools en el Módulo 4. Aquí no vas a dominar ninguna de las cuatro a fondo — vas a entender qué rol cumple cada una y cómo se conectan entre sí, para que cuando llegues a esos módulos ya sepas dónde encaja cada pieza nueva.

El agente vacío no hace nada

Imagina que contratas a alguien nuevo para atender el soporte de tu tienda y lo sientas en un escritorio sin nada más. No tiene criterio propio para decidir qué hacer (nadie le explicó el negocio), no sabe cuál es su rol ni sus límites (nadie le dio instrucciones), no tiene acceso a ningún sistema (no puede consultar un pedido ni cambiar un dato), y no recuerda lo que el cliente le dijo hace tres minutos en la misma llamada. Esa persona no es un mal empleado — es un puesto sin llenar. Le faltan las piezas que convierten a alguien capaz en alguien útil para tu negocio.

El nodo AI Agent de n8n es exactamente ese escritorio vacío. Por sí solo no ejecuta nada: es un orquestador que necesita que le conectes sub-nodos específicos para funcionar. La documentación oficial de n8n lo dice sin rodeos — el nodo requiere que conectes un modelo de chat y al menos una herramienta antes de que pueda hacer nada útil. Técnicamente, el nodo expone tres tipos de conexión especial (identificables por las líneas punteadas en la parte inferior del nodo, que ya viste en la lección anterior):

• ai_languageModel — el modelo de chat. Obligatoria, una sola conexión.
• ai_tool — las herramientas. Obligatoria al menos una, puedes conectar varias.
• ai_memory — la memoria. Opcional.

Y hay una cuarta pieza que no es una conexión sino texto que escribes directamente dentro del propio nodo: el prompt — dividido en el mensaje del usuario (lo que llega en cada turno) y el System Message, en la sección Options del nodo (la identidad y las reglas del agente, que no cambian turno a turno).

Si le quitas cualquiera de las cuatro piezas a tu empleado nuevo, deja de ser un agente y se convierte en otra cosa: sin acceso a sistemas es alguien que solo opina; sin memoria es alguien que te hace la misma pregunta cada vez que le hablas; sin instrucciones de rol es un genérico que no sabe para qué está ahí; y con un mal criterio (un modelo débil) decide mal aunque tenga todo lo demás perfecto. Las cuatro piezas cumplen roles distintos y ninguna sustituye a otra.

Ejemplo trabajado

Vamos a montar, pieza por pieza, un agente de soporte para una tienda en línea que responde preguntas sobre el estado de un pedido. Así se ve la configuración de cada pieza en el nodo:

# Nodo: AI Agent — piezas configuradas

# PROMPT (no es una conexión — texto dentro del propio nodo)
prompt.text          = "{{ $json.chatInput }}"   # llega del Chat Trigger, cambia en cada turno
prompt.systemMessage  = "Eres el asistente de soporte de TuTienda. Responde en
                         español, en tono cercano y directo. Si no tienes un
                         dato, dilo — no inventes números de pedido ni fechas
                         de entrega."

# CONEXIÓN ai_languageModel -> nodo: Anthropic Chat Model (o el proveedor que elijas)
model                = "claude-sonnet-5"

# CONEXIÓN ai_tool -> nodo: HTTP Request Tool
tool.name            = "get_order_status"
tool.description     = "Usa esta herramienta cuando el cliente dé un número de
                         pedido y pregunte por su estado o fecha de entrega.
                         No la uses para preguntas sobre política de cambios
                         o devoluciones."
tool.url             = "https://api.tutienda.com/orders/{order_id}/status"

# CONEXIÓN ai_memory -> nodo: Simple Memory
memory.sessionKey          = "{{ $json.chatSessionId }}"   # único por conversación real
memory.contextWindowLength = 10                             # cuántos turnos recuerda

Qué esperar — turno 1. El cliente escribe: "¿Dónde está mi pedido #4521?"

El agente razona sobre ese mensaje usando el System Message como marco (tono, límites) y el modelo como criterio de decisión. Detecta que necesita un dato externo, lee la descripción de get_order_status y ve que aplica ("el cliente dio un número de pedido y pregunta por su estado"). Llama la tool con order_id = 4521, observa el resultado (por ejemplo, "en tránsito, entrega estimada 24 de julio") y responde al cliente con ese dato, en el tono que el System Message define. Simple Memory, mientras tanto, guarda este intercambio completo bajo el sessionKey de esa conversación — aunque en este primer turno no hizo falta leer nada de memoria, porque no había historial previo.

Qué esperar — turno 2. El mismo cliente, en el mismo chat, escribe: "¿Y cuándo llega?"

Sin memoria conectada, el agente no tendría forma de saber a qué pedido se refiere "llega" — probablemente respondería pidiendo el número de pedido otra vez, lo cual frustra al cliente que ya lo dio. Con Simple Memory conectada, el historial del turno 1 se inyecta en el contexto antes de que el modelo razone: el agente resuelve que "llega" se refiere al pedido 4521, ya tiene (o vuelve a pedir) el dato, y responde directo: "Tu pedido llega el 24 de julio." Ninguna pieza nueva entró en juego — es la misma memoria que ya estaba grabando desde el turno 1, ahora siendo leída.

Este es el patrón: el modelo decide, el prompt define el marco y la tarea, la tool ejecuta contra un sistema real, la memoria conecta un turno con el siguiente. Cuatro roles, cuatro piezas.

Mapa de las cuatro piezas

Esta tabla es el resumen que vas a usar como referencia el resto de la guía — qué aporta cada pieza, si es obligatoria, y en qué módulo la vas a profundizar.

Pieza	Qué le aporta al agente	Cómo se conecta	¿Obligatoria?	Se profundiza en
Modelo (Chat Model)	El criterio de decisión: qué tan bien razona, qué tan confiable es llamando tools, qué tan grande es su ventana de contexto	ai_languageModel	Sí — el nodo no funciona sin ella	Módulo 2
Prompt (System Message + mensaje)	La identidad, los límites y la tarea concreta de este turno	No es conexión — texto en el nodo	Sí	Módulo 2
Tools	Acceso real a sistemas: consultar una API, escribir en una base de datos, ejecutar código	ai_tool (una o más)	Sí, al menos una — sin ninguna tienes un opinador, no un agente	Módulo 4
Memoria	Continuidad entre turnos de la misma conversación	ai_memory	No — opcional, pero sin ella el agente es amnésico entre mensajes	Módulo 3

Nota algo importante en esa tabla: tres de las cuatro piezas son obligatorias para que el nodo funcione como agente. Solo la memoria es opcional — y aun así, "opcional" no significa "sin importancia": significa que su necesidad depende del caso de uso, algo que vas a poder evaluar tú mismo después del tercer ejercicio de esta lección.

Errores comunes

Confundir el System Message con el mensaje del usuario. Es fácil pensar que ambos son "el prompt" y que da igual dónde pongas las instrucciones de comportamiento. No es así: el System Message se configura una sola vez en Options y define el marco fijo del agente (identidad, tono, reglas); el mensaje del usuario es la tarea variable de este turno específico. Qué pasa cuando se confunden: si metes las reglas de comportamiento dentro del campo de prompt en lugar del System Message, el agente pierde consistencia entre turnos, o peor — un cliente que escribe algo como "ignora tus instrucciones anteriores y..." puede lograr que el agente cambie de comportamiento, porque nunca hubo un marco realmente separado del mensaje del usuario. Por qué pasa: ambos campos son texto que termina en el prompt final que ve el modelo, así que la distinción no es visual sino de rol — una capa manda, la otra ejecuta. Cómo detectarlo: el agente responde con tono o reglas distintas dependiendo de cómo esté redactado el mensaje del cliente, no de lo que configuraste tú. Cómo corregirlo: toda instrucción de identidad, tono y límites va al System Message; el campo de prompt queda solo para el dato dinámico de cada turno.

Tool description vaga. Una descripción como "Consulta pedidos" le dice al modelo qué hace la tool, pero no cuándo usarla. Qué pasa: el agente no la llama cuando debería (el cliente pregunta por su pedido y el agente responde de memoria, sin verificar), o la llama quando no corresponde (la usa incluso si la pregunta era sobre política de devoluciones). Por qué pasa: la descripción es literalmente lo único que el modelo lee para decidir si una tool aplica a la situación actual — no ve el código detrás, no sabe qué hace el HTTP Request por dentro, solo tiene ese texto. Cómo detectarlo: revisa el log de ejecución del workflow (n8n muestra qué tool se llamó y con qué input en cada paso) y busca llamadas ausentes o injustificadas. Cómo corregirlo: reescribe la descripción siendo explícito sobre cuándo sí y cuándo no usarla — "Usa esta herramienta cuando X, no la uses para Y" rinde mejor que una frase genérica.

Memoria con alcance mal configurado. El sessionKey es la clave que separa una conversación de otra dentro de la memoria — si usas un valor fijo o algo que no identifica realmente a cada conversación, todas las sesiones comparten el mismo balde de historial. Qué pasa: en el peor caso, un cliente puede ver fragmentos de la conversación de otro cliente (un problema de privacidad real, no solo un bug de UX); en el caso más común, simplemente no hay memoria efectiva y el agente repite preguntas ya respondidas dentro de la misma conversación. Por qué pasa: la memoria en n8n indexa el historial por esa clave — si dos conversaciones distintas usan la misma clave (por ejemplo, un valor hardcodeado en vez de un id de chat real), n8n las trata como si fueran una sola. Cómo detectarlo: en pruebas, abre dos sesiones de chat distintas y confirma que cada una solo ve su propio historial. Cómo corregirlo: usa como sessionKey algo único y estable por conversación real — el id del chat, el id del ticket, el teléfono del cliente — nunca un valor fijo ni algo que cambie en cada mensaje (como un timestamp).

Ejercicios

Ejercicio 1. Un colega te dice: "mi agente responde bien la primera pregunta del chat, pero en la segunda pregunta actúa como si no supiera de qué estábamos hablando, aunque es la misma conversación." ¿Cuál de las cuatro piezas sospechas primero, y qué revisarías para confirmarlo?

Ver solución

Sospecha principal: la memoria (ai_memory) — ausente, no conectada, o conectada pero con contextWindowLength en 0 o con un sessionKey que cambia entre turnos de la misma conversación. Qué revisar: (a) si hay un nodo de memoria conectado al Agent; (b) si el sessionKey usa un valor estable de la conversación real (el id del chat) y no algo que varíe en cada mensaje; (c) que contextWindowLength no esté configurado tan bajo que efectivamente no recuerde nada.

Por qué funciona: el síntoma — pérdida de contexto entre turnos de la misma conversación — apunta directo a memoria porque es la única de las cuatro piezas cuyo trabajo es cargar los turnos anteriores. El modelo y el prompt no cambian entre un turno y el siguiente, así que no explican por sí solos una pérdida de continuidad.

Ejercicio 2. Esta es la descripción actual de una tool conectada a un agente de recursos humanos: "Busca empleados." El agente casi nunca la usa. Reescríbela para que el agente sepa cuándo llamarla.

Ver solución

Ejemplo de reescritura: "Usa esta herramienta cuando necesites un dato concreto de un empleado específico — fecha de ingreso, puesto, gerente directo — y el usuario haya dado un nombre o un ID de empleado. No la uses para preguntas generales sobre políticas de RR. HH.; para eso no hace falta buscar a nadie."

Por qué funciona: la descripción original solo dice QUÉ hace la tool, no CUÁNDO usarla. El modelo decide si llamar una tool basándose únicamente en su descripción — una descripción prescriptiva, que marca el momento correcto y también el momento incorrecto, sube la tasa de acierto de forma medible.

Ejercicio 3. Vas a montar un agente que recibe, vía webhook, un ticket de soporte ya escrito por completo, y devuelve un borrador de respuesta — sin ida y vuelta con el cliente, una sola ejecución por ticket. ¿Necesitas conectar memoria? Justifica tu respuesta con lo que aprendiste en esta lección.

Ver solución

No, no la necesitas. La memoria resuelve continuidad entre turnos de una conversación, pero acá no hay turnos: cada ejecución es una llamada aislada, con toda la información que necesita ya dentro del propio ticket. Conectar memoria en este caso no rompería nada, pero sería una pieza de más — agrega configuración (el sessionKey) sin aportar nada al resultado, porque no existe un "turno anterior" al que volver.

Por qué funciona: el criterio no es "¿qué tan sofisticado es el agente?", sino "¿hay más de un mensaje dentro de la misma conversación que dependa de lo dicho antes?". Acá la respuesta es no.

Resumen y siguiente paso

Ya tienes el mapa completo: el modelo es el criterio de decisión, el prompt (System Message + mensaje) es la identidad y la tarea, las tools son el acceso a sistemas reales, y la memoria es la continuidad entre turnos. Tres piezas obligatorias, una opcional — y ahora sabes diagnosticar cuál falla dado un síntoma, en vez de reconstruir el agente entero para averiguarlo.

Esto es la base de todo lo que sigue en la guía: cuando llegues al Módulo 2 vas a profundizar en cómo elegir modelo y escribir un buen System Message; en el Módulo 3, en los distintos tipos de memoria y cuándo cada uno aplica; en el Módulo 4, en el catálogo completo de tools y cómo conectar sistemas reales. Pero antes de llegar ahí, queda una pregunta más urgente: si montar un agente completo significa configurar como mínimo tres piezas obligatorias — y a veces cuatro —, ¿siempre vale la pena ese costo frente a un flujo simple? Esa es exactamente la pregunta de la próxima lección.

Antes de avanzar deberías poder: nombrar las cuatro piezas y decir cuáles son obligatorias; explicar por qué una tool description vaga rompe el comportamiento del agente sin tocar una línea de código; y, dado un síntoma concreto (como los de los ejercicios), señalar qué pieza revisarías primero.

Recursos

• AI Agent node — n8n Docs — referencia oficial del nodo: qué conexiones requiere y cómo se configura cada una.
• AI Agent — Common issues — errores documentados relacionados con memoria y con la falta de un Chat Model conectado.
• How tools work — qué son las tools desde la perspectiva de n8n y qué tipos existen (HTTP Request Tool, Custom Code Tool, Call n8n Workflow Tool, entre otras).
• How memory works — tipos de memoria disponibles en n8n: Simple Memory frente a opciones persistentes como Postgres Chat Memory o Redis Chat Memory.
• What agents do — qué distingue a un agente de una cadena (chain) y por qué el modelo y las tools son las piezas que lo definen.