SDK di incorporamento del widget

Controlla il widget Agentkit dal browser, invia messaggi proattivi, applica opzioni di pagina e ascolta gli eventi.

L'SDK consente alla pagina di aprire, chiudere, reimpostare, configurare e osservare il fumetto della chat Agentkit. È disponibile solo con l'incorporamento tramite script. L'iframe non definisce window.agentkit.

Installare la coda

Usa lo snippet della pagina Canali dell'agente. La coda rende equivalenti le chiamate effettuate prima e dopo il caricamento dello script asincrono.

<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>

Il vecchio incorporamento con un solo tag continua a funzionare. Aggiungi la coda se chiami l'SDK prima che il bundle sia caricato.

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

Con hideMessage, il messaggio proattivo non appare nella conversazione e il widget resta chiuso fino all'inizio della risposta dell'assistente.

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

L'SDK rifiuta messaggi vuoti, invii simultanei o limitati e invii quando il campo è nascosto o disabilitato o è attiva una chat dal vivo. close non termina una chat Salesforce attiva.

Usa send per offrire una piccola interfaccia di domanda nella pagina e mostrare la risposta fuori dal widget. Il messaggio entra nella normale conversazione senza aprire la presentazione. Ascolta l’evento dell’assistente e chiama open in seguito per continuare la stessa conversazione.

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 gli stessi controlli, limiti, persistenza ed eventi di open({ message }). Cambia solo l’apertura della presentazione.

Center Stage

Center Stage apre lo stesso agente come finestra di dialogo centrata a schermo intero sopra la tua pagina, al posto della bolla nell'angolo. È un canale a sé nella pagina Canali, con visualizzazione, voce, istruzioni e azioni proprie, e resta disattivato finché non lo abiliti lì.

Installalo con lo stesso bootstrap e aggiungi data-display="center-stage" al tag script. L'attributo va accanto a data-chatbot e data-locale:

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

Il launcher resta il modo predefinito per aprirlo e ogni chiamata dell'SDK funziona allo stesso modo: open mostra la finestra, close la chiude, e resetChat, setOptions, identify, gli eventi e gli strumenti del browser si comportano esattamente come con la bolla. La finestra trattiene il focus, si chiude con Esc o con il suo pulsante di chiusura, restituisce il focus a ciò che l'ha aperta e occupa tutto lo schermo sui telefoni.

Su una pagina può funzionare una sola presentazione Agentkit. Se si caricano due script di embed, vince il data-display del primo e un duplicato diverso scrive un avviso in console invece di montare un secondo widget. Impostazioni e chat di Center Stage si caricano da endpoint propri, quindi disattivare il canale nella pagina Canali lo ferma su ogni sito anche se la bolla resta attiva.

Reimpostare chat e opzioni

window.agentkit('resetChat');

Il comando cancella la conversazione memorizzata e crea un nuovo id. Mantiene l'identità e le opzioni temporanee della pagina.

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',
]);

Le chiavi supportate sono title, conversation.messagePlaceholder, conversation.initialMessages e conversation.defaultPrompts.prompts. Ogni chiave viene convalidata separatamente. I valori esistono solo nella pagina corrente e non modificano le impostazioni salvate o la memoria locale.

Eventi

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 lo stesso riferimento alla funzione per rimuovere il listener. Gli eventi sono user-message, assistant-message, tool-call e tool-result. Gli eventi dei messaggi contengono { conversationId, content }. Gli eventi degli strumenti vengono emessi prima e dopo l'esecuzione degli strumenti del browser registrati. Un errore in un listener non interrompe il widget.

Registrare strumenti del browser

Crea un'azione lato client nella dashboard, poi registra un handler con esattamente lo stesso nome dell'azione su ogni pagina in cui il widget può comparire. Una nuova registrazione sostituisce l'intero registro, rendendo prevedibile la pulizia per route nelle applicazioni a pagina singola.

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() };
  },
});

Gli handler ricevono { args, toolCallId, signal }. Restituisci { status: 'success', data } o { status: 'error', error }; un valore di ritorno compatibile con JSON viene trattato come successo. Il widget annulla il lavoro dopo 60 secondi e trasforma handler mancanti, eccezioni lanciate, timeout e risultati non validi in risultati di errore delimitati, così l'assistente può proseguire la conversazione.

Tratta gli argomenti degli strumenti come input non attendibile. Mantieni le credenziali privilegiate sul tuo server, passa il signal di annullamento fornito alle richieste di rete e non restituire mai segreti o dati personali non necessari. Gli strumenti client richiedono l'embed via script; l'embed via iframe non può accedere alle funzioni della pagina ospitante.

I comandi di identità esistenti restano compatibili:

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

Consulta Verifica dell'identità.

In TypeScript, importa il contratto Agentkit da @kit/chatbot-widget/sdk; nel browser si trova in window.agentkit. Gli eventi dei messaggi includono conversationId e content, mentre gli eventi degli strumenti aggiungono toolCallId, toolName, input e output. I comandi setOptions, resetOptions, resetChat, identify e resetUser sono tipizzati.