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

8. Mini-proyecto: tu primer agente que responde

Siguiente →

Descripción

Hoy vas a dejar la teoría atrás por un rato y a montar, de principio a fin, el agente más simple que de verdad funciona: un Chat Trigger, un modelo de chat, y una sola tool — sin memoria, sin ramas extra, sin nada que no necesites para la primera prueba. Vas a mandarle un mensaje desde el chat interno de n8n y vas a confirmar, mirando el log de ejecución y no solo la respuesta, que el bucle razonar-actuar-observar que viste en la lección 3 corrió de verdad.

Esto importa porque es exactamente el paso que un equipo real espera ver antes de construir nada más encima: "muéstrame que responde" no es lo mismo que "muéstrame que el agente decide por sí mismo cuándo usar una herramienta". Cualquiera puede conectar un modelo de chat solo y hacerle unas preguntas — eso ya existía antes de este módulo. Lo que vas a probar hoy es que las piezas que estudiaste realmente encajan y producen el comportamiento que prometían: un modelo que decide llamar a una herramienta cuando la necesita, no cuando tú se lo dictas paso a paso.

Conexión con el módulo: esta es la última lección del módulo. Community self-hosted, la decisión que tomaste en la lección anterior, es donde vas a correr este agente — $0 de infraestructura, con los nodos de IA ya incluidos en el core. Hoy juntas eso con todo lo demás: el nodo (lección 4), las cuatro piezas (lección 5), y el criterio de cuándo vale la pena un agente (lección 6) — aplicado, por primera vez, sobre un caso real en tu propio n8n.

Qué significa que el agente "funcione"

Cuando alguien rinde el examen práctico de manejo, la prueba no es "arranca el auto y da una vuelta a la manzana sin chocar" — con algo de suerte, cualquiera pasa eso. La prueba real incluye una situación donde el evaluador sabe, de antemano, que vas a tener que tomar una decisión: un semáforo en amarillo, un peatón que no se ve claro si va a cruzar. No basta con que el auto se mueva; hace falta ver que decidiste bien en el momento exacto donde había una decisión real que tomar.

Con un agente pasa lo mismo. Si le mandas al chat una pregunta que el modelo ya sabe responder de memoria — "¿cuánto es 2+2?", "¿en qué idioma se habla en Francia?" — vas a recibir una respuesta correcta aunque el agente nunca haya tocado ninguna tool. Eso no prueba nada: como viste en la lección 3, el número de vueltas del ciclo razonar-actuar-observar no está fijo, y puede ser cero. Un agente sin ninguna tool conectada, o con una tool rota, puede dar exactamente esa misma respuesta correcta, y nunca te enterarías de que algo anda mal — hasta que le preguntes algo que de verdad depende de un dato externo.

Por eso este mini-proyecto tiene dos objetivos, no uno: que el agente responda (lo fácil), y que puedas señalar, en el log de ejecución, el momento exacto donde razonó, actuó llamando a tu tool, y observó el resultado antes de responder. Eso segundo es lo que de verdad prueba que montaste un agente, y no un chat con un modelo suelto.

Ejemplo trabajado

Vas a montar un agente de referencia general con una sola tool: consulta el resumen de un artículo de Wikipedia a través de la API pública de Wikimedia (no necesita API key ni cuenta — cero costo, cero fricción para esta primera prueba). El system message está escrito a propósito para forzar el comportamiento que quieres verificar: que el agente use la tool para hechos concretos, aunque crea saber la respuesta.

Paso 1 — arrastra el Chat Trigger. En un workflow nuevo, agrega el nodo "When chat message received" (categoría Trigger). Este es el nodo que abre, más abajo en el canvas, el panel de Chat que vas a usar para probar — no hace falta configurar nada más que dejarlo con sus valores por defecto para una prueba local.

Paso 2 — agrega el AI Agent y conéctalo al Chat Trigger. Arrastra el nodo "AI Agent" y conecta la salida principal del Chat Trigger a su entrada principal (la línea recta, no los puertos curvos de abajo). Sin esta conexión —fácil de pasar por alto cuando te concentras en los conectores de IA— el chat nunca dispara al agente.

Paso 3 — conecta el modelo de chat. Haz clic en el botón "+ Chat Model" que aparece en el puerto obligatorio del AI Agent. Elige tu credencial (la que ya tengas configurada para tu proveedor) y el modelo. Antes de seguir, confirma que la credencial es válida — es el error más común de esta lección, y lo vas a ver en la sección de errores comunes.

Paso 4 — conecta la tool. Agrega un nodo "HTTP Request Tool" y conéctalo al puerto "Tool" del AI Agent. Configúralo así:

  • Nombre del nodo: Wikipedia Summary
  • Descripción de la tool: "Usa esta herramienta cuando necesites confirmar un hecho concreto sobre una persona, un lugar o un concepto específico. No la uses para cálculos ni para preguntas de opinión."
  • URL: https://en.wikipedia.org/api/rest_v1/page/summary/{{ $fromAI('title', 'Wikipedia page title in English, with spaces replaced by underscores, e.g. Ada_Lovelace', 'string') }}

Paso 5 — escribe el system message. En "Options" del AI Agent:

Eres un asistente de referencia general. Antes de responder cualquier
pregunta sobre una persona, un lugar o un concepto histórico específico,
usa la herramienta Wikipedia Summary para confirmar el dato, incluso si
crees saber la respuesta. Cita brevemente el resumen que obtuviste. Para
preguntas de cálculo u opinión, responde directo sin usar la herramienta.

Deja también activada la opción "Return Intermediate Steps" — la vas a necesitar en la siguiente sección para confirmar que el ciclo corrió.

Así queda el workflow exportado como JSON (las conexiones que importan hoy):

{
  "nodes": [
    {
      "name": "When chat message received",
      "type": "@n8n/n8n-nodes-langchain.chatTrigger"
    },
    {
      "name": "AI Agent",
      "type": "@n8n/n8n-nodes-langchain.agent",
      "typeVersion": 3.1,
      "parameters": {
        "promptType": "auto",
        "options": {
          "systemMessage": "Eres un asistente de referencia general. Antes de responder cualquier pregunta sobre una persona, un lugar o un concepto histórico específico, usa la herramienta Wikipedia Summary para confirmar el dato, incluso si crees saber la respuesta. Cita brevemente el resumen que obtuviste. Para preguntas de cálculo u opinión, responde directo sin usar la herramienta.",
          "returnIntermediateSteps": true
        }
      }
    },
    {
      "name": "Anthropic Chat Model",
      "type": "@n8n/n8n-nodes-langchain.lmChatAnthropic",
      "parameters": { "model": { "value": "claude-sonnet-5" } }
    },
    {
      "name": "Wikipedia Summary",
      "type": "@n8n/n8n-nodes-langchain.toolHttpRequest",
      "typeVersion": 1.1,
      "parameters": {
        "url": "https://en.wikipedia.org/api/rest_v1/page/summary/{{ $fromAI('title', 'Wikipedia page title in English, with spaces replaced by underscores, e.g. Ada_Lovelace', 'string') }}"
      }
    }
  ],
  "connections": {
    "When chat message received": {
      "main": [[ { "node": "AI Agent", "type": "main", "index": 0 } ]]
    },
    "Anthropic Chat Model": {
      "ai_languageModel": [[ { "node": "AI Agent", "type": "ai_languageModel", "index": 0 } ]]
    },
    "Wikipedia Summary": {
      "ai_tool": [[ { "node": "AI Agent", "type": "ai_tool", "index": 0 } ]]
    }
  }
}

Qué esperar. Guarda el workflow (no hace falta activarlo para esta prueba) y abre el panel de Chat que aparece en el canvas — ese panel es lo que provee el nodo Chat Trigger. Escribe:

¿Quién fue Ada Lovelace?

La respuesta que deberías recibir, un par de segundos después:

Ada Lovelace (1815–1852) fue una matemática y escritora inglesa, conocida principalmente por su trabajo sobre la máquina analítica propuesta por Charles Babbage — considerada por muchos la primera programadora de la historia. (Fuente: resumen de Wikipedia.)

Eso ya es una señal de que "algo" funcionó. Pero el objetivo real de este mini-proyecto está en la siguiente sección: confirmar que esa respuesta no salió solo de la memoria del modelo.

Cómo confirmar que el bucle corrió de verdad

Con "Return Intermediate Steps" activado, abre la ejecución que acabas de disparar (el panel de ejecuciones, o el propio nodo AI Agent después de correr) y revisa el output. Deberías ver algo así:

{
  "output": "Ada Lovelace (1815–1852) fue una matemática y escritora inglesa...",
  "intermediateSteps": [
    {
      "action": {
        "tool": "Wikipedia Summary",
        "toolInput": { "title": "Ada_Lovelace" }
      },
      "observation": "{\"title\":\"Ada Lovelace\",\"extract\":\"Augusta Ada King, Countess of Lovelace, also known as Ada Lovelace, was an English mathematician and writer chiefly known for her work on Charles Babbage's proposed mechanical general-purpose computer, the analytical engine...\"}"
    }
  ]
}

Ese arreglo intermediateSteps con una entrada es tu prueba: el agente razonó ("necesito confirmar este dato"), actuó (llamó a Wikipedia Summary con title: "Ada_Lovelace" — nota que resolvió solo el guion bajo, a partir de la descripción que le diste en $fromAI()), y observó el resultado (el JSON con el extract) antes de redactar la respuesta final. Si haces clic en el nodo "Wikipedia Summary" dentro del panel de ejecución, vas a ver ese mismo intercambio del lado del nodo: la URL resuelta con el título ya insertado, y la respuesta cruda de la API de Wikimedia.

Ahora repite la prueba con una pregunta que tu system message excluye a propósito:

¿Cuánto es 15 por 12?

Esta vez, si abres intermediateSteps, vas a encontrar un arreglo vacío — cero vueltas de actuar y observar. El agente razonó una sola vez y decidió que no necesitaba ninguna tool, exactamente como viste en la lección 3 con el ejemplo del horario de atención. Las dos pruebas juntas — una con tool, una sin tool, ambas correctas — son lo que te deja seguro de que el agente está decidiendo, no solo repitiendo.

Errores comunes

Dar por bueno el mini-proyecto solo porque la respuesta sonó correcta. Es el error conceptual central de esta lección. Qué pasa: mandas una pregunta, la respuesta es coherente y bien redactada, y cierras el mini-proyecto asumiendo que probaste el bucle agéntico — cuando en realidad pudiste haber probado solo que el modelo de chat, solo, sabe responder preguntas generales de su propio entrenamiento. Por qué pasa: una respuesta que vino de una tool real y una respuesta que vino de la memoria paramétrica del modelo se ven idénticas desde el chat; la única diferencia queda registrada en intermediateSteps, que nadie mira si el chat "ya respondió bien". Cómo detectarlo: revisa siempre el log de ejecución, no solo el chat — y hazte la pregunta antes de escribir el mensaje de prueba: ¿esta pregunta obliga al modelo a usar la tool, o la puede resolver solo? Cómo corregirlo: diseña el mensaje de prueba (como el de Ada Lovelace) sabiendo que tu system message fuerza el tool call para ese tipo de pregunta, y confirma intermediateSteps antes de dar el mini-proyecto por terminado.

Probar con el botón de "Test workflow" del canvas en vez del panel de Chat. Qué pasa: ejecutas el workflow completo con ese botón general, y el AI Agent recibe un input vacío o de prueba genérico, no un mensaje de chat real — la ejecución falla o produce una respuesta sin sentido, y parece que el agente está roto. Por qué pasa: "Test workflow" ejecuta el flujo una sola vez con los datos que tenga a mano, pensado para nodos normales de datos, no para una conversación de chat con turnos. Cómo detectarlo: si ves que el AI Agent corre con un campo de mensaje vacío o con una expresión sin resolver, esa es la señal. Cómo corregirlo: usa el panel de Chat que aparece en el canvas en cuanto agregas un Chat Trigger — ese panel sí simula una conversación real, turno por turno.

Mandar el primer mensaje sin haber configurado la credencial del modelo de chat. Qué pasa: el chat responde con un error de autenticación (o directamente no responde), y es fácil interpretar eso como "el agente no funciona" o "el bucle está roto", cuando el problema real es que la credencial de tu proveedor nunca quedó guardada o venció. Por qué pasa: en la lección anterior viste que self-hosted Community te da la infraestructura de n8n gratis — pero eso no incluye la llamada al modelo de chat, que sigue teniendo su propio costo y su propia clave según el proveedor, a menos que conectes un modelo que corras tú mismo. Cómo detectarlo: el mensaje de error del chat suele nombrar el proveedor y un código de autenticación. Cómo corregirlo: revisa la credencial del nodo de Chat Model antes de sospechar del resto del workflow — es el primer punto a descartar, no el último.

Ejercicios

Ejercicio 1. Mandaste "¿Quién fue Alan Turing?" a tu agente y la respuesta se ve perfecta, con fechas y datos correctos. Antes de dar el mini-proyecto por terminado, ¿qué paso concreto revisarías, y qué resultado en ese paso te confirmaría que sí hubo un tool call real?

Ver solución

Revisar el arreglo intermediateSteps de esa ejecución (con "Return Intermediate Steps" activado). Te confirma que hubo un tool call real si encuentras al menos una entrada con "tool": "Wikipedia Summary" y un toolInput con el título resuelto (por ejemplo "Alan_Turing"), junto con una observation que contenga el JSON crudo de la API de Wikimedia. Si el arreglo viene vacío, la respuesta —por correcta que suene— salió solo de la memoria del modelo, sin pasar por tu tool.

Por qué funciona: es exactamente el punto de esta lección — una respuesta correcta no es evidencia de que el bucle corrió; intermediateSteps es el único lugar donde esa evidencia queda registrada.

Ejercicio 2. Con el system message del ejemplo trabajado (usa la tool para personas, lugares y conceptos, no para cálculos), mandas: "¿Quién descubrió la penicilina y en qué año?" ¿Esperarías ver una o dos entradas en intermediateSteps? Justifica con lo que aprendiste sobre el bucle en la lección 3.

Ver solución

Lo más probable es una sola entrada: la pregunta pide un dato compuesto (persona y año), pero ambos datos suelen aparecer juntos en el resumen de un solo artículo de Wikipedia (el de Alexander Fleming o el de "Penicillin"), así que una llamada a la tool probablemente basta para que el agente tenga todo lo que necesita y responda. No hay una regla fija de "una pregunta con dos datos, dos tool calls" — como viste en la lección 3, el número de vueltas depende de si la observación de la primera llamada ya deja resuelta la pregunta completa, no de cuántas partes tenga la pregunta en el texto.

Por qué funciona: aplica el mismo criterio del ejemplo del agente de viajes en la lección 3 — el número de vueltas lo decide lo que falta por resolver después de cada observación, no la cantidad de sub-preguntas que el usuario escribió en una sola frase.

Ejercicio 3. Te pasan este fragmento de connections de un workflow que nunca responde en el chat:

"connections": {
  "AI Agent": {
    "main": [[ { "node": "When chat message received", "type": "main", "index": 0 } ]]
  },
  "Anthropic Chat Model": {
    "ai_languageModel": [[ { "node": "AI Agent", "type": "ai_languageModel", "index": 0 } ]]
  }
}

¿Qué está invertido en este fragmento, y por qué eso explica que el chat nunca dispare al agente?

Ver solución

La conexión main está al revés: dice que la salida del AI Agent apunta hacia el Chat Trigger ("node": "When chat message received"), cuando lo que necesita el workflow es lo opuesto — que la salida del Chat Trigger apunte hacia el AI Agent. Con esta dirección invertida, el mensaje que llega al Chat Trigger nunca fluye hacia el Agent por la conexión principal; el Agent nunca recibe el mensaje del usuario como input, así que no hay nada que dispare el bucle razonar-actuar-observar.

Por qué funciona: la conexión main —a diferencia de las conexiones ai_*, que siempre apuntan del sub-nodo hacia el nodo raíz— sigue el sentido normal del flujo de datos en n8n: de quien dispara el evento hacia quien lo procesa. Invertirla no produce un error de sintaxis, pero deja al Agent sin ninguna entrada real.

Resumen y siguiente paso

Ya montaste, probaste y verificaste tu primer agente completo: un Chat Trigger disparando al AI Agent, un modelo de chat decidiendo, una tool real conectada, y —lo que de verdad cierra el mini-proyecto— la confirmación en intermediateSteps de que el ciclo razonar-actuar-observar corrió cuando la pregunta lo necesitaba, y no corrió cuando no hacía falta. Ese es exactamente el bucle que trazaste en la lección 3, corriendo en tu propia instalación self-hosted.

Con esto cierra el Módulo 1: ya distingues agente de chatbot y de IA procedural, entiendes el bucle por dentro, conoces la anatomía del nodo AI Agent y sus cuatro piezas, sabes cuándo un agente vale la pena y cuándo no, decidiste dónde correrlo, y hoy lo probaste funcionando de verdad. El Módulo 2 toma la primera de esas cuatro piezas —el modelo y el prompt— y profundiza en cómo elegir entre proveedores y cómo escribir un system message que de verdad guíe al agente, más allá del ejemplo mínimo que usaste hoy.

Antes de avanzar deberías poder: armar de memoria las tres conexiones obligatorias de un agente (Chat Trigger al Agent por main, Chat Model y al menos una Tool por sus puertos ai_*), diseñar un mensaje de prueba que fuerce un tool call, y explicar por qué una respuesta correcta en el chat no es, por sí sola, prueba de que el bucle agéntico corrió.

Recursos

  • AI Agent node — n8n Docs — referencia oficial del nodo, la misma que citaste en las lecciones 4 y 5, útil aquí para confirmar la opción returnIntermediateSteps.
  • Chat Trigger node — n8n Docs — cómo funciona el panel de Chat, las opciones de acceso (hosted vs. embedded) y qué campo de salida espera del Agent.
  • What agents do — la fuente de la descripción oficial de n8n sobre cómo el agente "corre varias veces" antes de responder, la base del bucle que verificaste hoy.
  • How tools work — catálogo de tools que trae n8n de fábrica, incluida la HTTP Request Tool que usaste en este mini-proyecto.
  • Test and improve AI workflows — n8n Docs — el siguiente nivel después de esta prueba manual: evaluaciones repetibles para workflows con IA.
  • Wikimedia REST API — documentación interactiva oficial de la API pública que consulta la tool Wikipedia Summary, incluido el endpoint /page/summary/{title} usado en el ejemplo.
← Anterior7. Dónde correrás tus agentes: self-hosted Community vs CloudSiguiente →1. Introducción: el cerebro del agente