Visão geral das competências

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 desta forma, você pode criar um bot voltado para o usuário e estendê-lo consumindo 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 habilidades é um bot que pode chamar uma ou mais habilidades. Um consumidor de habilidades voltado para o usuário também é chamado de bot raiz.
• 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 e os pontos de extremidade da habilidade.
  • Os desenvolvedores que não têm acesso ao código-fonte da habilidade podem usar as informações no manifesto para projetar seu consumidor de habilidades.
  • O esquema de manifesto de habilidade é um arquivo JSON que descreve o esquema do manifesto de habilidade.
  • Veja como implementar uma habilidade e como escrever um manifesto de habilidade para exemplos de manifestos de habilidade.

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 uma habilidade.

O recurso de habilidades é projetado para que:

• Habilidades e consumidores se comunicam por HTTP usando o protocolo Bot Framework.
• Um consumidor de competências pode consumir múltiplas competências.
• Um consumidor de habilidades pode consumir uma habilidade independentemente da linguagem usada para implementá-la. Por exemplo, um bot C# pode consumir uma habilidade implementada usando JavaScript.
• Uma habilidade também pode ser um consumidor de habilidades e chamar outras habilidades.
• As habilidades suportam a autenticação do usuário; no entanto, a autenticação do usuário é local para a habilidade e não pode ser transferida para outro bot.
• As habilidades podem trabalhar com o adaptador Bot Framework e adaptadores personalizados.

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

Arquitetura conceptual

Um consumidor de habilidades e habilidades são bots separados, e você os publica de forma independente.

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

Este diagrama descreve o fluxo de atividades do usuário para o bot raiz para uma habilidade e vice-versa.

1. O adaptador do bot raiz recebe atividades do usuário e as encaminha para o manipulador de atividades 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 habilidade para enviar uma atividade para a habilidade. O cliente obtém as informações de conversação de habilidade do consumidor a partir de uma definição de habilidade e uma fábrica de ID de conversação de habilidade. Isso inclui a URL do serviço que a habilidade usará para responder à atividade.
3. O adaptador da habilidade recebe atividades do consumidor de habilidades e as encaminha para o manipulador de atividades da habilidade. (As atividades do consumidor são recebidas no ponto de extremidade de mensagens do bot de habilidades.)
4. Quando a habilidade responde, o manipulador de habilidades do bot raiz recebe a atividade. Ele obtém as informações de conversação do usuário raiz da fábrica de ID de conversação de habilidades. 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 todas as mensagens da habilidade para o usuário.

Esses objetos ajudam a gerenciar habilidades e rotear o tráfego de habilidades:

• Uma habilidade do Bot Framework descreve informações de roteamento para uma habilidade e pode ser lida no arquivo de configuração do consumidor de habilidades.
• Um cliente HTTP de habilidade envia atividades para uma habilidade.
• Um manipulador de habilidades recebe atividades de uma habilidade.
• A fábrica de ID de conversação de habilidade traduz entre a referência de conversação raiz do usuário e a referência de conversa de habilidade raiz.
• O serviço Bot Connector fornece autenticação de canal e de bot para bot. Usando um objeto de configuração de autenticação, você pode adicionar validação de declarações a um consumidor de habilidade ou habilidade para limitar quais aplicativos ou usuários têm acesso.

O cliente de habilidades e os objetos do manipulador de habilidades usam a fábrica de ID de conversação para traduzir 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 a habilidade.

Manifestos de habilidade

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, consulte como escrever um manifesto de habilidade.

Comunicação Bot-to-bot

É importante entender certos aspetos desse design, independentemente de qual bot você está projetando.

Ações de habilidade

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

• Veja como implementar uma habilidade para uma habilidade simples que implementa uma ação.
• Veja como usar diálogos dentro de uma habilidade para uma habilidade que usa diálogos para implementar várias ações.

Referências de conversação

A conversa raiz do usuário é diferente da conversa de habilidade raiz.

A fábrica de ID de conversação ajuda a gerenciar o tráfego entre um consumidor de habilidades e uma habilidade. A fábrica traduz entre o ID da conversa que a raiz tem com o usuário e o que ele tem com a habilidade. Em outras palavras, ele gera um ID de conversação para uso entre a raiz e a habilidade, e recupera o ID de conversação raiz do usuário original do ID de conversação de habilidade raiz.

Coordenação entre servidores

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

• Sempre salve o estado no consumidor de habilidade antes de encaminhar uma atividade para uma habilidade. Isso garante que a instância que recebe tráfego de uma habilidade possa continuar de onde a instância anterior parou antes de chamar a habilidade.
• Quando o manipulador de habilidades recebe uma atividade de uma habilidade, ele a traduz em um formulário apropriado para o consumidor de habilidade e a encaminha para o adaptador do consumidor.

Consumidor de habilidades e estado de habilidade

O consumidor de competências e as competências gerem o seu próprio estado separadamente. No entanto, o consumidor cria o ID de conversação que usa para se comunicar com a habilidade. Isso pode ter um efeito sobre o estado de conversação na habilidade.

Importante

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

Autenticação de bot para bot

Você não precisa de um ID de aplicativo e senha para testar um consumidor de habilidades 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 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 de entrada.)

Importante

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

Validação de sinistros

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. Lance um erro ou exceção em seu código de validação para rejeitar a solicitação.

Nota

O bot executa a validação de declarações se tiver um ID de 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 habilidades deve aceitar o tráfego apenas de habilidades com as quais ele pode ter iniciado 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 à habilidade a consumidores de habilidades específicas.

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 uma habilidade ou um consumidor de habilidades.

Depurando conversas de habilidade

Como o tráfego entre habilidades e consumidores de habilidades é autenticado, há etapas extras ao depurar esses bots.

• O consumidor de competências e todas as competências que consome, direta ou indiretamente, devem estar a correr.
• Se os bots estiverem sendo executados localmente e se algum deles tiver um ID de aplicativo e senha, todos os bots deverão ter IDs e senhas válidas.
• Se os bots estiverem todos implantados, veja como Depurar um bot de qualquer canal usando ngrok.
• Se alguns dos bots estiverem sendo executados localmente e alguns forem implantados, veja como Depurar uma habilidade ou consumidor de habilidades.

Caso contrário, você pode depurar um consumidor de habilidade ou habilidade da mesma forma que depurar outros bots. Para obter mais informações, consulte Depurando um bot e Depurando com o emulador do Bot Framework.

Informações adicionais

Do ponto de vista do usuário, eles estão interagindo com o bot raiz. Do ponto de vista da habilidade, o consumidor de habilidades é o canal pelo qual ele se comunica com o usuário.

• Para obter mais informações sobre consumidores de habilidades, consulte sobre consumidores de habilidades.