Compartilhar via

Usar uma caixa de diálogo para consumir um skill

  • Artigo

APLICA-SE A: SDK v4

Este artigo demonstra como usar uma caixa de diálogo de skill em um consumidor de skill. A caixa de diálogo de skill posta as atividades do bot pai para o bot de skill e retorna as respostas do skill para o usuário. O bot de skill acessado por esse consumidor pode lidar com as atividades de mensagens e eventos. Para obter um exemplo de manifesto de skill e informações sobre como implementar o skill, confira como usar caixas de diálogo em um skill.

Para saber mais sobre como usar um bot de skill fora das caixas de diálogo, confira como implementar um consumidor de skill.

Observação

Os SDKs JavaScript, C# e Python do Bot Framework continuarão a ser compatíveis. No entanto, o SDK Java está sendo desativado, com o suporte final de longo prazo terminando em novembro de 2023.

Os bots existentes criados com o SDK para Java continuarão a funcionar.

Para a criação de novos bots, considere usar o Microsoft Copilot Studio e leia sobre como escolher a solução de copiloto certa.

Para obter mais informações, confira O futuro da criação de bots.

Pré-requisitos

Sobre este exemplo

O exemplo skills skillDialog inclui projetos para dois bots:

  • O bot raiz do diálogo, que usa uma classe de diálogo de habilidades para consumir uma habilidade.
  • O bot de skill de caixa de diálogo, que usa uma caixa de diálogo para lidar com atividades provenientes de consumidores de skill.

Este artigo se concentra em como usar uma classe de caixa de diálogo de skill em um bot raiz para gerenciar o skill, enviar atividades de mensagens e eventos e cancelar o skill.

Para saber mais sobre outros aspectos da criação de um consumidor de skill, confira como implementar um consumidor de skill.

Para saber mais sobre o bot de skill de caixa de diálogo, confira como usar caixa de diálogo em um skill.

Recursos

Para bots implantados. a autenticação de bot para bot requer que cada bot participante tenha uma identidade válida. No entanto, você pode testar habilidades e consumidores de habilidades localmente com o Bot Framework Emulator sem informações de identidade.

Configuração de aplicativo

  1. Opcionalmente, adicione as informações de identidade do bot raiz ao arquivo de configuração.
  2. Adicione o ponto de extremidade do host de habilidades (o serviço ou URL de retorno de chamada) ao qual as habilidades devem responder ao consumidor de habilidade.
  3. Adicione uma entrada para cada skill que o consumidor de skills usará. Cada entrada inclui:
    • Uma ID que o consumidor de skills usará para identificar cada skill.
    • Opcionalmente, o aplicativo do bot de habilidades ou a ID do cliente.
    • O ponto de extremidade de mensagens do skill.

Observação

Se a habilidade ou o consumidor de habilidade especificar uma identidade, ambos deverão fazê-lo.

DialogRootBot\appsettings.json

Opcionalmente, adicione as informações de identidade do bot raiz e adicione a ID do aplicativo ou do cliente para o bot de habilidade de eco à matriz BotFrameworkSkills.

{
  "MicrosoftAppType": "",
  "MicrosoftAppId": "",
  "MicrosoftAppPassword": "",
  "MicrosoftAppTenantId": "",

  "SkillHostEndpoint": "http://localhost:3978/api/skills/",
  "BotFrameworkSkills": [
    {
      "Id": "DialogSkillBot",
      "AppId": "",
      "SkillEndpoint": "http://localhost:39783/api/messages"
    }
  ]
}

Lógica de caixa de diálogo

A caixa de diálogo principal do bot inclui uma caixa de diálogo de skill para cada skill consumido por esse bot. A caixa de diálogo de skill gerencia o skill por meio de vários objetos relacionados a skills para você, como o cliente de skill e os objetos de fábrica de IDs de conversa de skills. A caixa de diálogo principal também demonstra como cancelar o skill (por meio da caixa de diálogo de skill) com base na entrada do usuário.

O skill que esse bot usa dá suporte a alguns recursos diferentes. Ele pode reservar um voo ou obter o clima de uma cidade. Além disso, se ele receber uma mensagem fora desses contextos e um reconhecedor LUIS estiver configurado, ele tentará interpretar a intenção do usuário.

Observação

O reconhecimento de linguagem (LUIS) será desativado em 1º de outubro de 2025. A partir de 1º de abril de 2023, você não poderá criar recursos do LUIS. Uma versão mais recente do reconhecimento de linguagem já está disponível como parte da Linguagem de IA do Azure.

A compreensão da linguagem coloquial (CLU), um recurso da Linguagem de IA do Azure, é a versão atualizada do LUIS. Para obter mais informações sobre o suporte ao reconhecimento de linguagem no SDK do Bot Framework, confira Reconhecimento de linguagem natural.

O manifesto de habilidade (C#, JavaScript, Java, Python) descreve as ações que a habilidade pode executar, seus parâmetros de entrada e parâmetros de saída e os pontos de extremidade da habilidade. Observe que o skill pode lidar com um evento "BookFlight" ou "GetWeather". Ele também pode manipular mensagens.

A caixa de diálogo principal inclui código para:

A caixa de diálogo principal herda da classe caixa de diálogo de componente. Para obter mais informações sobre diálogos de componente, confira como Gerenciar a complexidade do diálogo.

Inicializar a caixa de diálogo principal

O diálogo principal inclui diálogos (para gerenciar o fluxo de conversas fora da habilidade) e um diálogo de habilidade (para gerenciar as habilidades). A cascata inclui as etapas a seguir, descritas em mais detalhes nas próximas seções.

  1. O usuário deverá selecionar o skill a ser usado. (O bot raiz consome uma habilidade.)
  2. O usuário deverá selecionar a ação a ser usada para esse skill. (O bot de habilidade define três ações.)
  3. Inicie o skill escolhido com uma atividade inicial com base na ação escolhida.
  4. Depois que o skill for concluído, exiba os resultados, se houver. Em seguida, reinicie a cascata.

DialogRootBot\Dialogs\MainDialog.cs

A classe MainDialog deriva de ComponentDialog. Além do estado da conversa, o diálogo precisa da identidade do bot raiz e das referências à fábrica de IDs de conversas de habilidades, ao cliente HTTP de habilidades e aos objetos de configuração de habilidades.

O construtor de diálogo verifica seus parâmetros de entrada, adiciona diálogos de habilidade, adiciona prompts e diálogos em cascata para gerenciar o fluxo de conversa fora da habilidade e cria um acessador de propriedade para rastrear a habilidade ativa, se houver.

O construtor chama AddSkillDialogs, um método auxiliar, para criar um SkillDialog para cada skill incluído no arquivo de configuração, como lido do arquivo de configuração para um objeto SkillsConfiguration.

// Helper method that creates and adds SkillDialog instances for the configured skills.
private void AddSkillDialogs(ConversationState conversationState, SkillConversationIdFactoryBase conversationIdFactory, SkillsConfiguration skillsConfig, string botId)
{
    foreach (var skillInfo in _skillsConfig.Skills.Values)
    {
        // Create the dialog options.
        var skillDialogOptions = new SkillDialogOptions
        {
            BotId = botId,
            ConversationIdFactory = conversationIdFactory,
            SkillClient = _auth.CreateBotFrameworkClient(),
            SkillHostEndpoint = skillsConfig.SkillHostEndpoint,
            ConversationState = conversationState,
            Skill = skillInfo
        };

        // Add a SkillDialog for the selected skill.
        AddDialog(new SkillDialog(skillDialogOptions, skillInfo.Id));
    }
}

Selecionar um skill

Em sua primeira etapa, o diálogo principal solicita ao usuário qual habilidade ele gostaria de chamar e usa o prompt de escolha "SkillPrompt" para obter a resposta. (Esse bot define apenas um skill).

DialogRootBot\Dialogs\MainDialog.cs

// Render a prompt to select the skill to call.
private async Task<DialogTurnResult> SelectSkillStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    // Create the PromptOptions from the skill configuration which contain the list of configured skills.
    var messageText = stepContext.Options?.ToString() ?? "What skill would you like to call?";
    var repromptMessageText = "That was not a valid choice, please select a valid skill.";
    var options = new PromptOptions
    {
        Prompt = MessageFactory.Text(messageText, messageText, InputHints.ExpectingInput),
        RetryPrompt = MessageFactory.Text(repromptMessageText, repromptMessageText, InputHints.ExpectingInput),
        Choices = _skillsConfig.Skills.Select(skill => new Choice(skill.Value.Id)).ToList()
    };

    // Prompt the user to select a skill.
    return await stepContext.PromptAsync("SkillPrompt", options, cancellationToken);
}

Selecionar uma ação de skill

Na próxima etapa, a caixa de diálogo principal:

  1. Salva informações sobre o skill selecionado pelo usuário.
  2. Solicita ao usuário qual ação de skill ele gostaria de usar e usa o prompt de opção "SkillActionPrompt" para obter a resposta.
    • Ele usa um método auxiliar para obter uma lista de ações a serem escolhidas.
    • O validador de prompts associado a esse prompt usará o padrão para enviar o skill de uma mensagem se a entrada do usuário não corresponder a uma das opções.

As opções incluídas neste bot ajudam a testar as ações definidas para esse skill. Normalmente, você deve ler as opções do manifesto do skill e apresentar as opções para o usuário com base nessa lista.

DialogRootBot\Dialogs\MainDialog.cs

// Render a prompt to select the action for the skill.
private async Task<DialogTurnResult> SelectSkillActionStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    // Get the skill info based on the selected skill.
    var selectedSkillId = ((FoundChoice)stepContext.Result).Value;
    var selectedSkill = _skillsConfig.Skills.FirstOrDefault(s => s.Value.Id == selectedSkillId).Value;

    // Remember the skill selected by the user.
    stepContext.Values[_selectedSkillKey] = selectedSkill;

    // Create the PromptOptions with the actions supported by the selected skill.
    var messageText = $"Select an action # to send to **{selectedSkill.Id}** or just type in a message and it will be forwarded to the skill";
    var options = new PromptOptions
    {
        Prompt = MessageFactory.Text(messageText, messageText, InputHints.ExpectingInput),
        Choices = GetSkillActions(selectedSkill)
    };

    // Prompt the user to select a skill action.
    return await stepContext.PromptAsync("SkillActionPrompt", options, cancellationToken);
}
// Helper method to create Choice elements for the actions supported by the skill.
private IList<Choice> GetSkillActions(BotFrameworkSkill skill)
{
    // Note: the bot would probably render this by reading the skill manifest.
    // We are just using hardcoded skill actions here for simplicity.

    var choices = new List<Choice>();
    switch (skill.Id)
    {
        case "DialogSkillBot":
            choices.Add(new Choice(SkillActionBookFlight));
            choices.Add(new Choice(SkillActionBookFlightWithInputParameters));
            choices.Add(new Choice(SkillActionGetWeather));
            break;
    }

    return choices;
}
// This validator defaults to Message if the user doesn't select an existing option.
private Task<bool> SkillActionPromptValidator(PromptValidatorContext<FoundChoice> promptContext, CancellationToken cancellationToken)
{
    if (!promptContext.Recognized.Succeeded)
    {
        // Assume the user wants to send a message if an item in the list is not selected.
        promptContext.Recognized.Value = new FoundChoice { Value = SkillActionMessage };
    }

    return Task.FromResult(true);
}

Iniciar um skill

Na próxima etapa, a caixa de diálogo principal:

  1. Recupera informações sobre o skill e a atividade de skill que o usuário selecionou.
  2. Usa um método auxiliar para criar a atividade a ser enviada inicialmente para o skill.
  3. Cria as opções de caixa de diálogo para iniciar a caixa de diálogo de skill. Isso inclui a atividade inicial a ser enviada.
  4. Salva o estado antes de chamar o skill. (Isso é necessário, pois a resposta do skill pode chegar a uma instância diferente do consumidor de skill).
  5. Inicia o caixa de diálogo de skill, passando a ID do skill a ser chamada e as opções para chamá-la.

DialogRootBot\Dialogs\MainDialog.cs

// Starts the SkillDialog based on the user's selections.
private async Task<DialogTurnResult> CallSkillActionStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    var selectedSkill = (BotFrameworkSkill)stepContext.Values[_selectedSkillKey];

    Activity skillActivity;
    switch (selectedSkill.Id)
    {
        case "DialogSkillBot":
            skillActivity = CreateDialogSkillBotActivity(((FoundChoice)stepContext.Result).Value, stepContext.Context);
            break;

        // We can add other case statements here if we support more than one skill.
        default:
            throw new Exception($"Unknown target skill id: {selectedSkill.Id}.");
    }

    // Create the BeginSkillDialogOptions and assign the activity to send.
    var skillDialogArgs = new BeginSkillDialogOptions { Activity = skillActivity };

    // Save active skill in state.
    await _activeSkillProperty.SetAsync(stepContext.Context, selectedSkill, cancellationToken);

    // Start the skillDialog instance with the arguments. 
    return await stepContext.BeginDialogAsync(selectedSkill.Id, skillDialogArgs, cancellationToken);
}

Resumir o resultado do skill

Na última etapa, a caixa de diálogo principal:

  1. Exibe o resultado para o usuário, caso o skill tenha retornado um valor.
  2. Limpa o skill ativo do estado de caixa de diálogo.
  3. Remove a propriedade de skill ativa do estado de conversa.
  4. Reinicia a si mesma (a caixa de diálogo principal).

DialogRootBot\Dialogs\MainDialog.cs

// The SkillDialog has ended, render the results (if any) and restart MainDialog.
private async Task<DialogTurnResult> FinalStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    var activeSkill = await _activeSkillProperty.GetAsync(stepContext.Context, () => null, cancellationToken);

    // Check if the skill returned any results and display them.
    if (stepContext.Result != null)
    {
        var message = $"Skill \"{activeSkill.Id}\" invocation complete.";
        message += $" Result: {JsonConvert.SerializeObject(stepContext.Result)}";
        await stepContext.Context.SendActivityAsync(MessageFactory.Text(message, message, inputHint: InputHints.IgnoringInput), cancellationToken: cancellationToken);
    }

    // Clear the skill selected by the user.
    stepContext.Values[_selectedSkillKey] = null;

    // Clear active skill in state.
    await _activeSkillProperty.DeleteAsync(stepContext.Context, cancellationToken);

    // Restart the main dialog with a different message the second time around.
    return await stepContext.ReplaceDialogAsync(InitialDialogId, $"Done with \"{activeSkill.Id}\". \n\n What skill would you like to call?", cancellationToken);
}

Permitir que o usuário cancele o skill

A caixa de diálogo principal substitui o comportamento padrão do método on continue dialog para permitir que o usuário cancele o skill atual, se houver. No método:

  • Caso haja uma habilidade ativa e o usuário envie uma mensagem de "abortar", cancele todos os diálogos e coloque o diálogo principal na fila para reiniciar.
  • Em seguida, chama a implementação base do método on continue dialog para continuar processando o turno atual.

DialogRootBot\Dialogs\MainDialog.cs

protected override async Task<DialogTurnResult> OnContinueDialogAsync(DialogContext innerDc, CancellationToken cancellationToken = default)
{
    // This is an example on how to cancel a SkillDialog that is currently in progress from the parent bot.
    var activeSkill = await _activeSkillProperty.GetAsync(innerDc.Context, () => null, cancellationToken);
    var activity = innerDc.Context.Activity;
    if (activeSkill != null && activity.Type == ActivityTypes.Message && activity.Text.Equals("abort", StringComparison.OrdinalIgnoreCase))
    {
        // Cancel all dialogs when the user says abort.
        // The SkillDialog automatically sends an EndOfConversation message to the skill to let the
        // skill know that it needs to end its current dialogs, too.
        await innerDc.CancelAllDialogsAsync(cancellationToken);
        return await innerDc.ReplaceDialogAsync(InitialDialogId, "Canceled! \n\n What skill would you like to call?", cancellationToken);
    }

    return await base.OnContinueDialogAsync(innerDc, cancellationToken);
}

Lógica do manipulador de atividades

Como a lógica de skill para cada turno é manipulada por uma caixa de diálogo principal, o manipulador de atividade é muito parecido com outros exemplos de caixa de diálogo.

DialogRootBot\Bots\RootBot.cs

public class RootBot<T> : ActivityHandler
    where T : Dialog

private readonly ConversationState _conversationState;
private readonly Dialog _mainDialog;

public RootBot(ConversationState conversationState, T mainDialog)
{
    _conversationState = conversationState;
    _mainDialog = mainDialog;
}

public override async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken = default)
{
    if (turnContext.Activity.Type != ActivityTypes.ConversationUpdate)
    {
        // Run the Dialog with the Activity.
        await _mainDialog.RunAsync(turnContext, _conversationState.CreateProperty<DialogState>("DialogState"), cancellationToken);
    }
    else
    {
        // Let the base class handle the activity.
        await base.OnTurnAsync(turnContext, cancellationToken);
    }

    // Save any state changes that might have occurred during the turn.
    await _conversationState.SaveChangesAsync(turnContext, false, cancellationToken);
}

Registro do serviço

Os serviços necessários para usar uma caixa de diálogo de skill são os mesmos necessários para um consumidor de skill em geral. Confira como implementar um consumidor de skill para ver uma discussão sobre os serviços necessários.

Testar o bot raiz

Você pode testar o consumidor de skills no Emulador como se fosse um bot normal. No entanto, você precisa executar os bots skills e consumidores de skill ao mesmo tempo. Confira como usar caixas de diálogo em um skill para saber mais sobre como configurar o skill.

Baixe e instale o Bot Framework Emulator mais recente.

  1. Execute o bot de skill de caixa de diálogo e o bot raiz de caixa de diálogo localmente em seu computador. Se você precisar de instruções, confira o README do exemplo para C#, JavaScript, Java, Python.
  2. Use o Emulador para testar o bot.
    • Quando você ingressa na conversa pela primeira vez, o bot exibe uma mensagem de boas-vindas e pergunta qual skill você gostaria de chamar. O bot de skill para este exemplo tem apenas um skill.
    • Selecione DialogSkillBot.
  3. Em seguida, o bot pede que você escolha uma ação para a habilidade. Escolha "BookFlight".
    1. Responda aos prompts.
    2. O skill é concluído, e o bot raiz exibe os detalhes da reserva antes de solicitar novamente o skill que você gostaria de chamar.
  4. Selecione DialogSkillBot novamente e "BookFlight".
    1. Responda ao primeiro prompt e, em seguida, digite "abort" para interromper o skill.
    2. O bot raiz cancela o skill e solicita o skill que você gostaria de chamar.

Mais sobre depuração

Como o tráfego entre as habilidades e os consumidores de habilidades é autenticado, há etapas adicionais na depuração desses bots.

  • O consumidor de habilidades e todas as habilidades que ele consome, direta ou indiretamente, devem estar em execução.
  • Se os bots estiverem sendo executados localmente e se algum dos bots tiver um ID do aplicativo e uma senha, então todos os bots deverão ter IDs e senhas válidos.
  • Se todos os bots estiverem implantados, veja como depurar um bot de qualquer canal usando devtunnel.
  • Se alguns dos bots estiverem sendo executados localmente e alguns estiverem implantados, confira como Depurar uma habilidade ou um consumidor de habilidades.

Caso contrário, você poderá depurar um consumidor de habilidades ou uma habilidade da mesma forma como você depura outros bots. Para obter mais informações, confira Depurar um bot e Depurar com o Bot Framework Emulator.

Informações adicionais

Confira como implementar um consumidor de skills para saber como implementar um consumidor de skills em geral.