Documentação

SDK de incorporação do widget

Controle o widget Agentkit no navegador, envie mensagens proativas, aplique opções da página e escute eventos.

O SDK permite que sua página abra, feche, redefina, configure e observe o balão de chat do Agentkit. Ele está disponível apenas na incorporação por script. A incorporação por iframe não define window.agentkit.

Instalar a fila

Use o trecho da página Canais do seu agente. A fila faz com que chamadas antes e depois do carregamento do script assíncrono tenham o mesmo comportamento.

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

A incorporação antiga com uma única tag continua funcionando. Adicione a fila se chamar o SDK antes de o bundle terminar de carregar.

Controlar o widget e enviar mensagens

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

Com hideMessage, a mensagem proativa não aparece na conversa e o widget permanece fechado até o assistente começar a responder.

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

O SDK recusa mensagens vazias, envios simultâneos ou limitados e envios quando o campo está oculto ou desativado ou há um chat ao vivo. close não encerra um chat ao vivo do Salesforce.

Enviar enquanto o widget permanece fechado

Use send quando a página oferece um campo de pergunta compacto e mostra a resposta fora do widget. A mensagem entra na conversa normal sem abrir a apresentação. Escute o evento do assistente e chame open depois para continuar a mesma conversa.

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 as mesmas verificações, limites, persistência e eventos de open({ message }). Só muda se a apresentação abre.

Center Stage

O Center Stage abre o mesmo agente como um diálogo centralizado em tela cheia sobre a sua página, em vez do balão no canto. É um canal próprio na página Canais, com exibição, voz, instruções e ações próprias, e fica desligado até você ativá-lo lá.

Instale-o com o mesmo bootstrap e adicione data-display="center-stage" à tag script. O atributo fica ao lado de 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>

O launcher continua sendo a forma padrão de abri-lo, e cada chamada do SDK funciona igual: open mostra o diálogo, close o fecha, e resetChat, setOptions, identify, eventos e ferramentas do navegador se comportam exatamente como no balão. O diálogo retém o foco, fecha com Escape ou com o botão de fechar, devolve o foco ao que o abriu e ocupa a tela inteira em celulares.

Só uma apresentação do Agentkit pode rodar por página. Se dois scripts de incorporação carregarem, o data-display do primeiro vence e uma duplicata divergente registra um aviso no console em vez de montar um segundo widget. As configurações e o chat do Center Stage carregam de endpoints próprios, então desativar o canal na página Canais o interrompe em todos os sites mesmo com o balão ativo.

Redefinir o chat e as opções

window.agentkit('resetChat');

O comando apaga a conversa em cache e cria um novo id. A identidade e as opções temporárias da página são mantidas.

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

As chaves aceitas são title, conversation.messagePlaceholder, conversation.initialMessages e conversation.defaultPrompts.prompts. Cada chave é validada separadamente. Os valores existem apenas na página atual e não alteram configurações salvas nem o armazenamento 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,
);

Use a mesma referência de função para remover o listener. Os eventos são user-message, assistant-message, tool-call e tool-result. Eventos de mensagem incluem { conversationId, content }. Eventos de ferramenta são emitidos antes e depois da execução das ferramentas do navegador registradas. Um erro em um listener não interrompe o widget.

Registrar ferramentas do navegador

Crie uma ação do lado do cliente no painel e registre um handler com exatamente o mesmo nome de ação em cada página onde o widget possa aparecer. Registrar novamente substitui o registro completo, o que torna a limpeza por rota previsível em aplicações de página única.

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

Os handlers recebem { args, toolCallId, signal }. Retorne { status: 'success', data } ou { status: 'error', error }; um valor de retorno compatível com JSON é tratado como sucesso. O widget cancela o trabalho após 60 segundos e converte handlers ausentes, exceções lançadas, timeouts e resultados inválidos em resultados de erro delimitados, para que o assistente possa continuar a conversa.

Trate os argumentos das ferramentas como entrada não confiável. Mantenha credenciais privilegiadas no seu próprio servidor, repasse o signal de cancelamento fornecido às requisições de rede e nunca retorne segredos ou dados pessoais desnecessários. Ferramentas de cliente exigem o embed por script; o embed por iframe não consegue acessar funções da página hospedeira.

Os comandos de identidade existentes continuam compatíveis:

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

Consulte Verificação de identidade.

No TypeScript, importe o contrato Agentkit de @kit/chatbot-widget/sdk; no navegador ele fica em window.agentkit. Eventos de mensagem incluem conversationId e content, e eventos de ferramenta acrescentam toolCallId, toolName, input e output. Os comandos setOptions, resetOptions, resetChat, identify e resetUser são tipados.