Общие сведения о концепциях агентов

Агент может взаимодействовать с помощью текста, речи, изображений или видео. Он обрабатывает вводимые пользователем данные, чтобы понять их запросы, и оценивает вводимые данные для выполнения соответствующих задач. Агент может запрашивать информацию или предоставлять доступ к службам, а также отвечает пользователю.

Области агентов

Агенты в Microsoft Teams могут участвовать в индивидуальных беседах, групповых чатах и каналах команд. Каждый область предоставляет уникальные возможности и проблемы для вашего разговорного агента.

В канале	В групповом чате	В индивидуальном чате
Огромный охват	Меньше участников	Традиционный способ
Краткие индивидуальные взаимодействия	@mention к агенту	Агенты Q&A
@mention к агенту	Похожий на канал	Агенты, которые рассказывают анекдоты и делают заметки

В канале

Каналы содержат цепочки бесед между несколькими людьми, даже до 2000. Это потенциально дает вашему оператору огромный охват, но индивидуальные взаимодействия должны быть лаконичными. Традиционные взаимодействия с несколькими поворотами не работают. Вместо этого вы должны использовать интерактивные карточки или диалоговые окна (называемые модулями задач в TeamsJS v1.x) или перевести разговор в индивидуальную беседу, чтобы собрать много информации. Ваш агент имеет доступ только к тем сообщениям, в которых он @mentioned. Вы можете получить дополнительные сообщения из беседы с помощью Microsoft Graph и разрешений на уровне организации.

Агенты лучше работают в канале в следующих случаях:

• Уведомления, где вы предоставляете пользователям интерактивную карту для получения дополнительной информации.
• Сценарии обратной связи, такие как опросы и исследования.
• Взаимодействия, решения которых можно получить в одном цикле из запроса и ответа, и результаты которых будут полезны для нескольких участников беседы.
• Социальные или веселые агенты, где вы получаете потрясающий образ кота, случайным образом выбираете победителя и так далее.

В групповом чате

Групповые чаты — это не потоковые беседы между тремя или более пользователями. Как правило, у них меньше участников, чем у канала, и они более временные. Как и в канале, ваш агент имеет доступ только к сообщениям, где он находится @mentioned напрямую.

Агенты, которые лучше работают в канале, также лучше работают в групповом чате.

В индивидуальном чате

Индивидуальный чат — это традиционный способ взаимодействия агента беседы с пользователем. Вот несколько примеров индивидуальных разговорных агентов.

• Агенты Q&A
• Агенты, инициирующие рабочие процессы в других системах.
• Агенты, которые рассказывают анекдоты.
• Агенты, которые делают заметки. Прежде чем создавать индивидуальных агентов, подумайте, является ли интерфейс на основе беседы лучшим способом представить ваши функциональные возможности.

Обработчик действий и логика агента

Чтобы создать приложение агента, отвечающее вашим потребностям, важно понимать обработчик действий Microsoft Teams и логику агента. Эти два ключевых компонента работают вместе, чтобы организовать логику диалога.

• Обработчик действий Teams: обрабатывает события и взаимодействия, относящиеся к Teams, такие как создание канала, добавление участников команды и другие действия, уникальные для среды Teams. В пакете SDK для Teams версии 2 обработчики регистрируются непосредственно в экземпляре App , а не через наследование классов.

• Логика агента: App объект содержит логику разговора агента и отвечает за принятие решений на основе ввода данных пользователем. Входящие действия направляются в соответствующий обработчик на основе типа действия и необязательного совпадения в шаблоне.

Обработчик действий Teams

Обработчик действий — это основа функциональности агента, управляющая и обрабатывающая взаимодействия с пользователем. В пакете SDK для Teams версии 2:

• Вы создаете App экземпляр объекта и регистрируете для него обработчики.
• Обработчики получают типизированный объект контекста (IActivityContext в TypeScript, IContext<TActivity> C#, ActivityContext[TActivity] Python).
• Ответы и упреждающие сообщения отправляются с помощью ctx.reply() или ctx.send().

Когда агент Teams получает действие, пакет SDK направляет его через зарегистрированный обработчик. События, относящиеся к Teams (жизненный цикл канала, изменения участников и т. д.), отображаются в виде событий с отдельными именами, поэтому вам не нужно проверять их channelData.eventType вручную.

Примечание.

Если обработка действия агента занимает более 15 секунд, Teams отправляет запрос на повторную попытку в конечную точку агента, поэтому вы можете увидеть повторяющиеся запросы.

Фрагменты кода обработчика действий

В следующих фрагментах показаны обработчики действий Teams для событий жизненного цикла канала и команды.

C# SDK версии 2.1

Агенты создаются с помощью этого пакета Microsoft.Teams.Apps . Вы создаете экземпляр регистрации обработчика и App цепочки с помощью методов расширения, таких как OnMessage(), OnChannelCreated(), и т. д. Все обработчики получают 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
});

C# SDK<2.1 (устаревшая версия)

Агенты создаются с помощью этого пакета Microsoft.Teams.Apps . Вы создаете экземпляр регистрации обработчика и App цепочки с помощью методов расширения, таких как OnMessage(), OnChannelCreated(), и т. д. Все обработчики получают 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
});

TypeScript

Агенты создаются с помощью этого пакета @microsoft/teams.apps . Создание экземпляра обработчиков app.on(eventName, handler)an App и register с помощью . 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
});

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

Пример обработчика действий агента

В приведенном ниже коде приведен пример действия агента:

C# SDK версии 2.1

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();

C# SDK<2.1 (устаревшая версия)

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();

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);

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())

Логика агента

Логика агента включает в себя фундаментальные правила и структуры принятия решений, которые диктуют действия и взаимодействия агента. В нем описано, как агент интерпретирует вводимые пользователем данные, формулирует ответы и участвует в беседах.

В пакете SDK для Teams версии 2 логика агента обрабатывает входящие действия из одного или нескольких каналов агента и создает исходящие действия. Вся маршрутизация активности обрабатывается инстансом App — вы регистрируете обработчиков, и SDK автоматически отправляет им действия.

C#

Обработчики основных действий

Класс App предоставляет методы расширения для регистрации обработчиков. Методы возвращаются App для беглой цепочки.

Событие	Метод расширения	Описание
Любой полученный тип действия	OnActivity(handler)	Универсальный обработчик, вызываемый для каждого действия.
Получено действий с сообщением	OnMessage(handler)	Обработка входящих SMS. Передайте строку регулярного выражения в качестве первого аргумента для сопоставления с шаблоном.
Получено обновление беседы	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)	Войдите и проверьте действия штата.

TypeScript

Обработчики основных действий

Список поддерживаемых app.on() имен событий включает в себя следующее:

Событие	Строка имени события	Описание
Любой полученный тип действия	'activity'	Универсальный обработчик, вызываемый для каждого действия.
Получено действий с сообщением	'message'	Обработка входящих SMS. Используется 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'	Диалоговое окно (модуль задач) было отправлено.

Python

Обработчики основных действий

Класс App представляет регистрацию обработчика в стиле декоратора.

Событие	Декоратор	Описание
Все полученные действия	@app.on_activity	Универсальный обработчик для каждого действия.
Сообщение получено	@app.on_message	Обработка входящих SMS.
Сообщение с шаблоном	@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)	Войдите и проверьте действия штата.

Теперь, когда вы ознакомились с обработчиками действий агентов, давайте посмотрим, как агенты ведут себя по-разному в зависимости от беседы и сообщений, которые она получает или отправляет.

Рекомендации

Продолжительный диалог между агентом и пользователем — это медленный и сложный способ выполнить задачу. Агент, поддерживающий лишние команды, особенно широкий спектр команд, не будет успешным или не будет положительно воспринят пользователями.

• Избегайте многооборотных интерфейсов в чате Обширное диалоговое окно требует от разработчика поддержания состояния. Чтобы выйти из этого состояния, пользователь должен либо выйти из него, либо выбрать команду "Отмена". К тому же процесс утомительный. Рассмотрим следующий сценарий разговора:

  ПОЛЬЗОВАТЕЛЬ: назначь встречу с Меган.

  АГЕНТ: Я нашел 200 результатов, включая имя и фамилию.

  ПОЛЬЗОВАТЕЛЬ: назначь встречу с Меган Боуэн.

  АГЕНТ: Хорошо, в какое время вы хотели бы встретиться с Меган Боуэн?

  ПОЛЬЗОВАТЕЛЬ: 13:00.

  АГЕНТ: В какой день?

• Поддержка шести или менее частых команд Поскольку в текущем меню агента всего шесть видимых команд, что-либо еще вряд ли будет использоваться с какой-либо частотой. Агенты, которые углубляются в определенную область, а не пытаются быть широкими помощниками, работают и чувствуют себя лучше.

• Оптимизация размера базы знаний для более быстрого взаимодействия Одним из недостатков агентов является то, что трудно поддерживать большую извлеченную базу знаний с неранжированными ответами. Операторы лучше всего подходят для коротких и быстрых взаимодействий, а не для поиска ответа по длинным спискам.

Примечание.

Платформа Teams поддерживает только протокол TLS версии 1.2. Настройте среду агента соответствующим образом.

Ознакомьтесь с другими функциями агента

Помимо обычных функций агента, можно также изучить дополнительные функции, доступные в приложении агента Teams:

• Получите контекст Teams для вашего агента.
• Агенты звонков и собраний по сети.
• Включите единый вход для приложения.

Пример кода

Название примера	Описание	TypeScript	C#	Python
Агент беседы Teams	Это приложение демонстрирует основные события агента.	Просмотр	Просмотр	Просмотр