22 de agosto de 2026
Por qué Barkan lee la pantalla y no la documentación
La documentación describe el producto en general. El DOM lo describe para este usuario, ahora mismo. Un vistazo por dentro a cómo Barkan convierte una página en vivo en algo sobre lo que un modelo puede actuar.
Cuando empezamos a construir Barkan, la arquitectura obvia era la que todos los demás ya habían lanzado: convertir la documentación del producto en embeddings, recuperar los fragmentos relevantes para cada pregunta y dejar que un modelo redactara la respuesta. Fue lo primero que construimos. Funcionaba lo bastante bien como para hacer demos y lo bastante mal como para no poder lanzarlo, y el fallo era siempre el mismo: la respuesta era correcta sobre el producto e incorrecta sobre el usuario. Este artículo trata de la decisión que vino después, basar cada respuesta en la interfaz renderizada en vivo, y de lo que eso exige en la práctica.
El fallo que cambió la arquitectura
La pregunta que tumbó la versión entrenada con documentación era de lo más corriente. Un tester preguntó «¿cómo añado una segunda licencia?» y recibió una respuesta limpia, de seis pasos, copiada tal cual del centro de ayuda. El paso cuatro decía que hiciera clic en Añadir miembro. En la pantalla del tester, ese botón aparecía en gris, con un tooltip que explicaba que el plan Launch se limita a una licencia.
La respuesta no era una alucinación. Era cierta en general, e inútil en particular. El modelo no tenía ni idea de que el botón estaba desactivado, porque nada en la documentación podía decirle cómo era la pantalla de esta cuenta en ese momento.
Esa es la limitación de fondo de cualquier asistente cuyo conocimiento sale de textos sobre el producto: conoce el producto tal como se diseñó, no tal como se le muestra a este usuario. Y la distancia entre ambos es justo donde los usuarios se atascan.
Si una respuesta depende de algo que el usuario puede ver, el modelo también tiene que poder verlo. La documentación puede explicar el porqué; solo la interfaz en vivo puede decir dónde.
Qué significa «leer la pantalla»
No significa hacer capturas de pantalla, ni volcar el HTML en el prompt. Las dos cosas son tentadoras y las dos fallan: las capturas pierden la estructura que el modelo necesita para actuar, y el HTML en bruto de una app moderna son cientos de kilobytes de ruido del framework con la señal útil enterrada dentro.
En su lugar, cuando un usuario pregunta algo, el widget captura una instantánea enriquecida del documento renderizado y la envía a la API junto con la pregunta. A grandes rasgos, contiene:
Capa · Qué contiene · Por qué importa
Elementos interactivos · Botones, enlaces y campos, con una referencia estable y una etiqueta accesible · Para que el modelo pueda señalar un control concreto y actuar sobre él
Relaciones · Qué etiqueta corresponde a qué campo y qué botón a qué formulario · Convierte «el campo del correo» en un elemento concreto
Datos de la interfaz · Estados desactivados, pestañas seleccionadas, insignias, contadores, errores de validación · La información de «en gris en el plan Launch» que la documentación nunca tuvo
Bloques de contenido · Títulos y texto visibles, sin duplicados y recortados · Contexto suficiente para entender la página, no la página entera
Resúmenes de formularios · Qué está rellenado, qué está vacío y qué no es válido · Permite al modelo retomar un flujo de trabajo a medias
Superficies activas y estado del scroll · Modales abiertos, paneles laterales, la zona visible actual · Distingue «no está en pantalla» de «no existe»
Metadatos de la página · Ruta, título, atributos data permitidos · Orientación barata y fiable
Todo está pensado para ser pequeño, estable y honesto. Pequeño, para que quepa en el presupuesto de contexto y quede margen para pensar. Estable, para que el mismo elemento reciba la misma referencia de un turno a otro, que es lo que hace posible señalar y encadenar acciones de varios pasos. Honesto, para que el modelo nunca vea un control que el usuario no ve.
Tres problemas de ingeniería que esto crea
Basarse en el DOM resuelve el problema de la respuesta «incorrecta sobre el usuario» y crea de inmediato otros tres. Merecen la pena, pero son reales.
1. La interfaz se mueve
Un índice de documentación cambia cuando alguien edita un documento. El DOM cambia cuando pasa cualquier cosa: se abre un desplegable, aparece un aviso emergente, termina de cargar una lista. Una instantánea tomada un segundo antes de tiempo describe una página que ya no existe.
Lo resolvemos de dos maneras. La instantánea se captura cuando la página se ha asentado: esperamos a que la actividad de red en curso y la maquetación se calmen, con un límite para que una página muy movida no bloquee la respuesta eternamente. Y en el modo Do, cada acción va seguida de una recaptura silenciosa antes de decidir el siguiente paso, de modo que el modelo siempre actúa sobre la página tal como es, no tal como era.
2. Referencias estables sobre un árbol inestable
Decirle al modelo «haz clic en el tercer botón» es frágil. Decirle «haz clic en el elemento con id b17» solo funciona si b17 significa lo mismo en el siguiente turno. Los frameworks modernos vuelven a renderizar de forma agresiva, así que no podemos apoyarnos en la identidad de los nodos del DOM.
Nuestras referencias se derivan de lo que usaría una persona para reconocer el elemento (su rol, su etiqueta, su posición entre sus hermanos, la región ARIA que lo contiene) y mantenemos un mapa de corta duración que asocia cada referencia a su nodo vivo. Cuando el mapa se queda obsoleto, la acción falla a la vista y el modelo vuelve a leer la página en lugar de hacer clic donde no debe. Una acción fallida que se ve es mucho mejor que una acción exitosa sobre el elemento equivocado.
3. Qué no enviar
Una instantánea enriquecida de un producto real contiene datos reales: nombres de clientes en una tabla, el total de una factura, una dirección de correo en un campo de formulario. Enviarlo todo a un modelo por defecto no es aceptable, y «lo necesitamos para el contexto» no es motivo suficiente.
La instantánea se minimiza en el cliente antes de salir de la página. El texto visible se recorta y se deduplica, los valores de los campos se resumen como rellenado / vacío / no válido en lugar de copiarse, y solo se reenvía una lista de atributos data permitidos. Lo que buscamos es que el modelo sepa que hay una tabla de clientes con 48 filas y un buscador encima, no quiénes son esos clientes.
La minimización a veces cuesta una respuesta. Si el usuario pregunta «¿por qué está mal el total de esta factura?», el modelo no puede ver la cifra. Creemos que es el comportamiento por defecto correcto: puede señalarle el campo al usuario y explicarle cómo se calcula el total, sin que la cifra salga nunca de la página.
Mostrar en lugar de contar
Una vez que el modelo se basa en la misma interfaz que está mirando el usuario, se vuelve posible algo que ningún asistente entrenado con documentación puede hacer: dejar de describir y empezar a señalar.
Cuando la respuesta menciona un elemento, el widget lleva un cursor hasta él en la página real y espera. En un flujo de trabajo de varios pasos, ese cursor acompaña al usuario de control en control, incluso cuando cambia de página, porque la instantánea se reconstruye en la nueva ruta. La instrucción y la interfaz pasan a ser lo mismo, y el paso de traducción que hace agotadora la documentación sencillamente desaparece.
Cualquier asistente puede decirte dónde está el botón. La diferencia está en si puede ver que ya estás mirando la página equivocada.
Dónde sigue importando la documentación
Nada de esto significa que la documentación no le sirva al modelo. Significa que tiene otro trabajo. La documentación aporta la intención (para qué sirve una función, cuándo usarla, qué significa un ajuste) y la pantalla aporta el estado. Una buena respuesta a menudo necesita las dos: la base de conocimiento explica que los webhooks se reintentan tres veces y la pantalla muestra que la última entrega de este webhook falló.
Así que Barkan sí consulta la base de conocimiento, pero lo hace después de haber leído la pantalla, y la pantalla gana siempre que las dos no coinciden. Si la documentación dice que hay un botón Añadir miembro y la pantalla dice que está desactivado, la respuesta trata del botón desactivado.
– Básate en la interfaz renderizada, no en la documentación. «Cierto en general» es el tipo de error más caro.
– Envía estructura, no píxeles ni HTML en bruto: elementos interactivos, relaciones, datos de la interfaz, contenido resumido.
– Captura cuando la página se haya asentado y vuelve a capturar tras cada acción; el DOM es un blanco móvil.
– Minimiza en el cliente. El modelo debe conocer la forma de los datos, no los datos.
– Señala, no describas. Si puedes ver el elemento, puedes mostrarlo.
La instalación sigue siendo una sola línea
Es razonable temer que «lee la interfaz renderizada» implique una integración profunda. No es así. El widget es una única etiqueta script en el layout que ya renderizas; monta su propia raíz en un shadow DOM, observa la página desde dentro del navegador y no necesita anotar rutas ni envolver componentes.
<script async src="https://trybarkan.com/widget.js" data-barkan-site="site_your_key"></script>Todo lo descrito arriba ocurre en ese script. El producto en el que se instala no necesita saber que Barkan existe.
Instala el snippet, abre tu app y pregúntale algo que tu documentación no sepa responder. US$25 en créditos para empezar, sin tarjeta.
«La mayoría de los usuarios no quieren otra respuesta. Quieren que les muestren el camino, o que se lo den hecho. Ese es todo el producto.»
Gabriel Lancelot
Cofundador de Barkan
