了解活動協議

活動通訊協定是 Microsoft 內部在許多 Microsoft 的 SDK、服務和用戶端中使用的通訊協定和標準協定。這包括 Microsoft 365 Copilot、Microsoft Copilot Studio 和 Microsoft 365 Agents SDK。活動通訊協定會定義的 Activity 形狀，以及訊息、事件和互動如何從通道流向程式碼，以及介於兩者之間的其他任何地方。客服專員可以連接到一個或多個通道以與使用者互動並與其他客服專員合作。活動通訊協定會標準化您正在使用的任何用戶端之間的通訊通訊協定，包括 Microsoft 和第三方用戶端，因此您不需要為您正在使用的每個通道建立自訂邏輯。

什麼是活動？

An Activity 是一個結構化的 JSON 對象，代表使用者和客服專員之間的任何互動。活動不僅僅是基於文本的消息，它們可以包括各種類型的交互，包括用戶加入或離開支持多個用戶的客戶的事件、鍵入指示器、文件上傳、卡片操作以及開發人員自己設計的自定義事件。

每個活動都包含有關以下內容的中繼資料：

是誰發送的（來自哪裡）
誰應該收到它（收件人）
對話內容
其來源頻道
互動類型
承載資料

活動架構 - 關鍵屬性

此規格定義了活動協定：活動協定 - 活動。活動通訊協定中定義的一些關鍵屬性包括：

房產	Description
`Id`	通常由頻道生成 (如果訊息來自頻道)
`Type`	類型會控制活動的意義，例如訊息類型
`ChannelID`	`ChannelID` 參照活動來源的通道。例如： `msteams` 。
`From`	活動的寄件者（可以是使用者或客服專員）
`Recipient`	活動的預期收件者
`Text`	訊息的文字內容
`Attachment`	豐富的內容，如卡片、文件圖像

存取活動資料

開發人員需要存取活動內的資料，才能完成物件中的 TurnContext 動作。

您可以在 Microsoft 365 代理程式 SDK 的每個語言版本中找到類別 TurnContext ：

.NET： TurnContext
Python： TurnContext
JavaScript： TurnContext

備註

本文中的程式碼片段使用 C#。 JavaScript 和 Python 版本的語法和 API 結構類似。

在 Microsoft 365 代理程式 SDK 的每個交談回合中，TurnContext 是一個重要物件。它提供對傳入活動的存取、回應傳送的方法、交談狀態管理，以及處理單次交談所需的上下文。它用於維護上下文、發送適當的響應以及與用戶客戶端/渠道中的用戶有效互動。每次您的代理程式從通道收到新活動時，代理程式 SDK 都會建立一個新 TurnContext 執行個體，並將其傳遞給您註冊的處理常式/方法。此上下文物件存在於單一回合期間，並在回合結束時被釋放。

回合定義為從用戶端傳送的訊息來回行程，並前往您的程式碼，您的程式碼會處理該資料，而程式碼可以選擇性地傳回回應以完成回合。該往返行程可以分為：

傳入活動：使用者傳送訊息或執行建立活動的動作。
您的程式碼會接收活動，而代理程式會使用 TurnContext進行處理。
您的 Agent 會回傳一個或多個活動。
回合結束且 TurnContext 被移除。

從 TurnContext存取資料，例如：

var messageText = turnContext.Activity.Text
var channelID = turnContext.Activity.ChannelId

此程式碼片段顯示完整回合的範例：

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken) =>
{
    var userMessage = turnContext.Activity.Text'
    var response = $"you said: {userMessage}";
    await turnContext.SendActivityAsync(MessageFactory.Text(response), cancellationToken);
});

在 TurnContext 類別中，常用的關鍵資訊包括：

活動：從活動中獲取信息的主要方式
配接器：用於創建活動的通道配接器
TurnState：回合的狀態

活動類型

活動的類型很重要，因為它定義了客戶、使用者和客服專員之間其餘活動中需要或預期的內容。

Message

常見的活動類型是的訊息類型 Activity，其中可能包含文字、附件和建議的動作，以列舉此類型的一些常見用途。

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken) =>
{
    var userMessage = turnContext.Activity.Text'
    var response = $"you said: {userMessage}";
    await turnContext.SendActivityAsync(MessageFactory.Text(response), cancellationToken);
});

對話更新

ConversationUpdate 類型會在Activity成員加入或離開對話時通知您的客服專員。並非所有客戶都支持此功能，一個值得注意的客戶端是 Microsoft Teams。

下列程式碼片段會在交談中問候新成員：

agent.OnActivity(ActivityTypes.ConversationUpdate, async (turnContext turnState, cancellationToken) =>
{
    var membersAdded = turnContext.Activity.MembersAdded
    if (membersAdded != null)
    {
        foreach (var member in membersAdded)
        {
            if (member.Id != turnContext.Activity.Reciepient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text($"Welcome {member.Name}!"), cancellationToken);
            }
        }
    }
})

活動

事件類型是自訂事件，允許通道或用戶端將結構化資料傳送至您的代理程式，而該資料未在Activity承載結構中預先定義。

您必須為特定 Event 類型建立方法/路由處理常式，然後根據下列項目管理所需的邏輯：

名稱 - 用戶端的事件名稱或識別碼值 - 通常是 JSON 物件的事件承載

agent.OnActivity(ActivityTypes.Event, async (turnContext turnState, cancellationToken) =>)
{
    var eventName = turnContext.Activity.Name
    var eventValue = turnContext.Activity.Value

    // custom event (E.g. a switch on eventName)
}

Invoke

叫用類型是Activity用戶端呼叫代理程式以執行命令或作業的特定活動類型，而不只是訊息。這些類型的活動範例在 Microsoft Teams 中針對 task/fetch 和 task/submit 很常見。並非所有頻道都支援這些類型的活動。

Typing

輸入類型的 Activity 是一種活動分類，用於表示有人正在交談中輸入文字。例如，這在 Microsoft Teams 用戶端中的人與人對話之間很常見。並非每個用戶端都支援輸入活動，特別是 Microsoft 365 Copilot 不支援輸入活動。

await turnContext.SendActivityAsync(new Activity { Type = ActivityTypes.Typing }, cancellationToken); 
await Task.Delay(2000);
await turnContext.SendActivityAsync(MessageFactory.Text("Here is your answer..."), cancellationToken)

建立和傳送活動

為了發送回應，'TurnContext' 提供了多種將回應發送回給使用者的方法。

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken))
{
    await turnContext.SendActivityAsync("hello!", cancellationToken: CancellationToken) // uses string directly
    await turnContext.SendActivityAsync(MessageFactory.Text("Hello"), cancellationToken) // uses Message Factory
    await turnContext.SendActivitiesAsync(activities, cancellationToken) // send multiple activities in an Activity array
}

使用附件

客服專員通常使用使用者（甚至其他客服專員）提交的附件。用戶端會傳送 Message 包含附件的活動（它不是特定類型的活動），而您的程式碼需要處理接收包含附件的訊息、讀取中繼資料，以及從用戶端提供的 URL 安全地擷取檔案。然後通常會將文件移動到您自己的存儲中。

接收附件

下列程式碼示範如何接收和附加

agent.OnActivity(ActivityTypes.Message, async(turnContext, turnState, cancellationToken)) =>
{
    var activity = turnContext.Activity;
    if (activity.Attachments != null && activity.Attachments.Count >0)
    {
        foreach (var attachment in activity.Attachments)
        {
            // get metadata as required e.g. attachment.ContextType or attachment.ContentUrl
            // use the URL to securely download the attachment and complete your business logic
        }
    }
}

一般而言，若要接收附件上的檔，用戶端會傳送已驗證的要求 GET 來擷取實際內容 - 每個配接器都有自己的方式來取得該數據，例如 Teams、OneDrive 等。同樣重要的是要知道這些 URL 通常是短暫的，因此不要假設它們會留在那裡，這就是為什麼如果您以後需要參考它，移動到您自己的存儲很重要。

引文

請務必知道附件和引文不是相同的物件類型。引用由用戶端 (例如 Microsoft Teams) 以各自方式處理，並依據您的用戶端設定，使用的Activity，可以透過 activity.Entities.Add 新增一個具有特定 Entity 定義的 Citation 物件。它會被序列化為一個 JSON 物件，然後用戶端將根據其在用戶端中的呈現方式來還原該序列化結果。從根本上來說，附件是訊息，而引用可以參照附件，並作為另一個物件傳送在 Entities 負載的 Activity 中。

通道特定考量

Microsoft 365 代理程式 SDK 建置為「中樞」，可讓開發人員建立可與任何用戶端搭配使用的代理程式，包括我們支援的用戶端，並提供開發人員使用相同架構建置自己的通道配接器的工具。這為開發人員提供了代理的廣度，並為客戶端提供了連接到該中心的可擴展性，該中心可以是一個或多個客戶端，例如 Microsoft Teams、Slack 等。

不同的管道有不同的功能和限制，以下是與普通客戶端合作時的注意事項摘要。

您可以透過檢查channelId中的Activity屬性來確認您收到活動的頻道。

通道包含不符合所有通道的通用 Activity 承載的特定資料，並且可以從 TurnContext 存取這些資料。Activity.ChannelData ，並特別將其轉換成變數，以便在程式碼中使用。

Microsoft 團隊

支援具備進階功能的豐富自適應卡片
支援訊息更新和刪除
具有特定 Teams 功能的頻道資料 (例如提及、會議資訊等)
支援任務模組的調用活動

Microsoft 365 Copilot

主要專注於訊息活動
支持回應中的引用和參考文獻
需要串流回應
對豐富卡片/調適型卡片的有限度支援

網路聊天/DirectLine

網路聊天是一種 HTTP 協定，用於客服專員透過 HTTPS 進行通話

全面支援所有活動類型
支持自定義渠道數據

第三方渠道

其中包括 Slack、Facebook 等。

對特定活動類型的支援可能有限
卡片渲染可能不同或不支援
請務必檢查特定頻道文件

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-11-19