🧰 Cómo usar este módulo
Es una compilación real. Cada bloque de código de abajo es un prompt para copiar y ejecutar en tu asistente (con n8n conectado vía MCP), siempre con 🎯 objetivo, el bloque para copiar y ✅ cómo verificar. Las partes entre <chaves> los reemplazas por tus valores. Requisitos previos: un asistente de código con el MCP de n8n conectado, una cuenta de correo electrónico y una clave de IA con embeddings (p. ej., OpenAI). Avanza por etapas: ejecuta un prompt, verifícalo y solo entonces continúa.
El plano del proyecto tiene dos máquinas que dividen el trabajo: una aprende las políticas una sola vez (el indexador), la otra responde cada vez que llega un correo electrónico (el agente). Se comunican a través de un lugar común: el vector store, donde el conocimiento se puede buscar.
Diagrama ilustrativo — el indexador alimenta el vector store; el agente lo consulta en cada ejecución. Separar «aprender» de «responder» mantiene cada parte fácil de probar.
🎯 El alcance del proyecto
Qué es
El proyecto es un agente de soporte por correo electrónico. Parte de dos documentos: uno de políticas (envíos, devoluciones, garantía, facturación, precios, promociones, privacidad, tarjetas de regalo) y uno de FAQ. A partir de ellos, por cada correo que llega, decide si es una consulta de soporte, busca la respuesta en los documentos y redacta una réplica — que una persona aún aprueba antes de enviar.
¿Qué es?RAG (Retrieval-Augmented Generation) — en lugar de que la IA "adivine" de memoria, primero búsqueda (recuperación) el fragmento correcto en tus documentos y solo entonces genera la respuesta basada en él. Borrador (draft) — la respuesta queda guardada como borrador en la bandeja de salida del correo; no se envía sola.
El alcance es deliberadamente limitado y seguro: el agente redacta, no envía (humano en el circuito), y la regla de oro es no inventar — si el tema no está en las políticas, no improvisa una respuesta. Ese límite es lo que hace que el proyecto sea lo bastante confiable para un entorno empresarial real.
Por qué aprender
Este es el «hola mundo» de los agentes que generan ingresos: reúne tres habilidades en un único caso útil — RAG (basarse en documentos), clasificación (filtrar lo que es soporte) y generación de texto (redactar la respuesta con el tono adecuado).
- •Anclado: las respuestas provienen de las políticas, no de la imaginación de la IA.
- •Seguro: borrador + una persona lo aprueba; fuera del alcance = no responde.
- •Reutilizable: cambia los PDFs y el mismo agente sirve a otra empresa.
Conceptos clave
Buscar antes de generar.
¿Es compatible o no?
Una persona aprueba el envío.
Fuera de alcance = no responde.
🏗️ La arquitectura: indexador + agente
Qué es
Son dos workflows separados. El indexador se ejecuta con un disparador manual: lee los documentos, divide el texto en fragmentos (text splitter), genera embeddings y registra en el vector store. O agente se ejecuta con un disparador de correo electrónico: cada 15 minutos lee los mensajes sin leer, los clasifica, consulta el vector store como herramienta y crea el borrador.
¿Qué es?Embeddings — una forma de convertir texto en números que capturan su significado, para que la búsqueda encuentre fragmentos por sentido, no solo por coincidencia exacta de palabras. Vector store — la base de datos que guarda esos números y devuelve los fragmentos más parecidos a la pregunta. Text splitter — divide el documento en fragmentos (chunks) del tamaño adecuado para la búsqueda.
Por qué aprender
Separar quién aprende de quién responde es una decisión de ingeniería: indexas solo cuando cambian las políticas (pocas veces), pero el agente se ejecuta todo el tiempo (a bajo costo, porque solo consulta). Mezclar ambas cosas encarecería cada correo electrónico y dificultaría las pruebas.
✓ Indexador (aprende)
- ✓Disparador manual — lo ejecutas cuando cambian los PDF.
- ✓Documento → splitter → embeddings → vector store.
- ✓Se ejecuta una vez y el conocimiento queda guardado.
✓ Agente (responde)
- ✓Disparador de Gmail — cada 15 min, correos no leídos.
- ✓Classifier → agente con la herramienta de vector store.
- ✓Genera el borrador; la rama "no relevante" termina.
🎯 Decisión de arquitectura: system prompt vs vector store
Para pocos documentos pequeños, puedes pegar todo el texto en el system prompt (más simple y barato). Pero elegimos vector store porque escala: busca solo la sección relevante, en vez de enviar el documento completo con cada correo electrónico; es mejor cuando la base crece. Deja que la IA lo proponga y confirma la elección.
Conceptos clave
Aprender vs. responder.
Puente entre los dos.
Encuentra solo lo relevante.
Indexa poco, consulta siempre.
📝 El prompt de apertura integral
Qué es
É una sola solicitud, en Plan Mode, que describe el resultado completo: los documentos de origen, la lógica del flujo y el comportamiento esperado, dejando que la IA elija cómo almacenar y buscar. Coloca los PDF en la carpeta del proyecto y haz referencia a ellos mediante una etiqueta. En lugar de pedir un vector store de entrada, describe el resultado y deja que la IA proponga la arquitectura.
¿Qué es?Plan Mode — un modo en el que la IA investiga, hace preguntas y propone un plan antes de construir, sin cambiar nada. Revisas y apruebas; solo entonces se ejecuta.
🎯 Objetivo: describir todo el agente en un solo prompt y dejar que la IA proponga el plan (en Plan Mode).
Entre em plan mode. Quero um agente de suporte por e-mail no n8n. Anexei dois documentos na pasta do projeto: - @(envio, devoluções, garantia, cobrança, preços, promoções, privacidade) - @ Resultado desejado: 1. Use esses documentos como base de conhecimento da empresa. 2. A cada e-mail novo, classifique se é uma dúvida de suporte técnico. 3. Se for, rascunhe uma resposta APOIADA nos documentos (não invente nada). 4. Se NÃO for suporte, ignore (não responda). 5. A resposta deve ficar como RASCUNHO no Gmail, nunca enviada automaticamente. Você decide como armazenar e buscar os documentos. Antes de construir, me faça as perguntas que precisar e me mostre o plano dos workflows.
✅ Cómo verificar: la IA debe hacer preguntas (proveedor de IA, cómo almacenarlo, qué cuenta como soporte, tono) y devolver un plan con dos workflows antes de crear cualquier nodo. Si ya empieza a construir, pídele "quédate en plan mode y muéstrame el plan primero".
Por qué aprender
Un buen prompt inicial ahorra horas: la IA anticipa las decisiones (proveedor, almacenamiento, tono, qué está «fuera de alcance») y pregunta qué falta, en vez de adivinar y construir algo incorrecto. Tú respondes, apruebas el plan y solo entonces dejas que construya: el ciclo Plan → Build en acción.
✓ En el prompt, incluye
- ✓Los documentos de origen (por etiqueta/adjunto).
- ✓El resultado completo (clasificar, fundamentar, redactar).
- ✓Las reglas de seguridad (no inventar, no enviar).
✗ Evita
- ✗Indicar «usa un nodo de vector store en memoria con…».
- ✗Dejar que la IA construya sin mostrar el plan antes.
- ✗Omitir sus preguntas de aclaración.
Conceptos clave
Planificar antes de construir.
El «qué», no el «cómo».
PDFs en la carpeta + etiqueta.
Responde las preguntas.
🔧 Construcción de los dos workflows
Qué es
Con el plan aprobado, la IA construye los nodos. El Workflow 1 (indexador) queda así: activador manual → nodo de código con el texto de los documentos → inserción en el vector store (con data loader y text splitter por carácter). El Workflow 2 (agente) queda así: activador de Gmail (cada 15 min, solo los no leídos) → classifier (soporte vs. no relevante) → agente de IA con la herramienta de vector store → nodo de borrador en Gmail; la rama «no relevante» termina sin responder.
🎯 Objetivo: cargar la base y activar el agente en el orden correcto.
1. Construa os dois workflows conforme o plano. 2. Rode o Workflow 1 (indexador) manualmente UMA vez, para popular o vector store com as políticas. 3. Só depois, ATIVE o Workflow 2 (agente do e-mail). 4. Se algum nó der erro, me copie a mensagem e diga em qual nó — eu te devolvo a correção.
✅ Cómo verificar: el indexador debe finalizar sin errores y el vector store debe quedar poblado. Activa el agente solo después — de lo contrario, consulta una base vacía.
🐛 Debug en capas (errores reales que aparecen)
En el build, dos errores típicos del classifier: (1) la propiedad del modelo necesitaba el formato estructurado {mode, id/value} en lugar de texto sin formato; (2) un error de parsing desaparece al desactivar la opción de respuesta-JSON predeterminada del nodo del modelo del classifier. La corrección siempre es la misma receta: copia el mensaje del nodo y devuélveselo a la IA con la ubicación.
Para leer un nodo: a la izquierda quedan las entradas (nodos anteriores), en el medio el nodo, a la derecha el resultado en JSON.
Por qué aprender
Observar el build y devolver errores es el ciclo central del vibe coding: no corriges los nodos a mano, describes el síntoma. Ver la entrada y salida de cada nodo también te enseña la anatomía de un pipeline RAG y a confirmar que el borrador coincide con la fuente (p. ej., que los términos de garantía del borrador coincidan con el PDF de políticas).
Conceptos clave
Indexa antes de activar.
Mensaje + nodo.
Entra por la izquierda, sale por la derecha.
El borrador coincide con el PDF.
🔑 Credenciales (lo que la IA NO hace)
Qué es
Hay un límite claro: la IA construye los flujos, pero tú conecta las credenciales manualmente. Son dos: la cuenta de correo electrónico mediante Gmail OAuth (autoriza a n8n a leer y redactar borradores) y la clave de API de IA (OpenAI, utilizada tanto por los modelos de chat como por los embeddings). Nunca pongas secretos en el chat.
¿Qué es?OAuth — una forma de autorizar a una app para que actúe en tu nombre sin entregar tu contraseña; haces clic en "permitir" y la app obtiene un acceso revocable. Clave de API — una contraseña de máquina que identifica y cobra el uso de la IA; se guarda en las credenciales de la herramienta, no en el código ni en el chat.
Diagrama ilustrativo — la IA no tiene (ni debe tener) tus credenciales. Conectar OAuth y pegar la clave es tarea tuya, en la herramienta.
Por qué aprender
Saber qué no delegar es la mitad de la disciplina de seguridad. El mapeo de credenciales y la autorización quedan a tu cargo; eso protege tus datos y mantiene el secreto fuera del contexto de la IA, una regla de oro que vuelve a aparecer en toda la ruta de producción.
Conceptos clave
Autoriza sin contraseña.
Chat + embeddings.
La IA no tiene el secreto.
El secreto permanece en la herramienta.
🧪 Pruebas: devolución, garantía, fuera del alcance
Qué es
Prueba con casos reales que cubran los tres comportamientos: un correo electrónico de devolución (debe responder con la política correcta), uno de garantía (la respuesta debe coincidir término por término con el PDF) y un fuera de alcance — un «¿cenamos mañana?» — que debe clasificarse como no relevante e no recibir respuesta. Verde ≠ correcto: solo estas pruebas revelan si el RAG realmente está anclado.
🎯 Objetivo: activar los tres escenarios y comprobar el comportamiento.
Envie 3 e-mails de teste para a caixa conectada: A) "Qual é o prazo para devolver um produto?" → deve rascunhar a política de devolução B) "Meu aparelho parou; ainda está na garantia?" → resposta deve bater com o PDF de garantia C) "Bora jantar amanhã às 20h?" → classificar como "não relevante", NÃO responder Rode o agente e me diga: ele ancorou nas políticas? Algum número (ex.: "30 dias") confere com o documento? Ele recusou o caso C sem inventar?
✅ Cómo verificar: A y B generan un borrador fiel al PDF (revisa los números — "30 días" ≠ "un año"); C no genera una respuesta. Si se respondió C, ajusta el classifier.
✓ Señales de que está bien
- ✓Los términos de garantía coinciden con el PDF, palabra por palabra.
- ✓El correo social se marca como «no relevante» y termina.
- ✓Los números (plazos, valores) coinciden con la fuente.
✗ Señales de alerta
- ✗Respuesta «bonita» pero con un plazo inventado.
- ✗El agente responde a la invitación a cenar.
- ✗Confiar en el "verde" sin leer el contenido del borrador.
Por qué aprender
El caso fuera de alcance es el más importante: demuestra que el agente se niega a inventar. Un agente que responde todo es peligroso; uno que sabe decir "eso no está en mi base" es confiable. Los casos límite lo revelan mejor que cualquier ejecución "en verde".
Conceptos clave
Devolución, garantía, social.
Números vs PDF.
Fuera de alcance = silencio.
Lee el contenido.
✨ Los 6 enhancements aplicados
Qué es
Seis mejoras incrementales, solicitadas en lenguaje natural y probadas una a la vez — iterar en capas en la práctica. Las tres primeras se ocupan de la lógica y los errores (fallback, filtro de tiempo, ignorar automáticos); las tres últimas, de la calidad de la salida (tono, nombre del cliente, indicador de confianza).
Diagrama ilustrativo — una capa a la vez, probando cada una. Si se rompe, sabes exactamente qué cambio fue el culpable.
🎯 Enhancement 1 — Fallback cuando no se encuentra: si la base no tiene la respuesta, no inventes.
Quando a base de conhecimento NÃO tiver a resposta, o agente não deve inventar.
Faça o agente emitir um marcador ("política encontrada" / "política não encontrada");
um nó de código lê esse marcador, um nó IF ramifica, e no caso "não encontrada"
crie um rascunho educado de "vamos pesquisar e retornamos em breve".
Antes de mudar, me pergunte o limiar de match e o texto do fallback.
✅ Cómo verificar: envía una pregunta fuera de la base (p. ej.: «¿Hacen envíos al exterior?»). Debe pasar al borrador de investigación, no a una respuesta inventada.
🎯 Enhancements 2 y 3 — Filtros: solo correos recientes; ignora los automáticos.
[2] Processe apenas e-mails recebidos há menos de <10> minutos.
(a IA descobre a sintaxe de busca do Gmail e adiciona um filtro
"newer than" no próprio gatilho, sem nó extra.)
[3] Ignore e-mails automáticos: fora-do-escritório, notificações de entrega,
newsletters e remetentes no-reply / postmaster / bounce / marketing.
Adicione um nó de código que marque isAutomated + motivo e ramifique
para PULAR esses casos.
✅ Cómo verificar: quedan tres puertas en secuencia: ¿automático? → ¿es soporte? → ¿tiene política? Atención a un error clásico: el filtro puede dejar pasar un no-reply@ si el código lee el campo equivocado del remitente.
🎯 Enhancements 4, 5 y 6 — Calidad: tono, nombre y confianza.
[4] Ajuste o tom para <amigável, prestativo, descontraído> — "experto, mas
nunca condescendente". Atualize TANTO o system prompt do agente QUANTO o
rascunho de "vamos pesquisar". Varie as despedidas.
[5] Personalize com o nome do cliente: um nó de código extrai o nome da
assinatura ("Abraço, João" / "Obrigada, Sara") e usa na saudação,
com fallback "Olá" quando não houver assinatura.
[6] Adicione um indicador de confiança (uso interno): o agente marca
alto/médio/baixo conforme o match (alto > 0.8, médio 0.6–0.8, baixo < 0.6);
um nó de código monta um selo HTML (verde/amarelo/vermelho) anexado ao
rascunho, só para revisão interna.
✅ Cómo verificar: el tono cambia en los dos borradores (respuesta y fallback); se responde a un correo firmado «Un abrazo, João» con «Hola, João»; el borrador muestra el sello de confianza. Prueba cada uno antes de pedir el siguiente.
Por qué aprender
Los enhancements muestran el stair-step real: cada mejora es una solicitud en portugués, probada de forma aislada. Observa cómo a veces la IA hace más de lo que pediste (reorganiza nodos, reescribe la rama falsa); por eso revisas cada paso. Ancla cada solicitud en el comportamiento deseado, no en la implementación.
Conceptos clave
Una mejora a la vez.
¿Automático? ¿soporte? ¿política?
Indicador alto/medio/bajo.
La IA hace algo extra; revísalo.
✅ Verificación final y checklist
Qué es
Antes de declarar "listo", sigue la checklist objetiva. Definir qué es "listo" evita el bucle infinito de "solo una mejora más" y te da un criterio claro para cerrar el proyecto con seguridad.
🎯 Objetivo: confirmar que el proyecto está listo y guardar una copia de seguridad.
[ ] O indexador popula o vector store sem erro. [ ] E-mails de suporte são classificados como suporte. [ ] As respostas ancoram nas políticas (números conferem com o PDF). [ ] Fora de escopo NÃO é respondido (recusa inventar). [ ] Automáticos e antigos são ignorados (3 portões funcionando). [ ] Tom, nome e selo de confiança aparecem no rascunho. [ ] Tudo fica como RASCUNHO; humano aprova o envio. Backup: "Exporte os dois workflows como JSON para eu guardar."
✅ Cómo verificar: todos los elementos marcados y el JSON exportado guardado. Si falla algún elemento, vuelve al tema correspondiente e itera solo esa capa.
Por qué aprender
"Listo" es una decisión, no un sentimiento. La lista de verificación convierte la comprobación en algo repetible, y el export JSON es tu copia de seguridad: si un cambio futuro rompe algo, restauras la versión que funcionaba. Es el mismo hábito de «hacer una copia de seguridad antes de cambiar» que sirve para todos los proyectos de esta ruta.
Un cliente pregunta algo que no está en las políticas. ¿Cuál es el comportamiento correcto del agente?
📌 Resumen del módulo
Siguiente módulo:
5.2 — Agentes alojados (programado + webhook): saca al agente de tu máquina y llévalo a la nube.