小工具嵌入 SDK

嵌入 SDK 可讓網頁開啟、關閉、重設、設定及監聽 Agentkit 聊天泡泡。SDK 僅適用於 script 嵌入方式，iframe 嵌入不會定義 window.agentkit。

安裝佇列

請使用代理程式「頻道」頁面提供的程式碼。佇列可讓非同步 script 載入前後的呼叫具有相同行為。

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

原本只有一個 script 標籤的嵌入方式仍可使用。若要在 bundle 載入完成前呼叫 SDK，請加入佇列。

控制小工具及傳送訊息

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

設定 hideMessage 後，主動訊息不會顯示在對話記錄中。小工具會等到助理開始回覆時才開啟。

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

SDK 會拒絕空白、同時傳送或超過速率限制的訊息。輸入欄位被隱藏或停用，以及真人客服進行中時也無法傳送。close 不會結束進行中的 Salesforce 真人聊天。

在小工具保持關閉時傳送訊息

當頁面提供精簡的問題介面並在小工具外顯示回答時，可使用 send。訊息會加入一般小工具對話，但不會開啟介面。監聽助理事件，之後呼叫 open 即可繼續同一段對話。

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 與 open({ message }) 使用相同的輸入檢查、速率限制、保存機制與訊息事件，差別只在於是否開啟介面。

Center Stage

Center Stage 會在你的頁面上方以置中的全螢幕對話框開啟同一個代理程式，而不是角落的聊天泡泡。它是「頻道」頁面上的獨立頻道，擁有自己的顯示、語音、指示與動作，且在你於該頁啟用前保持關閉。

使用相同的初始化程式碼安裝，並在 script 標籤加上 data-display="center-stage"。此屬性與 data-chatbot 和 data-locale 並列：

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

啟動器仍是預設的開啟方式，所有 SDK 呼叫行為相同：open 顯示對話框，close 關閉它，而 resetChat、setOptions、identify、事件與瀏覽器工具的行為與聊天泡泡完全一致。對話框會鎖住焦點、可用 Escape 或關閉按鈕關閉、關閉後把焦點還給開啟它的元素，並在手機上填滿整個畫面。

每個頁面只能執行一個 Agentkit 呈現方式。若載入兩個嵌入指令碼，以第一個指令碼的 data-display 為準，不一致的重複載入只會在主控台記錄警告而不會掛載第二個小工具。Center Stage 的設定與聊天由專屬端點載入，因此在「頻道」頁面停用該頻道後，即使聊天泡泡仍啟用，所有網站上的 Center Stage 都會停止。

重設聊天及選項

window.agentkit('resetChat');

此指令會清除快取的對話並建立新的對話 id，但會保留目前的驗證身分及暫時頁面選項。

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

支援的鍵值為 title、conversation.messagePlaceholder、conversation.initialMessages 及 conversation.defaultPrompts.prompts。每個鍵值會分別驗證。這些值只存在於目前頁面，不會修改已儲存的代理程式設定或本機儲存空間。

事件

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

移除 listener 時必須使用相同的函式參照。支援 user-message、assistant-message、tool-call 及 tool-result。訊息事件包含 { conversationId, content }。工具事件會在已註冊的瀏覽器工具執行前後觸發。單一 listener 發生錯誤時不會中斷小工具。

註冊瀏覽器工具

先在後台建立用戶端動作，然後在小工具可能出現的每個頁面上，以完全相同的動作名稱註冊 handler。再次註冊會取代整個註冊表，讓單頁應用程式中依路由清理的行為可預期。

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

Handler 會收到 { args, toolCallId, signal }。請回傳 { status: 'success', data } 或 { status: 'error', error }；一般 JSON 相容的回傳值會被視為成功。小工具會在 60 秒後取消執行，並把缺少 handler、拋出例外、逾時與無效結果轉換成有界的錯誤結果，讓助理能繼續對話。

請把工具引數視為不可信任的輸入。將特權憑證保留在你自己的伺服器上，把提供的取消 signal 傳給網路請求，且絕不要回傳機密或不必要的個人資料。用戶端工具需要 script 內嵌；iframe 內嵌無法存取父頁面的函式。

既有的身分指令仍可使用：

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

請參閱身分驗證。

TypeScript 專案可從 @kit/chatbot-widget/sdk 匯入 Agentkit 合約；瀏覽器中的介面是 window.agentkit。訊息事件包含 conversationId 和 content，工具事件另包含 toolCallId、toolName、input 和 output。setOptions、resetOptions、resetChat、identify 和 resetUser 指令都有型別定義。