El redactor técnico y los agentes de IA: lo que aprendí al crear a Artie

La mayoría de los redactores técnicos no creamos agentes de IA. Nos dedicamos a documentarlos. Asistimos a las revisiones de sprint y leemos los registros de decisiones de arquitectura. Después, nos las ingeniamos para explicar un proceso de recuperación de información a alguien que simplemente necesita que su integración funcione para el viernes.

Pero, aun así, yo creé uno.

Se llama Artie, un asistente de documentación basado en IA que desarrollé utilizando Algolia y que está integrado en este sitio web de mi portfolio. El proceso de crearlo me enseñó más sobre la intersección entre la redacción y la inteligencia artificial de lo que jamás podrían haberme enseñado ninguna charla en una conferencia ni ningún informe técnico.

Esto no es un recorrido por el diseño de Artie; para eso está el caso práctico. Se trata de las lecciones más generales sobre:

• Qué son realmente los agentes de IA
• Cómo funciona, en realidad, la generación aumentada por recuperación
• Por qué la ingeniería de prompts se parece más a la redacción técnica de lo que la mayoría de la gente cree
• Y qué significa todo esto para quienes formamos parte de este pequeño mundo nuestro

¿Qué es un agente de IA y qué no lo es?

El término «agente de IA» se utiliza de forma tan imprecisa que merece la pena definirlo. No todas las funciones basadas en IA son agentes. Un corrector ortográfico que utiliza aprendizaje automático no es un agente. Una sugerencia de autocompletado tampoco lo es. Ni siquiera un chatbot que sigue un árbol de decisión rígido es realmente un agente: es un diagrama de flujo con una entrada de texto.

Un agente de IA es un sistema capaz de interpretar un objetivo, razonar sobre cómo alcanzarlo y llevar a cabo acciones dentro de un entorno definido. La distinción clave es la autonomía dentro de unas restricciones. Un agente no se limita a responder a una solicitud; evalúa el contexto, selecciona una estrategia y la ejecuta, a menudo a través de varios pasos.

Entonces, ¿dónde se sitúa Artie en este espectro?

Es un agente especializado. No navega por la web, no ejecuta código ni encadena llamadas a herramientas de varios pasos. Pero sí que interpreta la intención del usuario («¿Se trata de una pregunta técnica o de una consulta sobre el portafolio?»), selecciona una estrategia de respuesta y aplica medidas de seguridad de forma autónoma. Eso es más que un chatbot. Es menos que un agente totalmente autónomo que pudiera, por ejemplo, enviar un informe de error basándose en la pregunta de un usuario.

Esta distinción es importante porque comprender las herramientas y los agentes de IA forma parte, cada vez más, del trabajo de un redactor técnico. Cuando documentas un producto impulsado por IA, necesitas saber en qué punto del espectro se sitúa. A continuación, debes comunicar dicha distinción a los usuarios, que pueden tener diferentes expectativas sobre lo que significa «IA».

Cómo funciona realmente la generación aumentada por recuperación

La generación aumentada por recuperación (RAG) es el patrón arquitectónico que subyace a Artie y a un número cada vez mayor de herramientas de documentación basadas en IA. El concepto aborda una limitación fundamental de los grandes modelos de lenguaje (LLM): se entrenan con un conjunto de datos estático y no contienen información sobre tu contenido específico.

Una interacción estándar con un LLM funciona así: el usuario envía una consulta y el modelo genera una respuesta a partir de sus datos de entrenamiento. Esto funciona bien para conocimientos generales, pero falla ante preguntas específicas de un ámbito concreto. Si le preguntas a un modelo básico sobre la API de tu producto, o bien inventará una respuesta o bien te responderá educadamente que no puede hacerlo.

RAG introduce un paso de recuperación entre la pregunta del usuario y la respuesta del modelo. El proceso es el siguiente:

1. Procesamiento de la consulta. Se recibe la pregunta del usuario y se convierte en un formato adecuado para la búsqueda. Esto se consigue transformando la consulta en una representación vectorial, es decir, una representación numérica del significado semántico de la pregunta.
2. Recuperación. El sistema busca en la base de conocimientos contenido que sea semánticamente similar a la consulta. En este caso, la base de conocimientos es un índice predefinido de su documentación. La búsqueda utiliza la similitud basada en el significado, no la coincidencia de palabras clave, por lo que «¿cómo configuro la autenticación?» y «configurar credenciales de inicio de sesión» coincidirían con la misma página de documentación.
3. Ensamblaje del contexto. Los documentos recuperados (o fragmentos de documentos) se ensamblan en una ventana de contexto junto con la pregunta original del usuario y la indicación del sistema. Este conjunto ensamblado es lo que procesa el modelo.
4. Generación. El modelo genera una respuesta basada en el contexto recuperado, en lugar de en sus datos de entrenamiento generales. Cuando el sistema está bien configurado, el modelo cita sus fuentes y se mantiene dentro de los límites de lo que realmente dicen los documentos recuperados.

Mermaid (image)

Mermaid (code)

flowchart TD
    A["🔍 Pregunta del usuario"] --> B["Procesamiento de consultas"]
    B -->|Incrustación vectorial| C["Recuperación"]
    KB[("📚 Base de conocimiento")] -.-> C
    C -->|Documentos pertinentes| D["Ensamblaje del contexto"]
    D -->|Prompt + contexto| E["Generación"]
    E --> F["📄 Respuesta fundamentada"]

La calidad de un sistema RAG depende totalmente del paso 2. Si la capa de recuperación muestra documentos erróneos o los clasifica mal, da igual lo capaz que sea el modelo. Generará una respuesta plausible y bien estructurada a partir de material de origen erróneo. Por eso la estrategia de indexación, el enfoque de segmentación y la selección del modelo de incrustación son más importantes de lo que la mayoría de la gente cree. El modelo de generación se lleva todo el mérito, pero la capa de recuperación es la que hace el trabajo pesado.

En el caso de Artie, la base de conocimientos es la documentación publicada en este sitio web, indexada y recuperada a través de Algolia. Se trata de una restricción deliberada: Artie no puede responder a preguntas sobre temas que no estén documentados aquí. El estudio de caso explica cómo se aplica esa restricción en la práctica, pero la conclusión arquitectónica es la siguiente: RAG no hace que un modelo sea más inteligente. Hace que un modelo sea más responsable al vincular sus respuestas a una fuente verificable.

La ingeniería de prompts es redacción técnica

Esta fue la principal conclusión de todo el proyecto: redactar un prompt para un sistema es, en esencia, un ejercicio de redacción técnica.

Piensa en lo que conlleva una indicación para el sistema bien elaborada. Hay que definir el público destinatario. Hay que establecer directrices sobre el tono y la voz. Hay que fijar los límites del ámbito de aplicación: lo que el sistema debe y no debe abordar. Hay que anticipar los casos extremos y redactar instrucciones lo suficientemente precisas como para que una máquina las siga sin necesidad de decisiones basadas en el criterio humano. Hay que organizar la información jerárquicamente para que las reglas más importantes tengan prioridad.

Eso no es ingeniería de prompts. Es un análisis del público objetivo, una guía de estilo y una especificación de contenido, todo ello reunido en un único documento.

La transferencia de habilidades es casi uno a uno:

• Análisis de público → Orientación del público. Un redactor técnico identifica al público al que va dirigido y adapta el contenido en consecuencia. Una indicación para el sistema hace lo mismo para una IA. La indicación de Artie se orienta tanto a usuarios técnicos como a reclutadores, exactamente igual que un sitio de documentación bien estructurado se adapta a diferentes perfiles de lectores.
• Guía de estilo → Calibración de perfiles. Todo equipo de documentación cuenta con directrices sobre voz y tono. Una indicación del sistema es una guía de estilo para una IA: sé conciso aquí, sé cordial allí, nunca utilices esta frase, incluye siempre un enlace a la fuente.
• Arquitectura de la información → Jerarquía de instrucciones. Los redactores técnicos saben que el orden y la estructura de la información afectan a la comprensión. Lo mismo ocurre con las indicaciones del sistema: el cumplimiento de las instrucciones por parte del modelo se ve influido por el lugar donde aparecen dichas instrucciones y por cómo están estructuradas.
• Documentación de casos extremos → Diseño de barreras de seguridad. Una buena documentación se anticipa a que el usuario haga algo inesperado y ofrece una orientación clara. Un buen diseño de indicaciones se anticipa a que el usuario intente burlar el sistema y establece límites claros.

No estoy diciendo que todo redactor técnico deba convertirse en ingeniero de indicaciones. Lo que digo es que la disciplina de la ingeniería de indicaciones se nutre en gran medida de las habilidades que los redactores técnicos llevan décadas desarrollando. Si eres capaz de redactar un documento claro, estructurado y adaptado al público, ya estás mejor preparado para este trabajo de lo que podrías pensar.

Las barreras de seguridad son un problema lingüístico

Cuando la gente piensa en la seguridad de la IA, tiende a considerarla un problema de ingeniería: limitación de tasa, autenticación, controles de acceso a los modelos. Todo eso es importante. Pero en el caso de una IA conversacional dirigida al público, una parte significativa de la superficie de seguridad es lingüística.

La inyección de comandos es, en esencia, un intento de utilizar el lenguaje para burlar los controles basados en el lenguaje. Defenderse de ella requiere redactar reglas lo suficientemente inequívocas como para que las entradas maliciosas no puedan engañar al modelo.

información

La inyección de comandos se produce cuando un usuario intenta anular el comando del sistema con instrucciones como «ignora todas las instrucciones anteriores».

El informe Los 10 principales riesgos para las aplicaciones de modelos de lenguaje a gran escala del Open Worldwide Application Security Project (OWASP) identifica la inyección de comandos como el principal riesgo. Pero si lees la lista, te darás cuenta de que muchos de los riesgos son, en el fondo, problemas de lenguaje:

• Gestión insegura de la salida (lo que el modelo genera)
• Adulteración de los datos de entrenamiento (lo que el modelo ha aprendido del texto)
• Agencia excesiva (lo que se le indica al modelo que puede hacer)

Los vectores de ataque son técnicos, pero las defensas suelen estar redactadas en lenguaje natural, integradas en el prompt del sistema.

Esto replantea el debate sobre la seguridad de una forma útil para los redactores técnicos. No se espera de nosotros que diseñemos sistemas de autenticación. Pero estamos en una posición idónea para redactar las reglas en lenguaje natural que rigen el comportamiento de una IA. Para redactarlas con la precisión necesaria para resistir un uso indebido malintencionado.

Hacia dónde se dirige esto

No pretendo predecir el futuro de la IA. Pero sí puedo describir la trayectoria que se vislumbra en este momento y lo que significa para quienes se dedican profesionalmente a la documentación.

Los asistentes de documentación impulsados por IA están pasando de ser una novedad a convertirse en algo esperado. Los usuarios están cada vez más insatisfechos con la búsqueda estática en los sitios web de documentación. Quieren formular una pregunta en lenguaje natural y obtener una respuesta fundamentada y específica, no diez enlaces azules. Los sistemas basados en RAG lo hacen posible ahora, y las herramientas para desarrollarlos son cada vez más accesibles.

consejo

¿Tienes curiosidad por conocer la infraestructura que hay detrás de los sistemas basados en modelos de lenguaje a gran escala (LLM)? La documentación sobre flujos de eventos y canalizaciones de observabilidad de este sitio web explica cómo herramientas como Datadog y Galileo supervisan y evalúan las llamadas a los modelos en producción.

El papel del redactor técnico no se está reduciendo, sino que, por el contrario, se está ampliando. Alguien tiene que gestionar la base de conocimientos de la que estos sistemas extraen información. Alguien tiene que redactar las indicaciones del sistema que rigen su comportamiento. Alguien tiene que definir los límites del ámbito de aplicación, las directrices de tono y los modos de fallo. Alguien tiene que comprobar si las respuestas de la IA se ajustan realmente a la documentación. Todo eso es trabajo de redacción y requiere el criterio que se adquiere tras años de reflexionar sobre cómo las personas consumen la información.

Los redactores técnicos deben aprender los fundamentos del funcionamiento de los modelos de lenguaje grande (LLM) y los sistemas RAG. No debemos convertirnos en ingenieros de aprendizaje automático, pero sí debemos contribuir de forma eficaz en los debates sobre productos impulsados por IA. Tenemos que comprender el proceso lo suficientemente bien como para saber dónde se aplica nuestra experiencia —y dónde no—.

Los redactores técnicos ya saben cómo escribir para múltiples públicos, estructurar la información para que resulte clara, definir el ámbito de aplicación y anticipar los usos indebidos. Estas no son habilidades secundarias en la era de la IA. Son fundamentales.

Los redactores técnicos no deberían ser sustituidos por la IA. Los modelos están mejorando en la generación de texto, pero siguen necesitando a alguien que decida qué decir, a quién y bajo qué restricciones. Necesitan editores. Nosotros somos los editores. El trabajo no está cambiando realmente. Las herramientas sí están cambiando. El trabajo no va a desaparecer. Con el tiempo, los temerarios se darán cuenta de su imprudencia y recordarán el valor de un buen redactor técnico.

Lee el caso práctico

Si esta entrada te ha explicado «por qué es importante» y «cómo funciona», lee el caso práctico. En él se describen las decisiones de diseño específicas que hay detrás de Artie:

• Enrutamiento del público
• Fundamentación del conocimiento
• Calibración de perfiles
• Medidas de seguridad
• Compensaciones que reconsideraría para una implementación en producción

Ambos artículos están pensados para complementarse. Empieza por el que más te interese.