SDK — quickstart

@nykk/ur-agent-client es un SDK headless, sin dependencias de runtime: no renderiza nada. Habla por SSE con el backend y te entrega los eventos; la UI la pones tú, en el framework que quieras o en ninguno.

Es la misma pieza que usa por debajo el widget. Si el widget no encaja con tu stack —necesitas tu propio diseño, o integrarlo en una pantalla que ya existe— esto es lo que habla con el backend.

1. Instala el paquete

npm install @nykk/ur-agent-client

Cero dependencias de runtime — usa solo fetch, crypto.randomUUID, localStorage y AbortController, todas ya disponibles en cualquier navegador moderno.

Es un paquete público en npmjs: no necesitas .npmrc ni token para instalarlo. Si tu proyecto ya mapea el scope @nykk a un registro privado, lo recibirás de ahí igualmente; es el mismo paquete.

2. Necesitas el identifier de un agente

En el panel, abre el agente que quieras exponer y copia su identifier (o su id). El canal js_sdk de ese agente tiene que estar habilitado — lo está por defecto al crear el agente, salvo que alguien lo haya deshabilitado. Ver Canales.

3. El snippet canónico

Este es exactamente el snippet que el propio panel muestra al configurar un canal js_sdk:

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.onNotice((text) => {
  /* mensaje automático único, ej. un aviso legal — ver la referencia */
});
client.onDone((threadId) => {
  /* el turno ha terminado */
});
client.onError((message) => {
  /* muéstralo como error */
});

await client.sendMessage('Hola');

Esto es todo lo que necesita el widget oficial por debajo — el resto de su código es únicamente shadow DOM y renderizado.

4. Restaurar una conversación al recargar

if (!client.isNewSubject) {
  const history = await client.loadHistory();
  // history.messages: { role: 'user' | 'bot', content, time, isAutoMessage? }[]
}

isNewSubject es true solo la primera vez que este navegador habla con este agente (la identidad de conversación se persiste en localStorage) — no hay nada que restaurar en ese caso.

5. Empezar una conversación nueva

client.resetConversation(); // aborta cualquier envío en curso y crea una conversación nueva

6. Si no quieres gestionar tú el acumulado de mensajes

Todo lo anterior (burbuja del usuario, ir acumulando los onToken en la burbuja del bot en curso, etc.) es exactamente el trabajo que hace createChatStore. Ver la referencia y los dos ejemplos completos en Ejemplos.

Lo que sigue

• La superficie completa → SDK — referencia.
• Pasarle datos de tu app a las tools → Contexto de cliente.
• Qué no hace todavía → Limitaciones.
• Delegar la integración en un agente de IA → Integrar con un agente de IA.