Agentes

Un agente de ur es una conversación con memoria: mantiene el hilo con cada usuario, puede consultar tus documentos y ejecutar tools, y responde en streaming, token a token.

Esta sección cubre las dos mitades del trabajo: configurarlo en el panel y integrarlo en tu producto.

Elegir la vía de integración

Vía	Escribes UI	Streaming	Dónde corre	Guía
Widget	No	Sí	Navegador	Widget embebible
SDK	Sí, la tuya	Sí	Navegador	SDK — quickstart

En la práctica:

• Empieza por el widget. Es una etiqueta <script>, coge los colores que hayas configurado en el panel y no tienes que mantener nada. Si encaja, has terminado.
• Pasa al SDK cuando el widget no dé: necesitas tu propio diseño, integrarlo en una pantalla que ya existe, o controlar el ciclo de vida de la conversación. @nykk/ur-agent-client no renderiza nada — habla con el backend y te da los eventos.
• Si quien pregunta no es un navegador (un proceso batch, un webhook, un bot de mensajería), un agente no es la vía: desde un backend no se habla con él. Para «procesar esto y devolver una respuesta», usa una inferencia.

El widget usa el SDK por debajo (@nykk/ur-agent-widget está construido sobre @nykk/ur-agent-client) y ambos hablan con los mismos endpoints. Aun así son dos canales distintos: se activan, se restringen y se visten por separado, y sus conversaciones no se comparten. Un widget propio construido con el SDK va por el canal del SDK, no por el del widget → Canales.

Lo que hay que configurar antes

1. El agente: prompt, modelo, documentos y tools → Configurar el agente.
2. El canal por el que vas a entrar. En la ficha del agente, sección Canales, hay dos filas: «Chat embebible en cualquier web» (@nykk/ur-agent-widget, el canal widget) y «Integración a medida con tu propia interfaz» (@nykk/ur-agent-client, el canal js_sdk). Las dos vienen activadas y abiertas a cualquier web al crear el agente (su resumen lo avisa); ahí compruebas que siga activada la tuya y decides desde qué dominios se acepta → Canales.
3. Opcionalmente, los límites y filtros de contenido → Seguridad y límites.
4. Si el agente tiene que saber quién es el usuario de tu aplicación, un emisor de tokens y el modo de usuario del agente → Usuarios identificados.

Desde tu backend no se habla con un agente: la API solo dice qué agentes alcanza un access token y qué tools tiene cada uno.

Antes de integrar, dos avisos

Por defecto, el canal público es anónimo

/embed/* no lleva ningún secreto, a propósito: un <script> en el navegador no puede guardar uno. La identidad de conversación la genera el propio navegador, y la lista de orígenes permitidos no es autenticación: evita el copia-pega en un sitio ajeno, pero un cliente que no sea un navegador puede omitir o falsificar la cabecera Origin. El freno real al abuso es el rate limit por IP y los límites por agente.

Si el agente tiene que saber quién es tu usuario, tu backend firma para él un token corto y el navegador lo manda en cada petición → Usuarios identificados.

El contexto de cliente no autoriza nada

Si vas a pasarle datos de tu aplicación al agente (contexto de cliente), sirven para decir qué mirar, nunca qué puede ver quien pregunta. Cualquiera puede falsificarlos con un curl.