Manual de usuario — Xabia Agent Core

Versión del producto: Xabia Agent Core v1.0.291 (agosto 2026)
Índice de manuales: https://xabia.ai/docs/
PDF en línea: https://xabia.ai/docs/manual-usuario-xabia-core.pdf
HTML en línea: https://xabia.ai/docs/manual-usuario-xabia-core.html

Guía rápida de instalación

1. Descargue el ZIP de Xabia Agent Core (xabia-agent-core-1.0.291.zip o paquete retail equivalente).
2. En WordPress, vaya a Plugins → Añadir nuevo → Subir plugin, seleccione el ZIP y pulse Instalar ahora → Activar.
3. Abra Xabia Agent y configure Conexión a la IA: pegue la licencia XABIA--…, elija Xabia Cloud (recomendado) o Infraestructura propia, y guarde.
4. Cree un agente desde Nuevo agente, escriba nombre, saludo e instrucciones básicas.
5. Elija una fuente de información (CSV, SQL, addon o multi-fuente), pulse Conectar / Mapear cuando proceda y guarde el agente.
6. Pulse Sincronizar datos y, si usa búsqueda vectorial, Entrenar IA.
7. Publique el agente con el shortcode [xabia_agent id="ID_DEL_AGENTE"] o active la interfaz nativa desde Apariencia → Mostrar en el sitio sin shortcode.
8. Pruebe en Playground y en una página real antes de abrirlo al público.

Actualización desde una versión anterior: suba el nuevo ZIP desde Plugins, sustituya la versión instalada y conserve la configuración existente. Si usa /xabia-box/, visite Ajustes → Enlaces permanentes → Guardar tras actualizar. Tras instalar 1.0.72+ con WPML, visite una página del front para que se sincronicen las traducciones de la UI del chat; vacíe caché (LiteSpeed, etc.). Con fuente SQL remota, tras actualizar a 1.0.164+ vuelva a Sincronizar (y enviar al Hub si aplica) para regenerar las fichas con el anexo de atributos mapeados.

Guía rápida: qué hacer en cada situación

Use esta tabla como hoja de ruta. Cada fila indica la pantalla exacta y el orden de pasos.

1. Estructura del menú en WordPress

Tras activar Xabia Agent Core, en el escritorio aparece el menú Xabia Agent con icono de “superhero”.

Opciones según lo que tenga instalado su sitio

• Si tiene Xabia Central activo, puede ver Federación (Xabia Central) como submenú para enlazar varios sitios o nodos cuando use esa función.
• Si tiene el addon Federación Nexus, puede aparecer Federación o Federación Nexus (consulte el manual de ese addon si lo usa).

Para cambiar casi todos los ajustes hace falta estar entrado como administrador de WordPress (o con un perfil equivalente que permita gestionar plugins y opciones del sitio).

2. Pantalla principal: listado de agentes

Cuando abre Xabia Agent sin estar editando un agente concreto, verá:

2.1 Título y acciones

• Nuevo agente: crea una ficha nueva y abre el editor. Al guardar por primera vez, el sistema le asigna un identificador estable (derivado del nombre); ese código es el que pegará más adelante en la página web con el shortcode (ver más abajo).

2.2 Tarjetas de agentes existentes

Cada tarjeta muestra:

• Nombre con el que verá el agente en el panel.
• ID: un código como ID: mi-asistente que debe coincidir con lo que pone en el shortcode: [xabia_agent id="mi-asistente"].
• Editar: abre toda la configuración del agente.
• Borrar: elimina el agente y toda la memoria de conocimiento que hubiera generado para él (lo aprendido al sincronizar y entrenar). No se puede deshacer con un solo clic.

Si borra un agente: pierde su configuración, los mapeos de datos y la “memoria” asociada. Si subió un archivo CSV para ese agente, el archivo puede seguir en el servidor; si ya no lo necesita, puede borrarlo desde Medios o por FTP según su caso.

2.3 Bloque «Addons disponibles»

Tarjetas con los complementos (addons) que Xabia conoce: nombre, breve descripción y enlace para instalar o gestionar. Activar o desactivar un plugin sigue haciéndose en Plugins de WordPress, como con cualquier otro plugin.

Importante: un addon puede estar instalado pero inactivo, o activo pero requerir otra configuración (licencia addon, tablas, etc.).

2.4 Pausar un agente (listado)

En cada tarjeta del listado hay tres acciones: Editar, Pausar / Activar y Borrar.

• Pausar: el agente deja de mostrarse en el sitio (no aparece el shortcode ni el disparador flotante). La configuración y la memoria se conservan.
• Si está pausado, la tarjeta muestra la etiqueta Pausado y el botón pasa a Activar.

2.5 Interfaz del chat por agente (pestañas Apariencia y Comportamiento IA)

Desde la v1.0.28, la interfaz se configura por agente. En las versiones actuales verá dos pestañas separadas:

• Apariencia: diseño visual (modo de presentación, avatar, burbuja, voz).
• Comportamiento IA: saludo, instrucciones, RAG, sinónimos y límites.

En Apariencia, el bloque principal es «¿Dónde se verá el agente?»: una cuadrícula de tarjetas visuales (con mini‑esquema) para elegir el perfil de presentación sin tener que interpretar nombres técnicos.

Desde la v1.0.57 hay modos claramente separados; desde la v1.0.192+ existe además el lanzador incrustable. El mapa siguiente resume qué pegar y qué verá el visitante.

Mapa visual: shortcodes y resultado

Las reglas Mostrar solo en estas páginas y Excluir estas páginas o entradas pertenecen a la burbuja de Web adaptable. En modo shortcode o lanzador el chat o botón aparece únicamente donde esté pegado el shortcode.

Avatar cinético oficial (v1.0.47)

El disparador por defecto reproduce el muñeco Xabia en capas SVG inline (cabeza, cuencas blancas y ojos/satélite), escaladas a una caja de 125×125 px:

El avatar mira al cursor con efecto de profundidad: la cabeza se mueve muy poco, las cuencas algo más y los ojos/satélite con mayor amplitud (animación GSAP). También puede usar imagen personalizada (PNG/SVG desde Medios).

Comportamiento en la web (sin Elementor)

Opciones principales en Apariencia

Guarde con Guardar agente. En modo nativo el plugin inyecta disparador y assets en wp_footer automáticamente. En modo shortcode, pegue [xabia_agent id="su-agente"] o [xabia_launcher id="su-agente" size="lg"] donde corresponda.

Aspecto del chat (v1.0.197–1.0.201)

El panel usa un layout en stream (sin burbujas de mensaje), esquinas cuadradas y controles (enviar / micrófono / mute) que se revelan al pasar el ratón sobre la zona de escritura. El texto del usuario puede heredar el color de acento del avatar. Las respuestas del bot admiten Markdown básico (**negrita**, listas con viñetas) desde la v1.0.201.

Chat embebido con shortcode: halo y foco

El chat generado por shortcode conserva la estética del panel nativo: borde luminoso animado y sombra suave. Al hacer foco en el campo de texto, el plugin puede elevar el chat sobre la página y mostrar un overlay con blur que tapa el fondo para mejorar la lectura.

El overlay se cierra haciendo clic fuera del chat, pulsando Escape o usando el botón de cierre en móvil. Esta capa es independiente del telón del avatar nativo: el shortcode sigue siendo un chat embebido, no un disparador flotante.

La ruta /xabia-box/ (Smart QR / tótem) muestra el chat a pantalla completa sin disparador flotante. Smart QR, generador de códigos y modo tótem están incluidos en el Core — consulte el manual Smart QR para la guía completa con ejemplos.

2.6 Documentación en línea (xabia.ai/docs)

Los manuales en PDF y HTML del producto se publican en:

En el repositorio de desarrollo, las fuentes están en xabia-agent-plugins/documentation/ y se regeneran con ./scripts/build-modular-manuals-pdf.sh.

3. Conexión a la IA (tarjeta global)

Aquí decide cómo su web se conecta a la inteligencia artificial y al servicio xabia.ai cuando use el modo recomendado.

Use el botón Guardar configuración de esta misma página (no confundir con Guardar agente dentro de un agente).

3.1 Modo de conexión

Tiene dos opciones:

Tras cambiar de modo, revise cada agente: en Cloud no debe preocuparse por el “motor”; en infraestructura propia debe comprobar en cada uno qué proveedor usa y si las rutas/claves están bien.

3.2 Licencia y saldo

Bloque informativo (tokens y caducidad)

• Tokens restantes: lo que figura después de que el sistema compruebe su licencia. Si lleva tiempo sin sincronizar, puede aparecer una raya hasta que pulse Actualizar saldo.
• Caducidad: fecha hasta la que su licencia está activa según lo que recibe el sistema.
• Comprobado: cuándo se hizo la última verificación contra el servicio central.

El botón Actualizar saldo vuelve a preguntar a Xabia y refresca estos datos. Si aún no ha guardado una licencia, le avisará antes.

Sin licencia válida o sin saldo, el chat puede no responder o mostrar un mensaje sobre saldo insuficiente o licencia según configuración del servicio.

Campo «Licencia Xabia de este sitio»

• Es un campo tipo contraseña; puede usar el ícono de ojo para ver solo lo que está escribiendo ahora.
• Si ya tiene una licencia guardada y deja este campo vacío al guardar, no borra la antigua. Para quitar definitivamente la licencia use la casilla Eliminar licencia guardada (véase más abajo).
• Solo pegue aquí cuando quiera cambiar la licencia por una nueva cadena que le hayan enviado.

Licencia guardada: en pantalla solo verá asteriscos y quizá los últimos caracteres (por seguridad).

Aviso amarillo: si el sistema detecta que lo guardado parece un ID de panel (por ejemplo empieza por lic_…) y no la cadena larga de activación que suele empezar por xabia_, le avisará: el servicio probablemente no la aceptará. Lo habitual es eliminar la licencia guardada, guardar, y volver a pegar la clave completa del correo o de su compra.

Botón «Ver licencia guardada en WordPress»

Muestra lo que realmente está guardado en su WordPress (sin espacios raros ni cortes). Solo lo deben usar administradores de confianza: quien vea la licencia podría usarla en otro sitio si la copiara.

Cómo se protege la conexión

Cuando la licencia es correcta, el plugin la usa para identificar de forma segura su sitio ante xabia.ai al enviar las peticiones. No hace falta que entienda el detalle técnico: si cambia de licencia, la nueva empieza a aplicarse al guardar. Si por error pega los asteriscos de la pantalla en lugar de la clave real, el sistema intenta no sustituir la buena licencia guardada.

Casilla «Eliminar licencia guardada de este sitio»

• Al marcarla y pulsar Guardar configuración, se borra la licencia de este sitio.
• Efecto: el chat dejará de usar el servicio Xabia asociado a esa clave hasta que pegue otra licencia válida.
• No borra por sí sola sus claves OpenAI o Google de la sección avanzada; solo la licencia Xabia.

3.3 Claves API y Google Cloud (cuenta propia)

Solo aparece si eligió Infraestructura propia. La sección viene plegada en desplegable para no abrumar: ábrala cuando vaya a configurar credenciales.

OpenAI — clave (global aquí)

• Es la clave secreta de su cuenta OpenAI.
• Sirve cuando el agente está configurado para usar OpenAI y cuando no lleva una clave distinta sólo para él.
• Trátela como una contraseña de banca: si alguien la copia, puede generar cargos en su nombre. Cambiela desde el panel OpenAI si cree que ha filtrado.

Google Cloud (Vertex AI) — ruta al archivo JSON de la cuenta de servicio

• Debe ser la ruta completa en el servidor al archivo JSON que le da Google para la cuenta de servicio con permisos de Vertex/Gemini.
• Si en un agente concreto no rellena nada, se usará esta ruta global.

Errores frecuentes: ruta mal escrita, el servidor no puede leer el archivo, la cuenta no tiene permisos de Vertex, o el proyecto/región no coinciden con lo que usa en Google.

Google Cloud — clave de Maps

• Para mapas en el chat o piezas visuales que integren Google Maps, si su proyecto lo usa.

Federación Nexus — «Activar solo modo Puente»

Solo verá esto si tiene instalado el addon Federación Nexus.

Importante: si está en Xabia Cloud, marcar o desmarcar esta casilla en esta pantalla puede no guardarse como espera; el valor real sigue el que ya tenía el sitio. Para cambiar el modo Puente con seguridad, use Infraestructura propia o la pantalla que indique el manual de Nexus.

Qué es el modo Puente (en pocas palabras): su WordPress actúa como servidor de datos para otros sitios de la federación. No es el modo normal para un hotel o tienda que solo quiere un chat en la página. Si lo activa por error en un sitio público, es posible que el shortcode habitual del chat no se muestre como antes; consulte con quien le haya pedido la federación.

Consejo: si no sabe para qué es la federación, no marque solo modo Puente.

4. Editor de un agente: vista general

Al pulsar Editar o Nuevo agente, el formulario usa pestañas. Las predeterminadas del Core son:

1. General — datos básicos, motor de IA solo si usa infraestructura propia, fuentes (CSV/SQL…) y cómo etiquetar columnas para el bot.
2. Smart QR / Tótems (Core) — página de aterrizaje, URLs de túnel, generador de QR por ente, modo kiosko. Manual detallado Smart QR.
3. Apariencia — modo de presentación (cuadrícula visual), avatar, burbuja web y voz.
4. Comportamiento IA — saludo, preguntas sugeridas, prompt maestro, RAG/sinónimos/relaciones y límites.
5. Registro de conversaciones — historial reciente guardado si lo tiene habilitado.

Los addons pueden añadir pestañas extra dentro del mismo agente (por ejemplo Avirato).

Pulse Guardar agente al final para aplicar cambios; hasta entonces solo hay borradores en pantalla.

5. Pestaña «General»

5.1 Nombre del agente

• Nombre visible en el panel para usted y su equipo.
• Si crea el agente hoy por primera vez, el identificador del shortcode se genera a partir del nombre. Si solo cambia el nombre de un agente antiguo, el identificador del shortcode suele mantenerse (no cambia la URL pegada antigua).

5.2 Shortcode

El esquema visual de qué pegar y qué se ve está en §2.5. Aquí, la referencia de atributos.

Tras guardar un agente se muestra:

[xabia_agent id="ID_DEL_PROYECTO"]

Alias: [xabia_chat id="ID_DEL_PROYECTO"] (mismo resultado).

Al pegarlo en una página publica ese agente (si no está Pausado). El aspecto lo decide Apariencia: chat embebido (web) o pantalla completa (tótem/pantalla).

• Si Mostrar en el sitio sin shortcode está activado, el shortcode puede convivir con la burbuja nativa; el avatar flotante lo controla Apariencia.
• Si está desactivado, [xabia_agent] muestra solo el chat (o el tótem) en esa página, sin burbuja global.

Atributos de [xabia_agent] / [xabia_chat]

Atributos de [xabia_launcher] / [xabia_avatar]

No combine en la misma página una burbuja nativa y un lanzador del mismo agente si no quiere dos avatares. Para un hero: desactive «Mostrar en el sitio sin shortcode» y use solo [xabia_launcher].

5.3 Bloque Xabia Cloud (cuando el UI está en modo Cloud)

Mensaje informativo: el agente usa el servicio de Xabia; la licencia y el saldo los gestiona en la pantalla principal del plugin, no aquí dentro del agente.

En esta vista no verá opciones duplicadas de motor o de Google Cloud: el sistema usa lo que ya tiene guardado para ese agente y lo coherente con Xabia Cloud.

5.4 Motor de inteligencia (solo aparece en infraestructura propia)

Motor de Inteligencia:

Archivo JSON de Google por agente (opcional): si está vacío, se usa la ruta global de ajustes generales.

Clave OpenAI solo para este agente (opcional):

• Si rellena y guarda, este agente usa esa clave y no la global.
• Si deja vacío al editar y el agente ya tenía clave, suele conservarse la anterior.
• Según su modo global y licencia, si no hay clave local donde haga falta, el sistema puede derivar por el proxy Xabia; depende del caso.

Consejo práctico: si un agente usa su cuenta OpenAI directa y otro no, pueden aparecer cargos separados por proveedor — anote cuál usa cuál si lo administra más de uno.

6. Fuente de información (de dónde aprende el asistente)

Aquí decide qué datos debe “leer” el sistema antes de crear la memoria que usa el chat (preguntas frecuentes, catálogo, contenidos estructurados, etc.). Es aparte del contexto automático que algunos addons añaden en cada mensaje (por ejemplo disponibilidad de reservas).

El plugin le recordará en pantalla que los addons activos pueden aportar información adicional sin pasar solo por aquí; lo que elija en esta lista es la base de conocimiento que usted controla con CSV, SQL o conectores.

6.1 Archivos CSV

• Útiles para catálogos en tabla: productos, puntos de interés, listados exportados desde Excel como CSV.
• Subir CSV guarda el archivo en el sitio y lo enlaza a este agente.
• Eliminar CSV quita el archivo enlazado y la referencia.
• Explorar / escanear CSV detecta columnas y prepara el mapeo (qué significa cada columna para el bot).
• Por lo general distingue si las columnas van separadas por coma o por punto y coma.

Recuerde: hasta que pulse Sincronizar datos —y, si usa búsqueda por similitud semántica, Entrenar— el asistente puede no “ver” bien esas filas en las respuestas.

6.2 Base de datos de WordPress (SQL local)

Una consulta sobre la base de datos del propio WordPress. Use el comodín {prefix} cuando la plantilla lo indique: el sistema lo sustituye por el prefijo real de sus tablas (suele ser wp_ u otro que haya configurado su alojamiento).

Consejo: las consultas muy amplias pueden ralentizar el sitio o sacar datos de más. Pruebe primero en copia de seguridad/desarrollo o con límites razonables.

6.3 Base de datos externa (SQL remota)

Rellene Host, Nombre de la base, Usuario, Contraseña y la consulta cuando el catálogo viva fuera de WordPress.

Si la base externa es un WordPress con Modern Events Calendar, puede usar Usar preset MEC remoto. El Core rellenará la consulta SQL de eventos, aplicará el mapeo recomendado (Evento, Fecha, Hora, Lugar, Link, Precio, Descripcion, Categorias_Tags, Imagen_URL) y guardará sql_preset = mec_remote.

Use este preset cuando no vaya a instalar el addon MEC en el sitio del chat. Si sí tiene Xabia MEC activo, el flujo recomendado es Conectores de addons → MEC con las credenciales SQL remotas (§6.4), igual que Woo.

Seguridad: las credenciales quedan guardadas con el agente; lo ideal es que el servidor remoto solo acepte conexiones desde la IP de su web.

6.4 Conectores de addons

Solo está disponible con un addon compatible instalado y activo. Si aparece como no disponible, instale primero ese plugin desde Plugins.

Tras seleccionarlo, use Conectar y Mapear para revisar las columnas que expone antes de usarlas.

Los addons MEC y Woo también pueden trabajar contra una base de datos remota desde los campos Host / DB / usuario / contraseña. En ese caso el modo sigue siendo Addon nativo (porque aporta reglas, mapeo y acciones del dominio), pero la lectura SQL se hace contra otro WordPress. Para MEC remoto (Core ≥ 1.0.202 + addon MEC), si el sitio del chat no tiene Modern Events Calendar local, el asistente nunca emite botones de reserva local ([ACTION:BOOK:ID]): dirige al visitante con [ACTION:URL:Link] usando la columma Link del evento remoto.

6.5 Varios orígenes a la vez (“multi‑fuente”)

Puede combinar hasta dos fuentes (por ejemplo SQL remoto + CSV).

• Cada parte lleva sus propios datos y su propio mapeo de columnas.
• En remotos suele poder ayudar un prefijo automático con el mismo criterio que {prefix}.

Consejo: más fuentes ofrecen flexibilidad, pero también más sitios donde equivocarse; revise cada bloque con tranquilidad.

7. Herramientas dentro de la pestaña Datos

7.1 Probar la consulta SQL (una fila)

Hace una lectura de prueba (solo la primera fila) de su consulta para mostrarle qué columnas detecta y ayudarle en el mapeo. Evite usarlo en picos de visitas en sitios en producción sin control: es una herramienta de comprobación.

7.2 Asistente de contenidos WordPress (“Consola de curación”)

Un asistente paso a paso que:

1. Lista los tipos de contenido de la fuente activa (no los del WordPress del chat si la fuente es otra).
2. Sugiere qué campos son interesantes para el bot (título, texto, metadatos, taxonomías…).
3. Puede transferir una consulta SQL y un mapeo razonable al formulario del agente.

Segregación por fuente (Core ≥ 1.0.162):

El modal muestra un aviso del origen (p. ej. «Base de Datos Remota»). En deep schema, productos Woo incluyen metas _price / _sku / stock; MEC incluye plazas calculadas cuando aplica.

Qué es “Ente”: marque el campo que identifica de forma única cada elemento (útil en experiencias con QR o cuando el visitante “elige” una ficha concreta).

También tiene un atajo para añadir metadatos de un tipo de contenido sin pasar por todo el asistente.

7.3 Mapeo de columnas (atributos repetibles)

💡 Piénsalo de forma sencilla: la IA es increíblemente inteligente, pero no puede adivinar qué número de tu Excel es un teléfono, cuál es un precio o qué celda es un enlace a una imagen. Al asignar el rol Teléfono o Imagen en el mapeador, le estás dando las llaves de tu negocio: le enseñas a rellenar su agenda de contactos para cuando el cliente le pida el teléfono de una empresa.

Por cada fila elija:

• Columna o campo del CSV/SQL.
• Etiqueta amigable (“Precio”, “Teléfono de reservas”…).
• Rol visual en el chat cuando corresponda mostrar tarjeta enriquecida: título, texto, fecha, imagen (fotos/galería), logotipo (marca corporativa), teléfono, web, email, mapa, etc.
• IDENTIDAD (ENTE) si ese campo distingue registros únicos en su proyecto.

Roles clave para catálogos de empresas (Core ≥ 1.0.118):

El Core no asume nombres fijos de campos de un cliente concreto. Todo se resuelve desde este mapeo.

Algunas columnas típicas de WordPress muestran un icono de “cerebro” para destacar que son buenos candidatos como texto principal del conocimiento — no es obligatorio tocarlo si no lo necesita.

8. Smart QR y modo tótem (incluidos en Core)

Desde la v1.0.59, toda la potencia de Smart QR (túnel por ente, generador de códigos, /xabia-box/, modo kiosko) forma parte de Xabia Agent Core. No hace falta instalar ni licenciar un plugin aparte.

8.1 Resumen en tres pasos

1. Sincronice conocimiento con al menos una columna marcada como IDENTIDAD (ENTE) (§7.3).
2. Publique una página con [xabia_agent id="…"] y selecciónela como Página de aterrizaje en Editar agente → Smart QR / Tótems.
3. Pulse Generar QR junto al ente deseado, descargue el PNG e imprímalo.

El escaneo abre el chat con contexto del ente (saludo y RAG acotados). Ejemplo de URL generada:

https://su-dominio.com/asistente/?ente_id=sala-impresionismo

8.2 Modo tótem (pantallas públicas tipo kiosko)

En Smart QR / Tótems puede activar Modo tótem y definir minutos de inactividad: tras ese tiempo sin usar el chat, la sesión vuelve al saludo inicial (útil en tablet en recepción).

También puede usar la ruta a pantalla completa:

https://su-dominio.com/xabia-box/?x_project=ID_DEL_AGENTE

En el shortcode puede forzar minutos con totem="10":

[xabia_agent id="mi-agente" ente_id="recepcion" totem="10"]

Resumen: Smart QR = carteles y enlaces por ente; modo tótem = quiosco en pantalla fija. No tiene que usar ninguno si solo quiere chat clásico en la web.

8.3 Documentación ampliada

Casos museo, hotel, retail, POI ?xqr=, migración del antiguo plugin xabia-smart-qr y solución de problemas: manual-usuario-xabia-smart-qr.md (PDF/HTML en xabia.ai/docs/manual-usuario-xabia-smart-qr.pdf).

9. Barra lateral (solo agente ya guardado, no «new»)

La columna derecha (memoria + Playground) hace scroll con la página (Core ≥ 1.0.165): no queda fijada arriba. Así puede revisar el formulario completo sin pelearse con paneles pegados.

9.1 Memoria del agente (cifras de la barra lateral)

• Registros sincronizados: líneas incorporadas tras la última Sincronizar datos.
• Listos para búsqueda inteligente: cuántos trozos ya llevan preparada la parte “semántica” si usa esa función.
• Tokens hoy: cuántos ha gastado ese agente hoy comparado con su tope diario (véase más abajo en Comportamiento IA).

9.2 Botón «1. Sincronizar datos»

Vuelve a leer su CSV/SQL/multi‑fuente o conector según lo que configuró en General. Hágalo después de cambiar archivos fuente o la consulta.

9.3 Botón «2. Entrenar» (cuando aplique vectorización)

Prepara los fragmentos de texto para la búsqueda por similitud. Si algo falla (permiso de Google, falta de saldo Cloud, etc.) el sistema mostrará un mensaje claro para corregirlo.

9.4 «Borrar memoria vectorial»

Limpia la memoria matemática asociada a este agente (no borra necesariamente el CSV en disco). Úselo cuando quiera empezar de cero después de mover muchos datos.

9.5 Zona de pruebas («Playground»)

Un chat de laboratorio igual que usará el visitante pero sin publicar página todavía. Ideal para tunear antes de abrir al público.

Cuando la respuesta incluye [ACTION:IMG:…], el Playground muestra la etiqueta (alt) «Imagen de la entidad»: es un texto agnóstico (empresa, producto, POI…), no específico de eventos. En el Playground no es obligatorio que la imagen cargue visualmente; el alt solo identifica el marcador.

10. Pestaña «Comportamiento IA»

Aquí define el estilo de respuesta del asistente y cómo usa su base de conocimiento.
La parte visual (modo de presentación, avatar y burbuja) está en la pestaña Apariencia.

10.1 Nombre del asistente (en los mensajes)

El nombre corto que verá el visitante junto a cada mensaje del bot (por defecto “Xabia”). No confundir con el avatar cinético del disparador flotante (§2.5). En el shortcode puede usar avatar_name="…" para personalizarlo.

10.2 Colores y tipografía

• Color identidad: botones y detalles destacados del chat.
• Color de fondo del chat.
• Tamaño del texto en píxeles (elija lo que se lea bien en móvil y ordenador).

10.3 Voz (lector del navegador)

El visitante puede usar leer en voz alta si su navegador lo permite.

• Tipo de voz (por defecto / más femenina / más masculina): es una sugerencia al sistema; el resultado depende del dispositivo.
• Velocidad: de lenta a rápida dentro del rango permitido.
• Filtros para que suene natural: puede quitar negritas asteriscos, marcas técnicas tipo [ACCIÓN:…] o emojis, y añadir textos concretos que no quiera que se lean (por ejemplo enlaces larguísimos).

En el chat, el botón de altavoz alterna entre voz desactivada y lectura en alto. Cuando un botón de acción está activo o resaltado (voz, micrófono o enviar), el icono cambia a blanco sobre fondo de color para mejorar el contraste.

10.4 Índice de confianza del contexto

Valor entre 0 y 1 (en pantalla suele sugerirse algo cercano a 0,20).

En lenguaje claro: cuánto debe “encajar” el material de su web con la pregunta para que el modelo lo use. Si sube mucho este valor, el asistente será más exigente: puede volverse cortante o genérico porque descarta trozos que no le parecen una coincidencia suficiente. Si baja el valor, aceptará más contexto relacionado; a veces aparece algo más de ruido si los datos no están bien ordenados.

Consejo: ajuste despacio y pruebe en el Playground antes de abrir al público.

10.5 Cuánto puede alargarse cada respuesta

Controla el tamaño máximo de texto que puede generar cada respuesta (el sistema tiene un rango razonable guardado).

Si aumenta este límite: las respuestas pueden ser más largas y detalladas, pero también gastan más tokens y pueden tardar algo más. Si reduce el límite: ahorra y es más directo, pero quizá no desarrolle tanto el tema.

10.6 Tope diario de consumo por agente

Número máximo de tokens que este agente puede usar en un día (el contador se cierra según el día “técnico” del servicio, habitualmente en horario universal).

Si se supera, el chat puede entrar en modo mantenimiento para ese agente aunque la cartera general tenga saldo: es un fusible útil frente a picos o abusos accidentales.

10.7 Cuántos trozos de conocimiento enviar en cada pregunta (“contexto”)

Número de fragmentos de su conocimiento base que se pueden mezclar con la pregunta en cada turno (suele estar en un rango amplio; si lo deja vacío, el sistema usará un valor por defecto).

• Más trozos: contextualmente más rico, pero más gasto y a veces más “disperso” si no acierta el contenido.
• Menos trozos: más económico y directo, pero el asistente puede dejar fuera datos que estaban en otros fragmentos menos priorizados.

10.8 Búsqueda inteligente (“vectorial”) y sensibilidad

• Activar búsqueda vectorial: conviene solo si ya ha hecho Entrenar y ve en la barra lateral que hay memoria lista. Si no hay nada entrenado, el texto de ayuda le avisará.
• Umbral de similitud (0–1): qué tan parecido debe ser un trozo a la pregunta para contar. Valores muy altos pueden hacer que “no encuentre nada” sobre temas relacionados pero no idénticos.
• Expansiones de palabras clave (Comportamiento IA / reglas avanzadas): mapa opcional aguja → sinónimos (p. ej. caballo → hípica|equitación|pony). Con Xabia Cloud ≥ 1.0.282, el Hub usa esas expansiones en la búsqueda léxica y el recorte de contexto prioriza fichas que coincidan con los sinónimos. Úselo cuando el visitante pregunta con un término y sus fichas usan otro (sin inventar un diccionario de todo el sector).

10.9 Saludo inicial

Texto HTML sencillo que ve el visitante al abrir el chat. WordPress aplicará sus reglas de seguridad habituales sobre etiquetas permitidas.

10.10 Instrucciones generales (personalidad y reglas)

Aquí escribe quién es el asistente, tono (formal, cercano, breve), límites (“no opina de política”, “no invente precios sin consultar datos”, etc.).

Consejo práctico: no hace falta listar todos los sinónimos de su sector; con buenos datos y una memoria bien sincronizada las respuestas son más naturales. Use este cuadro para el comportamiento estable del negocio.

10.11 Idiomas y respuestas políglotas

Xabia responde en el idioma del último mensaje del usuario. Si el conocimiento sincronizado está en español pero el visitante pregunta en inglés, francés o euskera, el modelo redacta la respuesta en ese idioma.

El idioma configurado por WordPress o por el atributo lang del shortcode afecta sobre todo a la interfaz fija (placeholder, botones, voz del navegador). No fuerza a la IA a responder siempre en ese idioma.

Evite en el prompt maestro frases rígidas como «responde exclusivamente en español» salvo que quiera bloquear el comportamiento políglota.

10.12 Sitio multilingüe con WPML (saludo + textos del chat)

¿Quieres que tu asistente hable euskera o inglés de forma automática? Con WPML + String Translation, Core ≥ 1.0.72 y licencia Cloud, sigue esta ruta rápida de 3 pasos:

1. Escribe tu saludo inicial en castellano dentro de la pestaña Comportamiento IA y guarda el agente.
2. Xabia detectará tus idiomas activos y se encargará (gracias a tu licencia Cloud) de traducir el saludo automáticamente por detrás.
3. Ve a WPML → String Translation y comprueba que tus traducciones están listas en el contexto Xabia AI. ¡Así de fácil!

Después, vacía la caché del sitio (LiteSpeed, Cloudflare…) y prueba en incógnito las URLs /, /eu/, /en/ (o las que uses).

Un ajuste WPML imprescindible (solo la primera vez)

En WPML → Configuración, baja hasta Traducción de cadenas → Cambiar el idioma original de las cadenas → elige Español.

Si no ves ese enlace: WPML → Traducción de cadenas → Utilidades y pon Español como idioma original de las cadenas del plugin. Así evitas que el saludo aparezca con bandera inglesa aunque el texto esté en castellano.

Textos fijos del chat («Escribe aquí…», botones)

Al visitar el sitio una vez tras instalar o actualizar, Xabia suele rellenar también las traducciones de la interfaz del chat (placeholder, Enviar, Hablar…). Si algún texto no cambia de idioma: vacía caché, vuelve a entrar al front y revisa String Translation. Si sigue vacío, escribe a soporte: a veces hace falta forzar una re-sincronización.

Si algo no cuadra

¿Sin WPML o sin licencia Cloud? Puedes traducir el saludo a mano en String Translation; el paso automático simplemente no se ejecuta.

11. Catálogo, pasaporte remoto y seguimientos por ente (Core ≥ 1.0.118 / 1.0.164+)

Desde la v1.0.118, Xabia Agent Core incluye un motor de catálogo agnóstico: listados y datos de ficha por empresa, producto o punto de interés sin depender de nombres de campos de un cliente concreto. Desde la v1.0.164, si tus datos viven en una base remota, al sincronizar Xabia guarda junto a cada ficha un anexo con los atributos que mapeaste en General (teléfono, email, web, etc.).

11.1 Qué resuelve

11.2 Qué necesita configurar (una sola vez)

1. Fuente de datos coherente con su catálogo (CSV, SQL local/remoto, multi-fuente, addon…).
2. Mapeo de columnas con al menos un campo IDENTIDAD (ENTE) y roles de contacto/imagen (§7.3).
3. Una categoría o taxonomía de actividad reconocible en su proyecto — el Core la deduce del mapeo, sin nombres fijos de un vertical.

Contenido en el mismo WordPress del chat: listados y ficha pueden leerse en vivo (sin sync obligatorio para ese atajo).

Datos en SQL remoto / Hub (Core ≥ 1.0.164): debe Sincronizar (y enviar al Hub si usa búsqueda en la nube) para que teléfono, email, etc. viajen con cada ficha. Xabia no inventa campos: solo usa lo que usted mapeó en General y tiene valor en la fila.

11.3 Flujo conversacional típico

1. Visitante: pregunta de listado (varias entidades).
2. Asistente: viñetas concisas; cierra invitando a elegir o pedir más detalle.
3. Visitante: «teléfono de [nombre]» / «contacto de la primera».
4. Asistente: datos de ficha (anexo o pasaporte).
5. Visitante: «y alguna imagen».
6. Asistente: muestra la imagen solo si el rol Imagen está mapeado y tiene valor.

El sistema recuerda el listado a partir del historial del chat que se envía en cada mensaje.

11.4 Modo lista vs ficha (Core ≥ 1.0.165)

Comportamiento agnóstico: solo depende de su mapeo, no de un cliente concreto.

11.5 Si algo falla en el Playground

Tras un listado, pruebe en el mismo chat: «¿teléfono de la primera?» o «¿alguna imagen?». Si no responde bien: Core ≥ 1.0.166, roles Teléfono / Imagen en el mapeo (§7.3) y, con SQL remoto, Sincronizar de nuevo.

Detalle técnico para integradores: DESARROLLO.md §11–12.

11.6 Hub vs catálogo local vs SQL remoto

Un Hub aún sin memoria entrenada no bloquea el listado local; sí limita las respuestas semánticas profundas hasta re-sincronizar.

11.7 Novedades 1.0.162 – 1.0.168 (resumen)

12. Pestaña «Registro de conversaciones»

Aquí aparece, cuando está activado, el historial reciente: fecha, mensaje del visitante y respuesta del asistente.

Privacidad (RGPD): compruebe con su responsable jurídico si puede guardar conversaciones que incluyan datos personales y si debe informarlo en política de privacidad / cookies como corresponda en su país.

13. Precios, licencias y packs

📢 Nota sobre tarifas y licencias: para garantizar que siempre veas las ofertas vigentes, la tabla de precios actualizada, los packs de tokens y las condiciones de renovación se gestionan en tiempo real en nuestra web oficial: https://xabia.ai/precio.

En la práctica encontrará ahí:

• Licencia Core (primer año y renovación), con tokens de cortesía según la oferta vigente.
• Packs de tokens (Starter, Business, Enterprise u otras denominaciones publicadas).
• Addons (Avirato, Woo, MEC, etc.) y proyectos de red federada a medida.

Las recargas se hacen en Xabia Agent → Cartera / Wallet. Los addons añaden funciones, pero las conversaciones con IA siguen usando tokens salvo donde un addon indique lo contrario (respuestas “ligeras” sin modelo).

14. Cartera / Wallet

Menú: Xabia Agent → Cartera / Wallet.

13.1 Qué muestra esta pantalla

• Saldo actual de tokens asociados a esta instalación cuando el servicio lo confirme.
• Un identificador de cliente o licencia que verá también en algunos enlaces de pago. No es necesariamente el mismo texto que la cadena secreta xabia_… que pega en Conexión a la IA. Si necesita estar seguro, use «Ver licencia guardada» en la pantalla principal.
• Histograma de consumo de las últimas semanas para hacerse una idea visual del ritmo de gasto.
• Renovar año aparece habitualmente cuando se acerca la fecha de caducidad (ventana habitual de orden de treinta días).

13.2 Cómo recargar tokens

1. Compruebe que en Conexión a la IA tiene la licencia larga correcta (la que fue el correo o la clave activable, normalmente formato xabia_…).
2. Entre en Cartera / Wallet como administrador.
3. Pulse Recargar en el pack que se ajuste a su público (consulte importes y tamaños vigentes en xabia.ai/precio).
4. Complete el pago en la pasarela que se abre. El sistema ya envía detrás los datos necesarios para asociar la compra a este sitio; suele hacer falta esperar unos minutos y después pulsar Actualizar saldo en la pantalla principal hasta que coincida.

Comprado desde otro ordenador: no suele haber problema mientras sea la misma combinación dominio + licencia que espera la tienda para su sitio.

Multisite o una copia de prueba (staging): fíjese bien en desde qué dirección URL tiene instalado Xabia: la compra puede quedar vinculada a esa máquina concreta.

13.3 Renovar solo la licencia

El botón de renovación debe continuar la misma licencia, no crear otra nueva. El importe vigente figura siempre en xabia.ai/precio. Si la fecha sigue vieja después de esperar un rato y de Actualizar saldo, abra incidente de soporte con el comprobante de pago.

13.4 Aviso de saldo bajo

Si el saldo baja de orden de las decenas de miles de tokens, puede ver un mensaje destacado recordándole revisar Wallet antes de que el público encuentre cortes por falta de créditos.

15. Pantalla Addons

Cuadrícula de complementos de pago (Avirato, Central, MEC, Woo… según instalación): estado, enlaces a Plugins y, para los que usan suscripción vía Hub, un formulario de licencia propio del addon (no sustituye a la licencia Xabia del sitio de la pantalla principal). Smart QR / tótems no aparece aquí: está integrado en el Core (pestaña del agente).

• Tienda: enlace habitual a polar.sh/digixop.
• Portal del cliente (gestionar suscripción): polar.sh/digixop/portal.
• Si un addon con licencia no valida o la suscripción está a punto de caducar, el aviso aparece aquí; en el chat público de addons como Avirato el visitante recibe mensajes genéricos de contacto, no errores técnicos de licencia.

El ZIP del instalador y el contrato siguen llegando por el canal comercial o el correo habitual de Xabia.

16. Orden práctico para no perderse

1. Modalidad Cloud vs infra propia, licencia y saldo (pantalla principal).
2. Crear agente — nombre identificativo y copiar shortcode.
3. Elegir fuente de datos — mapear con calma; pruebas en staging si existe.
4. Sincronizar datos → revisar barra lateral → si usa búsqueda inteligente, Entrenar.
5. Ajustar Apariencia (perfil de presentación) y Comportamiento IA → probar Playground → publicar → vigilar gasto en Wallet.

17. Problemas frecuentes (qué revisar antes de escribir a soporte)

18. Preguntas frecuentes

¿Tengo que sincronizar para que liste empresas al instante?

No para listados nativos y seguimientos de contacto/imagen (Core ≥ 1.0.118): el Core consulta WordPress en vivo según su mapeo. Sí si quiere RAG vectorial para preguntas abiertas sobre el catálogo.

¿Cuántos agentes puedo crear con una licencia?

En el uso típico retail, uno o varios agentes en el mismo dominio están incluidos sin coste extra por agente. Confirme siempre los límites exactos en su correo de bienvenida, en la página de precios oficial o con su comercial si el proyecto es grande.

¿Qué es exactamente un “token”?

Es la unidad con la que se mide cuánto trabajo de lenguaje ocupa una conversación (texto que entra más texto que sale cuando se usa el modelo). El entrenamiento de la memoria inteligente también consume tokens. Cuando la respuesta viene de una plantilla fija (sin modelo), muchas veces no gasta ninguno.

¿Tengo que pegar mi clave de OpenAI si uso Xabia Cloud?

Por lo general no. Con Cloud y licencia con saldo el tráfico habitual va por Xabia. La clave OpenAI entra en juego sobre todo en Infraestructura propia.

¿Por qué “no recuerda” mis tablas o PDF si los tengo en el servidor?

Debe incorporar ese conocimiento con Sincronizar (y Entrenar si activó búsqueda por similitudes). Los addons que aportan datos en vivo (reservas, etc.) son un canal aparte que no sustituye ese paso si usted quiere que el asistente cite su documentación.

¿Puedo usar copia de pruebas (staging) con la misma licencia que producción?

Depende de condiciones contractuales: dos direcciones públicas distintas a veces cuentan como dos instalaciones. Pregunte antes de mover tráfico real.

¿Si elimino la licencia se borran mis agentes?

No desaparecen de la lista ni su configuración borrada automáticamente, pero el chat dejará de funcionar bien en Cloud hasta que pegue otra licencia válida.

¿Hay saldo en la cartera pero el visitante ve “modo mantenimiento”?

Mire en Comportamiento IA el tope diario de tokens por agente. La barra lateral Tokens hoy muestra si ya alcanzó ese techo para el día técnico en curso; al día siguiente ese contador vuelve a cero para el agente, aunque su cartera global siga teniendo saldo disponible para otros agentes u otros días.

Notas de versión (Core)

Core v1.0.291 (agosto 2026)

• Publicación de manuales: mapa visual de shortcodes en Apariencia (PDF/HTML) e índices ES/EN/EU.

Core v1.0.290 (agosto 2026)

• Manual de usuario: mapa visual de shortcodes en Apariencia (burbuja nativa, chat embebido, launcher/avatar, tótem/pantalla y /xabia-box/) y tabla de atributos.

Core v1.0.283 (agosto 2026)

• Playground: alt de imágenes [ACTION:IMG:…] → «Imagen de la entidad» (agnóstico; sustituye «Imagen del evento»).

Core v1.0.282 (agosto 2026)

• RAG Cloud: el Hub aplica expansiones de palabras clave del agente en la búsqueda léxica.
• Recorte de contexto: prioriza fichas que coinciden con esos sinónimos (p. ej. pregunta «caballo» y ficha etiquetada «hípica»).

Core v1.0.281 (agosto 2026)

• RAG: densifica y trocea fichas del Hub antes del límite de caracteres; evita que un recorte UTF-8 inválido vacíe el contexto y el asistente diga que «no hay resultados».

Core v1.0.280 (agosto 2026)

• RAG: enrutador de intención de catálogo híbrido (regex + micro-LLM CATALOG/GENERAL) sin diccionarios de dominio.

Core v1.0.208 (agosto 2026)

• Actualizaciones: corrige el aviso en Plugins cuando WordPress aún no había creado el transient update_plugins.
• Actualizaciones: revalidación del Hub cada 5 minutos si la caché local coincide con la versión instalada.

Core v1.0.207 (agosto 2026)

• Actualizaciones automáticas también en modo LITE (sin licencia PRO activa).
• Panel de versión en el admin LITE con «Comprobar ahora».

Core v1.0.206 (agosto 2026)

• Checkout Polar: enlaces «Contratar suscripción» envían domain y license_key al Hub.
• Addons: badge «Hub Polar» debajo del título del panel.

Core v1.0.205 (agosto 2026)

• Retail: si Core arranca sin licencia (UI limitada), permite pegar la licencia Xabia y activar PRO sin WP-CLI.

Core v1.0.202 (agosto 2026)

• Acciones de chat: imágenes relativas en [ACTION:IMG:…]; fallback de reserva Amelia; reglas estrictas MEC remoto ([ACTION:URL:Link] únicamente).
• Monorepo alineado con producción: API completa y addons Woo/MEC/Avirato.

Core v1.0.201 (agosto 2026)

• Chat: Markdown básico en respuestas; UI stream sin burbujas; avatar parlante / launcher; preguntas de arranque; empaquetado completo del ZIP.

Core v1.0.168–1.0.171

• Latencia chat, Document-to-RAG, pasaporte remoto, listados, WPML/DTP (ver historial técnico en DESARROLLO.md).