Konverzace řízené událostmi za použití obsluhy aktivit

2025-04-22

PLATÍ PRO: SDK v4

Obslužná rutina pro aktivity je způsob uspořádání konverzační logiky robota řízený událostmi. Každý jiný typ nebo podtyp aktivity představuje jiný typ konverzační události. Interně volá obslužná rutina otáčení robota obslužnou rutinu jednotlivých aktivit pro jakýkoli typ přijaté aktivity.

Pokud například robot obdrží aktivitu zprávy, obslužná rutina pro zpracování otočení zjistí tuto příchozí aktivitu a předá ji obslužné rutině aktivity zprávy . Při sestavování robota bude logika robota pro zpracování a odpovídání na zprávy zpracovávána v této obslužné rutině zpráv. Logika pro zpracování členů přidaných do konverzace bude v obslužné rutině při přidání členů, která se volá při každém přidání člena do konverzace.

Další způsoby uspořádání logiky robota najdete v části logiky robota v tom, jak roboti fungují.

Poznámka:

Pokud chcete vytvářet agenty s výběrem služeb AI, orchestrace a znalostí, zvažte použití sady Microsoft 365 Agents SDK. Sada Agents SDK podporuje C#, JavaScript nebo Python. Další informace o sadě Agents SDK najdete v aka.ms/agents. Pokud hledáte platformu agenta založenou na SaaS, zvažte Microsoft Copilot Studio. Pokud máte existujícího robota sestaveného pomocí sady SDK služby Bot Framework, můžete robota aktualizovat na sadu SDK agentů. Můžete si projít základní změny a aktualizace v pokynech pro migraci z Bot Framework SDK na Agents SDK. Podpůrné tikety pro sadu SDK služby Bot Framework nebudou od 31. prosince 2025 nadále zpracovávány.

Pokud chcete implementovat logiku pro tyto obslužné rutiny, přepíšete tyto metody v botovi, například v obslužné rutině ukázkové aktivity níže. Pro každý z těchto obslužných programů není žádná základní implementace, takže stačí do svého přepsání přidat logiku, kterou chcete použít.

Existují určité situace, kdy budete chtít přepsat obslužnou rutinu základního turnu, například uložit stav na konci turnu. Při tom nezapomeňte nejprve zavolat await base.OnTurnAsync(turnContext, cancellationToken); , aby se před dalším kódem spustila základní implementace OnTurnAsync . Tato základní implementace je mimo jiné zodpovědná za volání ostatních obslužných rutin aktivit, jako je OnMessageActivityAsync.

JavaScript ActivityHandler používá model emitování a naslouchání událostí. Například použijte metodu onMessage k registraci posluchače událostí pro aktivity zpráv. Můžete zaregistrovat více posluchačů. Když robot obdrží aktivity zpráv, obslužná rutina aktivity zjistí, že se jedná o příchozí aktivitu, a odešle je každému z posluchačů aktivit v pořadí, v jakém byly zaregistrovány.

Při sestavování robota bude logika robota pro odpovídání na zprávy a jejich zpracování umístěna do onMessage naslouchacích zařízení. Stejně tak logika pro obsluhu členů přidaných do konverzace přejde do vašich posluchačů, které jsou vyvolány při každém přidání člena do konverzace. Pokud chcete přidat tyto posluchače, zaregistrujete je ve svém botovi, jak je ukázáno v části Logika bota níže. Pro každý posluchač zahrňte logiku bota a pak na konci nezapomeňte volat next(). Voláním next() zajistíte, že bude spuštěn další posluchač.

Před koncem turnu nezapomeňte uložit stav . Můžete to udělat tak, že přepíšete metodu obsluhy aktivity run a uložíte stav po dokončení metody nadřazené run.

Neexistují žádné běžné situace, kdy budete chtít přepsat základní obslužnou rutinu otáčení, proto buďte opatrní, pokud se to pokusíte provést. Existuje speciální program s názvem onDialog. Obslužná rutina onDialog se spustí na konci po spuštění zbývajících obslužných rutin a není svázaná s určitým typem aktivity. Stejně jako u všech výše uvedených obslužných rutin nezapomeňte zavolat next(), abyste zajistili dokončení zbytku procesu.

Pokud chcete implementovat logiku pro tyto obslužné rutiny, přepíšete tyto metody v botovi, například v obslužné rutině ukázkové aktivity níže. Pro každou z těchto obslužných procedur neexistuje základní implementace, proto při přepsání přidejte logiku, kterou potřebujete.

Existují určité situace, kdy budete chtít přepsat obslužnou rutinu základního turnu, například uložit stav na konci turnu. Při tom nezapomeňte nejprve zavolat super.onTurn(turnContext); , aby se před dalším kódem spustila základní implementace onTurn . Tato základní implementace je mimo jiné zodpovědná za volání ostatních obslužných rutin aktivit, jako je onMessageActivity.

Při sestavování robota bude logika robota pro zpracování a odpovídání na zprávy umístěna v této on_message_activity obslužné rutině. Stejně tak logika pro zpracování členů přidaných do konverzace přejde do obslužné on_members_added rutiny, která se volá při každém přidání člena do konverzace.

Pokud například robot obdrží aktivitu zprávy, obslužná rutina ji uvidí a poté odešle obslužné rutině aktivity on_message_activity.

Existují určité situace, kdy budete chtít přepsat obslužnou rutinu základního turnu, například uložit stav na konci turnu. Při tom nezapomeňte nejprve zavolat await super().on_turn(turnContext); , aby se před dalším kódem spustila základní implementace on_turn . Tato základní implementace je mimo jiné zodpovědná za volání ostatních obslužných rutin aktivit, jako je on_message_activity.

Zpracování aktivit

Logika robota zpracovává příchozí aktivity z jednoho nebo více kanálů a generuje odchozí aktivity v reakci.

Hlavní logika robota je definovaná v kódu robota. Chcete-li implementovat robota jako obslužnou rutinu aktivity, odvoďte třídu svého robota z ActivityHandler, které implementuje rozhraní IBot. ActivityHandler definuje různé obslužné rutiny pro různé typy aktivit, například OnMessageActivityAsync, a OnMembersAddedAsync. Tyto metody jsou chráněné, ale lze je přepsat, protože pocházíme z ActivityHandler.

Obslužné rutiny definované v ActivityHandler :

Událost	Zpracovatel	Popis
Všechny přijaté typy aktivit	`OnTurnAsync`	Zavolá jednoho z dalších zpracovatelů podle typu přijaté aktivity.
Aktivita zprávy přijata	`OnMessageActivityAsync`	Tuto možnost přepište, aby se zpracovávala `message` aktivita.
Přijatá aktivita aktualizace konverzace	`OnConversationUpdateActivityAsync`	Při aktivitě `conversationUpdate` volá obslužnou rutinu, pokud se někdo jiný než robot připojil nebo opustil konverzaci.
Členové, kteří nejsou roboti, se připojili ke konverzaci	`OnMembersAddedAsync`	Přepište tuto funkci, abyste mohli spravovat připojování členů ke konverzaci.
Členové, kteří nejsou roboti, opustili konverzaci.	`OnMembersRemovedAsync`	Přepište to tak, aby bylo možné řešit odchod členů z konverzace.
Aktivita události přijata	`OnEventActivityAsync`	Při aktivitě `event` volá obslužnou rutinu specifickou pro typ události.
Přijata aktivita události odpovědi na token	`OnTokenResponseEventAsync`	Přepište toto nastavení pro zpracování událostí odezvy tokenů.
Aktivita události přijatá bez tokenu odpovědi	`OnEventAsync`	Chcete-li zpracovávat jiné typy událostí, přepište tento kód.
Přijatá aktivita reakce k zprávě	`OnMessageReactionActivityAsync`	Při aktivitě `messageReaction` volá obslužnou rutinu, pokud byla přidána nebo odebrána jedna nebo více reakcí ze zprávy.
Reakce přidané k zprávě	`OnReactionsAddedAsync`	Přepište toto, aby zpracovávalo reakce přidané do zprávy.
Reakce na zprávu odstraněny	`OnReactionsRemovedAsync`	Přepište toto nastavení, aby dokázalo zpracovat reakce odstraněné ze zprávy.
Přijatá aktivita aktualizace instalace	`OnInstallationUpdateActivityAsync`	Při aktivitě `installationUpdate` volá obslužnou rutinu podle toho, zda byl bot nainstalován nebo odinstalován.
Nainstalovaný robot	`OnInstallationUpdateAddAsync`	Tuto možnost přepište, pokud chcete přidat logiku, když je robot nainstalovaný v organizační jednotce.
Bot odinstalován	`OnInstallationUpdateRemoveAsync`	Tuto možnost přepište, pokud chcete přidat logiku, když je robot odinstalován v rámci organizační jednotky.
Byl přijat jiný typ aktivity.	`OnUnrecognizedActivityTypeAsync`	Přepište tuto funkci tak, aby zpracovávala jakýkoli typ aktivity, který jinak není ošetřen.

Tyto různé obslužné rutiny mají turnContext, který poskytuje informace o příchozí aktivitě, jež odpovídá příchozímu požadavku HTTP. Aktivity mohou být různých typů, takže každá obslužná rutina poskytuje aktivitu silně typovanou v kontextovém parametru. Ve většině případů OnMessageActivityAsync bude vždy zpracovávána a nejčastěji se jedná o nejběžnější.

Stejně jako v předchozích verzích 4.x této architektury existuje také možnost implementovat veřejnou metodu OnTurnAsync. Základní implementace této metody v současné době zpracovává kontrolu chyb a potom volá všechny konkrétní obslužné rutiny (podobně jako ty dva, které definujeme v této ukázce) v závislosti na typu příchozí aktivity. Ve většině případů můžete tuto metodu ponechat samostatně a používat jednotlivé obslužné rutiny, ale pokud vaše situace vyžaduje vlastní implementaci OnTurnAsync, je to stále možnost.

Důležité

Pokud přepíšete metodu OnTurnAsync, budete muset zavolat base.OnTurnAsync, abyste získali základní implementaci pro volání všech ostatních On<activity>Async obslužných rutin, nebo tyto obslužné rutiny volat samostatně. Jinak se tyto obslužné rutiny nevolají a tento kód se nespustí.

Hlavní logika robota je definovaná v kódu robota. Implementujte robota jako obsluhovač aktivit rozšířením ActivityHandler. ActivityHandler definuje různé události pro různé typy aktivit a chování robota můžete upravit registrací naslouchačů událostí, například s onMessage a onConversationUpdate.

Pomocí těchto metod zaregistrujte posluchače pro každý typ události:

Událost	Metoda registrace	Popis
Všechny přijaté typy aktivit	`onTurn`	Zaregistruje posluchače při přijetí jakékoli aktivity.
Aktivita zprávy přijata	`onMessage`	Zaregistruje posluchače pro příjem `message` aktivity.
Přijatá aktivita aktualizace konverzace	`onConversationUpdate`	Zaregistruje nasluchač při příjmu jakékoliv `conversationUpdate` aktivity.
Členové se připojili ke konverzaci	`onMembersAdded`	Zaregistruje posluchače, když se členové připojují ke konverzaci, včetně robota.
Členové opustili konverzaci.	`onMembersRemoved`	Registruje posluchače pro případ, že členové, včetně bota, opustí konverzaci.
Přijatá aktivita reakce k zprávě	`onMessageReaction`	Zaregistruje nasluchač při příjmu jakékoliv `messageReaction` aktivity.
Reakce přidané k zprávě	`onReactionsAdded`	Zaregistruje posluchače, když se přidají reakce na zprávu.
Reakce na zprávu odstraněny	`onReactionsRemoved`	Zaregistruje nasluchač, když jsou ze zprávy odstraněny reakce.
Aktivita události přijata	`onEvent`	Zaregistruje nasluchač při příjmu jakékoliv `event` aktivity.
Přijata aktivita události odpovědi na token	`onTokenResponseEvent`	Zaregistruje naslouchacího události `tokens/response` pro případ, že je přijata.
Přijatá aktivita aktualizace instalace	`onInstallationUpdate`	Zaregistruje nasluchač při příjmu jakékoliv `installationUpdate` aktivity.
Nainstalovaný robot	`onInstallationUpdateAdd`	Zaregistruje posluchače pro případ, kdy je bot nainstalován v organizační jednotce.
Bot odinstalován	`onInstallationUpdateRemove`	Zaregistruje naslouchací funkci pro případ, kdy je robot odinstalován v rámci organizační jednotky.
Byl přijat jiný typ aktivity.	`onUnrecognizedActivityType`	Zaregistruje nasluchač, když není definována obslužná rutina pro konkrétní typ aktivity.
Obslužné rutiny aktivit byly dokončeny.	`onDialog`	Zavoláno po dokončení všech použitelných obslužných programů.

Voláním funkce next z každé obslužné rutiny umožněte pokračování zpracování. Pokud next není voláno, zpracování činnosti skončí.

Hlavní logika robota je definovaná v kódu robota. Chcete-li implementovat robota jako obslužnou rutinu aktivity, odvoďte třídu svého robota z ActivityHandler, které implementuje rozhraní Bot. ActivityHandler definuje různé obslužné rutiny pro různé typy aktivit, například onMessageActivity, a onMembersAdded. Tyto metody jsou chráněné, ale lze je přepsat, protože pocházíme z ActivityHandler.

Obslužné rutiny definované v ActivityHandler :

Událost	Zpracovatel	Popis
Všechny přijaté typy aktivit	`onTurn`	Zavolá jednoho z dalších zpracovatelů podle typu přijaté aktivity.
Aktivita zprávy přijata	`onMessageActivity`	Tuto možnost přepište, aby se zpracovávala `message` aktivita.
Přijatá aktivita aktualizace konverzace	`onConversationUpdateActivity`	Při aktivitě `conversationUpdate` volá obslužnou rutinu, pokud se někdo jiný než robot připojil nebo opustil konverzaci.
Členové, kteří nejsou roboti, se připojili ke konverzaci	`onMembersAdded`	Přepište tuto funkci, abyste mohli spravovat připojování členů ke konverzaci.
Členové, kteří nejsou roboti, opustili konverzaci.	`onMembersRemoved`	Přepište to tak, aby bylo možné řešit odchod členů z konverzace.
Aktivita události přijata	`onEventActivity`	Při aktivitě `event` volá obslužnou rutinu specifickou pro typ události.
Přijata aktivita události odpovědi na token	`onTokenResponseEvent`	Přepište toto nastavení pro zpracování událostí odezvy tokenů.
Aktivita události přijatá bez tokenu odpovědi	`onEvent`	Chcete-li zpracovávat jiné typy událostí, přepište tento kód.
Přijatá aktivita reakce k zprávě	`onMessageReactionActivity`	Při aktivitě `messageReaction` volá obslužnou rutinu, pokud byla přidána nebo odebrána jedna nebo více reakcí ze zprávy.
Reakce přidané k zprávě	`onReactionsAdded`	Přepište toto, aby zpracovávalo reakce přidané do zprávy.
Reakce na zprávu odstraněny	`onReactionsRemoved`	Přepište toto nastavení, aby dokázalo zpracovat reakce odstraněné ze zprávy.
Přijatá aktivita aktualizace instalace	`onInstallationUpdate`	Při aktivitě `installationUpdate` volá obslužnou rutinu podle toho, zda byl bot nainstalován nebo odinstalován.
Nainstalovaný robot	`onInstallationUpdateAdd`	Tuto možnost přepište, pokud chcete přidat logiku, když je robot nainstalovaný v organizační jednotce.
Bot odinstalován	`onInstallationUpdateRemove`	Tuto možnost přepište, pokud chcete přidat logiku, když je robot odinstalován v rámci organizační jednotky.
Byl přijat jiný typ aktivity.	`onUnrecognizedActivityType`	Přepište tuto funkci tak, aby zpracovávala jakýkoli typ aktivity, který jinak není ošetřen.

Tyto různé obslužné rutiny mají turnContext, který poskytuje informace o příchozí aktivitě, jež odpovídá příchozímu požadavku HTTP. Aktivity mohou být různých typů, takže každá obslužná rutina poskytuje aktivitu silně typovanou v kontextovém parametru. Ve většině případů onMessageActivity bude vždy zpracovávána a nejčastěji se jedná o nejběžnější.

K dispozici je také možnost implementovat veřejnou metodu onTurn. Základní implementace této metody v současné době zpracovává kontrolu chyb a potom volá všechny konkrétní obslužné rutiny (podobně jako ty dva, které definujeme v této ukázce) v závislosti na typu příchozí aktivity. Ve většině případů můžete tuto metodu ponechat samostatně a používat jednotlivé obslužné rutiny, ale pokud vaše situace vyžaduje vlastní implementaci onTurn, je to stále možnost.

Důležité

Pokud přepíšete metodu onTurn, budete muset zavolat super.onTurn, abyste získali základní implementaci pro volání všech ostatních on<activity> obslužných rutin, nebo tyto obslužné rutiny volat samostatně. Jinak se tyto obslužné rutiny nevolají a tento kód se nespustí.

Hlavní logika robota je definovaná v kódu robota. Chcete-li implementovat robota jako obslužnou rutinu aktivity, odvozujte třídu robota z ActivityHandler třídy, která se zase odvozuje z abstraktní Bot třídy. ActivityHandler definuje různé obslužné rutiny pro různé typy aktivit, například on_message_activity a on_members_added. Tyto metody jsou chráněné, ale lze je přepsat, protože pocházíme z ActivityHandler.

Obslužné rutiny definované v ActivityHandler :

Událost	Zpracovatel	Popis
Všechny přijaté typy aktivit	`on_turn`	Zavolá jednoho z dalších zpracovatelů podle typu přijaté aktivity.
Aktivita zprávy přijata	`on_message_activity`	Tuto možnost přepište, aby se zpracovávala `message` aktivita.
Přijatá aktivita aktualizace konverzace	`on_conversation_update_activity`	Při aktivitě `conversationUpdate` volá obslužnou rutinu, pokud se někdo jiný než robot připojil nebo opustil konverzaci.
Členové, kteří nejsou roboti, se připojili ke konverzaci	`on_members_added_activity`	Přepište tuto funkci, abyste mohli spravovat připojování členů ke konverzaci.
Členové, kteří nejsou roboti, opustili konverzaci.	`on_members_removed_activity`	Přepište to tak, aby bylo možné řešit odchod členů z konverzace.
Aktivita události přijata	`on_event_activity`	Při aktivitě `event` volá obslužnou rutinu specifickou pro typ události.
Přijata aktivita události odpovědi na token	`on_token_response_event`	Přepište toto nastavení pro zpracování událostí odezvy tokenů.
Aktivita události přijatá bez tokenu odpovědi	`on_event_activity`	Chcete-li zpracovávat jiné typy událostí, přepište tento kód.
Přijatá aktivita reakce k zprávě	`on_message_reaction_activity`	Při aktivitě `messageReaction` volá obslužnou rutinu, pokud byla přidána nebo odebrána jedna nebo více reakcí ze zprávy.
Reakce přidané k zprávě	`on_reactions_added`	Přepište toto, aby zpracovávalo reakce přidané do zprávy.
Reakce na zprávu odstraněny	`on_reactions_removed`	Přepište toto nastavení, aby dokázalo zpracovat reakce odstraněné ze zprávy.
Přijatá aktivita aktualizace instalace	`on_installation_update`	Při aktivitě `installationUpdate` volá obslužnou rutinu podle toho, zda byl bot nainstalován nebo odinstalován.
Nainstalovaný robot	`on_installation_update_add`	Tuto možnost přepište, pokud chcete přidat logiku, když je robot nainstalovaný v organizační jednotce.
Bot odinstalován	`on_installation_update_remove`	Tuto možnost přepište, pokud chcete přidat logiku, když je robot odinstalován v rámci organizační jednotky.
Byl přijat jiný typ aktivity.	`on_unrecognized_activity_type`	Přepište tuto funkci tak, aby zpracovávala jakýkoli typ aktivity, který jinak není ošetřen.

Tyto různé obslužné rutiny mají turn_context, který poskytuje informace o příchozí aktivitě, jež odpovídá příchozímu požadavku HTTP. Aktivity mohou být různých typů, takže každá obslužná rutina poskytuje aktivitu silně typovanou v kontextovém parametru. Ve většině případů on_message_activity bude vždy zpracovávána a nejčastěji se jedná o nejběžnější.

Stejně jako v předchozích verzích 4.x této architektury existuje také možnost implementovat veřejnou metodu on_turn. Základní implementace této metody v současné době zpracovává kontrolu chyb a potom volá všechny konkrétní obslužné rutiny (podobně jako ty dva, které definujeme v této ukázce) v závislosti na typu příchozí aktivity. Ve většině případů můžete tuto metodu ponechat samostatně a používat jednotlivé obslužné rutiny, ale pokud vaše situace vyžaduje vlastní implementaci on_turn, je to stále možnost.

Důležité

Pokud přepíšete metodu on_turn, budete muset zavolat super().on_turn, abyste získali základní implementaci pro volání všech ostatních on_<activity> obslužných rutin, nebo tyto obslužné rutiny volat samostatně. Jinak se tyto obslužné rutiny nevolají a tento kód se nespustí.

Obslužný zpracovatel ukázkové aktivity

Například můžete použít zpracování události při přidání členů pro vítání uživatelů do konverzace a použít zpracování události při zprávách k opakování zpráv, které posílají botovi.

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

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}")
        )

Další kroky

Kanál Microsoft Teams představuje některé aktivity specifické pro Teams, které robot bude muset podporovat, aby správně fungoval s Teams. Vysvětlení klíčových konceptů vývoje robotů pro Microsoft Teams najdete v tématu Jak fungují roboti Microsoft Teams.
Obslužná rutina aktivity je dobrým způsobem, jak navrhnout bota, který nemusí sledovat konverzační stav mezi jednotlivými kroky. Knihovna dialogových oken poskytuje způsoby správy dlouhotrvající konverzace s uživatelem.

Sdílet prostřednictvím

Konverzace řízené událostmi za použití obsluhy aktivit

Zpracování aktivit

Obslužný zpracovatel ukázkové aktivity

Další kroky

Další materiály