Visão geral de habilidades

APLICA-SE A: SDK v4

Você pode estender um bot usando um bot de habilidade. Uma habilidade pode ser consumida por vários outros bots, facilitando a reutilização e, dessa forma, você pode criar um bot voltado para o usuário e estendê-lo por meio do consumo de suas próprias habilidades ou de terceiros.

• Uma habilidade é um bot que pode executar um conjunto de tarefas para outro bot (um bot pode ser tanto uma habilidade quanto um bot voltado para o usuário).
• Um consumidor de skill é um bot que pode invocar um ou mais skills. Um consumidor de skill voltado para usuários também é chamado de bot raiz.
• Um manifesto de habilidade é um arquivo JSON que descreve as ações que a habilidade pode executar, os respectivos parâmetros de entrada e saída e os pontos de extremidade da habilidade.
  • Os desenvolvedores que não têm acesso ao código-fonte do skill podem usar as informações do manifesto para criar um consumidor de skill.
  • O esquema de manifesto do skill é um arquivo JSON que descreve o esquema do manifesto de skill.
  • Veja como implementar uma habilidade e como escrever um manifesto de habilidade para manifestos de habilidade de exemplo.

Em outras palavras, o usuário interage diretamente com o bot raiz e o bot raiz delega parte de sua lógica de conversação a um skill.

O recurso dos skills é projetado de forma que:

• Habilidades e consumidores se comunicam por HTTP usando o protocolo Bot Framework.
• Um consumidor de skills pode consumir vários skills.
• Um consumidor de skill pode consumir um skill independentemente da linguagem usada para implementar o skill. Por exemplo, um bot C# pode consumir uma habilidade implementada usando JavaScript.
• Um skill também pode ser um consumidor de skill e chamar outros skills.
• As habilidades são compatíveis com a autenticação de usuário. No entanto, a autenticação do usuário é local para a habilidade e não pode ser transferida para outro bot.
• Os skills podem trabalhar com adaptadores do Bot Framework e adaptadores personalizados.

Este diagrama mostra algumas das possíveis permutações.

Arquitetura conceitual

Um consumidor de skills e um skill são bots diferentes e você os publica de forma independente.

• Um consumidor de habilidade exige uma lógica adicional para gerenciar uma habilidade, como ao chamar ou cancelar a habilidade, e assim por diante. Além dos objetos de bot e adaptador usuais, o consumidor inclui alguns objetos relacionados ao skill, usados para trocar atividades com o skill. Um consumidor de habilidade implementa pelo menos dois pontos de extremidade HTTP:
  • Um ponto de extremidade de mensagens que recebe atividades do usuário ou canal. Esse é o ponto de extremidade de mensagens usual que todos os bots implementam.
  • Um ponto de extremidade de host de habilidade que recebe atividades de uma habilidade. Atua como uma URL de retorno de chamada, a URL de serviço à qual a habilidade responde. (O consumidor de habilidade precisa emparelhar o código que recebe a solicitação do método HTTP de uma habilidade com um manipulador de habilidades.)
• Uma habilidade precisa incluir lógica adicional para enviar uma atividade endOfConversation quando ela for concluída, para que o consumidor de habilidade saiba quando parar de encaminhar atividades para a habilidade.

Este diagrama descreve o fluxo de atividades do usuário para o bot raiz, para um skill e vice-versa.

1. O adaptador do bot raiz recebe atividades do usuário e as encaminha para o manipulador de atividade do bot raiz. (As atividades do usuário são recebidas no ponto de extremidade de mensagens do bot raiz.)
2. O bot raiz usa um cliente HTTP de skill para enviar uma atividade para o skill. O cliente obtém as informações de conversa entre habilidades do consumidor com base em uma definição de habilidade e de um alocador de ID de conversa de habilidades. Isso inclui a URL de serviço que será usada pelo skill para responder à atividade.
3. O adaptador de skill recebe atividades do consumidor de skill e as encaminha para o manipulador de atividades do skill. (As atividades do consumidor são recebidas no ponto de extremidade de mensagens do bot de habilidades.)
4. Quando o skill responde, o manipulador de skills do bot raiz recebe a atividade. Ele obtém as informações de conversa do usuário raiz do alocador de ID de conversa de skill. Em seguida, ele encaminha a atividade para o adaptador do bot raiz. (As atividades da habilidade são recebidas no ponto de extremidade do host de habilidades do bot raiz.)
5. O adaptador do bot raiz gera internamente uma mensagem proativa para retomar a conversa com o usuário.
6. O adaptador do bot raiz envia as mensagens do skill para o usuário.

Esses objetos ajudam a gerenciar os skills e rotear o seu tráfego:

• Um Skill do Bot Framework descreve informações de roteamento para um skill e pode ser lido no arquivo de configuração do consumidor de skills.
• Um cliente HTTP de skill envia atividades a um skill.
• Um manipulador de skills recebe atividades de um skill.
• O alocador de ID de conversa de skill faz a conversão entre a referência de conversa usuário-raiz e a referência de conversa raiz-skill.
• O serviço do Bot Connector fornece a autenticação de canal e de bot para bot. Ao usar um objeto de configuração de autenticação, você pode adicionar validação de declarações a uma habilidade ou consumidor de habilidade para limitar quais aplicativos ou usuários têm acesso.

Os objetos de cliente de skill e de manipulador de skill usam o alocador de ID de conversa para converter entre a conversa que o bot raiz usa para interagir com o usuário e a conversa que o bot raiz usa para interagir com o skill.

Manifestos de habilidades

Um manifesto de habilidade é um arquivo JSON que descreve as ações que a habilidade pode executar, seus parâmetros de entrada e saída, os pontos de extremidade da habilidade e modelos de despacho para a habilidade.

Para obter informações sobre o esquema de manifesto de habilidade, veja como escrever um manifesto de habilidade.

Comunicação de bot para bot

É importante entender determinados aspectos desse design, independentemente do bot que você está criando.

Ações de habilidade

Algumas habilidades podem executar várias tarefas ou ações. Por exemplo, uma habilidade de tarefas pendentes pode permitir criar, atualizar, exibir e excluir atividades que podem ser acessadas como conversas discretas.

• Confira como Implementar uma habilidade para obter uma habilidade simples que implementa uma ação.
• Confira como Usar diálogos em uma habilidade para obter uma habilidade que usa diálogos para implementar várias ações.

Referências de conversa

A conversa usuário-raiz é diferente da conversa raiz-skill.

O alocador de ID de conversa ajuda a gerenciar o tráfego entre um consumidor de skills e um skill. O alocador converte entre a ID de conversa que a raiz tem com o usuário e a que ela tem com o skill. Em outras palavras, ele gera uma ID de conversa para uso entre a raiz e o skill e recupera a ID de conversa usuário-raiz original da ID de conversa raiz-skill.

Coordenação entre servidores

Os bots raiz e de skill se comunicam por HTTP. Portanto, a instância do bot raiz que recebe uma atividade de um skill pode não ser a mesma instância que enviou a atividade de inicialização; em outras palavras, servidores diferentes podem manipular essas duas solicitações.

• Sempre salve o estado no consumidor de skills antes de encaminhar uma atividade para um skill. Isso garante que a instância que recebe o tráfego de um skill possa continuar do local em que a instância anterior parou antes de chamar o skill.
• Quando o manipulador de skills recebe uma atividade de um skill, ele a converte em um formato apropriado para o consumidor de skills e a encaminha para o adaptador do consumidor.

Consumidor de skills e estado de skill

O consumidor de skills e o skill gerenciam seu próprio estado separadamente. No entanto, o consumidor cria a ID de conversa que ele usa para se comunicar com o skill. Isso pode ter um efeito no estado da conversa no skill.

Importante

Conforme observado anteriormente, quando o consumidor de skills delega uma atividade do usuário a um skill, uma instância diferente do consumidor pode receber a resposta do skill. O consumidor sempre deve salvar o estado de conversa imediatamente antes de encaminhar uma atividade para um skill.

Autenticação de bot para bot

Você não precisa de uma ID de aplicativo e senha para testar uma habilidade e um consumidor de habilidade localmente no Bot Framework Emulator. Uma assinatura do Azure ainda é necessária para implantar sua habilidade no Azure.

A autenticação de nível de serviço é gerenciada pelo serviço do Bot Connector. A estrutura usa tokens de portador e IDs de aplicativo de bot para verificar a identidade de cada bot. (O Bot Framework usa um objeto de configuração de autenticação para validar o cabeçalho de autenticação em solicitações recebidas.)

Importante

Isso exige que todos os bots implantados (o consumidor de habilidade e quaisquer habilidades que ele consome) tenham credenciais de aplicativo válidas.

Validação de declarações

Você deve adicionar um validador de declarações à configuração de autenticação. As declarações são avaliadas após o cabeçalho de autenticação. Gere um erro ou uma exceção no código de validação para rejeitar a solicitação.

Observação

O bot realizará a validação de declarações se tiver um ID do aplicativo e senha; caso contrário, a validação de declarações não será executada.

Há vários motivos pelos quais você pode rejeitar uma solicitação autenticada de outra forma:

• Quando o consumidor de skills deve aceitar o tráfego somente de skills com as quais ele iniciou uma conversa.
• Quando uma habilidade faz parte de um serviço pago e os usuários que não estão no banco de dados não devem ter acesso.
• Quando você deseja restringir o acesso ao skill para consumidores de skills específicos.

Importante

Se você não fornecer um validador de declarações, seu bot gerará um erro ou exceção ao receber uma atividade de outro bot, seja ele um consumidor de habilidade, seja ele uma habilidade.

Como depurar conversas de habilidade

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 os bots estiverem todos implantados, confira como Depurar um bot em qualquer canal usando o ngrok.
• 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

Da perspectiva do usuário, ele está interagindo com o bot raiz. Da perspectiva do skill, o consumidor de skills é o canal pelo qual ele se comunica com o usuário.

• Confira mais informações sobre consumidores de skill.