@nykk/ur-agent-client

SDK headless, sin dependencias de runtime, para construir clientes de chat contra un agente de ur. No renderiza nada: habla por SSE con el backend (POST /embed/:agent/chat, GET /embed/:agent/history) y entrega los eventos en bruto. Opcionalmente, createChatStore() monta encima un pequeño store framework-agnóstico con la lista de mensajes ya acumulada.

Funciona en cualquier framework, o en ninguno. Solo usa fetch, crypto.randomUUID, localStorage y AbortController.

Instalación

npm install @nykk/ur-agent-client

Paquete público en npmjs. No requiere ningún registro privado.

Uso mínimo

import { UrAgentClient } from '@nykk/ur-agent-client';

const client = new UrAgentClient({
  agent: '<identifier-del-agente>',
  apiBase: '<origen-de-tu-backend-ur>',
});

client.onToken((delta) => {
  /* añade `delta` al mensaje del bot que estás construyendo */
});
client.onDone((threadId) => {
  /* el turno ha terminado */
});
client.onError((message) => {
  /* muestra el error */
});

await client.sendMessage('Hola');

El agente tiene que tener habilitado el canal js_sdk en el admin de ur (en el panel se llama Integración a medida con tu propia interfaz). Es el canal de cualquier UI propia hecha sobre esta SDK, también un widget a medida: el canal widget es el de @nykk/ur-agent-widget.

Título y colores

El título y los colores de marca que se configuran en el admin para ese canal se piden con getConfig(). Cada canal tiene los suyos, así que no depende de que el widget esté activado.

const { style, title } = await client.getConfig().catch(() => ({ style: {}, title: undefined }));
// style.color, style.colorText, style.colorBot: '#rrggbb' o ausentes

Todo es opcional: lo que no venga, lo pones tú. Es cosmético, así que si falla (un 404 es el canal apagado) lo normal es seguir con tu paleta.

Contexto para las tools del agente

Tu aplicación puede enviar datos en cada mensaje, agrupados por tool:

const client = new UrAgentClient({
  agent: 'soporte',
  context: { visitor_context: { page: '/precios' } },
});

// Se actualiza sin recrear el cliente (recrearlo perdería la conversación):
client.setContext({ visitor_context: { page: '/contacto' } });

Qué claves acepta un agente lo declaran sus tools; el admin de ur muestra el snippet exacto para cada agente. Las claves que ninguna tool declare se descartan sin fallar, y vuelven listadas en la cabecera X-Ur-Context-Dropped.

No es una credencial. El canal público no lleva autenticación, así que cualquiera puede falsificar estos valores. Sirven para indicar qué mirar, nunca para decidir qué puede ver quien pregunta.

Con store incluido

import { UrAgentClient, createChatStore } from '@nykk/ur-agent-client';

const client = new UrAgentClient({ agent: '<identifier>', apiBase: '<origen>' });
const store = createChatStore(client);

store.subscribe(() => render(store.getState().messages));
if (!client.isNewSubject) {
  await store.loadHistory();
}
await store.send('Hola');

store.subscribe/store.getState encajan directamente en useSyncExternalStore (React) o en un signal de Angular.

Relación con @nykk/ur-agent-widget

El Web Component <ur-agent-chat> de @nykk/ur-agent-widget usa esta misma SDK por debajo. Si el widget no encaja con tu stack, esta es la pieza que habla con el backend y el resto lo decides tú.

Licencia

MIT