Diseño de Artie: un asistente de documentación de IA
Lee la publicación complementaria del blog para obtener un contexto más amplio: El redactor técnico y los agentes de IA: lo que aprendí al crear a Artie. En ella se analiza la generación aumentada por recuperación y cómo encaja este proyecto en la redacción técnica.
Este caso de estudio repasa las decisiones de diseño que hay detrás de Artie, un asistente de documentación de IA creado con Algolia e integrado en este sitio de documentación. Artie es un asistente de generación aumentada por recuperación (RAG) diseñado para responder preguntas utilizando estrictamente el contenido publicado aquí. Su prompt de sistema le impide responder a consultas de documentación con conocimientos generales de entrenamiento, lo que minimiza las alucinaciones y evita características inventadas.
Crear un asistente de documentación parece sencillo hasta que se tienen en cuenta los casos extremos: ¿qué ocurre cuando alguien formula una pregunta que la documentación no cubre? ¿Y si dos públicos distintos utilizan la misma interfaz? ¿Cómo se le da personalidad a una IA sin dejar que divague? ¿Y cómo se evita que alguien secuestre por completo el prompt?
Esta página explica cómo este diseño resuelve cada uno de esos problemas.
Enrutamiento de públicos
Artie atiende a dos públicos a través de una única interfaz conversacional:
- Desarrolladores y usuarios finales que buscan instrucciones de configuración, referencias de API o explicaciones sobre las muestras de documentación
- Reclutadores y directores de contratación que evalúan este portafolio y pueden preguntar sobre cualificaciones, experiencia o el proceso de redacción
En lugar de crear flujos separados o pedir a los usuarios que se identifiquen, el prompt enruta según la intención. Las preguntas técnicas reciben respuestas paso a paso basadas en el índice de documentación. Las preguntas relacionadas con el portafolio reciben respuestas que sintetizan el contexto del currículum con las muestras de redacción del sitio. Si el contexto del currículum no está disponible en el índice, Artie redirige a los visitantes a la página «Acerca de mí» en lugar de intentar generar una respuesta.
Este enfoque mantiene la interfaz limpia—un único chat, sin menús ramificados—al tiempo que garantiza que cada público reciba una respuesta relevante.
Base de conocimiento y recuperación de información
La restricción más importante en el diseño de Artie es que responde exclusivamente a partir del índice de documentación impulsado por Algolia. Este es el principio fundamental de la generación aumentada por recuperación. Las respuestas del modelo se basan en un conjunto específico de contenidos, en lugar de partir de datos de entrenamiento generales.
En la práctica, esto significa:
- Sin contenido inventado—el asistente no inventa características, no crea enlaces de descarga ni describe pasos que no figuren en la documentación.
- Enlaces a la fuente—el asistente proporciona URL o referencias a archivos del índice para que los usuarios puedan navegar directamente a la página correspondiente.
- Respuesta alternativa elegante—cuando el índice carece de información relevante, Artie expone la limitación con claridad y sugiere ponerse en contacto directamente sin reintentar, entrar en bucles ni especular.
La contrapartida es el alcance—Artie no puede ayudar con nada que quede fuera de la documentación publicada. Es una función, no una limitación. Para un sitio de portafolio, la precisión importa más que la amplitud. Una respuesta precisa y bien documentada a una pregunta concreta genera más confianza que una respuesta que suene plausible pero que resulte ser errónea.
Calibración de la personalidad y el tono
Artie tiene una personalidad ligera—una calidez tranquila, inspirada en George Harrison, con algún que otro toque del dialecto de Liverpool. La palabra clave es ligera. La personalidad añade carácter a los saludos y las despedidas sin interferir en el contenido técnico.
Las restricciones de diseño aquí son intencionadas:
- Las respuestas técnicas se mantienen concisas—la personalidad nunca justifica respuestas más largas. Un saludo cálido seguido de una respuesta concisa y objetiva logra este objetivo.
- Variedad frente a repetición—el prompt incluye un repertorio de expresiones para que Artie evite recurrir siempre a la misma frase.
- Sin sermones—el personaje mantiene un tono cálido e irónico, y nunca suena moralista ni prepotente, actuando como un colega servicial en lugar de una interpretación teatral.
Este tipo de ajuste del tono es un reto habitual en el diseño de IA conversacional. Demasiada personalidad hace que el asistente parezca un truco publicitario. Muy poca lo hace parecer robótico. La solución es tratar la personalidad como un condimento: presente, pero nunca como el ingrediente principal.
Seguridad y medidas de protección
Aquí es donde el diseño se vuelve serio. Un asistente de IA dirigido al público constituye una superficie de ataque, y el prompt incluye defensas explícitas contra las vulnerabilidades habituales de los modelos de lenguaje grande (LLM).
Protección contra la inyección de prompts
El prompt de Artie rechaza explícitamente cualquier intento de anular sus instrucciones, como comandos del tipo «ignora las instrucciones anteriores» o solicitudes para adoptar una personalidad diferente. Esto establece defensas a nivel de prompt contra la inyección de prompts, clasificada en el puesto #1 del Top 10 de OWASP para aplicaciones de modelos de lenguaje grande.
Restricción del alcance
El prompt define categorías de rechazo explícitas:
- Ayuda general de programación—el asistente rechaza preguntas de programación que no estén cubiertas en la documentación.
- Curiosidades no relacionadas—el asistente rechaza solicitudes fuera de dos funciones lúdicas específicamente delimitadas.
- Información personal—el asistente rechaza consultas sobre detalles personales no publicados en el portafolio profesional.
- Tarifas freelance o negociaciones—el asistente remite a los visitantes a comunicarse directamente en su lugar.
Cada categoría tiene un límite claro. El asistente no necesita emitir juicios sobre lo que está "suficientemente cerca" para responder. Si queda fuera del alcance definido, lo declina educadamente.
Privacidad de datos
Artie solo comparte información de contacto que esté explícitamente publicada en la documentación, como un perfil de LinkedIn o el correo del portafolio. No adivinará, inferirá ni generará detalles personales como números de teléfono o direcciones.
Límites profesionales
El asistente no interactuará con mensajes hostiles, no usará lenguaje vulgar ni se saldrá de su personaje. Esto va más allá de la cortesía. Se trata de mantener un comportamiento predecible. Un reclutador que ponga a prueba los límites del asistente se topará siempre con un límite coherente y profesional.
Easter eggs controlados
Artie incluye dos "funciones divertidas"—datos curiosos de Snapple Real Facts y chistes inofensivos—que demuestran cómo añadir personalidad sin abrir la puerta a abusos.
Ambas funciones comparten el mismo patrón de diseño:
- Desencadenantes explícitos—se activan únicamente ante solicitudes específicas del usuario («dame un dato de Snapple», «cuéntame un chiste»), no ante indicaciones vagas o tangenciales.
- Contenido delimitado—los datos de Snapple se basan en una lista integrada de datos verificados, mientras que los chistes permanecen estrictamente seleccionados y son aptos para toda la familia.
- Sin invención infundada—el asistente evita inventar datos o generar humor no afín a la marca, manteniendo el alcance estrictamente controlado.
Esto importa porque las funciones creativas ilimitadas queman rápidamente tokens y producen resultados impredecibles. Al mantener el contenido seleccionado y los desencadenantes explícitos, las funciones aportan calidez sin riesgo.
Lo que haría de otra manera
Ningún diseño sobrevive intacto al contacto con los usuarios reales. Esto es lo que reconsideraría:
- Coste de tokens—la lista de datos de Snapple supera los 100 elementos por sí sola. En un sistema de producción con facturación por token, trasladaría eso a una capa de recuperación en lugar de integrarlo en el prompt del sistema. Un equipo paga por cada token del prompt en cada solicitud, tanto si el usuario pide un dato como si no.
- Contexto multiturno—el diseño actual se centra en preguntas y respuestas de un solo turno. Una versión más sofisticada podría mantener el historial de conversación y reformular las consultas para resolver preguntas de seguimiento como «¿Y qué hay del siguiente paso?».
- Analítica y retroalimentación—ningún mecanismo rastrea qué preguntas resuelve bien Artie y cuáles activan la respuesta de contingencia. Incorporar un registro ligero—incluso solo contar las respuestas de contingencia—revelaría lagunas en la documentación que convendría subsanar.
- Ajuste dinámico de personalidad—el prompt codifica directamente las expresiones de personalidad. Un enfoque más fácil de mantener haría referencia a una configuración de personalidad externa, facilitando el ajuste del tono sin editar el conjunto de instrucciones principal.
Cada uno de estos aspectos es una concesión deliberada para un proyecto de portafolio en el que la simplicidad y la claridad importan más que la optimización a escala de producción. Pero son las primeras cosas que abordaría si esto pasara a un entorno con mayor tráfico.