Módulo 1: De chatbot a agente: qué cambia con la IA agéntica

4. El nodo AI Agent nativo en n8n 2.0

Descripción

En la lección anterior viste el bucle razonar-actuar-observar como concepto: la secuencia que ejecuta un agente por dentro cuando decide qué hacer. Hoy vas a abrir el nodo que corre ese bucle por ti — vas a reconocer cada conector del nodo AI Agent de n8n 2.0, distinguir cuáles son obligatorios y cuáles opcionales, y entender qué prácticas manuales reemplazó.

Esto importa porque durante años, antes de que n8n tuviera un nodo de agente nativo, la gente que necesitaba "algo parecido a un agente" lo armaba a mano: un nodo HTTP Request llamando a la API del modelo, un Code node parseando la respuesta en JSON, y un Switch decidiendo a qué rama ir según lo que el modelo "dijo" que quería hacer. Funcionaba, a veces. Pero no había memoria real entre pasos, no había un límite de iteraciones controlado, y cada bifurcación nueva significaba más nodos IF apilados. Si hoy entras a un equipo de automatización y les dices que vas a "simular un agente con un Switch", te van a preguntar por qué no usas el nodo que ya hace exactamente eso — y necesitas poder responder con la anatomía concreta del nodo, no solo con la teoría del bucle.

Conexión con el módulo: la lección 3 te dio el modelo mental del bucle agéntico; esta lección te da su forma física en el canvas de n8n 2.0. La lección 5 va a profundizar en cada una de las cuatro piezas que se conectan al nodo (modelo, prompt, tools, memoria) — hoy es solo el mapa: qué conectores existen, qué parámetros configuras, y qué relación tienen entre sí.

El nodo raíz y sus conectores

Piensa en una central telefónica de las antiguas, de esas con clavijas y una operadora sentada en el medio. La operadora no resuelve los problemas de quien llama — no arregla la factura, no despacha el pedido. Lo que hace es escuchar la llamada, decidir a qué línea conectarla (contabilidad, bodega, soporte) y, si hace falta, volver a conectar a otra línea según la respuesta que llegue. La operadora es un punto central con varios enchufes alrededor, cada uno hacia un recurso distinto.

El nodo AI Agent es esa operadora. En la documentación de n8n aparece clasificado, literalmente, dentro de la categoría Root Nodes (nodos raíz): un nodo que no funciona solo, que necesita otros nodos conectados a sus puertos especiales para tener con qué razonar y con qué actuar. Los nodos que se conectan a esos puertos se llaman sub-nodos, y no viajan por el flujo normal de datos (la conexión "main", la línea horizontal que ya conoces de cualquier flujo de n8n). Viajan por conexiones de un tipo distinto, reservadas para IA, que en el motor de n8n tienen nombres propios:

ai_languageModel — el modelo de chat.
ai_memory — la memoria conversacional.
ai_tool — cada herramienta.
ai_outputParser — el parser de salida estructurada.

En el canvas, estas conexiones no se ven como la línea recta principal: aparecen como pequeños puertos en el borde inferior del nodo, con líneas curvas que bajan hacia cada sub-nodo. Es la señal visual de "esto no es dato que fluye, esto es una pieza que el agente usa para pensar o actuar".

Los puertos concretos del nodo AI Agent, con su comportamiento real:

Puerto	Tipo de conexión	Obligatorio	Máximo de conexiones
Chat Model	`ai_languageModel`	Sí	1
Fallback Model (si activas la opción)	`ai_languageModel`	Sí, una vez activado	1
Memory	`ai_memory`	No	1
Tool	`ai_tool`	No, según el editor — pero sin ninguno el agente no puede actuar	sin límite
Output Parser (si activas la opción)	`ai_outputParser`	No	1

Dos matices importan aquí. Primero, el puerto Chat Model filtra qué nodos puedes conectar: excluye a propósito algunos modelos de chat antiguos (como el nodo clásico de OpenAI o el de Hugging Face Inference) porque no soportan bien el tool-calling estructurado que el agente necesita para decidir qué herramienta llamar. Si arrastras el modelo equivocado, el editor ni te deja conectarlo. Segundo, el puerto Tool no lleva asterisco de obligatorio en el editor — técnicamente puedes guardar el nodo sin ninguna tool conectada — pero un agente sin tools solo puede conversar: no tiene manos, solo boca. La documentación oficial de n8n es explícita en esto: hay que conectar al menos un sub-nodo de tool para que el nodo funcione como agente de verdad.

Ejemplo trabajado

Vamos a armar el agente más simple posible y ver qué queda registrado. Sobre el canvas, conectas tres piezas al nodo AI Agent: un Chat Trigger (para recibir el mensaje), un modelo de chat, y una tool.

Paso 1 — arrastra el nodo y conecta el modelo. Sueltas "AI Agent" en el canvas. El nodo aparece con un puerto rojo "Chat Model" pidiendo conexión obligatoria. Haces clic en el botón "+ Chat Model" que aparece justo en ese puerto, eliges tu credencial de OpenAI y seleccionas el modelo.

Paso 2 — conecta una tool. Agregas un nodo "HTTP Request Tool" y lo conectas al puerto "Tool" del agente. Le das una URL que consulta el estado de un pedido por ID.

Paso 3 — defines el prompt y las opciones. En el panel del nodo, dejas "Source for Prompt (User Message)" en "Connected Chat Trigger Node" (así el agente toma el mensaje que llega del Chat Trigger sin que tengas que escribir nada más), y en "Options" escribes un System Message.

Si exportas ese workflow como JSON — algo que puedes hacer desde el menú de n8n en cualquier momento para revisar o versionar tu flujo — las conexiones especiales quedan así:

{
  "nodes": [
    {
      "name": "AI Agent",
      "type": "@n8n/n8n-nodes-langchain.agent",
      "typeVersion": 3.1,
      "parameters": {
        "promptType": "auto",
        "hasOutputParser": false,
        "options": {
          "systemMessage": "You are a support agent for an online store. Use the available tools before answering.",
          "maxIterations": 10,
          "returnIntermediateSteps": true
        }
      }
    },
    {
      "name": "OpenAI Chat Model",
      "type": "@n8n/n8n-nodes-langchain.lmChatOpenAi",
      "typeVersion": 1.3,
      "parameters": {
        "model": { "value": "gpt-5.4" }
      }
    },
    {
      "name": "Order Status Tool",
      "type": "@n8n/n8n-nodes-langchain.toolHttpRequest",
      "typeVersion": 1.1,
      "parameters": {
        "url": "https://api.example-store.com/orders/{{ $fromAI('order_id', 'The order ID mentioned by the customer', 'string') }}"
      }
    }
  ],
  "connections": {
    "OpenAI Chat Model": {
      "ai_languageModel": [[ { "node": "AI Agent", "type": "ai_languageModel", "index": 0 } ]]
    },
    "Order Status Tool": {
      "ai_tool": [[ { "node": "AI Agent", "type": "ai_tool", "index": 0 } ]]
    }
  }
}

Qué esperar: al mandar "¿Cómo va mi pedido 4821?" desde el chat, el panel de ejecución del nodo AI Agent muestra, en orden: una llamada al modelo, una llamada a "Order Status Tool" con order_id resuelto automáticamente por $fromAI() a partir del mensaje, y finalmente el texto de respuesta en $json.output. Como dejaste returnIntermediateSteps en true, el output también trae un arreglo intermediateSteps con cada acción que el agente tomó antes de responder — es tu ventana para depurar sin adivinar qué pasó adentro.

Qué reemplazó este nodo

El detalle que conviene tener claro para justificar por qué existe este nodo: hasta la versión 1.82 de n8n, el nodo AI Agent ni siquiera era uno solo por dentro — tenías que elegir un "tipo de agente" en un desplegable (Conversational Agent, OpenAI Functions Agent, ReAct Agent, entre otros), cada uno con su propia lógica interna y sus propias limitaciones. Desde esa versión, esa elección desapareció: todo nodo AI Agent trabaja como Tools Agent, el único tipo que sobrevivió por ser el más usado y el más flexible. Ya no decides "qué clase de razonamiento" quieres — el motor decide por ti cómo encadenar tools, y tú solo configuras qué tools están disponibles.

n8n 2.0 sumó otra capa encima de eso: el rediseño del panel de configuración del nodo (la vista que se abre al hacer doble clic, antes detrás de un feature flag y ahora el comportamiento por defecto) y mejoras en cómo el canvas muestra el estado visual de cada nodo — por ejemplo, un aviso directo en el propio nodo cuando falta una conexión que vas a necesitar en producción, como el de "conecta un modelo adicional como fallback" en cuanto activas esa opción. Esa retroalimentación inmediata es exactamente lo que un IF/Switch armado a mano nunca te daba: ahí, si algo fallaba a mitad del pseudo-bucle, el error aparecía tres nodos después y sin contexto de qué pieza faltaba.

Errores comunes

No conectar ninguna tool porque el editor no lo exige. El puerto Tool no lleva asterisco rojo como el Chat Model, así que es fácil guardar y publicar un agente sin ninguna tool conectada. El flujo corre sin errores — el problema es que el agente solo puede conversar, nunca actuar. Lo detectas cuando el System Message promete acciones ("voy a revisar tu pedido") pero la respuesta nunca refleja datos reales, solo texto genérico o inventado. Se corrige conectando al menos un sub-nodo de tool real antes de publicar.

Dejar "Max Iterations" en su valor por defecto para una tarea que necesita varias llamadas encadenadas. El campo trae 10 de fábrica, que alcanza para la mayoría de los casos, pero si tu tarea requiere que el agente llame a una tool, evalúe el resultado, llame a otra, y repita ese ciclo varias veces, puede cortarse a mitad de camino sin lanzar ningún error visible — simplemente entrega una respuesta incompleta. Lo detectas activando "Return Intermediate Steps" y contando cuántos pasos aparecen: si el número coincide con el límite de iteraciones, ahí está el corte. Se corrige subiendo el valor o simplificando el prompt para que necesite menos pasos.

Arrastrar el nodo de modelo de chat equivocado al puerto Chat Model. Quien viene de automatizaciones más viejas a veces intenta conectar el nodo clásico de OpenAI (el de peticiones HTTP genéricas, no el de LangChain) o un modelo como Hugging Face Inference. n8n filtra esos nodos a propósito porque no soportan el formato de tool-calling que el agente necesita para decidir qué herramienta llamar. Lo notas porque el editor directamente no te deja soltar la conexión sobre ese puerto. Se corrige usando el nodo de modelo de chat de la familia LangChain que corresponda a tu proveedor (por ejemplo, "OpenAI Chat Model", no "OpenAI").

Ejercicios

Ejercicio 1. Te pasan este fragmento de connections de un workflow exportado y el flujo no responde nunca — el chat se queda esperando:

"connections": {
  "OpenAI Chat Model": {
    "ai_languageModel": [[ { "node": "AI Agent", "type": "ai_languageModel", "index": 0 } ]]
  }
}

¿Qué falta en este workflow para que el agente pueda actuar, aunque nada del código anterior tenga un error de sintaxis?

Ver solución

Falta cualquier conexión de tipo ai_tool hacia el AI Agent. El fragmento solo conecta el modelo de chat — sintácticamente válido, el nodo corre — pero sin ninguna tool el agente solo puede generar texto conversacional. Si la tarea esperada requiere consultar un sistema externo (una API, una base de datos), el agente no tiene cómo hacerlo y probablemente entra en un ciclo de "quiero usar una herramienta que no existe" o responde con información inventada.

Por qué funciona la corrección: agregar un nodo de tool (por ejemplo un HTTP Request Tool) y conectarlo con "ai_tool": [[ { "node": "AI Agent", "type": "ai_tool", "index": 0 } ]] le da al agente un recurso real que ejecutar durante el bucle razonar-actuar-observar.

Ejercicio 2. Un agente tiene "options": { "maxIterations": 3 } y su tarea requiere: (1) buscar el ID de un cliente, (2) con ese ID buscar sus pedidos, (3) con el pedido más reciente consultar el estado de envío, (4) formatear la respuesta. ¿Qué es probable que ocurra, y qué cambiarías primero?

Ver solución

Es probable que el agente corte antes de llegar al paso 4: cada llamada a una tool (pasos 1, 2 y 3) cuenta como una iteración del bucle, así que con el límite en 3 el agente alcanza a hacer las tres consultas pero se queda sin margen para la iteración final donde arma la respuesta con esos datos — el resultado es una respuesta vacía o cortada a mitad.

Lo primero que cambiaría no es necesariamente subir maxIterations a ciegas: activaría "Return Intermediate Steps" para confirmar que efectivamente se corta ahí (y no por otra causa, como un error de la tool), y recién con esa evidencia subiría el límite a un número que cubra los pasos reales de la tarea más un margen razonable.

Ejercicio 3. Explica en dos o tres líneas, sin usar la palabra "Switch", por qué el nodo AI Agent no es "lo mismo pero más bonito" que armar la decisión a mano con nodos de lógica condicional.

Ver solución

No es una cuestión estética: el nodo AI Agent delega la decisión de qué acción tomar al modelo de lenguaje en tiempo de ejecución, dentro de un bucle que se repite hasta maxIterations sin que tú predefinas las ramas posibles. Una cadena de nodos de lógica condicional, en cambio, solo puede seguir rutas que tú anticipaste de antemano al construir el flujo. Si aparece una combinación de casos que no previste, el nodo de lógica condicional simplemente no tiene una rama para eso; el agente, con las tools correctas conectadas, puede intentar una combinación nueva porque no está siguiendo un guion fijo.

Resumen y siguiente paso

Ya reconoces la anatomía del nodo AI Agent: un nodo raíz con puertos especiales — Chat Model obligatorio y limitado a una conexión, Memory y Output Parser opcionales y también limitados a una conexión, Tool sin límite de conexiones pero indispensable en la práctica aunque el editor no lo marque como obligatorio — y sabes qué reemplazó: el desplegable de tipos de agente que existía antes de la versión 1.82 (ahora todo es Tools Agent) y las cadenas manuales de HTTP Request más Switch que la gente armaba antes de que este nodo existiera.

Lo que aprendiste hoy es el mapa; en la siguiente lección vas a entrar a cada territorio de ese mapa: qué modelo de chat elegir y por qué la elección importa, cómo escribir un System Message y un prompt que de verdad guíen al agente, qué tipos de tools existen y cuándo usar cada una, y qué opciones de memoria hay más allá de la conversación simple que probaste aquí.

Antes de avanzar deberías poder explicar, sin mirar esta lección: cuáles de los cuatro puertos del nodo AI Agent son obligatorios, qué tipo de conexión usa cada uno (ai_languageModel, ai_memory, ai_tool, ai_outputParser), y qué le pasa a un agente si no tiene ninguna tool conectada.

Recursos

AI Agent node documentation — referencia oficial del nodo: descripción, requisitos de conexión y enlaces relacionados.
Common issues — AI Agent node — errores frecuentes al configurar el prompt y el modelo, incluida la razón por la que hace falta al menos una tool.
What agents do — explica la diferencia entre un agente y una cadena (chain), y cómo decide qué tool usar.
How tools work — cómo se conectan los sub-nodos de tools al nodo raíz y qué tools trae n8n de fábrica.
How memory works — por qué solo los nodos de agente (no las chains) pueden usar memoria, y las opciones de memoria disponibles.
n8n GitHub releases — changelog real de cada versión, útil para confirmar qué cambió exactamente entre 1.x y 2.0 antes de dar por sentado un comportamiento.

← Anterior3. Qué es un bucle agéntico: razonar, actuar, observar Siguiente →5. Las cuatro piezas: modelo, prompt, tools y memoria