Conversazioni guidate dagli eventi usando un gestore attività

SI APPLICA A: SDK v4

Un gestore di attività è un modo basato su eventi per organizzare la logica di conversazione per il bot. Ogni tipo o sottotipo di attività diverso rappresenta un tipo diverso di evento di conversazione. Sotto le quinte, il gestore dei turni del bot chiama il singolo gestore attività per qualsiasi tipo di attività ricevuto.

Ad esempio, se il bot riceve un'attività di messaggio, il gestore dei turni noterà che l'attività in ingresso e la invierà al gestore dell'attività del messaggio. Quando si compila il bot, la logica del bot per la gestione e la risposta ai messaggi verrà inserita nel gestore attività dei messaggi. Analogamente, la logica per la gestione dei membri aggiunti alla conversazione verrà inserita nei membri aggiunti , che viene chiamata ogni volta che un membro viene aggiunto alla conversazione.

Per altri modi per organizzare la logica del bot, vedere la sezione relativa alla logica del bot in come funzionano i bot.

Nota

Gli SDK JavaScript, C# e Python di Bot Framework continueranno a essere supportati, ma Java SDK verrà ritirato con il supporto finale a lungo termine che termina a novembre 2023.

I bot esistenti creati con Java SDK continueranno a funzionare.

Per la creazione di nuovi bot, è consigliabile usare Microsoft Copilot Studio e leggere le informazioni sulla scelta della soluzione copilota appropriata.

Per altre informazioni, vedere Il futuro della compilazione di bot.

C#

Per implementare la logica per questi gestori, è necessario eseguire l'override di questi metodi nel bot, ad esempio nella sezione del gestore attività di esempio seguente. Per ognuno di questi gestori, non è disponibile alcuna implementazione di base, quindi è sufficiente aggiungere la logica desiderata nell'override.

Esistono alcune situazioni in cui si vuole eseguire l'override del gestore dei turni di base, ad esempio il salvataggio dello stato alla fine di un turno. In tal caso, accertarsi di chiamare prima await base.OnTurnAsync(turnContext, cancellationToken); per far sì che l'implementazione di base di OnTurnAsync venga eseguita prima del proprio codice aggiuntivo. Questa implementazione di base è anche responsabile della chiamata al resto dei gestori di attività come OnMessageActivityAsync.

JavaScript

La classe ActivityHandler JavaScript usa un modello basato su emettitore e listener. Usare, ad esempio, il metodo onMessage per registrare un listener di eventi per le attività di messaggistica. È possibile registrare più di un listener. Quando il bot riceve un'attività di messaggistica, il gestore di attività rileverà tale attività in ingresso e la invierà a ognuno dei listener di attività di onMessage, nell'ordine in cui sono stati registrati.

Quando si compila il bot, la logica del bot per la gestione e la risposta ai messaggi verrà inserita nei listener di onMessage. Allo stesso modo, la logica di gestione dei membri aggiunti alla conversazione verrà inserita nei listener di onMembersAdded, che vengono chiamati ogni volta che un membro viene aggiunto alla conversazione. Per aggiungere questi listener, è necessario registrarli nel bot come illustrato nella sezione Logica bot seguente. Includere la logica del bot per ognuno di questi listener e quindi assicurarsi di chiamare next() al termine. next()Chiamando , assicurarsi che il listener successivo venga eseguito.

Assicurarsi di salvare lo stato prima della fine del turno. A tale scopo, eseguire l'override del metodo run del gestore attività e salvare lo stato dopo il completamento del metodo run dell'elemento padre.

Non ci sono situazioni comuni in cui si vuole eseguire l'override del gestore dei turni di base, quindi prestare attenzione se si tenta di farlo. Esiste un gestore speciale denominato onDialog. Il onDialog gestore viene eseguito alla fine, dopo l'esecuzione del resto dei gestori e non è associato a un determinato tipo di attività. Come con tutti i gestori precedenti, assicurarsi di chiamare next() per far sì che il resto del processo venga completato.

Java

Per implementare la logica per questi gestori, è necessario eseguire l'override di questi metodi nel bot, ad esempio nella sezione del gestore attività di esempio seguente. Non esiste un'implementazione di base per ognuno di questi gestori, quindi aggiungere la logica desiderata nell'override.

Esistono alcune situazioni in cui si vuole eseguire l'override del gestore dei turni di base, ad esempio il salvataggio dello stato alla fine di un turno. In questo caso, assicurarsi di chiamare super.onTurn(turnContext); prima di tutto per assicurarsi che l'implementazione di base di venga eseguita prima del onTurn codice aggiuntivo. Questa implementazione di base è anche responsabile della chiamata al resto dei gestori di attività come onMessageActivity.

Python

Quando si compila il bot, la logica del bot per la gestione e la risposta ai messaggi verrà inserita in questo gestore on_message_activity. Allo stesso modo, la logica di gestione dei membri aggiunti alla conversazione verrà inserita nel gestore on_members_added, che viene chiamato ogni volta che un membro viene aggiunto alla conversazione.

Se ad esempio il bot riceve un'attività di messaggistica, il gestore dei turni rileverà tale attività in ingresso e la invierà al gestore di attività on_message_activity.

Per implementare la logica per questi gestori, è necessario eseguire l'override di questi metodi nel bot, ad esempio nella sezione del gestore attività di esempio seguente. Per ognuno di questi gestori, non è disponibile alcuna implementazione di base, quindi è sufficiente aggiungere la logica desiderata nell'override.

Esistono alcune situazioni in cui si vuole eseguire l'override del gestore dei turni di base, ad esempio il salvataggio dello stato alla fine di un turno. In tal caso, accertarsi di chiamare prima await super().on_turn(turnContext); per far sì che l'implementazione di base di on_turn venga eseguita prima del proprio codice aggiuntivo. Questa implementazione di base è anche responsabile della chiamata al resto dei gestori di attività come on_message_activity.

Gestione delle attività

La logica del bot elabora le attività in ingresso da uno o più canali e genera attività in uscita in risposta.

C#

La logica principale del bot è definita nel codice del bot. Per implementare un bot come gestore attività, derivare la classe bot da ActivityHandler, che implementa l'interfaccia IBot . ActivityHandler definisce vari gestori per diversi tipi di attività, ad esempio OnMessageActivityAsync, e OnMembersAddedAsync. Questi metodi sono protetti, ma possono essere sottoposti a override, poiché si deriva da ActivityHandler.

I gestori definiti in ActivityHandler sono:

Event	Gestore	Descrizione
Qualsiasi tipo di attività ricevuto	OnTurnAsync	Chiama uno degli altri gestori, in base al tipo di attività ricevuto.
Attività di messaggistica ricevuta	OnMessageActivityAsync	Eseguire l'override per gestire un'attività message.
Attività di aggiornamento della conversazione ricevuta	OnConversationUpdateActivityAsync	In un'attività conversationUpdate, chiama un gestore se membri diversi dal bot si sono aggiunti alla conversazione o l'hanno abbandonata.
Membri non bot si sono aggiunti alla conversazione	OnMembersAddedAsync	Eseguire l'override per gestire i membri che si aggiungono a una conversazione.
Membri non bot hanno abbandonato la conversazione	OnMembersRemovedAsync	Eseguire l'override per gestire i membri che abbandonano una conversazione.
Attività evento ricevuta	OnEventActivityAsync	In un'attività event, chiamare un gestore specifico per il tipo di evento.
Attività evento di risposta token	OnTokenResponseEventAsync	Eseguire l'override per gestire gli eventi di risposta token.
Attività evento di risposta non token ricevuta	OnEventAsync	Eseguire l'override per gestire altri tipi di eventi.
Attività di reazione al messaggio ricevuta	OnMessageReactionActivityAsync	In un'attività messageReaction chiama un gestore se una o più reazioni sono state aggiunte o rimosse da un messaggio.
Reazioni al messaggio aggiunte a un messaggio	OnReactionsAddedAsync	Eseguire l'override per gestire le reazioni aggiunte a un messaggio.
Reazioni al messaggio rimosse da un messaggio	OnReactionsRemovedAsync	Eseguire l'override per gestire le reazioni rimosse da un messaggio.
Attività di aggiornamento dell'installazione ricevuta	OnInstallationUpdateActivityAsync	In un'attività installationUpdate chiama un gestore in base al fatto che il bot sia stato installato o disinstallato.
Bot installato	OnInstallationUpdateAddAsync	Eseguire l'override di questa opzione per aggiungere la logica per quando il bot viene installato all'interno di un'unità organizzativa.
Bot disinstallato	OnInstallationUpdateRemoveAsync	Eseguire l'override di questa opzione per aggiungere la logica per quando il bot viene disinstallato all'interno di un'unità organizzativa.
Altro tipo di attività ricevuto	OnUnrecognizedActivityTypeAsync	Eseguire l'override per gestire qualsiasi tipo di attività altrimenti non gestito.

Questi gestori diversi hanno un turnContext che fornisce informazioni sull'attività in ingresso, corrispondente alla richiesta HTTP in ingresso. Le attività possono essere di vario tipo, quindi ogni gestore fornisce un'attività fortemente tipizzata nel relativo parametro di contesto del turno. Nella maggior parte dei casi, OnMessageActivityAsync verrà sempre gestito ed è generalmente il più comune.

Come nelle versioni precedenti della versione 4.x di questo framework, è anche possibile implementare il metodo OnTurnAsyncpubblico . L'implementazione di base di questo metodo gestisce attualmente il controllo degli errori e quindi chiama ognuno dei gestori specifici (ad esempio, i due definiti in questo esempio) a seconda del tipo di attività in ingresso. Nella maggior parte dei casi, è possibile lasciare il metodo da solo e usare i singoli gestori, ma se la situazione richiede un'implementazione personalizzata di OnTurnAsync, è comunque un'opzione.

Importante

Se si esegue l'override del metodo OnTurnAsync, è necessario chiamare base.OnTurnAsync per far sì che l'implementazione di base chiami tutti gli altri gestori On<activity>Async. In alternativa, chiamare manualmente tali gestori. In caso contrario, questi gestori non verranno chiamati e il codice non verrà eseguito.

JavaScript

La logica principale del bot è definita nel codice del bot. Per implementare un bot come gestore attività, estendere ActivityHandler. ActivityHandler definisce vari eventi per diversi tipi di attività ed è possibile modificare il comportamento del bot registrando listener di eventi, ad esempio con onMessage e onConversationUpdate.

Usare questi metodi per registrare i listener per ogni tipo di evento:

Event	Metodo di registrazione	Descrizione
Qualsiasi tipo di attività ricevuto	onTurn	Registra un listener per quando viene ricevuta un'attività .
Attività di messaggistica ricevuta	onMessage	Registra un listener per quando viene ricevuta un'attività message.
Attività di aggiornamento della conversazione ricevuta	onConversationUpdate	Registra un listener per quando viene ricevuta un'attività conversationUpdate.
I membri si sono uniti alla conversazione	onMembersAdded	Registra un listener per quando tutti i membri, incluso il bot, partecipano alla conversazione.
I membri hanno abbandonato la conversazione	onMembersRemoved	Registra un listener per quando tutti i membri, incluso il bot, abbandonano la conversazione.
Attività di reazione al messaggio ricevuta	onMessageReaction	Registra un listener per quando viene ricevuta un'attività messageReaction.
Reazioni al messaggio aggiunte a un messaggio	onReactionsAdded	Registra un listener per quando vengono aggiunte reazioni a un messaggio.
Reazioni al messaggio rimosse da un messaggio	onReactionsRemoved	Registra un listener per quando vengono rimosse reazioni da un messaggio.
Attività evento ricevuta	onEvent	Registra un listener per quando viene ricevuta un'attività event.
Attività evento di risposta token	onTokenResponseEvent	Registra un listener per quando viene ricevuto un evento tokens/response.
Attività di aggiornamento dell'installazione ricevuta	onInstallationUpdate	Registra un listener per quando viene ricevuta un'attività installationUpdate.
Bot installato	onInstallationUpdateAdd	Registra un listener per quando il bot viene installato all'interno di un'unità organizzativa.
Bot disinstallato	onInstallationUpdateRemove	Registra un listener per quando il bot viene disinstallato all'interno di un'unità organizzativa.
Altro tipo di attività ricevuto	onUnrecognizedActivityType	Registra un listener per quando un gestore per il tipo specifico di attività non è definito.
I gestori di attività sono stati completati	onDialog	Chiamato dopo il completamento di tutti i gestori applicabili.

Chiamare la funzione di continuazione next da ogni gestore per consentire la continuazione dell'elaborazione. Se next non viene chiamato, l'elaborazione dell'attività termina.

Java

La logica principale del bot è definita nel codice del bot. Per implementare un bot come gestore attività, derivare la classe bot da ActivityHandler, che implementa l'interfaccia Bot . ActivityHandler definisce vari gestori per diversi tipi di attività, ad esempio onMessageActivity, e onMembersAdded. Questi metodi sono protetti, ma possono essere sottoposti a override, poiché si deriva da ActivityHandler.

I gestori definiti in ActivityHandler sono:

Event	Gestore	Descrizione
Qualsiasi tipo di attività ricevuto	onTurn	Chiama uno degli altri gestori, in base al tipo di attività ricevuto.
Attività di messaggistica ricevuta	onMessageActivity	Eseguire l'override per gestire un'attività message.
Attività di aggiornamento della conversazione ricevuta	onConversationUpdateActivity	In un'attività conversationUpdate, chiama un gestore se membri diversi dal bot si sono aggiunti alla conversazione o l'hanno abbandonata.
Membri non bot si sono aggiunti alla conversazione	onMembersAdded	Eseguire l'override per gestire i membri che si aggiungono a una conversazione.
Membri non bot hanno abbandonato la conversazione	onMembersRemoved	Eseguire l'override per gestire i membri che abbandonano una conversazione.
Attività evento ricevuta	onEventActivity	In un'attività event, chiamare un gestore specifico per il tipo di evento.
Attività evento di risposta token	onTokenResponseEvent	Eseguire l'override per gestire gli eventi di risposta token.
Attività evento di risposta non token ricevuta	onEvent	Eseguire l'override per gestire altri tipi di eventi.
Attività di reazione al messaggio ricevuta	onMessageReactionActivity	In un'attività messageReaction chiama un gestore se una o più reazioni sono state aggiunte o rimosse da un messaggio.
Reazioni al messaggio aggiunte a un messaggio	onReactionsAdded	Eseguire l'override per gestire le reazioni aggiunte a un messaggio.
Reazioni al messaggio rimosse da un messaggio	onReactionsRemoved	Eseguire l'override per gestire le reazioni rimosse da un messaggio.
Attività di aggiornamento dell'installazione ricevuta	onInstallationUpdate	In un'attività installationUpdate chiama un gestore in base al fatto che il bot sia stato installato o disinstallato.
Bot installato	onInstallationUpdateAdd	Eseguire l'override di questa opzione per aggiungere la logica per quando il bot viene installato all'interno di un'unità organizzativa.
Bot disinstallato	onInstallationUpdateRemove	Eseguire l'override di questa opzione per aggiungere la logica per quando il bot viene disinstallato all'interno di un'unità organizzativa.
Altro tipo di attività ricevuto	onUnrecognizedActivityType	Eseguire l'override per gestire qualsiasi tipo di attività altrimenti non gestito.

Questi gestori diversi hanno un turnContext che fornisce informazioni sull'attività in ingresso, corrispondente alla richiesta HTTP in ingresso. Le attività possono essere di vario tipo, quindi ogni gestore fornisce un'attività fortemente tipizzata nel relativo parametro di contesto del turno. Nella maggior parte dei casi, onMessageActivity verrà sempre gestito ed è generalmente il più comune.

È anche disponibile l'opzione per implementare il metodo onTurnpubblico . L'implementazione di base di questo metodo gestisce attualmente il controllo degli errori e quindi chiama ognuno dei gestori specifici (ad esempio, i due definiti in questo esempio) a seconda del tipo di attività in ingresso. Nella maggior parte dei casi, è possibile lasciare il metodo da solo e usare i singoli gestori, ma se la situazione richiede un'implementazione personalizzata di onTurn, è comunque un'opzione.

Importante

Se si esegue l'override del metodo onTurn, è necessario chiamare super.onTurn per far sì che l'implementazione di base chiami tutti gli altri gestori on<activity>. In alternativa, chiamare manualmente tali gestori. In caso contrario, questi gestori non verranno chiamati e il codice non verrà eseguito.

Python

La logica principale del bot è definita nel codice del bot. Per implementare un bot come gestore attività, derivare la classe bot da ActivityHandler, che a sua volta deriva dalla classe astratta Bot . ActivityHandler definisce vari gestori per diversi tipi di attività, ad esempio on_message_activity e on_members_added. Questi metodi sono protetti, ma possono essere sottoposti a override, poiché si deriva da ActivityHandler.

I gestori definiti in ActivityHandler sono:

Event	Gestore	Descrizione
Qualsiasi tipo di attività ricevuto	on_turn	Chiama uno degli altri gestori, in base al tipo di attività ricevuto.
Attività di messaggistica ricevuta	on_message_activity	Eseguire l'override per gestire un'attività message.
Attività di aggiornamento della conversazione ricevuta	on_conversation_update_activity	In un'attività conversationUpdate, chiama un gestore se membri diversi dal bot si sono aggiunti alla conversazione o l'hanno abbandonata.
Membri non bot si sono aggiunti alla conversazione	on_members_added_activity	Eseguire l'override per gestire i membri che si aggiungono a una conversazione.
Membri non bot hanno abbandonato la conversazione	on_members_removed_activity	Eseguire l'override per gestire i membri che abbandonano una conversazione.
Attività evento ricevuta	on_event_activity	In un'attività event, chiamare un gestore specifico per il tipo di evento.
Attività evento di risposta token	on_token_response_event	Eseguire l'override per gestire gli eventi di risposta token.
Attività evento di risposta non token ricevuta	on_event_activity	Eseguire l'override per gestire altri tipi di eventi.
Attività di reazione al messaggio ricevuta	on_message_reaction_activity	In un'attività messageReaction chiama un gestore se una o più reazioni sono state aggiunte o rimosse da un messaggio.
Reazioni al messaggio aggiunte a un messaggio	on_reactions_added	Eseguire l'override per gestire le reazioni aggiunte a un messaggio.
Reazioni al messaggio rimosse da un messaggio	on_reactions_removed	Eseguire l'override per gestire le reazioni rimosse da un messaggio.
Attività di aggiornamento dell'installazione ricevuta	on_installation_update	In un'attività installationUpdate chiama un gestore in base al fatto che il bot sia stato installato o disinstallato.
Bot installato	on_installation_update_add	Eseguire l'override di questa opzione per aggiungere la logica per quando il bot viene installato all'interno di un'unità organizzativa.
Bot disinstallato	on_installation_update_remove	Eseguire l'override di questa opzione per aggiungere la logica per quando il bot viene disinstallato all'interno di un'unità organizzativa.
Altro tipo di attività ricevuto	on_unrecognized_activity_type	Eseguire l'override per gestire qualsiasi tipo di attività altrimenti non gestito.

Questi gestori diversi hanno un turn_context che fornisce informazioni sull'attività in ingresso, corrispondente alla richiesta HTTP in ingresso. Le attività possono essere di vario tipo, quindi ogni gestore fornisce un'attività fortemente tipizzata nel relativo parametro di contesto del turno. Nella maggior parte dei casi, on_message_activity verrà sempre gestito ed è generalmente il più comune.

Come nelle versioni precedenti della versione 4.x di questo framework, è anche possibile implementare il metodo on_turnpubblico . L'implementazione di base di questo metodo gestisce attualmente il controllo degli errori e quindi chiama ognuno dei gestori specifici (ad esempio, i due definiti in questo esempio) a seconda del tipo di attività in ingresso. Nella maggior parte dei casi, è possibile lasciare il metodo da solo e usare i singoli gestori, ma se la situazione richiede un'implementazione personalizzata di on_turn, è comunque un'opzione.

Importante

Se si esegue l'override del metodo on_turn, è necessario chiamare super().on_turn per far sì che l'implementazione di base chiami tutti gli altri gestori on_<activity>. In alternativa, chiamare manualmente tali gestori. In caso contrario, questi gestori non verranno chiamati e il codice non verrà eseguito.

Gestore attività di esempio

Ad esempio, è possibile gestire i membri aggiunti per accogliere gli utenti a una conversazione e gestirli sul messaggio per restituire i messaggi inviati al bot.

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

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

Java

public class EchoBot extends ActivityHandler {

    @Override
    protected CompletableFuture<Void> onMessageActivity(TurnContext turnContext) {
        return turnContext.sendActivity(
            MessageFactory.text("Echo: " + turnContext.getActivity().getText())
        ).thenApply(sendResult -> null);
    }

    @Override
    protected CompletableFuture<Void> onMembersAdded(
        List<ChannelAccount> membersAdded,
        TurnContext turnContext
    ) {
        String welcomeText = "Hello and welcome!";
        return membersAdded.stream()
            .filter(
                member -> !StringUtils
                    .equals(member.getId(), turnContext.getActivity().getRecipient().getId())
            ).map(channel -> turnContext.sendActivity(MessageFactory.text(welcomeText, welcomeText, null)))
            .collect(CompletableFutures.toFutureList()).thenApply(resourceResponses -> null);
    }
}

Python

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

Passaggi successivi

• Il canale Microsoft Teams introduce alcune attività specifiche di Teams che il bot dovrà supportare per funzionare correttamente con Teams. Per comprendere i concetti chiave relativi allo sviluppo di bot per Microsoft Teams, vedere Funzionamento dei bot per Microsoft Teams.
• Un gestore attività è un buon modo per progettare un bot che non deve tenere traccia dello stato della conversazione tra turni. La libreria dialogs offre modi per gestire una conversazione a esecuzione prolungata con l'utente.