Condividi tramite


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.

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.

Gestione delle attività

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

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.

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.

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

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.