了解活动协议

活动协议是一种标准通信协议，广泛应用于 Microsoft 的许多 SDK、服务和客户端中。活动协议可由智能智能 Microsoft 365 Copilot 副驾驶® 副驾驶®、Microsoft Copilot Studio、Microsoft Teams 和 Microsoft 365 智能体 SDK 使用。? 活动协议定义 Activity 的结构，以及消息、活动和交互如何从渠道流向您的代码以及其间的任何其他位置。智能体可以连接到一个或多个渠道，以与用户交互并与其他智能体协同工作。活动协议标准化您正在使用的任何客户端（包括 Microsoft 和非 Microsoft 客户端）的通信协议，因此您无需为每个渠道创建自定义逻辑。

什么是活动？

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 智能体 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：回合的状态

活动类型

活动的类型可定义活动在客户端、用户和智能体之间所需或期望的剩余部分。

其中包括：

消息
ConversationUpdate
活动
调用
Typing

消息

一种常见的活动类型是消息类型的 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

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 等。此外，重要的是要知道，这些 URL 通常有效时间很短，所以不要假设 URL 长时间有效。正因为此限制，如果您需要以后查阅内容，将其移至自己的存储非常重要。

引文

重要的是要知道，附件和引用不是相同的对象类型。客户端（例如 Microsoft Teams）以自己的方式处理引用。它们使用 Activity 的实体属性。您可以添加具有 activity.Entities.Add 的引用，也可以添加一个新的 Entity 对象，该对象基于客户端具有特定的 Citation 定义。它会序列化为 JSON 对象，然后客户端会根据其在客户端中的呈现方式进行反序列化。从根本上讲，附件是消息，而引用可以引用附件，并且是 Activity 有效负载 Entities 中发送的另一个对象。

渠道特定考量

Microsoft 365 智能体 SDK 作为一个“中心”生成，开发人员可以使用它创建可与任何客户端（包括我们支持的客户端）协同工作的智能体。它为开发人员提供使用相同框架生成自己的渠道适配器的工具。这种架构为开发人员提供了广泛的智能体选择，并为客户端提供了可扩展性以连接到该中心，该中心可以是一个或多个客户端，如 Microsoft Teams、Slack 等。

不同渠道具有不同的功能和限制。

您可以通过检查 Activity 中的 channelId 属性，检查从中收到活动的渠道。

渠道包含不符合所有渠道中通用 Activity 有效负载的特定数据。您可以通过将其转换为变量来访问 TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) 属性中的数据，以便在代码中使用。

以下部分汇总了使用常见客户端时的注意事项。

Microsoft Teams

支持具有高级功能的丰富自适应卡片。
支持消息更新和删除。
包含 Teams 功能的特定频道数据，例如提及和会议信息。
支持任务模块的调用操作。

智能智能 Microsoft 365 Copilot 副驾驶® 副驾驶®

主要侧重于消息活动。
在回复中支持引用和参考。
需要流式回复。
对丰富卡片和自适应卡片的支持有限。

Web 聊天/DirectLine

Web 聊天是一种 HTTP 协议，智能体可以使用该协议通过 HTTPS 进行通信。

对所有活动类型的完全支持。
支持自定义渠道数据。

非 Microsoft 渠道

这些渠道包括 Slack、Facebook 等。

对某些活动类型的支持可能有限。
卡片呈现可能有所不同或不受支持。
请务必查阅具体渠道文档。

后续步骤

了解 AgentApplication

反馈

此页面是否有帮助？

Last updated on 2026-07-29