Noções básicas do Serviço do 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 do Azure é uma plataforma de nuvem. Ele hospeda bots e os disponibiliza para canais, como Microsoft Teams, Facebook ou Slack.

O Serviço do Bot Framework, que é um componente do Serviço de Bot 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 que eles enviam. 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 simples.

O Serviço do Bot Framework 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 que ingressa na conversa e outra para a junção do bot). Para distinguir essas atividades de atualização de conversa, verifique quem está incluído na propriedade adicionada aos membros 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 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 enviarem 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; não é incomum que um bot responda a uma atividade de atualização de conversa enviando um texto de boas-vindas em uma atividade de mensagem. Mais informações podem ser encontradas em como receber 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 do Azure. O serviço define uma API REST e um protocolo de atividade para como seu bot e 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.

Os bots são aplicativos que têm uma interface de conversa. 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 bot em cada canal no qual pretende disponibilizar o bot.

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

Atividades

Cada interação entre o usuário (ou um canal) e o bot é representada como uma atividade. O esquema de Atividade do Bot Framework define as atividades que podem ser trocadas entre um usuário ou canal e um bot. As atividades podem representar texto humano ou fala, 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 uma vez 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 curva termina. Na próxima vez, o bot recebe uma nova mensagem do usuário que pode conter a resposta para a pergunta do bot ou pode representar uma alteração 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 lida com o raciocínio de conversa para o aplicativo bot. A classe de bot:

• Reconhece e interpreta a entrada do usuário.
• Motivos sobre a entrada e realiza 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 e métodos para gerar solicitações para o canal do usuário.
• Inclui um pipeline de middleware, que inclui transformar o processamento fora do manipulador de turno do bot.
• Chama o manipulador de turnos do bot e captura erros não tratados de outra forma no manipulador de turno.

Além disso, os bots geralmente precisam recuperar e armazenar o estado a cada turno. Isso é tratado por meio de classes de armazenamento, estado do bot e 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.

Lógica do bot

O objeto bot contém o raciocínio ou a lógica de conversa para uma vez e expõe um manipulador de turno, 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 de atividade de entrada e subtipos são os eventos. Isso pode ser bom 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 de atividade ou subtipo ao qual o 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 requer que o bot manipule algum comportamento específico do canal.)
• A biblioteca de diálogos fornece um modelo baseado em estado para gerenciar uma conversa de longa execução com o usuário.
  • Use um manipulador de atividades e uma caixa de diálogo de componente para conversas em grande parte sequenciais. Consulte mais informações sobre caixas de diálogo de componente e cascata .
  • Use um gerenciador de diálogos e uma caixa de diálogo adaptável para um fluxo de conversa flexível que possa lidar com uma gama mais ampla de interação do usuário. Confira a introdução às caixas de diálogo adaptáveis para obter mais informações.
• Implemente sua própria classe de bot e forneça sua própria lógica para lidar com cada turno. Veja como criar seus próprios prompts para coletar a entrada do usuário para obter um exemplo de como isso pode ser.

O adaptador de bot

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

• Ele usa o corpo da solicitação (o conteúdo da solicitação, traduzido para 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 a curva.
• Ele executa isso por meio de seu pipeline de middleware .
• Ele envia a atividade para o manipulador de turno do objeto bot.

O adaptador também:

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

O contexto de turno

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 só 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 de ativação que o adaptador chama.

O manipulador de turno usa um contexto de turno como argumento, normalmente a lógica do aplicativo em execução dentro da função de manipulador de turno processará o conteúdo da atividade de entrada e gerará uma ou mais atividades em resposta, enviando-as 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 do Middleware são executados antes e depois da função do manipulador de turnos do bot. A execução é inerentemente aninhada e, como tal, às vezes se refere a ser como uma cebola.

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

Estado do bot e armazenamento

Assim como acontece com outros aplicativos Web, um bot é inerentemente sem estado. O estado dentro de um bot segue os mesmos paradigmas que os 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 no qual receber mensagens. Ele também precisará provisionar recursos para o bot de acordo com a plataforma que você decidir usar.

Siga o 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 na qual 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 reconhecer a chamada com um 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 analisar o diagrama de sequência anterior com foco na chegada de uma atividade de mensagem.

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. Em C#, isso normalmente será um projeto ASP.NET, em um projeto de Node.js JavaScript, essa provavelmente será uma das estruturas populares, como Express ou restify.

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, em seguida, é 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. Para isso, 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 encadeamento que manipula o giro do bot primário lida com a disposição do objeto de contexto quando isso é feito. 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 é gravada 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 os 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 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 recebe um usuário na conversa enviando uma mensagem "olá, mundo" na primeira vez da conversa.
• Bot de Eco
  • Usa um manipulador de atividades para receber usuários e retornar a entrada do usuário.
• Bot principal
  • Reúne muitos recursos do SDK e demonstra as melhores práticas para um bot.
  • Usa um manipulador de atividades para receber os 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 do LUIS (Reconhecimento Vocal) e do QnA Maker.

Informações adicionais

Gerenciamento de recursos de bot

Você precisará gerenciar os recursos do bot, como a ID e a senha do aplicativo e também as informações para quaisquer serviços conectados. Quando você implantar o bot, ele precisará de acesso seguro a essas informações. Para evitar a 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 as diretrizes de segurança do Bot Framework.
• Para gerenciar chaves e segredos no Azure, consulte Sobre o Azure Key Vault.

Adaptadores de canal

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

O SDK fornece alguns adaptadores de canal em alguns idiomas. Mais adaptadores de canal estão disponíveis por meio dos repositórios do Botkit e da Comunidade. Para obter mais detalhes, consulte a tabela de canais e adaptadores do repositório do SDK do Bot Framework.

A API REST do Conector de Bot

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 dão 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