理解活動協定

活動協定是一種標準通訊協定廣泛應用於Microsoft許多Microsoft SDK、服務與用戶端中。活動協定被 Microsoft 365 Copilot、Microsoft Copilot Studio 以及 Microsoft 365 Agents SDK 採用。活動協定定義了Activity的結構，以及訊息、事件和互動如何從一個通道流向你的程式碼及其他地方。客服專員可以連接到一個或多個通道以與使用者互動並與其他客服專員合作。活動協定標準化了與你正在使用的任何客戶端的通訊協定，包括 Microsoft 及非 Microsoft 客戶端，讓你不必為每個通道建立自訂邏輯。

什麼是活動？

An Activity 是一個結構化的 JSON 對象，代表使用者和客服專員之間的任何互動。活動不僅限於文字訊息。它們可以包含各種互動類型，例如支援多用戶的客戶端加入或離開事件、打字指示、檔案上傳、卡片操作，以及開發者設計的自訂事件。

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

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

活動架構 - 關鍵屬性

本規範定義了活動協定：活動協定 - 活動。活動協定中定義的一些關鍵屬性包括：

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

存取活動資料

要完成物件中的 TurnContext 操作，開發者需要存取活動中的資料。

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

.NET： TurnContext
Python： TurnContext
JavaScript： TurnContext

備註

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

TurnContext 是Microsoft 365 Agents SDK中每個對話回合都會用到的重要物件。它提供對傳入操作、發送回應的方法、對話狀態管理功能以及處理單輪對話所需的環境的訪問。利用它來維持上下文、發送適當的回應，並有效地與用戶在客戶端或頻道互動。每當你的代理從某個通道收到新的活動時，代理的 SDK 會建立一個新 TurnContext 實例，並傳給你註冊的處理器或方法。這個上下文物件在該回合中存在，回合結束後會被丟棄。

回合的定義是一則訊息從客戶端發出，往返至你程式碼的過程。你的程式碼會處理這些資料，並可以選擇性地回傳回應以完成回合。這趟往返行程可分為以下幾個步驟：

進入活動：使用者發送訊息或執行動作，產生活動。
您的程式碼會接收活動，而代理程式會使用 TurnContext進行處理。
您的代理會傳回一個或多個活動。
回合結束且 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：回合的狀態

活動類型

活動的類型定義了該活動其他部分在客戶、使用者與代理人之間所需的或期望的內容。

這些包括：

訊息
對話更新
事件
叫用
Typing

訊息

一種常見的活動類型是Message類型的Activity。這 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.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text($"Welcome {member.Name}!"), cancellationToken);
            }
        }
    }
})

事件

事件類型Activity是通道或客戶端用來傳送結構化資料給你的代理的自訂事件。這些資料並非預先定義在 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)
});

叫用

呼叫類型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 等等。同時也要知道，這些網址通常壽命很短，所以不要假設它們能維持有效期太久。這個限制是為什麼如果日後需要參考內容，搬到自己的儲存空間很重要。

引文

請務必知道附件和引文不是相同的物件類型。客戶端，如 Microsoft Teams，則有自己的方式處理引用。它們使用 Entities 屬性的 Activity。你可以根據客戶端新增 activity.Entities.Add 引用，並新增一個 Entity 物件，其具有根據客戶端的特定 Citation 定義。它會被序列化成 JSON 物件，然後客戶端根據它在客戶端的呈現方式反序列化。基本上，附件是訊息，而引用則可以參考附件，並且是有效載荷中另一個被傳送EntitiesActivity的物件。

通道特定考量

Microsoft 365 Agents SDK被打造為一個「樞紐」，開發者用來創建能與any客戶端（包括我們支援的客戶）合作的代理。它提供開發者工具，以便他們使用相同框架自己開發通道適配器。這種架構讓開發者在代理上擁有廣泛的空間，也讓客戶端能夠連接該樞紐，這些樞紐可以是像 Microsoft Teams、Slack 等一個或多個客戶端。

不同頻道有不同的功能和限制。

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

通道包含一些具體的資料，這些資料與所有通道的通用 Activity 有效載荷不符。你可以透過將 TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) 屬性的資料型別轉換成變數，來存取這些資料，以便在程式碼中使用。

以下章節將總結與常見客戶合作時的考量事項。

Microsoft 團隊

支援豐富的調適型卡片並具備進階功能。
支援訊息更新與刪除。
有針對 Teams 功能的專屬頻道資料，例如提及和會議資訊。
支援任務模組的呼叫活動。

Microsoft 365 Copilot

主要專注於訊息傳送活動。
支持回應中的引用與參考資料。
需要串流回應。
對豐富卡和自適應卡的支援有限。

網路聊天/DirectLine

網路聊天是一種 HTTP 協定，代理可以用來透過 HTTPS 進行通訊。

全方位支援所有活動類型。
支援自訂頻道資料。

非 Microsoft 頻道

這些頻道包括 Slack、Facebook 等。

某些活動類型可能會受到支援限制。
卡片渲染可能不同或不支援。
務必查看特定的頻道文件。

後續步驟

了解 AgentApplication

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-04-29