了解代理概念

代理的交互可以使用文本、语音、图像或视频。 它处理用户的输入以了解他们的请求,并评估输入以执行相关任务。 代理可以请求信息或启用对服务的访问,并响应用户。

代理作用域

Microsoft Teams 中的代理可以是一对一对话、群组聊天或团队中频道的一部分。 每个范围都为您的对话代理提供了独特的机遇和挑战。

在频道中 在群组聊天中 在一对一聊天中
广阔的范围 成员数减少 传统方式
简洁的个人交互 @mention 代理 Q&A 代理
@mention 代理 类似于频道 讲笑话和做笔记的智能体

在频道中

频道包含多人之间的线程对话,甚至最多 2000 人。 这可能会为您的代理提供广泛的覆盖范围,但个人互动必须简洁。 传统的多轮次交互不起作用。 相反,必须在 TeamsJS v1.x) 中使用交互式卡片或对话框 (称为任务模块,或者将对话移动到一对一对话以收集大量信息。 您的代理只能访问位于其中的消息。@mentioned 可以使用 Microsoft Graph 和组织级别权限从对话中检索额外的消息。

在以下情况下,代理在频道中工作效果更好:

  • 通知,特别是在为用户提供交互卡以便获取额外信息时。
  • 像投票和调查这样的反馈场景。
  • 单个请求或响应周期可解决交互,结果对多个成员对话非常有用。
  • 社交或有趣的代理商,您可以在其中获得很棒的猫图像,随机选择获胜者,等等。

在群组聊天中

群聊是在三个及以上人员之间进行的非按线索组织的对话。 其中的成员一般比频道中的少且更短暂。 与频道类似,您的代理只能直接访问消息 @mentioned 。

在频道中工作得更好的代理在群聊中也工作得更好。

在一对一聊天中

一对一聊天是对话代理与用户交互的传统方式。 一对一对话代理的几个示例如下:

  • Q&A 代理
  • 在其他系统中启动工作流的代理。
  • 讲笑话的特工。
  • 做笔记的代理。 在创建一对一代理之前,请考虑基于对话的界面是否是展示功能的最佳方式。

活动处理程序和代理逻辑

要创建满足您需求的代理应用程序,了解 Microsoft Teams 活动处理程序和代理逻辑至关重要。 这两个关键组件协同工作来组织对话逻辑。

  • Teams 活动处理程序:处理特定于 Teams 的事件和交互,例如频道创建、团队成员添加以及 Teams 环境特有的其他操作。 在 Teams SDK v2 中,处理程序直接在实例上 App 注册,而不是通过类继承注册。

  • 代理逻辑:对象 App 包含代理的对话逻辑,负责根据用户输入做出决策。 传入活动将根据活动类型和可选模式匹配路由到相应的处理程序。

Teams 活动处理程序

活动处理程序是代理功能的核心,管理和处理用户交互。 在 Teams SDK v2 中:

  • 实例化 App 对象并在其上注册处理程序。
  • 处理程序在 TypeScriptIContext<TActivity>、C# ActivityContext[TActivity] 和 Python) 中接收类型化上下文对象 (IActivityContext。
  • 回复和主动消息通过 ctx.reply() or 发送 ctx.send()。

当 Teams 代理收到活动时,SDK 将通过注册的处理程序路由它。 频道生命周期、成员更改等 (特定于 Teams 的事件 ) 显示为不同的命名事件,因此无需手动检查 channelData.eventType 。

注意

如果代理活动的处理时间超过 15 秒,Teams 将向代理终结点发送重试请求,因此你可能会看到重复请求。

活动处理程序代码片段

以下代码段展示了频道和团队生命周期事件的 Teams 活动处理程序。

代理是使用该 Microsoft.Teams.Apps 包生成的。 您可以使用扩展方法(如 OnMessage()、 等OnChannelCreated())实例化和App链处理程序注册。所有处理程序都会接收一个IContext<TActivity>对象。

OnChannelCreated

using Microsoft.Teams.Apps;

WebApplicationBuilder builder = WebApplication.CreateSlimBuilder(args);
builder.Services.AddTeamsBotApplication();

WebApplication app = builder.Build();
TeamsBotApplication teams = app.UseTeamsBotApplication();

teams.OnChannelCreated(async (context, cancellationToken) =>
{
    var channel = context.Activity.ChannelData.Channel;
    var team    = context.Activity.ChannelData.Team;
    // Code logic here
});

OnChannelDeleted

teams.OnChannelDeleted(async (context, cancellationToken) =>
{
    // Code logic here
});

OnChannelRenamed

teams.OnChannelRenamed(async (context, cancellationToken) =>
{
    // Code logic here
});

OnTeamRenamed

teams.OnTeamRenamed(async (context, cancellationToken) =>
{
    // Code logic here
});

OnMembersAdded

teams.OnMembersAdded(async (context, cancellationToken) =>
{
  foreach (var member in context.Activity.MembersAdded)
  {
        // Code logic here
    }
});

OnMembersRemoved

teams.OnMembersRemoved(async (context, cancellationToken) =>
{
  foreach (var member in context.Activity.MembersRemoved)
  {
        // Code logic here
    }
});

OnMessageUpdate / OnMessageDelete

邮件编辑通过 OnMessageUpdate进行处理。 软删除通过 OnMessageDelete进行处理。

teams.OnMessageUpdate(async (context, cancellationToken) =>
{
    // Code logic here
});

teams.OnMessageDelete(async (context, cancellationToken) =>
{
    // Code logic here
});

代理活动处理程序示例

以下代码提供了代理活动的示例:

using Microsoft.Teams.Apps;

WebApplicationBuilder builder = WebApplication.CreateSlimBuilder(args);
builder.Services.AddTeamsBotApplication();

WebApplication app = builder.Build();
TeamsBotApplication teams = app.UseTeamsBotApplication();

teams.OnMessage(async (context, cancellationToken) =>
{
    var senderName = context.Activity.From.Name;
    await context.SendAsync($"Hello <at>{senderName}</at>.", cancellationToken);
});

app.Run();

代理逻辑

代理逻辑包含决定代理行动和交互的基本规则和决策框架。 它概述了代理如何解释用户输入、制定响应和参与对话。

在 Teams SDK v2 中,代理逻辑处理来自一个或多个代理频道的传入活动并生成传出活动。 所有活动路由都由 App 实例处理 - 你注册处理程序,SDK 会自动将活动调度到它们。

核心活动处理程序

此类 App 公开用于注册处理程序的扩展方法。 用于流畅链接的方法返回 App 。

事件 扩展方法 说明
收到的任何活动类型 OnActivity(handler) 为每个活动调用的 Catch-all 处理程序。
收到的消息活动 OnMessage(handler) 处理传入文本消息。 将正则表达式字符串作为模式匹配的第一个参数传递。
已接收对话更新 OnConversationUpdate(handler) 原始对话更新活动。
非代理成员加入 OnMembersAdded(handler) 触发时间 MembersAdded.Length > 0。
非代理成员离开 OnMembersRemoved(handler) 触发时间 MembersRemoved.Length > 0。
已添加安装 OnInstall(handler) 代理已安装。

特定于 Teams 的活动处理程序

事件 扩展方法 说明
已创建频道 OnChannelCreated(handler) 创建了 Teams 频道。
已删除频道 OnChannelDeleted(handler) 已删除 Teams 频道。
已重命名频道 OnChannelRenamed(handler) 重命名了 Teams 频道。
已重命名团队 OnTeamRenamed(handler) 该团队已更名。
已编辑消息 OnMessageUpdate(handler) 已编辑消息。
软删除的消息 OnMessageDelete(handler) 已软删除一封邮件。

Teams 调用活动

调用类型 扩展方法 说明
CardAction.Invoke OnExecuteAction(handler) 收到卡操作调用活动。
task/fetch OnTaskFetch(handler) 已提取任务模块) (对话框。
task/submit OnTaskSubmit(handler) 已提交任务模块) (对话框。
fileConsent/invoke OnFileConsent(handler) 已收到文件同意卡活动。
signin/verifyState 由 SDK 自动处理 (OAuth 流) 登录验证状态活动。

现在您已经熟悉了代理活动处理程序,让我们看看代理的行为如何根据对话及其接收或发送的消息而有所不同。

建议

您的代理和用户之间的广泛对话是完成任务的一种缓慢而复杂的方式。 支持过多命令(尤其是范围广泛的命令)的代理不会成功,也不会受到用户的积极评价。

  • 避免聊天中的多轮体验 广泛的对话需要开发者维护状态。 若要退出此状态,用户必须超时或选择 “取消”。 此外,这个过程也很繁琐。 例如,请查看以下对话方案:

    用户:安排与 Megan 的会议。

    代理人:我找到了 200 个结果,包括名字和姓氏。

    用户:安排与 Megan Bowen 的会面。

    经纪人:好的,你想什么时候和Megan Bowen见面?

    用户:下午 1:00。

    代理人:哪一天?

  • 支持六个或更少的频率命令 由于当前代理菜单中只有六个可见命令,因此不太可能以任何频率使用更多命令。 深入特定领域的代理而不是试图成为广泛的助手,工作和表现更好。

  • 优化知识库的大小以加快交互速度 代理的缺点之一是很难维护具有未排名响应的大型检索知识库。 代理最适合简短、快速的交互,而不是在长长的列表中寻找答案。

注意

Teams 平台仅支持传输层安全性 (TLS) 版本 1.2。 确保相应地配置代理环境。

探索其他代理功能

除了传统的智能体功能,还可以浏览 Teams 智能体应用中提供的高级功能:

代码示例

示例名称 Description TypeScript C# Python
Teams 对话代理 此应用演示基本代理事件。 View View View