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 o Microsoft Teams, o Facebook ou o Slack.

O Bot Framework Service, 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 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.

O Bot Framework Service envia uma atualização de conversa quando uma parte entra na conversa. Por exemplo, ao iniciar uma conversa com o Bot Framework Emulator, você poderá ver duas atividades de atualização de conversa (uma para o usuário que está entrando na conversa e outra para o bot que está entrando). 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 contém 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 do 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 outros enviam atividades de atualização de conversa depois de enviarem a primeira atividade de mensagem. Um canal pode incluir tanto o bot quanto 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, confira 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 que seu bot e canais ou usuários possam 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 não seja necessário 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ção. 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 aos 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 pretende disponibilizá-lo.

As interações envolvem a troca de atividades, que são gerenciadas 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 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 e, nesse momento, o turno termina. No próximo turno, 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 de bot

O SDK define uma classe de bot que lida com o raciocínio de conversação para o aplicativo de bot. A classe de bot:

• Reconhece e interpreta a entrada de usuário.
• Raciocina sobre 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 lida com 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 turno fora do manipulador de turno de seu bot.
• Chama o manipulador de turno do bot e captura os erros que não foram gerenciados de outra forma no manipulador de turnos.

Além disso, os bots geralmente precisam recuperar e armazenar o estado a cada turno. O estado é gerenciado por meio de classes de armazenamento, estado de bot e acessador de propriedade. O SDK não oferece armazenamento interno, mas fornece abstrações para armazenamento e algumas implementações de uma camada de armazenamento. O tópico sobre gerenciamento de estado 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. A estrutura do bot tem modelos e exemplos para ASP.NET (C#), restify (JavaScript) e aiohttp (Python). No entanto, é possível optar por usar uma camada de aplicativo diferente para o 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. A estrutura do bot 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 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.

Lógica do bot

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

O SDK oferece alguns paradigmas diferentes para gerenciar a lógica do seu bot.

• Os manipuladores de atividade fornecem um modelo orientado 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 curtas e limitadas com o usuário.
  • Use um manipulador de atividade e implemente manipuladores para cada tipo ou subtipo de atividade que seu bot reconhecerá e ao qual reagirá.
  • Use um manipulador de atividade do Teams para criar bots que possam se conectar ao canal do Teams. (O canal do Teams exige que o bot manipule alguns comportamentos específicos do canal).
• A biblioteca de diálogos fornece um modelo baseado em estado para gerenciar uma conversa de longa duração com o usuário.
  • Use um manipulador de atividades e um componente de diálogo para conversas amplamente sequenciais. Para obter mais informações, confira sobre diálogos de componentes e cascata.
• 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 informações do usuário.

O adaptador de bot

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

• Ele recebe o corpo da solicitação (a payload 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 turno do objeto do 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.
• Exibe outros métodos fornecidos pela API REST do Bot Connector, como atualizar mensagem e excluir mensagem.
• Captura erros ou exceções não capturados de outra forma para o turno.

O contexto do 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ó transmite a atividade de entrada para todos os componentes de middleware e para a lógica do aplicativo, mas também fornece o mecanismo pelo qual os componentes de middleware e a lógica de 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 no turno que o adaptador chama.

O manipulador de turno usa um contexto de turno como argumento. Normalmente, a lógica do aplicativo executada dentro da função do manipulador de turno 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 enviar atividade no contexto do 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 do manipulador de turno do bot. A execução é inerentemente aninhada e, como tal, às vezes é chamada de cebola.

O tópico sobre middleware descreve o middleware com mais detalhes.

Estado do bot e armazenamento

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

O tópico sobre gerenciamento de estado 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 um status 200 na maioria dos canais. Se o bot não responder em 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.

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. Geralmente, os projetos ASP.NET são usados para bots C#, e uma estrutura popular, como Express ou restify, é usada para bots JavaScript Node.js.

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 é então 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 encadeamento que manipula o bot primário, por sua vez, 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 a camada de aplicativo a ser usada em seu aplicativo. No entanto, o Bot Framework tem modelos e exemplos para ASP.NET (C#), restify (JavaScript) e aiohttp (Python). A documentação foi escrita supondo que você usa uma dessas plataformas, mas o SDK não exige essa condição. Confira o início rápido de Criar um bot para obter instruções sobre como acessar e instalar os modelos.

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

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

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

• Bot vazio
  • Inclui um manipulador de atividade que dá as boas-vindas a um usuário na conversa enviando uma mensagem "olá, mundo" no primeiro turno da conversa.
• Bot de eco
  • Usa um manipulador de atividade para dar as boas-vindas aos usuários e ecoar a entrada do usuário.
• Bot principal
  • Reúne vários recursos do SDK e demonstra as melhores práticas para um bot.
  • Usa um manipulador de atividade para dar as boas-vindas aos usuários.
  • Usa um diálogo de componente e diálogos secundários para gerenciar a conversa.
  • As caixas de diálogo usam os recursos de reconhecimento de linguagem (LUIS) e QnA Maker.

Observação

O QnA Maker da IA do Azure será desativada 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.

Respostas às perguntas personalizadas, um recurso de 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, confira reconhecimento de linguagem natural.

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.

Informações adicionais

Gerenciar recursos do bot

Você precisará gerenciar os recursos do seu bot, como a 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 a complexidade, a maioria dos artigos do SDK do Bot Framework não descreve como gerenciar essas informações.

• Para obter informações gerais sobre segurança, confira as Diretrizes de segurança do Bot Framework.
• Para gerenciar chaves e segredos no Azure, confira 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 executa adicionalmente 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 nos repositórios do Botkit e da Comunidade. Para obter mais informações, confira 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 abrange e se baseia na API REST do Bot Connector. Se você quiser entender as solicitações HTTP subjacentes que são compatíveis com o SDK, confira a autenticação do Connector e os artigos associados. As atividades que um bot envia e recebe estão em conformidade com o esquema de atividades 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