Configurar el agente

Todo lo de esta página se hace en el panel, antes de escribir una línea de integración. Aquí está solo lo que afecta a cómo se comporta el agente de cara a tu integración.

Identidad y prompt

El identifier es el slug con el que lo vas a llamar desde el widget, el SDK o la API. Su id (UUID) también sirve en cualquier sitio donde se pida el agente, y a diferencia del slug no cambia nunca — si el nombre puede cambiar, usa el id.

El prompt de sistema admite dos modos:

• Simple — un único bloque de texto libre.
• Avanzado — secciones separadas (identidad, tono, qué hacer, qué no hacer, estilo de respuesta) que ur compone. Más fácil de mantener y de revisar a cuatro manos.

Las respuestas vienen en Markdown

A todos los prompts se les añade un bloque de formato que le pide al modelo que responda en Markdown. El widget lo renderiza; si montas tu propia UI con el SDK, te toca a ti renderizarlo (los ejemplos lo hacen con marked + DOMPurify).

Áreas de conocimiento

Fragmentos de texto que se inyectan en el prompt, pensados para datos cortos y estables: horarios, políticas de devolución, tarifas. Cada una tiene un extracto y un contenido, y se puede activar o desactivar sin borrarla.

Para volúmenes grandes de documentación no uses esto: usa un RAG.

Modelo

El modelo que responde, elegido entre los que hayas dado de alta en el panel. Junto a él hay tres ajustes de resiliencia, independientes entre sí:

Ajuste	Por defecto	Qué hace
Timeout de petición	120 000 ms	Tiempo de inactividad, no de duración total: se reinicia con cada token que llega. Una respuesta larga y sana nunca se corta por esto.
Modelo de reserva	—	Un reintento contra un segundo modelo si el principal falla.
Resumen automático	Desactivado	Cuando un hilo pasa de N mensajes, se escribe un resumen acumulado y a partir de ahí solo se envía desde ese punto.

El modelo de reserva pierde bloques no portables

En ese reintento los mensajes se sanean a una forma portable, porque unos proveedores rechazan los bloques de otros. Se pierden los bloques de razonamiento y los multimodales de ese turno. Es el precio de que el fallback funcione entre proveedores distintos.

El resumen aparece en el historial como un mensaje más, así que si montas tu propia UI lo verás llegar en loadHistory().

Documentos (RAG)

Para que el agente consulte tus documentos, se le vincula una instancia de la tool rag_retrieve. No es un ajuste del agente: es una tool.

Una instancia de rag_retrieve apunta a uno o varios RAGs y expone cinco funciones al modelo: buscar fragmentos, listar rutas, listar etiquetas, procesar un fichero entero y obtener un enlace. Su configuración incluye la estrategia de búsqueda, cuántos fragmentos recuperar, el umbral de similitud y si aplica reranking.

El reranking degrada en silencio

Si activas reranking pero el RAG no tiene un modelo reranker configurado, no falla: simplemente devuelve los primeros resultados sin reordenar. La recuperación nunca lanza un error — si algo va mal (timeout, la clave del reranker agotada), devuelve lo que puede y marca la degradación.

Tools

Recuerda la distinción de Conceptos: las plantillas son el código y solo se activan o desactivan; las instancias son una plantilla configurada y con nombre propio, y son lo que se vincula al agente.

Lo que el modelo ve de cada instancia es su nombre y su descripción — nada más. Esos dos campos son, en la práctica, parte del prompt: si el agente no llama a una tool cuando debería, suele ser la descripción, no el prompt de sistema.

El nombre debe cumplir ^[a-zA-Z0-9_]{1,64}$, y es además la clave con la que se le pasa el contexto de cliente.

Misma tool, otros parámetros = otra instancia

La configuración vive en la instancia. Si quieres buscar en los mismos RAGs con un topK distinto o sin reranking, no puedes "parametrizarlo al vuelo": creas una segunda instancia con otro nombre y se la vinculas también.

Mensaje automático

Un texto que el agente envía como si lo hubiera escrito él, una sola vez por conversación (un aviso legal, una bienvenida). Se entrega antes que cualquier token de la primera respuesta.

Cómo te llega según la vía:

• Widget — se pinta solo.
• SDK — por el callback onNotice. Si no te suscribes no se pierde: vuelve en loadHistory() marcado con isAutoMessage: true.
• HTTP — en el campo notice de la respuesta.

Si lo activas y dejas el texto vacío, no se envía nada y guardar no falla.

Lo que sigue

• Habilitar el canal y restringir los dominios → Canales.
• Límites de abuso y filtros de contenido → Seguridad y límites.
• Integrarlo → Widget o SDK.