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.

Crear el agente y su resumen

En Agentes → Nuevo agente se piden tres cosas: el nombre, el modelo y unas líneas de instrucciones (el prompt, en modo simple). Al crearlo llegas a su resumen, la primera sección de la ficha, con una lista de lo que tiene configurado y lo que le falta: las tools y los canales, sobre todo; seguridad, mensajes y áreas de conocimiento van con los valores de la instalación mientras no los cambies. La misma lista avisa de lo que conviene revisar, como una tool que consulta un RAG que ya no existe o un canal abierto a cualquier web. Cada sección acaba en Siguiente, que lleva a la de debajo.

Los cambios se guardan con Guardar, en la barra que aparece abajo en cuanto cambias algo; te quedas en la misma sección.

Identidad y prompt

El panel muestra, bajo el nombre, el Identificador del agente: un slug derivado del nombre que se regenera cada vez que lo renombras. El agente tiene además un id (UUID) que no cambia nunca.

Cuál usar depende de la vía:

• Widget y SDK (/embed/*) — valen los dos, y el snippet que te da el panel ya trae el id. Usa ese: si alguien renombra el agente, el identifier cambia y tu integración empieza a recibir 404.
• La API (GET /api/agents/…) — aquí solo se resuelve por identifier; un UUID devuelve 404.

El prompt de sistema admite dos modos:

• Simple — un único bloque de texto libre.
• Avanzado — secciones separadas (Identidad, Tono y estilo, Qué hacer, Qué no hacer, Cómo responder) que ur compone, cada una bajo su propio título. Más fácil de mantener y de revisar a cuatro manos.

La fecha y la hora

El prompt puede llevar la fecha y la hora en que empezó la conversación:

Placeholder	Sale como	Qué es
{{now}} (o {{now.utc}})	2026-11-05	La fecha, en UTC
{{time}} (o {{time.utc}})	09:15	La hora, en UTC y en 24 h
{{now.Europe/Madrid}}	2026-11-05	La fecha en esa zona horaria
{{time.Europe/Madrid}}	10:15	La hora en esa zona horaria

Juntos dan la fecha completa:

La conversación empezó el {{now.Europe/Madrid}} a las {{time.Europe/Madrid}} (hora de Madrid).
Si el usuario dice «mañana», cuenta desde esa fecha.

• Son las del primer mensaje, no las de cada turno. No cambian mientras dura la conversación, aunque se retome al día siguiente. Por eso conviene decírselo así al modelo, «la conversación empezó el…», y no «hoy es…» ni «son las…». Lo hace así para que el prompt sea el mismo en todos los turnos y el proveedor lo pueda seguir cacheando.
• Las zonas horarias. Sin zona van en UTC, la hora universal: la de la España peninsular es una hora más en invierno y dos en verano. Con una zona salen en la hora local de ese sitio, con el cambio de hora ya aplicado. La zona se escribe con su nombre IANA, Región/Ciudad: Europe/Madrid, Atlantic/Canary, America/Mexico_City… Cerca de la medianoche, la fecha también puede cambiar de una zona a otra.
• La hora, mejor al final del prompt. Cambia con cada conversación, y el proveedor solo comparte entre conversaciones la parte del prompt que va antes de ella. Con la caché de Anthropic, ur corta el prompt justo antes de la línea de la primera hora: lo de antes se lee de la caché en todas las conversaciones; lo de detrás, solo a partir del segundo turno de cada una. La fecha da igual dónde vaya: cambia una vez al día.
• Dónde vale. En los dos modos del prompt, en el formato de respuesta y en las instrucciones por audiencia de Autenticación.
• Mal escrita no se guarda. {{now}, {now}, {{TIME}} o una zona que no existe ({{now.Europe/Madird}}): el panel lo avisa junto al campo y la API contesta 400. Un {time} con una sola llave se manda tal cual.
• La vista previa del prompt las enseña ya cambiadas, con las de ahora: ahí no hay conversación.

Las respuestas vienen en Markdown

A todos los prompts se les añade detrás 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).

Ese bloque es el Formato de respuesta, en la sección Prompt, debajo del prompt. Hereda el de Ajustes del sistema → Prompts, o el agente tiene el suyo: por ejemplo, texto plano para un agente que se escucha por voz. Admite y , como el prompt. Un agente con salida estructurada (JSON) no lo recibe.

Ver prompt final, en la sección Prompt, enseña el prompt entero que recibe el modelo, bloque a bloque: el del agente, las áreas de conocimiento, el formato de respuesta y, con usuario final, sus instrucciones. Los que añade ur dicen de dónde salen: Fábrica, Sistema (la versión de Ajustes del sistema → Prompts) o Propio del agente. Arriba, cuántos tokens son y lo que cuestan con el modelo elegido, también con el borrador sin guardar.

Áreas de conocimiento

Bloques de conocimiento propios del agente, pensados para datos cortos y estables: horarios, políticas de devolución, tarifas. Cada una tiene un extracto (un resumen de una línea) y un contenido, y se puede activar o desactivar sin borrarla.

Solo el extracto viaja en el prompt, como una lista de las áreas disponibles. El contenido lo carga el agente bajo demanda, con una tool interna (load_knowledge_area) que se activa sola en cuanto hay un área activada — no hay que vincularla. La verás en Probar agente y en las conversaciones del panel cuando el agente tire de un área; por el widget y el SDK no llega ninguna señal.

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. Cada modelo sale una vez por cada clave del proveedor que lo sirve, con el nombre de la clave al lado. Si hay dos claves o más, encima de la lista hay una pastilla por clave: al elegir una quedan solo sus modelos. Pasa igual al crear el agente y en la sección Modelo LLM.

En la ficha del agente, sección Modelo LLM, junto al modelo hay cuatro ajustes, independientes entre sí:

Ajuste	Por defecto	Qué hace
Timeout de la petición (ms)	120 000	Tiempo sin recibir nada del modelo, no de duración total: cuenta hasta el primer token de la respuesta y, después, entre un token y el siguiente. Una respuesta larga que sigue llegando no se corta, ni en el widget ni en el SDK; un modelo que tarda más que esto en empezar a contestar (uno que razona en silencio, por ejemplo), sí. Al agotarse entra el fallback, si está activado. También acota la llamada que escribe el resumen.
Máximo de tokens de salida	El recomendado para el modelo elegido	Lo más que puede generar el modelo en cada llamada. Debajo del campo se ve el valor recomendado para el modelo principal, con un botón Usar: 8 192 en los modelos que no piensan y 16 384 o 32 768 en los que piensan. Un agente nuevo nace con el del modelo que elijas al crearlo; después, cambiar de modelo no lo cambia. Al llegarle, la respuesta se corta a media frase, sin error ni aviso; en los modelos de razonamiento el pensamiento cuenta dentro, así que un tope bajo puede dejarla vacía. Vale también para el modelo de fallback. Cuando se conoce el máximo del modelo, no puede pasarlo (el panel lo rechaza diciendo cuál es) y en el fallback se ajusta al suyo; cuando no se conoce, el panel acepta hasta 1 000 000 y se manda tal cual, así que un valor por encima del máximo real del modelo puede hacer fallar todas sus llamadas. Vacío, cada proveedor usa su valor por defecto; en los modelos de Anthropic, el máximo del modelo si se conoce (si no, el de por defecto: 16 384 en claude-opus-5-5 y claude-fable-5-1). No acota el resumen.
Usar modelo de fallback	Desactivado	Un reintento contra un segundo modelo (Modelo de fallback) si el principal falla.
Resumir conversaciones largas	Desactivado	Al llegar a N mensajes desde el último resumen (30 por defecto, en «Nº de mensajes antes de resumir»), 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, marcado con isSummaryMarker: true: si montas tu propia UI lo verás llegar en loadHistory() y tienes que filtrarlo, o el usuario verá un resumen de su propia conversación como si se lo hubiera dicho el agente. Ver SDK — referencia.

Cuando la conversación ya no cabe en el modelo

Sin resumen, cada turno le envía al modelo la conversación entera, y un hilo largo acaba por no caber en su ventana de contexto. Lo que pasa entonces depende del proveedor del modelo:

• Anthropic u OpenAI (y un servidor openai-compatible, vLLM por ejemplo, cuyo error diga, como el de OpenAI, context_length_exceeded o maximum context length): la llamada que el proveedor rechaza se reintenta sin los intercambios más antiguos (el mensaje en curso siempre va entero). El agente contesta, pero sin ver lo más antiguo, y la respuesta no lo indica de ninguna forma. El historial (loadHistory() y el del panel) sigue completo. Mientras el hilo no quepa, cada llamada al modelo se rechaza antes de reintentarse, así que cada turno tarda algo más.
• Google o Mistral: el turno falla, y con él todos los siguientes de ese hilo, salvo que lo salve el modelo de fallback: el mensaje de error del catálogo en el widget y el SDK. Con Mistral puede llegar además como si el proveedor estuviera saturado.

Si tus conversaciones son largas, activa Resumir conversaciones largas con su Modelo de resumen: es lo que mantiene el hilo dentro de la ventana.

Documentos (RAG)

Para que el agente consulte tus documentos, se le vincula una instancia de la plantilla RAG retrieve (rag_retrieve es su identificador técnico, el que verás en la API). 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 sigue adelante.

Por el canal del agente —widget o SDK— no llega ninguna señal que puedas leer desde tu código: el campo degraded que sí existe en inferencias y en RAGs no aparece aquí. Si la búsqueda no ha podido ejecutarse y no hay ningún fragmento, el agente lo avisa por su cuenta en la respuesta, en vez de afirmar que la información no existe.

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 — nunca su configuración. 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.

En una plantilla de una sola función (la calculadora, por ejemplo) tu descripción sustituye a la que trae la plantilla. En una multifunción como RAG retrieve se añade a la descripción técnica de cada función, y el modelo ve un nombre por función: {nombre}, {nombre}_list_paths, {nombre}_list_tags, {nombre}_process_file y {nombre}_get_link.

El nombre debe cumplir ^[a-zA-Z0-9_]{1,64}$, y en una plantilla multifunción hay que dejar sitio para los sufijos de sus funciones (en RAG retrieve el más largo es _process_file, así que el nombre no puede pasar de 51 caracteres). Es además la clave con la que se le pasa el contexto de cliente.

Para conectar el agente con una API propia o de terceros sin escribir código está la plantilla http_request: ver Tool de petición HTTP. Si la API publica un spec OpenAPI, la plantilla openapi la importa entera, una función por operación: ver Tool OpenAPI. Para que busque en internet, con el buscador de Anthropic, Google, OpenAI o Tavily, está web_search: ver Tool de búsqueda web.

Si el agente identifica a su usuario, cada tool vinculada se puede marcar Solo usuarios identificados: en una conversación anónima el modelo no la ve. Ver Modo parcial.

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.

Autenticación

Quién puede hablar con el agente: cualquiera (Abierto, por defecto), anónimos y usuarios identificados (Parcial) o solo usuarios identificados (Obligatorio). Para las dos últimas, tu aplicación firma un token para cada usuario y el agente lo verifica con un Emisor de los tokens que da de alta un administrador. Puedes añadir además instrucciones para los identificados, con sus datos (su nombre, su email, cualquier claim del token), y en Parcial otras para los anónimos. Todo, en Usuarios identificados.

Mensaje automático

Un texto que el agente envía como si lo hubiera escrito él, una sola vez por conversación y como su primer mensaje (una bienvenida, un aviso legal).

Cuándo sale depende de la vía:

• Widget — al desplegar el chat, antes de que el visitante escriba: el agente habla primero. Se pinta solo.
• SDK — igual, cuando tu UI llama a start() al enseñar el chat; llega por el callback onNotice (ver Que el agente hable primero). Si tu integración no llama a start(), llega con la primera respuesta, antes de cualquier token. Si no te suscribes a onNotice no se pierde: vuelve en loadHistory() marcado con isAutoMessage: true.
• Chat de pruebas del panel — al abrirlo vacío y en cada conversación nueva, como en el widget.

Quien abre el chat y no escribe se queda con una conversación que solo tiene la bienvenida. No cuenta en el dashboard ni sale en el listado de Conversaciones, salvo que marques Incluir chats sin mensajes.

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

En varios idiomas

El mensaje puede tener una versión por idioma: cada visitante recibe la suya, y la conversación guarda la que vio. En la sección Mensajes hay una pestaña por idioma:

• La de por defecto lleva la marca «Por defecto», y su texto sale siempre arriba como «Saludo por defecto». Es el que recibe quien no tiene ninguno de los otros idiomas, y no se puede quitar: para quitarlo, antes marca otro con Usar por defecto.
• + Añadir crea un idioma nuevo. Se elige de un desplegable, con los habituales arriba; para una variante (es-MX, pt-BR) está Otro código. Una vez guardado, el idioma de una pestaña ya no se cambia, solo su texto: para otro idioma, quita la pestaña y añade una nueva.
• Ver todos enseña la lista entera en una tabla.
• Como mucho, 20 idiomas además del de por defecto.

Indica el idioma del texto por defecto. Si no, ese texto solo es el de reserva: un navegador configurado con es-ES, es, en recibiría la versión inglesa antes que la castellana. Los agentes de antes de los idiomas lo tienen «Sin indicar», y se puede elegir una vez.

Cómo se elige la versión:

1. Los idiomas que manda el chat: el lang del widget (o data-lang), la opción locale del SDK o, sin ninguno, los del navegador.
2. Si no, la cabecera Accept-Language del navegador.
3. Para cada idioma, en orden, primero el código exacto y luego el idioma base: quien pide eu-ES recibe el de eu. Una variante (es-MX) solo la recibe quien la pide tal cual, así que, si la añades, conviene tener también el idioma base.
4. Si no coincide ninguno, el texto por defecto. Es también lo que recibe un canal que no sabe el idioma del visitante.

En Probar agente, si el agente tiene otros idiomas, un selector en la cabecera elige con qué idioma se prueba: «Navegador» manda los tuyos, como un visitante, y cada idioma del agente manda solo el suyo. Cambiarlo abre una conversación nueva, porque la bienvenida solo sale en una vacía.

Límite de conversación

En la sección Seguridad de la ficha puedes acotar cuántos mensajes contesta el agente en una misma conversación y cuántas horas sin actividad tarda el navegador en olvidarla. Al agotarse los turnos, el usuario recibe la última respuesta, el mensaje Límite de conversación del catálogo, y la caja de texto se cierra. Los detalles, en Seguridad y límites.

Cuándo surten efecto los cambios

La resolución del agente y el contrato de contexto se cachean, así que lo que toques en el panel —renombrar un agente, habilitar un canal, vincular una tool— tarda hasta 30 segundos en verse en /embed/*. Si acabas de cambiar algo y no lo ves reflejado, dale ese margen antes de buscar el fallo en otro sitio.

Un caso tarda algo más: si cambias la configuración de una instancia de tool (desde la página Tools — el topK, el umbral, el reranking), el agente sigue ejecutándola con los valores anteriores hasta un minuto. Lo que tocas en la ficha del propio agente entra antes.

Lo que sigue

• Habilitar el canal y restringir los dominios → Canales.
• Límites de abuso y filtros de contenido → Seguridad y límites.
• Saber quién es el usuario de tu aplicación → Usuarios identificados.
• Integrarlo → Widget o SDK.