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

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

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

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

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

В канале

Каналы содержат потоковые беседы между несколькими людьми, даже до 2000. Это потенциально дает вашему агенту огромный охват, но отдельные взаимодействия должны быть краткими. Традиционные многоэтапные взаимодействия не работают. Вместо этого необходимо использовать интерактивные карточки или диалоги (называемые модулями задач в TeamsJS версии 1.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 для событий жизненного цикла канала и команды.

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 пакета. Вы создаете 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
});

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

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

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

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

TypeScript

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

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

Событие	Строка имени события	Описание
Любой полученный тип действия	'activity'	Обработчик catch-all вызывается для каждого действия.
Получено действий с сообщением	'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 для беглой цепочки.

Событие	Метод расширения	Описание
Любой полученный тип действия	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)	При входе проверьте действие состояния.

Python

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

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

Событие	Декоратор	Описание
Любое полученное действие	@app.on_activity	Обработчик catch-all для каждого действия.
Получено сообщение	@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)	При входе проверьте действие состояния.

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

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

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

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

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

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

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

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

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

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

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

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

Примечание.

Платформа Teams поддерживает только tls версии 1.2. Убедитесь, что среда агента настроена соответствующим образом.

Изучение других функций агента

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

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

Пример кода

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