Microsoft Bot Framework 的基本概念

適用於： SDK v4

Bot 是使用者以交談方式互動、使用文字、圖形（例如卡片或影像）或語音的應用程式。 Azure AI Bot Service 是雲端平臺。 它會裝載 Bot，並將其提供給 頻道，例如 Microsoft Teams、Facebook 或 Slack。

Bot Framework Service 是 Azure AI Bot Service 的元件，會在使用者 Bot 連線的應用程式與 Bot 之間傳送資訊。 每個通道都可以在他們傳送的活動中包含其他資訊。 建立 Bot 之前，請務必瞭解 Bot 如何使用活動物件與其用戶通訊。

此圖說明使用者與回應 Bot 通訊時，可能會交換的兩種活動類型： 交談更新 和 訊息。

Bot Framework 服務會在合作物件加入交談時傳送 交談更新 。 例如，在開始使用 Bot Framework 模擬器交談時，您可能會看到兩個交談更新活動（一個用於加入交談的使用者，另一個用於 Bot 加入）。 若要區分這些交談更新活動，請檢查活動的成員新增屬性中包含誰。

訊息活動會攜帶雙方之間的交談資訊。 在回應 Bot 範例中，訊息活動會攜帶簡單的文字，而通道會轉譯此文字。 或者，訊息活動可能會攜帶要說出的文字、建議的動作或要顯示的卡片。

提示

每個通道皆可實作 Bot Framework 通訊協定，以及每個通道的運作方式可能稍有不同。 例如，某些通道會先傳送交談更新活動，有些通道會在傳送第一個訊息活動之後傳送交談更新活動。 通道可能會在一個交談更新活動中同時包含 Bot 和使用者，而另一個通道可能會傳送兩個交談更新活動。

在此範例中，Bot 會建立並傳送訊息活動，以回應已收到的輸入訊息活動。 不過，Bot 可以透過其他方式回應已接收的訊息活動，而且 Bot 通常會透過傳送含有歡迎訊息的訊息活動來回應交談更新活動。 如需詳細資訊，請參閱如何 歡迎使用者。

The Bot Framework SDK

Bot Framework SDK 可讓您建置可在 Azure AI Bot Service 上裝載的 Bot。 此服務會定義 REST API 和活動通訊協定，以瞭解 Bot 和通道或使用者可以如何互動。 SDK 會以這個 REST API 為基礎，並提供服務的抽象概念，讓您可以專注於交談邏輯。 雖然您不需要瞭解 REST 服務才能使用 SDK，但瞭解其部分功能會很有説明。

Bot 是具有交談介面的應用程式。 它們可以用來將簡單、重複的工作，例如將晚餐預訂或收集配置檔資訊移轉到自動化系統，而自動化系統可能不再需要直接人為介入。 使用者使用文字、互動式卡片和語音與 Bot 交談。 Bot 互動可以是快速的問與答，也可以是以智慧方式提供服務存取權的複雜對話。

注意

SDK 和 REST API 所提供的功能支援會因通道而異。 您可以使用 Bot Framework 模擬器來測試 Bot，但也應該在您想要讓 Bot 可供使用的每個通道上測試 Bot 的所有功能。

互動牽涉到活動交換 ，這些活動會輪 流處理。

活動

使用者（或通道）與 Bot 之間的每個互動都會以活動表示。 Bot Framework 活動架構 會定義可在使用者或通道與 Bot 之間交換的活動。 活動可以代表人類文字或語音、應用程式對應用程式通知、對其他訊息的反應等等。

回合

在談話中，人們經常一次說話，輪流說話。 使用 Bot 時，通常會回應使用者輸入。 在 Bot Framework SDK 中，回合包含使用者對 Bot 的傳入活動，以及 Bot 以立即回應的形式傳回給使用者的任何活動。 您可以將回合視為與接收指定活動之 Bot 相關聯的處理。

例如，使用者可能會要求 Bot 執行特定工作。 Bot 可能會回應問題，以取得工作的詳細資訊，此時此回合結束。 在下一個回合中，Bot 會收到來自使用者的新訊息，其中包含 Bot 問題的解答，或者它可能代表主旨變更或要求來忽略執行工作的初始要求。

Bot 應用程式結構

SDK 會定義 Bot 類別，以處理 Bot 應用程式的交談推理。 Bot 類別：

• 辨識和解譯用戶的輸入。
• 輸入及執行相關工作的原因。
• 產生 Bot 正在執行或已完成之動作的回應。

SDK 也會定義 處理與通道連線的配接器 類別。 配接器：

• 提供處理要求的方法，以及用來產生使用者通道要求的方法。
• 包含中間件管線，其中包含 Bot 回合處理程式之外的回合處理。
• 呼叫 Bot 的回合處理程式，並攔截回合處理程式中未處理的錯誤。

此外，Bot 通常需要擷取並儲存每個回合的狀態。 狀態是透過 記憶體、 Bot 狀態和 屬性存取子 類別來處理。 SDK 不提供內建記憶體，但會提供記憶體的抽象概念，以及儲存層的一些實作。 管理 狀態 主題描述這些狀態和記憶體功能。

SDK 不需要您使用特定的應用層來傳送和接收 Web 要求。 Bot Framework 具有適用於 ASP.NET （C#）、restify （JavaScript） 和 aioHTTP （Python） 的範本和範例。 不過，您可以選擇為應用程式使用不同的應用層。

當您使用 SDK 建立 Bot 時，您會提供程式代碼來接收 HTTP 流量，並將其轉送至配接器。 Bot Framework 提供一些範本和範例，可供您用來開發自己的 Bot。

注意

Bot Framework JavaScript、C# 和 Python SDK 將會繼續受到支援，不過，Java SDK 即將淘汰，最終長期支援將於 2023 年 11 月結束。

使用 Java SDK 建置的現有 Bot 將繼續運作。

針對新的 Bot 建置，請考慮使用 Microsoft Copilot Studio ，並閱讀 選擇正確的 Copilot 解決方案。

如需詳細資訊，請參閱 Bot 建置的未來。

Bot 邏輯

Bot 物件包含回合的對話推理或邏輯，並公開 回合處理程式，這是可以接受 Bot 配接器傳入活動的方法。

SDK 提供幾個不同的範例來管理 Bot 邏輯。

• 活動處理程式 會提供事件驅動模型，其中傳入活動類型和子類型是事件。 針對與使用者有有限且簡短互動的 Bot，請考慮活動處理程式。
  • 使用活動處理程式，並針對 Bot 將辨識和回應的每個活動類型或子類型實作處理程式。
  • 使用 Teams 活動處理程式建立可連線到 Teams 頻道的 Bot。 （Teams 頻道需要 Bot 處理某些頻道特定的行為。
• 對話框連結庫提供狀態型模型，以管理與用戶長時間執行的交談。
  • 針對基本上循序對話使用活動處理程式和 元件對話框 。 如需詳細資訊，請參閱 元件和瀑布式對話。
• 實作您自己的 Bot 類別，並提供您自己的邏輯來處理每個回合。 如需範例，請參閱如何 建立您自己的提示來收集用戶輸入。

Bot 配接器

配接器具有 啟動回合的進程活動 方法。

• 它接受要求本文（要求承載，轉譯為活動）和要求標頭作為自變數。
• 它會檢查驗證標頭是否有效。
• 它會建立 回合的內容 物件。 內容物件包含活動的相關信息。
• 它會透過其 中間件 管線傳送內容物件。
• 然後，它會將內容對象傳送至 Bot 物件的回合處理程式。

配接器也：

• 格式化並傳送響應活動。 這些回應通常是使用者的訊息，但也可能包含使用者通道直接取用的資訊。
• 顯示 Bot 連接器 REST API 所提供的其他方法，例如 更新訊息 和 刪除訊息。
• 擷取錯誤或例外狀況，否則不會攔截回合的錯誤或例外狀況。

回合內容

回合 內容 物件會提供活動的相關信息，例如傳送者和接收者、通道，以及處理活動所需的其他數據。 它也允許在輪替期間跨各種 Bot 層新增資訊。

回合內容是 SDK 中最重要的抽象概念之一。 它不僅會將輸入活動傳送至所有中間件元件和應用程式邏輯，還會提供中間件元件和 Bot 邏輯可以傳送輸出活動的機制。

中介軟體

中間件與任何其他傳訊中間件類似，由一組線性元件組成，每個元件會依序執行，讓每個元件有機會在活動上運作。 中間件管線的最後一個階段是應用程式向配接器進程活動方法註冊之 Bot 類別上開啟處理程式的回呼。 中間件會實作 配接器呼叫的 on turn 方法。

回合處理程式會採用回合內容作為其自變數，通常是回合處理程式函式內執行的應用程式邏輯會處理輸入活動的內容，並在響應中產生一或多個活動，並使用 回合內容上的傳送活動函式傳送這些輸出活動 。 在回合內容上呼叫 傳送活動 會導致在輸出活動上叫用中間件元件。 中間件元件會在 Bot 的回合處理程式函式前後執行。 執行原本就是巢狀的，因此有時稱為洋蔥。

中間 件 主題會更深入地描述中間件。

Bot 狀態和記憶體

與其他 Web 應用程式一樣，Bot 本質上是無狀態的。 Bot 中的狀態會遵循與新式 Web 應用程式相同的範例，而 Bot Framework SDK 提供儲存層和狀態管理抽象概念，讓狀態管理更容易。

管理 狀態 主題描述這些狀態和記憶體功能。

傳訊端點和布建

一般而言，您的應用程式需要 REST 端點，才能接收訊息。 它也需要根據您決定使用的平臺，為您的 Bot 布建資源。

請遵循建立 Bot 快速入門來建立及測試簡單的回應 Bot。

HTTP 詳細數據

活動會透過 HTTP POST 要求從 Bot Framework 服務抵達 Bot。 Bot 會以 200 HTTP 狀態代碼回應輸入 POST 要求。 從 Bot 傳送至通道的活動會以個別的 HTTP POST 傳送至 Bot Framework 服務。 這反過來又會以 200 HTTP 狀態代碼認可。

通訊協定不會指定這些 POST 要求及其認可的順序。 不過，為了配合常見的 HTTP 服務架構，通常這些要求是巢狀的，這表示輸出 HTTP 要求是從 Bot 在輸入 HTTP 要求的範圍內進行。 此模式會在先前的圖表中說明。 由於有兩個不同的 HTTP 連線回溯，因此安全性模型必須同時提供兩者。

注意

Bot 有 15 秒的時間可確認大部分通道的狀態為 200 的呼叫。 如果 Bot 未在 15 秒內回應，就會發生 HTTP GatewayTimeout 錯誤 （504）。

活動處理堆疊

讓我們鑽研上一個時序圖，並將焦點放在訊息活動的抵達。

通道會將使用者的訊息傳送至 Azure AI Bot 服務，而服務會將訊息轉送至 Bot 的傳訊端點。 Bot 的回應會在回合範圍內傳送給使用者。

在上述範例中，Bot 會以包含相同文字訊息的另一個訊息活動回復訊息活動。 處理會從 HTTP POST 要求開始，活動資訊會以 JSON 承載的形式傳送，抵達網頁伺服器。 通常，ASP.NET 項目用於 C# Bot，而 Express 或 restify 等熱門架構則用於 JavaScript Node.js Bot。

配 接器是 SDK 的整合元件，是 SDK 執行時間的核心。 活動會在 HTTP POST 主體中以 JSON 形式傳送。 這個 JSON 會還原串行化，以建立 活動 對象，然後透過其 進程活動 方法將它交給配接器。 在接收活動時，配接器會 建立回合內容 並呼叫中間件。

如上所述，回合內容會提供機制讓 Bot 傳送輸出活動，最常是為了回應輸入活動。 回合內容提供 傳送、 更新和 刪除活動 回應方法。 每個回應方法都會在異步進程中執行。

重要

處理主要 Bot 的線程會在完成時處理處置內容物件。 請務必 await 呼叫任何活動， 讓主要線程在完成其處理和處置回合內容之前，先等候產生的活動。 否則，如果回應（包括其處理程式）花費任何大量的時間，並嘗試對內容對象採取行動，它可能會收到 已處置 的內容錯誤。

Bot 範本

您必須為您的應用程式選擇應用層使用;不過，Bot Framework 具有適用於 ASP.NET （C#）、 restify （JavaScript） 和 aioHTTP （Python） 的範本和範例。 假設您使用其中一個平臺，但 SDK 不需要您，就會撰寫檔。 如需如何存取及安裝範本的指示，請參閱建立 Bot 快速入門。

Bot 是 Web 應用程式，而且會針對 SDK 的每個語言版本提供範本。 所有範本都提供預設端點實作和配接器。 每個樣本都包含：

• 資源佈建
• 特定語言的 HTTP 端點實作，會將連入活動路由傳送至配接器。
• 配接器物件
• Bot 物件

不同範本類型之間的主要差異在於 Bot 物件中。 範本如下：

• 空的 Bot
  • 包含活動處理程式，可藉由在交談的第一個回合傳送「你好世界」訊息來歡迎用戶進行交談。
• Echo Bot
  • 使用活動處理程式來歡迎使用者，並回應使用者輸入。
• 核心 Bot
  • 整合 SDK 的許多功能，並示範 Bot 的最佳做法。
  • 使用活動處理程式歡迎使用者。
  • 使用元件對話框和子對話來管理交談。
  • 對話框會使用 Language Understanding （LUIS） 和 QnA Maker 功能。

注意

Azure AI QnA Maker 將於 2025 年 3 月 31 日淘汰。 從 2022 年 10 月起，您將無法建立新的 QnA Maker 資源或知識庫。 較新版的問題和解答功能現在隨附於 Azure AI 語言。

自定義問題解答是 Azure AI 語言的一項功能，是 QnA Maker 服務的更新版本。 如需 Bot Framework SDK 中問答支援的詳細資訊，請參閱 自然語言理解。

注意

Language Understanding （LUIS） 將於 2025 年 10 月 1 日淘汰。 從 2023 年 4 月 1 日起，您將無法建立新的 LUIS 資源。 新版的語言理解現在已提供作為 Azure AI 語言的一部分。

對話式語言理解（CLU）是 Azure AI 語言的一項功能，是 LUIS 的更新版本。 如需 Bot Framework SDK 中語言理解支援的詳細資訊，請參閱 自然語言理解。

其他資訊

管理 Bot 資源

您必須管理 Bot 的資源，例如其應用程式識別碼和密碼，以及任何已連線服務的資訊。 當您部署 Bot 時，需要安全存取這項資訊。 為了避免複雜性，大部分的 Bot Framework SDK 文章不會描述如何管理這項資訊。

• 如需一般安全性資訊，請參閱 Bot Framework 安全性指導方針。
• 若要管理 Azure 中的密鑰和秘密，請參閱關於 Azure 金鑰保存庫。

管道配接器

SDK 也可讓您使用通道配接器，其中配接器本身會額外執行 Bot 連接器服務針對通道正常執行的工作。

SDK 提供一些語言的通道配接器。 更多通道配接器可透過 Botkit 和社群存放庫取得。 如需詳細資訊，請參閱 Bot Framework SDK 存放庫的通道和配接器數據表。

Bot 連接器 REST API

Bot Framework SDK 會包裝並建置在 Bot 連接器 REST API 上。 如果您想要了解支援 SDK 的基礎 HTTP 要求，請參閱連接器 驗證 和相關文章。 Bot 傳送和接收的活動符合 Bot Framework 活動架構。

下一步

• 若要瞭解 Bot 中狀態的角色，請參閱 管理狀態。
• 若要了解開發 Microsoft Teams Bot 的重要概念，請參閱 Microsoft Teams Bot 的運作方式