了解活動通訊協定

活動通訊協定是一種標準通訊協定，廣泛用於 Microsoft 內部許多 SDK、服務及用戶端。 Microsoft 365 Copilot、Microsoft Copilot Studio、Microsoft Teams 及 Microsoft 365 Agents SDK 皆使用活動通訊協定。 活動通訊協定定義了一個 Activity 的結構，以及訊息、事件及互動如何從通道流向您的程式碼及其間的其他各處。 Agent 可連線至一或多個通道，與使用者互動並與其他 Agent 合作。 活動通訊協定會統一您所使用之任何用戶端的通訊協定 (包括 Microsoft 及非 Microsoft 用戶端)，讓您不必為每個通道建立自訂邏輯。

什麼是 Activity？

Activity 是一個結構化 JSON 物件，代表使用者與您的 Agent 之間的任何互動。 Activity 不僅限於文字型訊息。 其中可包含各種互動類型，例如支援多使用者之用戶端中使用者加入或離開等事件、打字指示器、檔案上傳、卡片動作，以及開發人員自行設計的自訂事件。

每個活動都包含下列相關的中繼資料：

• 傳送者是誰 (from)
• 接收者是誰 (recipient)
• 交談內容
• 活動的來源通道
• 互動類型
• 裝載資料

Activity 結構描述 - 主要屬性

本規格定義了活動通訊協定：活動通訊協定 - Activity。 活動通訊協定中定義的部分主要屬性如下：

屬性	Description
Id	通常由頻道生成 (如果訊息來自頻道)
Type	type 用於控制活動的意義，例如訊息類型
ChannelID	ChannelID 會參照活動的來源通道。 例如：msteams。
From	活動的傳送者 (可以是使用者或 Agent)
Recipient	活動的預定接收者
Text	訊息的文字內容
Attachment	卡片、影像或檔案等豐富內容

存取活動資料

若要透過 TurnContext 物件完成動作，開發人員需要存取活動中的資料。

Microsoft 365 Agents SDK 的每種語言版本中，都可找到 TurnContext 類別：

• .NET:TurnContext
• Python:TurnContext
• JavaScript:TurnContext

注意

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

TurnContext 是在 Microsoft 365 Agents SDK 中每個交談回合都會使用的重要物件。 這會提供傳入活動的存取、傳送回應的方法、交談狀態管理，以及處理單次交談所需的背景資訊。 使用此物件可維持內容、傳送適當的回應，並在使用者的用戶端或通道中與其有效互動。 每當 Agent 從某個管道收到新活動時，Agent SDK 都會建立新的 TurnContext 執行個體，並將其傳遞至您註冊的處理常式或方法。 此內容物件僅在單一回合期間存在，回合結束後即會處置。

回合的定義是指訊息從用戶端發送並一路傳遞至您程式碼的來回行程。 您的程式碼會處理該資料，並可選擇傳送回應以完成該回合。 該來回程序可分成下列步驟：

1. 傳入活動：使用者傳送訊息或執行動作，進而建立活動。

2. 您的程式碼會接收該活動，並由 Agent 使用 TurnContext 進行處理。

3. Agent 會回傳一個或多個活動。

4. 回合結束後，即會處置 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 類別中，常用的主要資訊包括：

• Activity：從活動取得資訊的主要方式
• Adapter：建立該活動的通道配接器
• TurnState：該回合的狀態

活動類型

活動的類型會決定該活動其餘部分在用戶端、使用者與 Agent 之間所需要或預期的內容。

其中包括：

• 訊息
• ConversationUpdate
• 事件
• 叫用
• 輸入

訊息

常見的活動類型是 Activity 的 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 的 ConversationUpdate 類型會在成員加入或離開交談時通知您的 Agent。 並非所有用戶端都支援此通知，但 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 的 Event 類型是通道或用戶端用來向您的 Agent 傳送結構化資料的自訂事件。 此資料並未在 Activity 裝載結構中預先定義。

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

• Name：來自用戶端的事件名稱或識別碼
• Value：通常是 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 的 Invoke 類型是用戶端呼叫至 Agent 以執行命令或作業的特定活動類型。 這不只是一則訊息。 這類活動的範例常見於 Microsoft Teams 中的 task/fetch 及 task/submit。 並非所有通道都支援這些類型的活動。

輸入

輸入類型的 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
}

使用附件

Agent 經常會處理使用者 (或甚至其他 Agent) 所提交的附件。 用戶端會傳送包含附件的 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 通常存續時間很短，請勿假設這些 URL 會長時間保持有效。 因此，如果您日後需要參考這些內容，將檔案移至您自己的儲存體就十分重要。

引用

請務必了解，Attachment 與 Citation 並非相同的物件類型。 如 Microsoft Teams 等用戶端，會以自己的方式處理引文。 它們使用 Activity 的 Entities 屬性。 您可以新增包含 activity.Entities.Add 的引文，並根據用戶端新增含有特定 Citation 定義的新 Entity 物件。 它會序列化為 JSON 物件，用戶端接著會根據其轉譯方式進行還原序列化。 從根本上說，附件是訊息，而引文可以參考附件，並且是另一個在 Activity 承載的 Entities 中傳送的物件。

通道特定考量

Microsoft 365 Agents SDK 建置為一個「中樞」，供開發人員用來建立可搭配任何用戶端運作的 Agent，包括我們所支援的用戶端。 它為開發人員提供工具，可使用相同的架構建置自己的通道配接器。 此架構讓開發人員在建立 Agent 時擁有更廣的彈性，並為用戶端提供可擴充性，以連線至該中樞 (可以是 Microsoft Teams、Slack 等一或多個用戶端)。

不同的通道具有不同的功能與限制。

您可以檢查 Activity 中的 channelId 屬性，確認活動的來源通道。

通道所包含的特定資料，未必符合所有通道通用的 Activity 裝載格式。 您可以從 TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) 屬性存取此資料，並將其轉換為變數，以便在程式碼中使用。

下列各節摘要說明使用常見用戶端時的考量。

Microsoft Teams

• 支援提供進階功能的多媒體調適型卡片。
• 支援訊息更新與刪除。
• 具有特定 Teams 功能的管道資料，例如提及和會議資訊。
• 支援工作模組的叫用活動。

Microsoft 365 Copilot

• 主要著重於訊息活動。
• 支援在回應中使用引文與參考資料。
• 需要串流回應。
• 對豐富卡片及調適型卡片的支援有限。

網頁聊天/DirectLine

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

• 完整支援所有活動類型。
• 支援自訂通道資料。

非 Microsoft 通道

這些通道包括 Slack、Facebook 等。

• 對於特定活動類型的支援可能有限。
• 卡片轉譯方式可能不同，或不受支援。
• 請務必查閱特定通道的相關文件。

後續步驟

• 了解 AgentApplication