Caso 01
Un agente de documentación, elegido midiendo tres arquitecturas
Quería un agente que respondiera a partir de nuestros manuales técnicos versionados y citara siempre la fuente. Hice construir y evaluar tres arquitecturas, y elegí con datos, no con opiniones.
- 4,46 → 4,85
- puntaje del juez LLM (1–5), v1 RAG frente a v2 de contexto completo, en 26 preguntas de referencia
- 12/17 → 15/17
- preguntas con respuesta fundamentada, v1 frente a v2
- 97 %
- Recall@10 de v3 en 34 preguntas parafraseadas en español e inglés
Mis decisiones 04
- Elegir la arquitectura con una evaluación medida: 26 preguntas de referencia en cuatro categorías, calificadas por un juez LLM.
- Diseñar v3 bajo la restricción real de no tener base de datos vectorial.
- Descartar Pandoc para convertir de Word a Markdown, porque el contenido no sale del equipo.
- Usar un flujo fijo en lugar de un agente con herramientas, porque el nodo de agente no permitía obligarlo a usar su herramienta.
Ejecución asistida 03
- Claude Code construyó las tres versiones y sus flujos de n8n bajo mis reglas.
- Claude Code escribió el convertidor de Word a Markdown solo con la librería estándar de Python, y sus pruebas: 29/29 unitarias y 9/9 de simulación de flujo.
- Claude Code corrió la evaluación y calculó las métricas de recuperación.
Contexto
Respondo por la documentación técnica de una línea de productos de prevención de fraude en ciberseguridad empresarial. Los manuales son largos, cambian con cada versión y existen en español y en inglés. Quería un agente que respondiera preguntas sobre ellos y mostrara siempre de dónde sale la respuesta.
Qué decidí
Decidí no escoger la arquitectura por preferencia. Cada una se construiría y se mediría con las mismas preguntas antes de elegir.
El conjunto de referencia tenía 26 preguntas en cuatro categorías: con respuesta, sin respuesta en la documentación, sobre otro producto y sobre otra versión. Tres de las cuatro categorías prueban si el agente sabe abstenerse. Responder con seguridad algo que el manual no cubre es la falla más peligrosa.
Para la tercera versión acepté una restricción real: no había base de datos vectorial disponible. También descarté Pandoc para la conversión de documentos. Nuestra política de privacidad no lo permite, y la regla es simple: el contenido no sale del equipo.
Cómo funciona
Tres arquitecturas, construidas en secuencia:
- v1, RAG. Un índice vectorial (Pinecone) y un modelo Claude vía Bedrock, orquestados en n8n.
- v2, contexto completo. Todos los manuales de una versión entran al contexto del modelo.
- v3, sin base vectorial. Un índice BM25 propio y luego tres llamadas al modelo: planear, seleccionar secciones y responder. Las respuestas llevan citas
[n]verificadas, y los subagentes se comunican con contratos al estilo A2A. El corpus es un producto, 14 versiones, 194 manuales y 16 notas de versión, en español e inglés.
La evaluación de v1 frente a v2:
| Métrica | v1 RAG | v2 contexto completo |
|---|---|---|
| Puntaje del juez (1–5) | 4,46 | 4,85 |
| Respuestas fundamentadas (de 17 con respuesta) | 12 | 15 |
| Fallas reales de fundamentación | 2 | 0 |
| Preguntas trampa bien manejadas | 9/9 | 9/9 |
| Latencia p50 | 10,7 s | 13,8 s |
v2 fue más precisa y más lenta. Ese balance llegó a quien decidía en un resumen de una página.
Qué produjo
v3 alcanzó un Recall@5 de 91 %, un Recall@10 de 97 % y un MRR de 0,79, en 34 preguntas parafraseadas en los dos idiomas. Las dos cifras de recall superaron sus metas.
El proceso de conversión pasó 194 manuales de Word a Markdown con una retención mínima de texto de 99,4 %, encabezados idénticos y cero alertas. Además encontró diferencias de estructura entre los originales en español y en inglés, y corrigió los nombres de documento en los 194 manuales.
Lo que aún no prueba
Es una prueba de concepto. En v3 hay un subagente validado en n8n (7/7, cerca de 1 s); el orquestador está listo para importar, pero no desplegado. Nadie usa todavía el agente en el trabajo diario, así que no tengo datos de preguntas por día, satisfacción ni proporción de respuestas con una cita válida.
Qué haría después
Agregar un subagente de fundamentación y un canal de retroalimentación. Después, poner el agente frente a usuarios reales y medir preguntas por día, satisfacción y proporción de respuestas con una cita válida.