Беседы, инициируемые событиями, с помощью обработчика активности

ОБЛАСТЬ ПРИМЕНЕНИЯ: ПАКЕТ SDK версии 4

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

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

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

Примечание.

Чтобы создавать агенты с помощью выбранной службы ИИ, оркестрации и знаний, рекомендуется использовать пакет SDK для агентов Microsoft 365. Пакет SDK для агентов поддерживает C#, JavaScript или Python. Дополнительные сведения о пакете SDK для агентов см. в aka.ms/agents. Если вы ищете платформу агента на основе SaaS, рассмотрите microsoft Copilot Studio. Если у вас есть существующий бот, созданный с помощью пакета SDK Bot Framework, вы можете обновить бота до пакета SDK для агентов. Вы можете ознакомиться с основными изменениями и обновлениями в руководстве по миграции с Bot Framework SDK на SDK для агентов. Запросы на поддержку пакета SDK Bot Framework больше не будут обслуживаться с 31 декабря 2025 г.

C#

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

Существуют некоторые ситуации, когда вы хотите переопределить базовый обработчик поворота, например сохранение состояния в конце поворота. Перед этим обязательно вызовите await base.OnTurnAsync(turnContext, cancellationToken);, чтобы убедиться, что базовая реализация OnTurnAsync выполняется перед дополнительным кодом. Эта базовая реализация, помимо прочего, отвечает за вызов остальных обработчиков действий, таких как OnMessageActivityAsync.

JavaScript

JavaScript использует шаблон передатчика и прослушивателя событий ActivityHandler. Например, метод onMessage позволяет зарегистрировать прослушиватель событий для обработки сообщений. Вы можете зарегистрировать несколько прослушивателей. Когда бот получает сообщение activity, обработчик активности видит входящее действие и отправляет его каждому из слушателей активности onMessage в том порядке, в котором они были зарегистрированы.

При создании вашего бота логику обработки сообщений и реагирования на них следует помещать в прослушиватели onMessage. Аналогичным образом, логика обработки участников, добавляемых в беседу, размещается в ваших прослушивателях onMembersAdded, которые вызываются при каждом добавлении участника в беседу. Чтобы добавить эти прослушиватели, зарегистрируйте их в вашем боте, как показано в разделе логики бота ниже. Добавьте вашу логику бота для каждого слушателя, затем не забудьте вызвать next() в конце. При вызове next()убедитесь, что следующий прослушиватель запущен.

Убедитесь, что состояние сохранено перед завершением хода. Для этого переопределите метод обработчика действий run и сохраните состояние после завершения родительского метода run.

Нет обычных ситуаций, когда вы хотите изменить обработчик базового поворота, поэтому будьте осторожны, если попытаетесь сделать это. Специальный обработчик называется onDialog. Обработчик onDialog выполняется в конце, после выполнения остальных обработчиков и не привязан к определенному типу действия. Как и для всех упомянутых выше обработчиков, обязательно вызовите next(), чтобы завершить процесс.

Ява

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

Существуют некоторые ситуации, когда вы хотите переопределить базовый обработчик поворота, например сохранение состояния в конце поворота. При этом необходимо сначала вызвать super.onTurn(turnContext);, чтобы убедиться, что базовая реализация onTurn выполнена, прежде чем добавлять дополнительный код. Эта базовая реализация, помимо прочего, отвечает за вызов остальных обработчиков действий, таких как onMessageActivity.

Питон

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

Например, если бот получает активность сообщений, обработчик хода распознает эту входящую активность и затем отправляет ее в обработчик активности on_message_activity.

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

Существуют некоторые ситуации, когда вы хотите переопределить базовый обработчик поворота, например сохранение состояния в конце поворота. Перед этим обязательно вызовите await super().on_turn(turnContext);, чтобы убедиться, что базовая реализация on_turn выполняется перед дополнительным кодом. Эта базовая реализация, помимо прочего, отвечает за вызов остальных обработчиков действий, таких как on_message_activity.

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

Логика бота обрабатывает входящие действия из одного или нескольких каналов и создает исходящие действия в ответ.

C#

Основная логика бота определяется в коде бота. Чтобы реализовать бота как обработчик действий, унаследуйте свой класс бота от ActivityHandler, который реализует IBot интерфейс. ActivityHandler определяет различные обработчики для различных типов действий, таких как OnMessageActivityAsync, и OnMembersAddedAsync. Эти методы защищены, но могут быть переопределены, так как мы наследуем от ActivityHandler.

Ниже описаны обработчики, определенные в ActivityHandler:

Мероприятие	Обработчик	Описание
Любой вид полученной активности	OnTurnAsync	Вызывает один из других обработчиков, основываясь на типе полученной активности.
Полученная активность сообщения	OnMessageActivityAsync	Переопределите это, чтобы обработать действие message.
Получена активность обновления беседы	OnConversationUpdateActivityAsync	В действии conversationUpdate вызывает обработчик, если участники, кроме бота, присоединились к беседе или покинули её.
Участники, не являющиеся ботами, присоединились к беседе	OnMembersAddedAsync	Переопределите это, чтобы обрабатывать участников, присоединяющихся к беседе.
Участники, которые не являются ботами, покинули беседу.	OnMembersRemovedAsync	Переопределите это, чтобы обрабатывать случаи, когда участники покидают беседу.
Получена активность события	OnEventActivityAsync	В действии event вызывает обработчик для события определенного типа.
Получена активность события отклика маркера	OnTokenResponseEventAsync	Переопределите этот метод для обработки событий ответа токена.
Получено событие активности без токен-ответа	OnEventAsync	Переопределите это, чтобы обрабатывать события других типов.
Получена активность реакции на сообщение	OnMessageReactionActivityAsync	В рамках действия messageReaction вызывает обработчик, если к сообщению были добавлены или из него удалены одна или несколько реакций.
Добавление реакций к сообщению	OnReactionsAddedAsync	Чтобы обрабатывать добавление реакций к сообщению, измените настройки.
Удаление реакции на сообщение из сообщения	OnReactionsRemovedAsync	Переопределите этот метод, чтобы обрабатывать удаление реакций из сообщения.
Получено уведомление о деятельности по обновлению установки	OnInstallationUpdateActivityAsync	В ходе действия installationUpdate вызывается обработчик в зависимости от того, установлен ли или удален бот.
Бот установлен	OnInstallationUpdateAddAsync	Переопределите это, чтобы добавить логику при установке бота в подразделении.
Бот удален	OnInstallationUpdateRemoveAsync	Переопределите это, чтобы добавить логику при удалении бота в подразделении.
Другой тип полученной активности	OnUnrecognizedActivityTypeAsync	Переопределите для обработки любого типа действия, иначе не будет обработано.

Эти разные обработчики используют turnContext для получения сведений о входящем действии, которое соответствует входящему HTTP-запросу. Действия могут быть разных типов, поэтому каждый обработчик предоставляет строго типизированное действие в параметре контекста обращения. В большинстве случаев OnMessageActivityAsync является наиболее распространенным и обычно всегда обрабатывается.

Как и в предыдущих версиях 4.x этой платформы, существует также возможность реализации общедоступного метода OnTurnAsync. Сейчас базовая реализация этого метода выполняет проверку ошибок, а затем вызывает каждый из определенных обработчиков (например те два, которые мы определяем в этом примере) в зависимости от типа входящего действия. В большинстве случаев вы можете оставить этот метод без изменений и использовать отдельные обработчики, но если в вашей ситуации требуется пользовательская реализация OnTurnAsync, это всё ещё остаётся вариантом.

Внимание

При переопределении метода OnTurnAsync вам нужно вызвать base.OnTurnAsync, чтобы получить базовую реализацию для вызова всех остальных обработчиков On<activity>Async. Но вы также можете вызвать эти обработчики самостоятельно. В противном случае эти обработчики не будут вызваны и код не будет выполняться.

JavaScript

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

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

Мероприятие	Метод регистрации	Описание
Любой вид полученной активности	onTurn	Регистрация слушателя, который вызывается при получении любой активности.
Полученная активность сообщения	onMessage	Регистрация прослушивателя, который вызывается при получении действия message.
Получена активность обновления беседы	onConversationUpdate	Регистрирует слушателя, который вызывается при получении любой активности conversationUpdate.
Участники присоединились к беседе	onMembersAdded	Регистрирует слушателя для ситуаций, когда к беседе присоединяется любой участник, включая бота.
Выход участников из беседы	onMembersRemoved	Регистрирует слушателя для ситуаций, когда кто-либо из участников выходит из беседы, включая бота.
Получена активность реакции на сообщение	onMessageReaction	Регистрирует слушателя, который вызывается при получении любой активности messageReaction.
Добавление реакций к сообщению	onReactionsAdded	Регистрирует прослушивателя, когда реакции добавляются к сообщению.
Удаление реакции на сообщение из сообщения	onReactionsRemoved	Регистрирует слушателя для удаления реакций из сообщения.
Получена активность события	onEvent	Регистрирует слушателя, который вызывается при получении любой активности event.
Получена активность события отклика маркера	onTokenResponseEvent	Регистрация слушателя для получения события tokens/response.
Получено уведомление о деятельности по обновлению установки	onInstallationUpdate	Регистрирует слушателя, который вызывается при получении любой активности installationUpdate.
Бот установлен	onInstallationUpdateAdd	Регистрирует слушатель при установке бота в подразделении.
Бот удален	onInstallationUpdateRemove	Регистрирует слушатель для случая, когда бот удаляется внутри подразделения.
Другой тип полученной активности	onUnrecognizedActivityType	Регистрирует слушателя для случаев, когда обработчик для определенного типа действия не определен.
Выполнение обработчиков действий завершено	onDialog	Вызывается после завершения всех применимых обработчиков.

Вызывайте функцию продолжения next из каждого обработчика, чтобы продолжить обработку. Если next не вызывается, обработка действия заканчивается.

Ява

Основная логика бота определяется в коде бота. Чтобы реализовать бота как обработчик действий, унаследуйте свой класс бота от ActivityHandler, который реализует Bot интерфейс. ActivityHandler определяет различные обработчики для различных типов действий, таких как onMessageActivity, и onMembersAdded. Эти методы защищены, но могут быть переопределены, так как мы наследуем от ActivityHandler.

Ниже описаны обработчики, определенные в ActivityHandler:

Мероприятие	Обработчик	Описание
Любой вид полученной активности	onTurn	Вызывает один из других обработчиков, основываясь на типе полученной активности.
Полученная активность сообщения	onMessageActivity	Переопределите это, чтобы обработать действие message.
Получена активность обновления беседы	onConversationUpdateActivity	В действии conversationUpdate вызывает обработчик, если участники, кроме бота, присоединились к беседе или покинули её.
Участники, не являющиеся ботами, присоединились к беседе	onMembersAdded	Переопределите это, чтобы обрабатывать участников, присоединяющихся к беседе.
Участники, которые не являются ботами, покинули беседу.	onMembersRemoved	Переопределите это, чтобы обрабатывать случаи, когда участники покидают беседу.
Получена активность события	onEventActivity	В действии event вызывает обработчик для события определенного типа.
Получена активность события отклика маркера	onTokenResponseEvent	Переопределите этот метод для обработки событий ответа токена.
Получено событие активности без токен-ответа	onEvent	Переопределите это, чтобы обрабатывать события других типов.
Получена активность реакции на сообщение	onMessageReactionActivity	В рамках действия messageReaction вызывает обработчик, если к сообщению были добавлены или из него удалены одна или несколько реакций.
Добавление реакций к сообщению	onReactionsAdded	Чтобы обрабатывать добавление реакций к сообщению, измените настройки.
Удаление реакции на сообщение из сообщения	onReactionsRemoved	Переопределите этот метод, чтобы обрабатывать удаление реакций из сообщения.
Получено уведомление о деятельности по обновлению установки	onInstallationUpdate	В ходе действия installationUpdate вызывается обработчик в зависимости от того, установлен ли или удален бот.
Бот установлен	onInstallationUpdateAdd	Переопределите это, чтобы добавить логику при установке бота в подразделении.
Бот удален	onInstallationUpdateRemove	Переопределите это, чтобы добавить логику при удалении бота в подразделении.
Другой тип полученной активности	onUnrecognizedActivityType	Переопределите для обработки любого типа действия, иначе не будет обработано.

Эти разные обработчики используют turnContext для получения сведений о входящем действии, которое соответствует входящему HTTP-запросу. Действия могут быть разных типов, поэтому каждый обработчик предоставляет строго типизированное действие в параметре контекста обращения. В большинстве случаев onMessageActivity является наиболее распространенным и обычно всегда обрабатывается.

Существует также возможность реализации общедоступного метода onTurn. Сейчас базовая реализация этого метода выполняет проверку ошибок, а затем вызывает каждый из определенных обработчиков (например те два, которые мы определяем в этом примере) в зависимости от типа входящего действия. В большинстве случаев вы можете оставить этот метод без изменений и использовать отдельные обработчики, но если в вашей ситуации требуется пользовательская реализация onTurn, это всё ещё остаётся вариантом.

Внимание

При переопределении метода onTurn вам нужно вызвать super.onTurn, чтобы получить базовую реализацию для вызова всех остальных обработчиков on<activity>. Но вы также можете вызвать эти обработчики самостоятельно. В противном случае эти обработчики не будут вызваны и код не будет выполняться.

Питон

Основная логика бота определяется в коде бота. Чтобы реализовать бот в качестве обработчика действий, создайте ваш класс бота на основе ActivityHandler, который, в свою очередь, наследует абстрактный класс Bot. ActivityHandler определяет различные обработчики для различных типов действий, таких как on_message_activity и on_members_added. Эти методы защищены, но могут быть переопределены, так как мы наследуем от ActivityHandler.

Ниже описаны обработчики, определенные в ActivityHandler:

Мероприятие	Обработчик	Описание
Любой вид полученной активности	on_turn	Вызывает один из других обработчиков, основываясь на типе полученной активности.
Полученная активность сообщения	on_message_activity	Переопределите это, чтобы обработать действие message.
Получена активность обновления беседы	on_conversation_update_activity	В действии conversationUpdate вызывает обработчик, если участники, кроме бота, присоединились к беседе или покинули её.
Участники, не являющиеся ботами, присоединились к беседе	on_members_added_activity	Переопределите это, чтобы обрабатывать участников, присоединяющихся к беседе.
Участники, которые не являются ботами, покинули беседу.	on_members_removed_activity	Переопределите это, чтобы обрабатывать случаи, когда участники покидают беседу.
Получена активность события	on_event_activity	В действии event вызывает обработчик для события определенного типа.
Получена активность события отклика маркера	on_token_response_event	Переопределите этот метод для обработки событий ответа токена.
Получено событие активности без токен-ответа	on_event_activity	Переопределите это, чтобы обрабатывать события других типов.
Получена активность реакции на сообщение	on_message_reaction_activity	В рамках действия messageReaction вызывает обработчик, если к сообщению были добавлены или из него удалены одна или несколько реакций.
Добавление реакций к сообщению	on_reactions_added	Чтобы обрабатывать добавление реакций к сообщению, измените настройки.
Удаление реакции на сообщение из сообщения	on_reactions_removed	Переопределите этот метод, чтобы обрабатывать удаление реакций из сообщения.
Получено уведомление о деятельности по обновлению установки	on_installation_update	В ходе действия installationUpdate вызывается обработчик в зависимости от того, установлен ли или удален бот.
Бот установлен	on_installation_update_add	Переопределите это, чтобы добавить логику при установке бота в подразделении.
Бот удален	on_installation_update_remove	Переопределите это, чтобы добавить логику при удалении бота в подразделении.
Другой тип полученной активности	on_unrecognized_activity_type	Переопределите для обработки любого типа действия, иначе не будет обработано.

Эти разные обработчики используют turn_context для получения сведений о входящем действии, которое соответствует входящему HTTP-запросу. Действия могут быть разных типов, поэтому каждый обработчик предоставляет строго типизированное действие в параметре контекста обращения. В большинстве случаев on_message_activity является наиболее распространенным и обычно всегда обрабатывается.

Как и в предыдущих версиях 4.x этой платформы, существует также возможность реализации общедоступного метода on_turn. Сейчас базовая реализация этого метода выполняет проверку ошибок, а затем вызывает каждый из определенных обработчиков (например те два, которые мы определяем в этом примере) в зависимости от типа входящего действия. В большинстве случаев вы можете оставить этот метод без изменений и использовать отдельные обработчики, но если в вашей ситуации требуется пользовательская реализация on_turn, это всё ещё остаётся вариантом.

Внимание

При переопределении метода on_turn вам нужно вызвать super().on_turn, чтобы получить базовую реализацию для вызова всех остальных обработчиков on_<activity>. Но вы также можете вызвать эти обработчики самостоятельно. В противном случае эти обработчики не будут вызваны и код не будет выполняться.

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

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

C#

public class EchoBot : ActivityHandler
{
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
        var replyText = $"Echo: {turnContext.Activity.Text}";
        await turnContext.SendActivityAsync(MessageFactory.Text(replyText, replyText), cancellationToken);
    }

    protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
    {
        var welcomeText = "Hello and welcome!";
        foreach (var member in membersAdded)
        {
            if (member.Id != turnContext.Activity.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text(welcomeText, welcomeText), cancellationToken);
            }
        }
    }
}

JavaScript

const { ActivityHandler, MessageFactory } = require('botbuilder');

class EchoBot extends ActivityHandler {
    constructor() {
        super();
        // See https://aka.ms/about-bot-activity-message to learn more about the message and other activity types.
        this.onMessage(async (context, next) => {
            const replyText = `Echo: ${ context.activity.text }`;
            await context.sendActivity(MessageFactory.text(replyText, replyText));
            // By calling next() you ensure that the next BotHandler is run.
            await next();
        });

        this.onMembersAdded(async (context, next) => {
            const membersAdded = context.activity.membersAdded ?? [];
            const welcomeText = 'Hello and welcome!';
            for (let cnt = 0; cnt < membersAdded.length; ++cnt) {
                if (membersAdded[cnt].id !== context.activity.recipient.id) {
                    await context.sendActivity(MessageFactory.text(welcomeText, welcomeText));
                }
            }
            // By calling next() you ensure that the next BotHandler is run.
            await next();
        });

Ява

Предупреждение

Похоже, пример, который вы искали, был перемещен! Будьте уверены, что мы работаем над решением этого.

Питон

class EchoBot(ActivityHandler):
    async def on_members_added_activity(
        self, members_added: [ChannelAccount], turn_context: TurnContext
    ):
        for member in members_added:
            if member.id != turn_context.activity.recipient.id:
                await turn_context.send_activity("Hello and welcome!")

    async def on_message_activity(self, turn_context: TurnContext):
        return await turn_context.send_activity(
            MessageFactory.text(f"Echo: {turn_context.activity.text}")
        )

Следующие шаги

• Канал Microsoft Teams представляет некоторые действия, связанные с Teams, которые бот должен поддерживать для правильной работы с Teams. Основные понятия разработки ботов для Microsoft Teams вам поможет понять статья How Microsoft Teams bots work (Принцип работы ботов Microsoft Teams).
• Обработчик действий — хороший способ разработки бота, которому не нужно отслеживать состояние беседы между шагами. Библиотека диалогов предоставляет способы управления длительным диалогом с пользователем.