了解代理概念

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

代理范围

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 并在该对象上注册处理程序。
• 处理程序在 TypeScript 中接收类型化上下文对象 (IActivityContext ， IContext<TActivity> 在 C# 中， ActivityContext[TActivity] 在 Python) 。
• 答复和主动消息通过 ctx.reply() 或 ctx.send()发送。

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

注意

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

活动处理程序代码片段

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

TypeScript

代理是使用 @microsoft/teams.apps 包生成的。 使用 实例化 App 并注册处理程序 app.on(eventName, handler)。 SDK 根据事件名称字符串将活动路由到正确的处理程序。

channelCreated

import { App } from '@microsoft/teams.apps';

const app = new App();

app.on('channelCreated', async ({ activity }) => {
  const channel = activity.channelData.channel; // { id, name }
  const team    = activity.channelData.team;    // { id, name }
  // Code logic here
});

channelDeleted

app.on('channelDeleted', async ({ activity }) => {
  // Code logic here
});

channelRenamed

app.on('channelRenamed', async ({ activity }) => {
  // Code logic here
});

teamRenamed

app.on('teamRenamed', async ({ activity }) => {
  // Code logic here
});

membersAdded / membersRemoved

app.on('membersAdded', async ({ activity, send }) => {
  for (const member of activity.membersAdded) {
    await send(`Welcome, ${member.name}!`);
  }
});

app.on('membersRemoved', async ({ activity }) => {
  // Code logic here
});

messageUpdate / messageDelete

消息编辑显示为 messageUpdate。 软删除 messageDelete 显示为 - activity.channelData.eventType 将为 'softDeleteMessage'。

app.on('messageUpdate', async ({ activity }) => {
  // Code logic here
});

app.on('messageDelete', async ({ activity }) => {
  // activity.channelData.eventType === 'softDeleteMessage' for soft deletes
  // Code logic here
});

C#

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

OnChannelCreated

using Microsoft.Teams.Apps;

var app = new App();

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

OnChannelDeleted

app.OnChannelDeleted(async context => {
    // Code logic here
});

OnChannelRenamed

app.OnChannelRenamed(async context => {
    // Code logic here
});

OnTeamRenamed

app.OnTeamRenamed(async context => {
    // Code logic here
});

OnMembersAdded

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

OnMembersRemoved

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

OnMessageUpdate / OnMessageDelete

通过 处理 OnMessageUpdate消息编辑。 软删除通过 OnMessageDelete进行处理。

app.OnMessageUpdate(async context => {
    // Code logic here
});

app.OnMessageDelete(async context => {
    // Code logic here
});

Python

代理是使用 microsoft-teams-apps 包生成的。 处理程序是在实例上使用修饰器注册的 App 。 每个处理程序都是一个 async 接收 ActivityContext[TActivity] 对象的函数。

on_channel_created

from microsoft_teams.apps import App, ActivityContext
from microsoft_teams.api.activities import ConversationUpdateActivity

app = App()

@app.on_channel_created
async def handle_channel_created(ctx: ActivityContext[ConversationUpdateActivity]):
    channel = ctx.activity.channel_data.channel
    team    = ctx.activity.channel_data.team
    # Code logic here

on_channel_deleted

@app.on_channel_deleted
async def handle_channel_deleted(ctx: ActivityContext[ConversationUpdateActivity]):
    # Code logic here

on_channel_renamed

@app.on_channel_renamed
async def handle_channel_renamed(ctx: ActivityContext[ConversationUpdateActivity]):
    # Code logic here

on_team_renamed

@app.on_team_renamed
async def handle_team_renamed(ctx: ActivityContext[ConversationUpdateActivity]):
    # Code logic here

on_conversation_update 添加/删除) (成员

添加和删除事件的成员通过 on_conversation_update进行处理。 检查 ctx.activity.members_added 和 ctx.activity.members_removed：

@app.on_conversation_update
async def handle_conversation_update(ctx: ActivityContext[ConversationUpdateActivity]):
    if ctx.activity.members_added:
        for member in ctx.activity.members_added:
            await ctx.send(f"Welcome, {member.name}!")
    if ctx.activity.members_removed:
        # Code logic here

on_edit_message / on_soft_delete_message / on_undelete_message

@app.on_edit_message
async def handle_edit_message(ctx: ActivityContext):
    # Code logic here

@app.on_soft_delete_message
async def handle_soft_delete_message(ctx: ActivityContext):
    # Code logic here

@app.on_undelete_message
async def handle_undelete_message(ctx: ActivityContext):
    # Code logic here

代理活动处理程序示例

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

TypeScript

import { App } from '@microsoft/teams.apps';

const app = new App();

app.on('message', async ({ activity, reply }) => {
  const senderName = activity.from.name;
  await send(`Hello <at>${senderName}</at>.`);
});

app.start().catch(console.error);

C#

using Microsoft.Teams.Apps.Activities;
using Microsoft.Teams.Apps.Extensions;
using Microsoft.Teams.Plugins.AspNetCore.DevTools.Extensions;
using Microsoft.Teams.Plugins.AspNetCore.Extensions;

var builder = WebApplication.CreateBuilder(args);
builder.AddTeams().AddTeamsDevTools();
var app = builder.Build();
var teams = app.UseTeams();

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

app.Run();

Python

import asyncio
from microsoft_teams.apps import App, ActivityContext
from microsoft_teams.api import MessageActivity

app = App()

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    sender_name = ctx.activity.from_property.name
    await ctx.send(f"Hello <at>{sender_name}</at>.")

if __name__ == "__main__":
    asyncio.run(app.start())

代理逻辑

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

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

TypeScript

核心活动处理程序

支持 app.on() 的事件名称列表包括：

事件	事件名称字符串	说明
收到的任何活动类型	'activity'	为每个活动调用的捕获全部处理程序。
收到的消息活动	'message'	处理传入的文本消息。 用于 app.message(pattern, handler) 正则表达式匹配。
已收到对话更新	'conversationUpdate'	原始对话更新活动。
已添加安装	'install.add'	已安装代理。
已删除安装	'install.remove'	代理已卸载。
已添加成员。	'membersAdded'	一个或多个成员加入了对话。
已删除成员	'membersRemoved'	一个或多个成员离开了对话。
已编辑的邮件	'messageUpdate'	对话中的消息已编辑。
软删除的消息	'messageDelete'	邮件 () activity.channelData.eventType === 'softDeleteMessage' 软删除。
已收到已读回执	'readReceipt'	已收到已读回执。

特定于 Teams 的事件处理程序

app.on() 支持以下特定于 Teams 的事件名称字符串：

事件	事件名称字符串	说明
channelCreated	'channelCreated'	已创建 Teams 频道。
channelDeleted	'channelDeleted'	Teams 频道已删除。
channelRenamed	'channelRenamed'	Teams 频道已重命名。
channelRestored	'channelRestored'	Teams 频道已还原。
channelMemberAdded	'channelMemberAdded'	已将成员添加到频道。
channelMemberRemoved	'channelMemberRemoved'	已从频道中删除成员。
teamRenamed	'teamRenamed'	团队已重命名。
teamArchived	'teamArchived'	该团队已存档。
teamDeleted	'teamDeleted'	团队已删除。
teamRestored	'teamRestored'	团队已恢复。
会议已启动	'meetingStart'	会议已开始。
会议已结束	'meetingEnd'	会议已结束。
参与者已加入	'meetingParticipantJoin'	参与者已加入会议。
参与者左	'meetingParticipantLeave'	参与者离开了会议。

Teams 调用活动

下表列出了通过 app.on()提供的调用活动处理程序：

调用类型	事件名称字符串	说明
CardAction.Invoke	'card.action'	) (收到卡adaptiveCard/action操作调用活动。
signin/verifyState	由 SDK (OAuth 流自动处理)	登录验证状态活动。
task/fetch	'dialog.open'	已提取 (任务模块) 的对话。
task/submit	'dialog.submit'	提交) (任务模块的对话。

C#

核心活动处理程序

类 App 公开用于注册处理程序的扩展方法。 方法返回 App fluent chaining。

事件	扩展方法	说明
收到的任何活动类型	OnActivity(handler)	为每个活动调用的捕获全部处理程序。
收到的消息活动	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 流自动处理)	登录验证状态活动。

Python

核心活动处理程序

类 App 公开修饰器样式处理程序注册。

事件	装饰	说明
收到的任何活动	@app.on_activity	每个活动的捕获全部处理程序。
收到的消息	@app.on_message	处理传入的文本消息。
具有模式的消息	@app.on_message_pattern(re.compile(...))	处理与正则表达式模式匹配的消息。
对话更新	@app.on_conversation_update	原始对话更新;members_added / members_removed检查 。
已添加安装	@app.on_install_add	已安装代理。
已删除安装	@app.on_install_remove	代理已卸载。

特定于 Teams 的活动处理程序

事件	装饰	说明
已创建频道	@app.on_channel_created	已创建 Teams 频道。
已删除频道	@app.on_channel_deleted	Teams 频道已删除。
已重命名频道	@app.on_channel_renamed	Teams 频道已重命名。
已重命名团队	@app.on_team_renamed	团队已重命名。
已编辑的邮件	@app.on_edit_message	已编辑消息。
软删除的消息	@app.on_soft_delete_message	邮件已软删除。
取消删除的消息	@app.on_undelete_message	已删除的消息已还原。
会议已启动	@app.on_meeting_start	会议已开始。
会议已结束	@app.on_meeting_end	会议已结束。
参与者已加入	@app.on_meeting_participant_join	参与者已加入会议。
参与者左	@app.on_meeting_participant_leave	参与者离开了会议。

Teams 调用活动

调用类型	装饰	说明
CardAction.Invoke	@app.on_card_action	收到卡操作调用活动。
task/fetch	@app.on_dialog_open	已提取 (任务模块) 的对话。
task/submit	@app.on_dialog_submit	提交) (任务模块的对话。
fileConsent/invoke	@app.on_file_consent	收到文件同意卡活动。
signin/verifyState	由 SDK (OAuth 流自动处理)	登录验证状态活动。

现在，你已熟悉代理活动处理程序，让我们看看代理如何根据会话及其接收或发送的消息以不同的方式运行。

建议

代理与用户之间的广泛对话是完成任务的一种缓慢而复杂的方法。 支持过多命令（尤其是各种命令）的代理不会成功或被用户正面查看。

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

  用户：安排与 Megan 的会议。

  代理：我发现了 200 个结果，包括名字和姓氏。

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

  特工：好吧，你想什么时间和梅根·鲍文见面？

  用户：下午 1：00。

  代理：哪一天？

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

• 优化知识库的大小以加快交互速度 代理的一个缺点是，很难使用未调和的响应维护大型检索知识库。 代理最适合进行简短的快速交互，而不是通过长列表筛选来寻找答案。

注意

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

探索其他代理功能

除了传统的代理功能，还可以探索 Teams 代理应用中提供的高级功能：

• 获取代理的 Teams 特定上下文。
• 呼叫和联机会议代理。
• 为应用启用 SSO。

代码示例

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