Limitaciones

Qué no hace todavía la integración de agentes. Conviene leerlo antes de diseñar encima.

No hay autenticación de ningún tipo

No existe una API key, un token de sesión, ni nada parecido en el canal público. Un <script> de terceros o un SDK en el navegador no puede guardar un secreto de forma segura, así que el modelo de confianza de /embed/* es distinto al de /api/* (que sí usa Bearer): la identidad de conversación es un subjectId generado por el propio navegador, y el freno real al abuso son los límites por IP y por agente.

La lista de orígenes permitidos del canal no cierra este hueco: evita el copia-pega en un sitio ajeno, pero un cliente que no sea un navegador puede omitir o falsificar la cabecera Origin.

Si necesitas invocar recursos que sí requieren autenticación real, la vía es la API con un access token, pensada para integraciones servidor a servidor.

getAuthHeaders existe, pero no hace nada todavía

UrAgentClientOptions.getAuthHeaders es un punto de extensión reservado: sus cabeceras viajan y el backend deja la cabecera X-Widget-Auth disponible internamente, pero nada la lee todavía. Está ahí para no romper la firma pública de UrAgentClientOptions cuando llegue esa fase.

No la presentes como funcional en lo que construyas.

Fase futura relacionada, no implementada aún:

• OAuth por usuario final — cada usuario autoriza su propia cuenta (ej. Google Calendar) para que las tools del agente actúen en su nombre. Es la fase que getAuthHeaders anticipa.

El contexto de cliente no es de fiar, por diseño

context llega a las tools, pero el canal público no tiene autenticación de ningún tipo: cualquiera puede enviar los valores que quiera con un curl. Sirve para decirle al agente qué mirar (un id de pedido, la página actual), nunca qué puede ver quien pregunta. Una tool que busque algo con un valor del contexto tiene que cruzarlo con una identidad verificada por tu propio backend; el contexto por sí solo no autoriza nada.

onToolEvent / onUsage solo disparan en el canal demo

Son afordancias internas del "Probar agente" del panel. Un embed público (widget/js_sdk) nunca recibe esos frames — el backend no revela qué tools usa un agente ni su coste a un integrador externo. Si los registras en una integración real, simplemente nunca se disparan; no es un fallo.

Sin motor de reintentos/backoff propio

sendMessage()/loadHistory() fallan en el primer error de red — no hay reintento automático. Si lo necesitas, envuélvelo tú (por ejemplo, en el nivel del framework que estés usando).

Un bloqueo no se distingue de una respuesta

Por el canal público, un mensaje parado por un filtro de seguridad llega como un turno normal: tokens y fin. Es deliberado —no darle a quien sondea un mapa de los filtros—, pero significa que tu UI no puede reaccionar distinto. La única vía donde se distingue es HTTP, por el campo security.

Los cambios de configuración tardan hasta 30 segundos

La resolución del agente y el contrato de contexto se cachean. Renombrar un agente, habilitar un canal o vincular una tool puede tardar medio minuto en reflejarse en /embed/*.