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 forma conversacional, usando texto, gráficos (como cartões ou imagens) ou fala. O Azure AI Bot Service é uma plataforma de nuvem. Ele hospeda bots e os disponibiliza para canais, como Microsoft Teams, Facebook ou Slack.

O Serviço de Bot Framework, que é um componente do Serviço de Bot do Azure AI, 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 envia. 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ção e mensagem, que podem ser trocadas 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ê pode ver duas atividades de atualização de conversa (uma para o usuário que ingressa na conversa e outra para o bot que ingressa). 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 estão carregando texto simples e o canal renderizará esse texto. Como alternativa, a atividade da mensagem pode conter texto a ser falado, ações sugeridas ou cartões a serem exibidos.

Gorjeta

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 outros 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 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 receber um usuário.

O SDK do Bot Framework

O SDK do Bot Framework permite criar bots que podem ser hospedados no Serviço de Bot do Azure AI. 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.

Bots são aplicativos que têm uma interface de conversação. Eles podem ser usados para transferir tarefas simples e repetitivas, como fazer uma reserva para um jantar ou coletar informações de perfil, para sistemas automatizados que podem não exigir mais intervenção humana direta. Os utilizadores conversam com um bot através de texto, cartões interativos e voz. Uma interação com um bot pode ser uma pergunta e resposta rápida ou uma conversação sofisticada que dá acesso a serviços de forma inteligente.

Nota

O suporte para recursos fornecidos pelo SDK e 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

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.

Voltas

Em uma conversa, as pessoas costumam falar uma de cada vez, revezando-se na fala. Com um bot, ele geralmente reage à entrada do usuário. Dentro do SDK do Bot Framework, um turno consiste na atividade de entrada do usuário para o bot e qualquer atividade que o bot envia de volta ao 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 volta 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 da aplicação Bot

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

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

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

Nota

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

Os bots existentes construídos com o Java SDK 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 copilot 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 de 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 tenham 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 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 lide com algum comportamento específico 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 uma caixa de diálogo de componentes 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 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 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 diretamente pelo canal do usuário.
• Apresenta outros métodos fornecidos pela API REST do Bot Connector, como mensagem de atualização e mensagem de exclusão.
• Deteta erros ou exceções não capturados de outra forma para a virada.

O contexto da viragem

O objeto de contexto turn fornece informações sobre a atividade, como o emissor e o recetor, 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 do SDK. Ele não apenas carrega a atividade de entrada para todos os componentes de middleware e 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 turnos na classe de bot que o aplicativo registrou com o método de atividade de processo 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 send activity no contexto de turno. Chamar a atividade de envio no contexto de turno fará 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 outras aplicações Web, um bot é inerentemente sem 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 HTTP

As atividades chegam ao bot a partir do Bot Framework Service 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 um HTTP POST separado para o Bot Framework Service. Isso, por sua vez, é reconhecido 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, normalmente essas solicitações são aninhadas, o que significa que a solicitação HTTP de saída é feita a partir do bot dentro do escopo da solicitação HTTP de entrada. Este padrão é ilustrado no diagrama anterior. Como há duas conexões HTTP distintas de volta para trás, o modelo de segurança deve fornecer ambas.

Nota

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 atividades

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 do Azure AI 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 da 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 transportadas como uma carga JSON chegando, chegando ao servidor web. Muitas vezes, ASP.NET projetos são usados para bots C#, e uma estrutura popular, como Express ou restify, é usada para JavaScript Node.js bots.

O adaptador, um componente integrado do SDK, é o núcleo do tempo de execução do SDK. A atividade é realizada 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.

Como mencionado acima, o contexto de turno fornece o mecanismo para o bot enviar atividades de saída, na maioria das vezes 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 o turno do bot primário lida com a eliminação do objeto de contexto quando ele é concluído. Certifique-se de que await todas as chamadas de atividade para que o thread principal aguarde a atividade gerada antes de terminar seu processamento e descartar o contexto de turno. Caso contrário, se uma resposta (incluindo seus manipuladores) levar uma quantidade significativa de tempo e tentar agir sobre o objeto de contexto, ele pode obter um erro de contexto foi 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 os modelos são fornecidos para cada versão de idioma do SDK. Todos os modelos fornecem uma implementação de ponto de extremidade padrão e um adaptador. Cada modelo inclui:

• Aprovisionamento 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 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 dá as boas-vindas a um usuário à conversa enviando uma mensagem de "olá mundo" no primeiro turno da conversa.
• Bot de eco
  • Usa um manipulador de atividades para receber os 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 receber 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 os recursos Language Understanding (LUIS) e QnA Maker.

Nota

O Azure AI QnA Maker será desativado em 31 de março de 2025. A partir de 1º de outubro de 2022, você não poderá criar novos recursos ou bases de conhecimento do QnA Maker. Uma versão mais recente do recurso 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.

Nota

O Language Understanding (LUIS) será aposentado em 1 de outubro de 2025. A partir de 1 de abril de 2023, não será possível criar novos recursos LUIS. Uma versão mais recente do entendimento de idiomas agora está disponível como parte do Azure AI Language.

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

Informações adicionais

Gerenciando recursos de bot

Você precisará gerenciar os recursos para seu bot, como o ID do aplicativo e a senha, e também as informações de quaisquer serviços conectados. Quando você implanta 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 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 Bot Connector Service 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 do Botkit e repositórios da Comunidade. Para obter mais informações, consulte a tabela de canais e adaptadores do repositório do SDK do Bot Framework.

A API REST do conector 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 suportam o 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óximos passos

• Para entender o papel do estado em bots, consulte gerenciando estado.
• Para entender os principais conceitos de desenvolvimento de bots para o Microsoft Teams, consulte Como os bots do Microsoft Teams funcionam