Documentación

SDK de inserción del widget

Controla el widget de chat de Agentkit desde el navegador, envía mensajes proactivos, aplica opciones de página y escucha eventos.

El SDK permite abrir, cerrar, reiniciar, configurar y observar la burbuja de chat de Agentkit. Solo está disponible con la inserción mediante script. La inserción con iframe no define window.agentkit.

Instalar la cola

Usa el fragmento de la página Canales de tu agente. La cola hace que las llamadas realizadas antes y después de cargar el script asíncrono se comporten igual.

<script>
  (function (w) {
    if (w.agentkit) return;
    var q = [];
    var agentkit = function () { q.push(arguments); };
    agentkit.q = q;
    w.agentkit = agentkit;
  })(window);
</script>
<script async data-chatbot="YOUR_CHATBOT_ID" src="https://YOUR_WIDGET_HOST/agentkit-chatbot.js"></script>

La inserción anterior de una sola etiqueta sigue funcionando. Añade la cola si llamas al SDK antes de que termine de cargar el bundle.

Controlar el widget y enviar mensajes

window.agentkit('open');
window.agentkit('close');
window.agentkit('open', { message: 'Can you help me choose a plan?' });

Con hideMessage, el mensaje proactivo no aparece en la conversación y el widget permanece cerrado hasta que el asistente empieza a responder.

window.agentkit('open', {
  message: 'Explain the current page in one sentence.',
  hideMessage: true,
});

El SDK rechaza mensajes vacíos, envíos simultáneos o limitados por frecuencia, y envíos cuando el campo está oculto o desactivado o hay un chat en vivo. close no finaliza un chat en vivo de Salesforce.

Enviar con el widget cerrado

Usa send para mostrar una interfaz de preguntas compacta en tu página y renderizar la respuesta fuera del widget. El mensaje se añade a la conversación normal sin abrir la presentación. Escucha el evento del asistente y llama a open después para continuar la misma conversación.

let pendingQuestion = null;
let questionAccepted = false;

function onUserMessage(event) {
  if (event.detail.content === pendingQuestion) questionAccepted = true;
}

function showAnswer(event) {
  if (!questionAccepted) return;
  document.querySelector('#answer').textContent = event.detail.content;
  pendingQuestion = null;
  questionAccepted = false;
}

window.agentkit('addEventListener', 'user-message', onUserMessage);
window.agentkit('addEventListener', 'assistant-message', showAnswer);

pendingQuestion = 'Do you offer a free plan?';
window.agentkit('send', { message: pendingQuestion });

// Later, from a “Continue in chat” control:
window.agentkit('open');

send usa las mismas comprobaciones, límites, persistencia y eventos que open({ message }). Solo cambia si se abre la presentación.

Center Stage

Center Stage abre el mismo agente como un diálogo centrado a pantalla completa sobre tu página en lugar de la burbuja de la esquina. Es un canal propio en la página Canales, con su propia visualización, voz, instrucciones y acciones, y permanece desactivado hasta que lo actives allí.

Instálalo con el mismo bootstrap y añade data-display="center-stage" a la etiqueta script. El atributo va junto a data-chatbot y data-locale:

<script async data-chatbot="YOUR_CHATBOT_ID" data-display="center-stage" src="https://YOUR_WIDGET_HOST/agentkit-chatbot.js"></script>

El lanzador sigue siendo la forma predeterminada de abrirlo, y cada llamada del SDK funciona igual: open muestra el diálogo, close lo cierra, y resetChat, setOptions, identify, los eventos y las herramientas del navegador se comportan exactamente como en la burbuja. El diálogo retiene el foco, se cierra con Escape o con su botón de cierre, devuelve el foco a lo que lo abrió y ocupa toda la pantalla en teléfonos.

Solo puede ejecutarse una presentación de Agentkit por página. Si se cargan dos scripts de inserción, gana el data-display del primero y un duplicado distinto registra una advertencia en la consola en lugar de montar un segundo widget. Los ajustes y el chat de Center Stage se cargan desde sus propios endpoints, así que desactivar el canal en la página Canales lo detiene en todos los sitios aunque la burbuja siga activa.

Reiniciar el chat y las opciones

window.agentkit('resetChat');

Este comando borra la conversación guardada y crea un nuevo id de conversación. Conserva la identidad y las opciones temporales de la página.

window.agentkit('setOptions', {
  title: 'Checkout assistant',
  conversation: {
    messagePlaceholder: 'Ask about checkout',
    initialMessages: ['Need help finishing your order?'],
    defaultPrompts: {
      prompts: ['Delivery times', 'Returns', 'Payment methods'],
    },
  },
});
window.agentkit('resetOptions');
window.agentkit('resetOptions', [
  'title',
  'conversation.initialMessages',
]);

Las claves admitidas son title, conversation.messagePlaceholder, conversation.initialMessages y conversation.defaultPrompts.prompts. Cada clave se valida por separado. Los valores solo existen en la página actual y no modifican la configuración guardada ni el almacenamiento local.

Eventos

function onAssistantMessage(event) {
  console.log(event.detail.conversationId);
  console.log(event.detail.content);
}

window.agentkit(
  'addEventListener',
  'assistant-message',
  onAssistantMessage,
);

// Clean up when this page or route no longer needs the listener.
window.agentkit(
  'removeEventListener',
  'assistant-message',
  onAssistantMessage,
);

Usa la misma referencia de función para eliminar el listener. Los eventos son user-message, assistant-message, tool-call y tool-result. Los eventos de mensaje incluyen { conversationId, content }. Los eventos de herramientas se emiten antes y después de ejecutar las herramientas del navegador registradas. Un error en un listener no interrumpe el widget.

Registrar herramientas del navegador

Crea una acción del lado del cliente en el panel y registra un handler con exactamente el mismo nombre de acción en cada página donde pueda aparecer el widget. Registrar de nuevo reemplaza el registro completo, lo que hace predecible la limpieza por ruta en aplicaciones de una sola página.

window.agentkit('registerTools', {
  checkInventory: async ({ args, signal }) => {
    const response = await fetch(`/api/inventory?sku=${args.sku}`, { signal });

    if (!response.ok) {
      return { status: 'error', error: 'Inventory is unavailable.' };
    }

    return { status: 'success', data: await response.json() };
  },
});

Los handlers reciben { args, toolCallId, signal }. Devuelve { status: 'success', data } o { status: 'error', error }; un valor de retorno compatible con JSON se trata como éxito. El widget cancela el trabajo tras 60 segundos y convierte handlers ausentes, excepciones lanzadas, timeouts y resultados inválidos en resultados de error acotados para que el asistente pueda continuar la conversación.

Trata los argumentos de las herramientas como entrada no confiable. Mantén las credenciales privilegiadas en tu propio servidor, pasa el signal de cancelación proporcionado a las peticiones de red y nunca devuelvas secretos ni datos personales innecesarios. Las herramientas de cliente requieren el embed por script; el embed por iframe no puede acceder a funciones de la página contenedora.

Los comandos de identidad existentes siguen siendo compatibles:

window.agentkit('identify', { token: newToken });
window.agentkit('resetUser');

Consulta Verificación de identidad.

En TypeScript, importa el contrato Agentkit desde @kit/chatbot-widget/sdk; en el navegador está en window.agentkit. Los eventos de mensaje incluyen conversationId y content, y los de herramientas añaden toolCallId, toolName, input y output. Los comandos setOptions, resetOptions, resetChat, identify y resetUser están tipados.