Tema
Conceptos
Los siete términos que aparecen en el resto de la documentación.
Agente
Una conversación con memoria. Tiene un prompt de sistema, un modelo, opcionalmente un conjunto de tools y de áreas de conocimiento, y recuerda lo hablado con cada usuario.
Es lo que embebes en tu producto como chat. Se identifica por un identifier (un slug legible, p. ej. soporte, que se regenera si renombras el agente) y por su id (un UUID inmutable). Cuál vale depende de la vía: en el widget y el SDK (/embed/*), cualquiera de los dos —y el snippet del panel trae el id, que es el que conviene—; en GET /api/agents/{identifier}, solo el identifier; en las tools del MCP, solo el id.
→ Configurar el agente · Integrar un agente
Inferencia
Una llamada suelta y sin estado: entra un prompt, sale una respuesta. No recuerda nada entre llamadas y no conversa.
Se configura en el panel (prompt de sistema, modelo, RAGs y tools vinculadas) y se ejecuta desde tu backend con POST /api/inferences/{identifier}. Es la herramienta para clasificar, extraer, resumir o generar JSON estructurado.
RAG
Un conjunto de documentos indexados sobre el que se puede buscar por significado en vez de por palabra exacta. Retrieval-Augmented Generation: se recuperan los fragmentos relevantes y se le pasan al modelo como contexto.
Un RAG se alimenta de una file source y se asocia a agentes (vía la tool rag_retrieve) o a inferencias.
File source
El origen de los documentos de un RAG: un directorio del sistema de ficheros, una carpeta de Google Drive, una biblioteca de SharePoint o un OneDrive (sharepoint), o un sitio web rastreado. ur lo escanea periódicamente, extrae el texto e indexa los fragmentos.
Tiene su propio estado de sincronización, y puedes consultar si un fichero concreto llegó a indexarse.
Tool
Una función que el modelo puede decidir invocar durante un turno (function calling). ur distingue dos niveles:
- Plantilla — el código de la tool. Viene con el producto y solo se puede activar o desactivar.
- Instancia — una plantilla ya configurada y con nombre propio. Es lo que se vincula a un agente o a una inferencia.
La consecuencia práctica: la configuración vive en la instancia, así que si quieres los mismos documentos con otros parámetros, creas una segunda instancia con otro nombre.
Las que vienen de serie son calculator, datetime (fecha y hora actuales, el día que cae «dentro de 5 días» y el día de la semana de una fecha y cuánto falta para ella, en la zona horaria que se pida o en la de la instalación), rag_retrieve (buscar en tus RAGs), http_request (llamar a cualquier API HTTP, ver Tool de petición HTTP), openapi (una API entera desde su spec, ver Tool OpenAPI) y web_search (buscar en internet, ver Tool de búsqueda web).
Canal
Por dónde entra una conversación a un agente. Hay dos canales configurables, creados automáticamente con el agente y que solo se editan, nunca se crean ni se borran:
widget— el chat flotante embebido con<script>. En el panel: Chat embebible en cualquier web.js_sdk— tu propia UI, construida con el SDK. En el panel: Integración a medida con tu propia interfaz.
Ojo con los identificadores: widget y js_sdk salen en la URL, en el filtro de canal del listado de conversaciones y en esta documentación, pero la ficha del agente no los muestra — allí cada canal se reconoce por ese nombre y por el paquete npm que aparece debajo.
Cada uno se habilita y se restringe por origen de forma independiente, y el widget tiene además su apariencia (título y colores): con el SDK, la interfaz y su aspecto son tuyos. Además, las conversaciones de un canal y otro son hilos separados, aunque sea el mismo usuario.
Hay además una vía que no se configura y que lleva su hilo aparte: demo (el botón Probar agente del panel, que solo responde con una sesión del panel abierta y con acceso al agente).
→ Canales
Subject e hilo
El subjectId es la identidad de conversación: quién está hablando, desde el punto de vista del agente. En el widget y el SDK lo genera el propio navegador y se guarda en localStorage.
El hilo es la conversación en sí, y se identifica por la terna (agente, subjectId, canal). De ahí que el mismo subjectId en widget y en js_sdk sean dos conversaciones distintas.
Salvo que el agente identifique a su usuario, en el widget y el SDK nadie se autentica, así que conocer un subjectId basta para leer esa conversación y seguir escribiendo en ella. Si lo fijas tú en vez de dejar que lo genere el navegador, que sea imposible de adivinar (un UUID aleatorio), nunca el id o el email de tu usuario. Con un usuario identificado, el hilo es además de ese usuario: otro con el mismo subjectId cae en otra conversación.
Empezar de cero equivale a generar un subjectId nuevo.