Configurar uma habilidade do Bot Framework para usar no Copilot Studio

Artigo
04/08/2024

Importante

As capacidades e os recursos do Power Virtual Agents agora fazem parte do Microsoft Copilot Studio após investimentos significativos em IA generativa e integrações aprimoradas no Microsoft Copilot.

Alguns artigos e capturas de tela podem fazer referência ao Power Virtual Agents enquanto atualizamos a documentação e o conteúdo do treinamento.

O Copilot Studio permite que você estenda o copiloto usando habilidades do Bot Framework. Se você já tiver criado e implantado bots na organização (usando o SDK e as ferramentas pró-código do Bot Framework) para cenários específicos, é possível converter esses bots em uma habilidade e registrá-la em um copiloto do Copilot Studio.

Observação

Você pode adicionar uma habilidade no aplicativo do Copilot Studio no Microsoft Teams, você deve ter uma assinatura autônoma do Microsoft Copilot Studio.

Este artigo é destinado a administradores do sistema ou profissionais de TI familiarizados com as habilidades do Bot Framework. Após o registro de uma habilidade em um copiloto do Copilot Studio, os autores podem perfeitamente disparar ações da habilidade na conversa.

Pré-requisitos

Revisar as restrições e a validação de habilidades usadas no Copilot Studio

Importante

Os copilotos do Copilot Studio só dá suporte a habilidades criadas com o SDK do Bot Framework versão 4.12.0+.

Os chatbots clássicos só dão suporte a habilidades criadas com o Bot Framework SDK versão 4.7+.

Se você estiver usando o Bot Framework Composer, é altamente recomendável usar o Composer 2.x. Se você quiser usar um copiloto do Composer 1.x existente, primeiro migre-o para o Composer 2.x antes de usá-lo como uma habilidade.

Para configurar uma habilidade, o registro de aplicativo associado no Microsoft Entra ID da sua habilidade deve ser definido como Configuração multilocatário.

Ações de fluxos e ações de habilidades

A tabela a seguir ajudará a determinar quando usar habilidades para uma conversa.

	Ações de Fluxo	Ações de habilidade
Persona	Os autores do copiloto podem criar Fluxos reutilizáveis para inseri-los em qualquer conversa do copiloto.	Os desenvolvedores podem criar, implantar e hospedar habilidades personalizadas em seu próprio ambiente
Conversa	Use Fluxos para operações simples de um turno. Por exemplo, fazer um pedido ou obter o status do pedido.	Use habilidades para operações complexas de várias vezes. Por exemplo, agendar uma reunião ou reservar um voo.
Resposta	Use Fluxos para emitir uma resposta do copiloto. Por exemplo, mostrar uma mensagem personalizada ou imagens embutidas.	Use habilidades para emitir qualquer resposta do copiloto compatível. Por exemplo, mostre um cartão adaptável ou envie respostas aleatórias.
Ações	Use Fluxos para disparar ações de turno único no servidor. Por exemplo, chame uma API HTTP ou dispare um conector personalizado.	Use habilidades para disparar eventos e ações do lado do servidor e do cliente. Por exemplo, navegue para uma página após a resposta do copiloto.

Configurar uma habilidade

Primeiro, use o Copilot Studio para criar um copiloto e criar e implantar uma habilidade usando ferramentas de código profissional em sua organização.

Antes de registrar a habilidade, forneça a ID do copiloto ao desenvolvedor de habilidades para autorizar o copiloto a chamar ações na habilidade. Saiba mais sobre a lista de permissões da habilidade. Você pode obter a ID do copiloto na janela Adicionar uma habilidade.

Para adicionar uma habilidade em seu copiloto:

No painel de navegação, expanda Configurações e selecione Habilidades.
Na parte superior da página Habilidades, selecione Adicionar habilidade.
Copie a ID do seu copiloto e forneça-a ao seu desenvolvedor de habilidades.
Insira a URL para o manifesto da habilidade. O manifesto de uma habilidade contém as informações necessárias para seu copiloto disparar ações dentro de uma habilidade.
Selecione Avançar para iniciar o processo de validação. Depois que a validação for bem-sucedida, sua habilidade será adicionada ao seu copiloto. Agora você pode usar essa habilidade em seus tópicos.

Considerações de conformidade

Para proteger a privacidade do usuário, exigimos que as habilidades sejam registradas como um aplicativo no locatário do Microsoft Entra ID do usuário conectado.

Solucionar erros durante o registro de habilidades

Uma série de verificações de validação é feita na URL. Essas verificações garantem a conformidade, a governança e a usabilidade da habilidade que está sendo adicionada ao seu copiloto. Você precisará corrigir esses erros antes de registrar uma habilidade.

Mensagem de erro	Solucionar problemas/mitigação
Encontramos problemas ao obter o manifesto de habilidade. (`MANIFEST_FETCH_FAILED`)	Tente abrir a URL do seu manifesto em um navegador da Web. Se o URL renderizar a página em 10 segundos, registre novamente a habilidade.
O manifesto é incompatível. (`MANIFEST_MALFORMED`)	(a) Verifique se o manifesto é um arquivo JSON válido. (b) Verifique se o manifesto contém as propriedades necessárias Por exemplo, (`name`, `msaAppId`, `endpoint` único, `activities`/`id`, `activities`/`description`, `activities`/`type` (`event` único ou `message` compatível)).
Há uma incompatibilidade nos seus pontos de extremidade (`MANIFEST_ENDPOINT_ORIGIN_MISMATCH`)	Verifique se o seu ponto de extremidade da habilidade corresponde ao campo `Publisher domain`Registro de aplicativo do Microsoft Entra ID (preferencial) ou ao campo`Home page URL`. Saiba mais sobre como definir a home page para pontos de extremidade.
Para adicionar uma habilidade, é necessário registrá-la primeiro (`APPID_NOT_IN_TENANT`)	Verifique se a ID do aplicativo da sua habilidade está registrada no locatário do Microsoft Entra ID da sua organização.
O link não é válido; ele deve começar com https:// (`URL_MALFORMED`, `URL_NOT_HTTPS`)	Digite novamente o link como uma URL segura.
O manifesto é muito grande; (`MANIFEST_TOO_LARGE`)	Verifique o tamanho do manifesto. Ele deve ser menor ou igual a 500 KB.
Esta habilidade já foi adicionada ao seu copiloto. (`MANIFEST_ALREADY_IMPORTED`)	Exclua a habilidade e tente registrá-la novamente.
A habilidade está limitada a 100 ações. (`LIMITS_TOO_MANY_ACTIONS`)	Existem muitas ações de habilidade definidas no manifesto da habilidade. Remova as ações e tente novamente.
As ações são limitadas a 25 entradas. (`LIMITS_TOO_MANY_INPUTS`)	Existem muitos parâmetros de entrada de ação da habilidade. Remova os parâmetros e tente novamente.
As ações são limitadas a 25 saídas. (`LIMITS_TOO_MANY_OUTPUTS`)	Existem muitos parâmetros de saída de ação da habilidade. Remova os parâmetros e tente novamente.
Seu copiloto pode ter, no máximo, 100 habilidades. (`LIMITS_TOO_MANY_SKILLS`)	Existem muitas habilidades adicionadas a um copiloto. Remova uma habilidade existente e tente novamente.
Parece que algo deu errado. (`AADERROR_OTHER`)	Ocorreu um erro transitório ao validar sua habilidade. Tente novamente.
Ocorreu um erro ao verificar sua habilidade. (`ENDPOINT_HEALTHCHECK_FAILED`, `HEALTH_PING_FAILED`)	Verifique se o ponto de extremidade de sua habilidade está online e respondendo a mensagens.
Essa habilidade não inclui seu copiloto na lista de permissões (`ENDPOINT_HEALTHCHECK_UNAUTHORIZED`)	Verifique se o copiloto foi adicionado à lista de permissões das habilidades.

Compartilhar via