Noções básicas do Microsoft Bot Framework

APLICA-SE A: SDK v4

Um bot é um aplicativo com o qual os usuários interagem de maneira conversacional usando texto, gráficos (cartões ou imagens) ou fala. O Serviço de Bot de IA do Azure é uma plataforma de nuvem. Ele hospeda bots e os disponibiliza para canais, como Microsoft Teams, Facebook ou Slack.

O Serviço de Estrutura de Bot, que é um componente do Serviço de Bot de IA do Azure, envia informações entre o aplicativo conectado ao bot do usuário e o bot. Cada canal pode incluir informações adicionais nas atividades enviadas. Antes de criar bots, é importante entender como um bot usa objetos de atividade para se comunicar com seus usuários.

Este diagrama ilustra dois tipos de atividade, atualização de conversa e mensagem, que podem ser trocados quando um usuário se comunica com um bot de eco.

O Bot Framework Service envia uma atualização de conversa quando uma parte ingressa na conversa. Por exemplo, ao iniciar uma conversa com o Bot Framework Emulator, você pode ver duas atividades de atualização de conversa (uma para o usuário ingressando na conversa e outra para o bot ingressando). Para distinguir essas atividades de atualização de conversa, verifique quem está incluído na propriedade de membros adicionados da atividade.

A atividade de mensagem carrega informações de conversa entre as partes. Em um exemplo de bot de eco, as atividades de mensagem transmitem texto simples e o canal renderiza esse texto. Como alternativa, a atividade de mensagem pode conter o texto a ser falado, as ações sugeridas ou os cartões a serem exibidos.

Dica

Cabe a cada canal implementar o protocolo Bot Framework e a forma como cada canal faz isso pode ser um pouco diferente. Por exemplo, alguns canais enviam atividades de atualização de conversa primeiro e alguns enviam atividades de atualização de conversa depois de enviar a primeira atividade de mensagem. Um canal pode incluir o bot e o usuário em uma atividade de atualização de conversa, enquanto outro pode enviar duas atividades de atualização de conversa.

Neste exemplo, o bot criou e enviou uma atividade de mensagem em resposta à atividade de mensagem de entrada que ele recebeu. No entanto, um bot pode responder de outras maneiras a uma atividade de mensagem recebida, e é comum que um bot responda a uma atividade de atualização de conversa enviando uma atividade de mensagem com uma mensagem de boas-vindas. Para obter mais informações, consulte como dar as boas-vindas a um usuário.

O SDK do Bot Framework

O SDK do Bot Framework permite que você crie bots que podem ser hospedados no Serviço de Bot de IA do Azure. O serviço define uma API REST e um protocolo de atividade para como o bot e os canais ou usuários podem interagir. O SDK se baseia nessa API REST e fornece uma abstração do serviço para que você possa se concentrar na lógica de conversação. Embora você não precise entender o serviço REST para usar o SDK, entender alguns de seus recursos pode ser útil.

Bots são aplicativos que possuem uma interface conversacional. Eles podem ser usados para transferir simples tarefas repetitivas, como fazer a reserva para um jantar ou coletar informações de perfil, para sistemas automatizados que não exigem uma intervenção humana direta. Os usuários conversam com um bot usando texto, cartões interativos e fala. Uma interação de bot pode ser uma pergunta e resposta rápidas, ou pode ser uma conversa sofisticada que fornece acesso aos serviços de forma inteligente.

Observação

O suporte para recursos fornecidos pelo SDK e pela API REST varia de acordo com o canal. Você pode testar seu bot usando o Bot Framework Emulator, mas também deve testar todos os recursos do seu bot em cada canal no qual você pretende disponibilizar seu bot.

As interações envolvem a troca de atividades, que são tratadas em turnos.

Atividades

Toda interação entre o usuário (ou um canal) e o bot é representada como uma atividade. O esquema Bot Framework Activity define as atividades que podem ser trocadas entre um usuário ou canal e um bot. As atividades podem representar texto ou fala humana, notificações de aplicativo para aplicativo, reações a outras mensagens e assim por diante.

Ativa

Em uma conversa, as pessoas geralmente falam uma de cada vez, alternando a vez de falar. Com um bot, geralmente ele reage à entrada do usuário. Dentro do SDK do Bot Framework, um turno é a atividade de entrada do usuário para o bot e qualquer atividade que o bot envia de volta para o usuário como uma resposta imediata. Você pode pensar em um turno como o processamento associado ao bot que recebe uma determinada atividade.

Por exemplo, um usuário pode pedir a um bot para executar uma determinada tarefa. O bot pode responder com uma pergunta para obter mais informações sobre a tarefa, momento em que essa virada termina. No turno seguinte, o bot recebe uma nova mensagem do usuário que pode conter a resposta à pergunta do bot, ou pode representar uma mudança de assunto ou uma solicitação para ignorar a solicitação inicial para executar a tarefa.

Estrutura do aplicativo Bot

O SDK define uma classe de bot que manipula o raciocínio conversacional para o aplicativo bot . A classe bot:

• Reconhece e interpreta a entrada do usuário.
• Fundamenta a entrada e executa tarefas relevantes.
• Gera respostas sobre o que o bot está fazendo ou fez.

O SDK também define uma classe de adaptador que manipula a conectividade com os canais. O adaptador:

• Fornece um método para lidar com solicitações de e métodos para gerar solicitações para o canal do usuário.
• Inclui um pipeline de middleware, que inclui o processamento de turnos fora do manipulador de turnos do bot.
• Chama o manipulador de turnos do bot e detecta erros não manipulados de outra forma no manipulador de turnos.

Além disso, os bots geralmente precisam recuperar e armazenar o estado a cada turno. O estado é manipulado por meio de armazenamento, estado do bot e classes de acessador de propriedade. O SDK não fornece armazenamento interno, mas fornece abstrações para armazenamento e algumas implementações de uma camada de armazenamento. O tópico de estado de gerenciamento descreve esses recursos de estado e armazenamento.

O SDK não exige que você use uma camada de aplicativo específica para enviar e receber solicitações da Web. O Bot Framework tem modelos e exemplos para ASP.NET (C#), restify (JavaScript) e aiohttp (Python). No entanto, você pode optar por usar uma camada de aplicativo diferente para seu aplicativo.

Ao criar um bot usando o SDK, você fornece o código para receber o tráfego HTTP e encaminhá-lo para o adaptador. O Bot Framework fornece alguns modelos e exemplos que você pode usar para desenvolver seus próprios bots.

Observação

Os SDKs JavaScript, C# e Python do Bot Framework continuarão a ser suportados, no entanto, o SDK Java está sendo desativado com suporte final de longo prazo terminando em novembro de 2023. Somente correções críticas de segurança e bugs dentro deste repositório serão realizadas.

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

Para criar novos bots, considere usar o Power Virtual Agents e leia sobre como escolher a solução de chatbot certa.

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

Lógica do bot

O objeto bot contém o raciocínio conversacional ou a lógica para um turno e expõe um manipulador de turnos, que é o método que pode aceitar atividades de entrada do adaptador de bot.

O SDK fornece alguns paradigmas diferentes para gerenciar sua lógica de bot.

• Os manipuladores de atividade fornecem um modelo controlado por eventos no qual os tipos e subtipos de atividade de entrada são os eventos. Considere um manipulador de atividades para bots que têm interações limitadas e curtas com o usuário.
  • Use um manipulador de atividades e implemente manipuladores para cada tipo ou subtipo de atividade que seu bot reconhecerá e reagirá.
  • Use um manipulador de atividades do Teams para criar bots que possam se conectar ao canal do Teams. (O canal do Teams exige que o bot manipule algum comportamento específico do canal.)
• A biblioteca de caixas de diálogo fornece um modelo baseado em estado para gerenciar uma conversa de longa duração com o usuário.
  • Use um manipulador de atividades e uma caixa de diálogo de componente para conversas em grande parte sequenciais. Para obter mais informações, consulte sobre caixas de diálogo de componentes e cascatas.
• Implemente sua própria classe de bot e forneça sua própria lógica para lidar com cada turno. Para obter um exemplo, veja como criar seus próprios prompts para coletar a entrada do usuário.

O adaptador de bot

O adaptador tem um método de atividade de processo para iniciar uma volta.

• Ele usa o corpo da solicitação (a carga útil da solicitação, traduzida em uma atividade) e o cabeçalho da solicitação como argumentos.
• Ele verifica se o cabeçalho de autenticação é válido.
• Ele cria um objeto de contexto para o turno. O objeto de contexto inclui informações sobre a atividade.
• Ele envia o objeto de contexto por meio de seu pipeline de middleware .
• Em seguida, ele envia o objeto de contexto para o manipulador de turnos do objeto bot.

O adaptador também:

• Formata e envia atividades de resposta. Essas respostas geralmente são mensagens para o usuário, mas também podem incluir informações a serem consumidas pelo canal do usuário diretamente.
• Apresenta outros métodos fornecidos pela API REST do Bot Connector, como mensagem de atualização e mensagem de exclusão.
• Captura erros ou exceções não detectadas de outra forma para a virada.

O contexto da virada

O objeto contexto de turno fornece informações sobre a atividade, como o remetente e o receptor, o canal e outros dados necessários para processar a atividade. Ele também permite a adição de informações durante o turno em várias camadas do bot.

O contexto de turno é uma das abstrações mais importantes no SDK. Ele não apenas carrega a atividade de entrada para todos os componentes do middleware e a lógica do aplicativo, mas também fornece o mecanismo pelo qual os componentes do middleware e a lógica do bot podem enviar atividades de saída.

Middleware

O Middleware é muito parecido com qualquer outro middleware de mensagens, compreendendo um conjunto linear de componentes que são executados em ordem, dando a cada um a chance de operar na atividade. O estágio final do pipeline de middleware é um retorno de chamada para o manipulador de turno na classe do bot que o aplicativo registrou com o método processar atividade do adaptador. O middleware implementa um método on turn que o adaptador chama.

O manipulador de turnos usa um contexto de turno como argumento, normalmente a lógica do aplicativo em execução dentro da função de manipulador de turnos processará o conteúdo da atividade de entrada e gerará uma ou mais atividades em resposta, enviando essas atividades de saída usando a função de atividade de envio no contexto de turno. Chamar enviar atividade no contexto de turno faz com que os componentes de middleware sejam invocados nas atividades de saída. Os componentes de middleware são executados antes e depois da função de manipulador de turnos do bot. A execução é inerentemente aninhada e, como tal, às vezes referida como sendo como uma cebola.

O tópico middleware descreve o middleware em maior profundidade.

Estado e armazenamento do bot

Tal como acontece com outros aplicativos Web, um bot é inerentemente sem monitoração de estado. O estado dentro de um bot segue os mesmos paradigmas dos aplicativos Web modernos, e o SDK do Bot Framework fornece abstrações de gerenciamento de estado e camada de armazenamento para facilitar o gerenciamento de estado.

O tópico de estado de gerenciamento descreve esses recursos de estado e armazenamento.

Ponto de extremidade e provisionamento de mensagens

Normalmente, seu aplicativo precisará de um ponto de extremidade REST para receber mensagens. Ele também precisará provisionar recursos para seu bot de acordo com a plataforma que você decidir usar.

Siga o guia de início rápido Criar um bot para criar e testar um bot de eco simples.

Detalhes do HTTP

As atividades chegam ao bot do serviço Bot Framework por meio de uma solicitação HTTP POST. O bot responde à solicitação POST de entrada com um código de status HTTP 200. As atividades enviadas do bot para o canal são enviadas em uma HTTP POST separada para o serviço Bot Framework. Isso, por sua vez, é confirmado com um código de status HTTP 200.

O protocolo não especifica a ordem em que essas solicitações POST e suas confirmações são feitas. No entanto, para se ajustar a estruturas de serviço HTTP comuns, essas solicitações normalmente são aninhadas, o que significa que a solicitação HTTP de saída é feita do bot dentro do escopo da solicitação HTTP de entrada. Esse padrão é ilustrado no diagrama anterior. Como há duas conexões HTTP distintas de ponta a ponta, o modelo de segurança deve servir a ambas.

Observação

O bot tem 15 segundos para confirmar a chamada com status 200 na maioria dos canais. Se o bot não responder dentro de 15 segundos, ocorrerá um erro HTTP GatewayTimeout (504).

A pilha de processamento de atividade

Vamos detalhar o diagrama de sequência anterior com foco na chegada de uma atividade de mensagem.

O canal envia a mensagem do usuário para o Serviço de Bot de IA do Azure e o serviço encaminha a mensagem para o ponto de extremidade de mensagens do bot. A resposta do bot é enviada ao usuário dentro do escopo do turno.

No exemplo acima, o bot respondeu à atividade de mensagem com outra atividade de mensagem contendo a mesma mensagem de texto. O processamento começa com a solicitação HTTP POST, com as informações de atividade transmitidas como uma carga JSON, chegando ao servidor Web. Muitas vezes, projetos ASP.NET são usados para bots C#, e uma estrutura popular, como Express ou restify, é usada para bots JavaScript Node.js bots.

O adaptador, um componente integrado do SDK, é o núcleo do runtime do SDK. A atividade é executada como JSON no corpo HTTP POST. Esse JSON é desserializado para criar o objeto de atividade que é entregue ao adaptador por meio de seu método de atividade de processo. Ao receber a atividade, o adaptador cria um contexto de turno e chama o middleware.

Conforme mencionado acima, o contexto de turno fornece o mecanismo para que o bot envie atividades de saída, geralmente em resposta a uma atividade de entrada. O contexto de turno fornece métodos de resposta de atividade de envio, atualização e exclusão. Cada método de resposta é executado em um processo assíncrono.

Importante

O thread que manipula a virada do bot principal lida com o descarte do objeto de contexto quando ele é concluído. Certifique-se de await todas as chamadas de atividade para que o segmento principal espere na atividade gerada antes de terminar o processamento e a eliminação do contexto de turno. Caso contrário, se uma resposta (incluindo seus manipuladores) demora um tempo significativo e tenta agir no objeto de contexto, ela pode receber um erro de contexto descartado.

Modelos de bot

Você precisa escolher o uso da camada de aplicativo para seu aplicativo; no entanto, o Bot Framework tem modelos e exemplos para ASP.NET (C#), restify (JavaScript) e aiohttp (Python). A documentação é escrita supondo que você use uma dessas plataformas, mas o SDK não exige isso de você. Consulte o Guia de início rápido Criar um bot para obter instruções sobre como acessar e instalar os modelos.

Um bot é um aplicativo Web e modelos são fornecidos para cada versão de idioma do SDK. Todos os modelos fornecem uma implementação e um adaptador de ponto de extremidade padrão. Cada modelo inclui:

• Provisionamento de recursos
• Uma implementação de ponto de extremidade HTTP específica do idioma que roteia as atividades de entrada para um adaptador.
• Um objeto de adaptador
• Um objeto de bot

A principal diferença entre os diferentes tipos de modelo está no objeto bot. Os modelos são:

• Bot vazio
  • Inclui um manipulador de atividades que dá as boas-vindas a um usuário na conversa enviando uma mensagem "hello world" no primeiro turno da conversa.
• Bot de eco
  • Usa um manipulador de atividades para dar as boas-vindas aos usuários e ecoar a entrada do usuário.
• Bot principal
  • Reúne muitos recursos do SDK e demonstra as práticas recomendadas para um bot.
  • Usa um manipulador de atividades para dar boas-vindas aos usuários.
  • Usa uma caixa de diálogo de componente e caixas de diálogo filho para gerenciar a conversa.
  • As caixas de diálogo usam recursos LUIS (Language Understanding) e QnA Maker.

Observação

O Azure AI QnA Maker será desativado em 31 de março de 2025. A partir de 1° de outubro de 2022, não será mais possível criar recursos ou bases de conhecimento do QnA Maker. Uma versão mais recente da funcionalidade de perguntas e respostas agora está disponível como parte da Linguagem de IA do Azure.

A resposta a perguntas personalizadas, um recurso da Linguagem de IA do Azure, é a versão atualizada do serviço QnA Maker. Para obter mais informações sobre o suporte a perguntas e respostas no SDK do Bot Framework, consulte Compreensão de linguagem natural.

Observação

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

A compreensão de linguagem conversacional (CLU), um recurso da Linguagem de IA do Azure, é a versão atualizada do LUIS. Para obter mais informações sobre o suporte à compreensão de idioma no SDK do Bot Framework, consulte Compreensão de linguagem natural.

Informações adicionais

Gerenciando recursos de bot

Você precisará gerenciar os recursos do bot, como o ID do aplicativo e a senha, e também as informações de todos os serviços conectados. Quando você implantar seu bot, ele precisará de acesso seguro a essas informações. Para evitar complexidade, a maioria dos artigos do SDK do Bot Framework não descreve como gerenciar essas informações.

• Para obter informações gerais de segurança, consulte Diretrizes de segurança do Bot Framework.
• Para gerenciar chaves e segredos no Azure, consulte Sobre o Cofre de Chaves do Azure.

Adaptadores de canal

O SDK também permite que você use adaptadores de canal, nos quais o próprio adaptador executa adicionalmente as tarefas que o Serviço de Conector de Bot normalmente faria para um canal.

O SDK fornece alguns adaptadores de canal em alguns idiomas. Mais adaptadores de canal estão disponíveis através dos repositórios Botkit e Community. Para obter mais informações, consulte a tabela de canais e adaptadores do repositório do SDK do Bot Framework.

A API REST do Bot Connector

O SDK do Bot Framework encapsula e se baseia na API REST do Bot Connector. Se você quiser entender as solicitações HTTP subjacentes que oferecem suporte ao SDK, consulte a autenticação do conector e os artigos associados. As atividades que um bot envia e recebe estão em conformidade com o esquema de Atividade do Bot Framework.

Próximas etapas

• Para entender a função do estado dos bots, consulte gerenciar o estado.
• Para entender os principais conceitos de desenvolvimento de bots para o Microsoft Teams, confira Como os bots do Microsoft Teams funcionam