Configurar uma habilidade do Bot Framework para usar no Copilot Studio

O Copilot Studio permite que você estenda seu agente usando Habilidades do Bot Framework. Se você já tiver criado e implantado bots na organização (usando o SDK e as ferramentas de código profissional do Bot Framework) para cenários específicos, é possível converter esses bots em uma habilidade e registrá-la em um agente 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 agente 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 agentes do Copilot Studio só dão 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 agente 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 para 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 agente podem criar Fluxos reutilizáveis para inseri-los em qualquer conversa do agente.	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.
Response	Use Fluxos para emitir uma resposta do agente. Por exemplo, mostrar uma mensagem personalizada ou imagens embutidas.	Use habilidades para emitir qualquer resposta de agente 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 agente.

Configurar uma habilidade

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

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

Para adicionar uma habilidade ao seu agente:

1. No painel de navegação, expanda Configurações e selecione Habilidades.

2. Na parte superior da página Habilidades, selecione Adicionar habilidade.

3. Copie a ID do seu agente e forneça-a ao seu desenvolvedor de habilidades.

4. Insira a URL para o manifesto da habilidade. O manifesto de uma habilidade contém as informações necessárias para seu agente disparar ações dentro de uma habilidade.

5. Selecione Avançar para iniciar o processo de validação. Uma vez que a validação é bem-sucedida, sua habilidade é adicionada ao seu agente. 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 agente. 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 domainRegistro de aplicativo do Microsoft Entra ID (preferencial) ou ao campoHome 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 agente. (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 agente pode ter, no máximo, 100 habilidades. (LIMITS_TOO_MANY_SKILLS)	Existem muitas habilidades adicionadas a um agente. 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 incluiu seu agente (ENDPOINT_HEALTHCHECK_UNAUTHORIZED)	Verifique se o agente foi adicionado à lista de permissões das habilidades.