Persona.js

Persona: La Librería UI de VanillaJS para Experiencias de Agentes con WebMCP

En la era de la inteligencia artificial, la forma en que los usuarios interactúan con las aplicaciones web está evolucionando. Persona se presenta como la solución definitiva para desarrolladores que buscan crear experiencias de front-end agentic de vanguardia. Esta Agent UI Library basada en VanillaJS permite integrar agentes inteligentes de manera fluida, ligera y altamente extensible, siendo nativa del estándar WebMCP.

¿Qué es Persona?

Persona es una biblioteca de interfaz de usuario diseñada específicamente para el ecosistema de agentes de IA. A diferencia de otros frameworks pesados, Persona está construida con pure JS (VanillaJS), lo que la hace increíblemente ligera y compatible con cualquier stack tecnológico. Su propósito principal es ayudar a los desarrolladores a construir interfaces donde los agentes no solo chateen, sino que operen activamente dentro de la aplicación.

Al ser WebMCP-native, Persona aprovecha el protocolo de contexto de modelo para que los agentes puedan descubrir y utilizar herramientas directamente en el navegador, ofreciendo una experiencia de usuario cohesiva y potente.

Características Principales de Persona

Persona no es solo un widget de chat; es un sistema completo de interacción agentic. Sus características están diseñadas para maximizar la eficiencia del desarrollador y la experiencia del usuario final.

1. Aislamiento Total con Shadow DOM

Uno de los mayores retos al añadir widgets de terceros es el conflicto de estilos. Persona utiliza Shadow DOM rendering y CSS con prefijos, lo que garantiza que los estilos del widget y de la aplicación host se mantengan completamente separados. Puedes soltar a Persona en cualquier página con la seguridad de que nada se filtrará hacia afuera ni hacia adentro.

2. Transporte y Streaming SSE

La interactividad en tiempo real es clave para los agentes. Persona soporta SSE streaming (Server-Sent Events) con parsers conectables. Esto permite adaptar cualquier forma de evento o solicitud mediante customFetch y parseSSEEvent. Aunque Persona funciona de maravilla con Runtype, no es un requisito obligatorio, permitiendo la conexión con cualquier backend SSE.

3. Personalización y Theming

La identidad visual de tu marca es prioritaria. Persona incluye un árbol de tokens de tres capas (paleta, semántica y componente) y un Theme Editor en vivo. Esto permite que el widget se integre visualmente en tu aplicación sin necesidad de realizar un fork del código original, incluyendo soporte nativo para modo oscuro.

4. Capacidad Agentic Nativa

Persona permite que el agente opere tu aplicación. Al exponer acciones de la página como herramientas de WebMCP (búsquedas, carritos de compra, reservas), el agente puede dirigirlas directamente, siempre contando con la aprobación del usuario incorporada en la interfaz.

Cómo Usar Persona en tu Proyecto

Persona ofrece múltiples caminos de integración dependiendo de la complejidad y las necesidades de tu stack tecnológico.

Instalación Inicial

Puedes comenzar instalando el paquete a través de npm:

npm install @runtypelabs/persona

O si prefieres una implementación rápida, puedes utilizar una etiqueta de script estándar en tu HTML.

Configuración del Widget

Para iniciar un widget básico, puedes usar el siguiente patrón de código en JavaScript:

import "@runtypelabs/persona/widget.css";
import { initAgentWidget } from "@runtypelabs/persona";

initAgentWidget({
  target: "#chat",
  config: {
    apiUrl: "https://tu-api.com/chat",
    // El launcher flotante es el valor por defecto
  },
});

Registro de Herramientas WebMCP

Para que Persona pueda interactuar con tu aplicación, debes registrar las herramientas en el contexto del modelo:

"WebMCP da al navegador un lugar estándar para las herramientas de la página: document.modelContext. Persona descubre esas herramientas y pregunta al usuario antes de ejecutarlas."

Ejemplo de registro de una herramienta de búsqueda:

document.modelContext.registerTool({
  name: "search_products",
  description: "Buscar en el catálogo.",
  inputSchema: {
    type: "object",
    properties: {
      query: { type: "string" },
    },
    required: ["query"],
  },
  async execute({ query }) {
    return searchCatalog(query);
  },
});

Casos de Uso (Use Cases)

Persona es versátil y se adapta a diversos escenarios empresariales y técnicos:

• Soporte y Onboarding: Utiliza el diseño Floating para un asistente que guíe a los nuevos usuarios o resuelva dudas frecuentes.
• E-commerce (Storefront): Un agente que ayude a buscar productos y gestionar el carrito de compras mediante herramientas WebMCP.
• Productividad (Calendarios y Diapositivas): Agentes que puedan agendar citas o manipular elementos en una presentación directamente desde el chat.
• Paneles de Control (Docked Panel): Un copiloto anclado al lado de tu aplicación principal para asistir en tareas complejas de análisis de datos.
• Asistentes de Pantalla Completa: Ideales para experiencias de IA inmersivas donde el agente es el centro de la interacción.

Opciones de Diseño de UX

Persona permite cambiar el punto de entrada y la experiencia de usuario simplemente modificando la configuración del launcher, sin alterar la lógica del agente o de la aplicación:

• Floating: Un lanzador en la esquina que abre un panel flotante. Ideal para ventas o soporte.
• Docked: Un copiloto anclado al lateral de tu aplicación.
• Fullscreen: Un asistente que ocupa toda la pantalla para interacciones profundas.

Preguntas Frecuentes (FAQ)

¿Persona requiere un framework específico como React o Vue? No, Persona es una VanillaJS Agent UI Library, lo que significa que funciona de forma independiente en cualquier entorno web sin depender de frameworks específicos.

¿Con qué backends es compatible Persona? Es compatible con cualquier backend que soporte SSE (Server-Sent Events). Existen ejemplos pre-construidos para Vercel AI SDK, OpenAI Agents, LangGraph.js, Hono, Express, SvelteKit y más.

¿Cómo garantiza Persona que no afectará el diseño de mi sitio web? Persona utiliza Shadow DOM y CSS prefijado para aislar completamente sus estilos, asegurando que no haya fugas de diseño entre el widget y la página principal.

¿Qué es WebMCP y por qué es importante para Persona? WebMCP es un estándar que permite a los agentes descubrir herramientas directamente en el código de tu página. Persona es nativo de este estándar, lo que facilita que el agente realice acciones como búsquedas o reservas sin necesidad de complejas integraciones de backend adicionales.

¿Puedo personalizar los colores y la apariencia? Sí, Persona cuenta con un sistema de theming basado en tokens y un Theme Editor que permite ajustar la paleta de colores y la semántica para que coincida perfectamente con tu marca.