Implementar uma habilidade para uso no Copilot Studio

APLICA-SE A: SDK v4

Uma habilidade é um bot que pode ser usado por outro bot. Dessa forma, você pode criar um único bot voltado para o usuário e estendê-lo com uma ou mais habilidades. Saiba mais sobre as habilidades em geral na Visão geral das habilidades e como criá-las em Implementar uma habilidade. Como alternativa, os modelos do Assistente Virtual contêm um conjunto de habilidades predefinidas que você pode personalizar e implantar em vez de criar uma do zero.

Se você espera que sua habilidade seja consumida de um copiloto do Copilot Studio , existem algumas outras restrições impostas à sua habilidade que você deve considerar.

Restrições de manifesto

O Copilot Studio impõe restrições sobre o que você pode declarar em seu manifesto de habilidades.

• Você pode declarar apenas 100 ou menos ações.
• Cada ação é limitada a 25 ou menos entradas ou saídas.
• Não é possível usar o tipo de matriz para entradas ou saídas.

Restrição de mesmo locatário

Para garantir a conformidade e a governança adequada das habilidades personalizadas que estão sendo registradas para uso no Copilot Studio, seu bot de habilidade deve ser um aplicativo registrado na ID do Microsoft Entra. Ao adicionar uma habilidade, validamos se o ID do aplicativo da habilidade está no tenant do usuário conectado e se o ponto de extremidade de habilidades corresponde ao arquivo .Home Page URL

Antes de registrar seu bot como uma habilidade no Copilot Studio, você deve garantir que, para o bot, a home page no portal do Azure esteja definida como a URL do manifesto de habilidade do bot.

Restrição de locatário único e multilocatário

O Copilot Studio criou anteriormente aplicativos de ID do Entra multilocatário. No entanto, agora ele está criando aplicativos de ID do Entra de locatário único. Para que as habilidades funcionem corretamente com os agentes com base em novos aplicativos de ID do Entra de locatário único, as habilidades precisam ser configuradas para uma instância de locatário único.

Converter uma habilidade existente de multilocatário em locatário único

Você pode converter habilidades existentes de suporte multilocatário em suporte de locatário único. Para converter uma habilidade multilocatário em uma habilidade de locatário único, você precisa executar as seguintes alterações:

• Criar um novo registro de aplicativo de ID do Entra de locatário único
• Atualizar a configuração de habilidade para usar o locatário único
• Implantar a habilidade
• (Opcional) atualizar o código-fonte

Os seguintes valores são necessários para habilidades de locatário único:

Propriedade	Valor
MicrosoftAppType	SingleTenant
MicrosoftAppId	ID do aplicativo do bot
MicrosoftAppPassword	A senha do aplicativo do bot
MicrosoftAppTenantId	ID do locatário do aplicativo do bot

Para referência, os seguintes valores foram usados para habilidades multilocatários:

Propriedade	Valor
MicrosoftAppType	MultiTenant
MicrosoftAppId	ID do aplicativo do bot
MicrosoftAppPassword	A senha do aplicativo do bot
MicrosoftAppTenantId	Não aplicável; deixado em branco para bots multilocatários

Depois de converter os valores, importe a habilidade em uma instância do agente criada como uma instância de locatário único. Você também pode exibir o registro do aplicativo Entra ID para ver como ele foi criado. Vá para Gerenciar>Tipos de conta com suporte>autenticação.

Atualização de código multilocatário para locatário único

Depois de converter os valores, talvez seja necessário atualizar também o código para permitir a conexão do locatário especificado com a habilidade. Para obter mais informações, consulte BotBuilder-Samples.

Validação executada durante o registro de uma habilidade

Quando um usuário final tentar se conectar à sua habilidade a partir do copiloto, primeiro ele precisará importar a habilidade para o Copilot Studio. Sua habilidade passa por uma série de verificações de validação. Uma falha de uma dessas verificações pode resultar em uma mensagem de erro, conforme descrito nesta tabela.

Etapa de validação	Código de erro	Mensagem de erro	Descrição ou mitigação
O URL do manifesto é válido	URL_MALFORMED, URL_NOT_HTTPS	O link não é válido; o link precisa começar com https://	Insira novamente o link como um URL seguro.
O manifesto é recuperável	MANIFEST_FETCH_FAILED	Encontramos problemas ao obter o manifesto de habilidades.	Verifique se o URL do manifesto corresponde a um link para o seu manifesto; para isso, tente abrir o URL do manifesto em um navegador da Web. Se o URL renderizar a página em 10 segundos, registre novamente a habilidade.
O manifesto é legível	MANIFEST_TOO_LARGE	O manifesto é muito grande.	Seu manifesto deve ter 500 KB ou menos.
O manifesto é legível	MANIFEST_MALFORMED	O manifesto é incompatível.	Verifique se o manifesto é um arquivo JSON válido. Verifique se o manifesto contém propriedades obrigatórias, como name, msaAppId, e assim por diante. Confira Restrições de manifesto para obter mais informações.
A habilidade ainda não está registrada	MANIFEST_ALREADY_IMPORTED	Esta habilidade já foi adicionada ao seu bot.	Exclua a habilidade e efetue o registro dela novamente.
O ponto de extremidade do manifesto e os domínios da home page correspondem	MANIFEST_ENDPOINT_ORIGIN_MISMATCH	Há uma incompatibilidade nos pontos de extremidade da habilidade.	O domínio de URL da home page do aplicativo Microsoft Entra ID e o domínio de URL do manifesto devem corresponder. Confira Restrição de mesmo locatário
A habilidade está hospedada no locatário do usuário conectado	APPID_NOT_IN_TENANT	Para adicionar uma habilidade, primeiro ela precisa ser registrada.	Um administrador deve registrar a habilidade na organização do usuário conectado.
As ações são limitadas	LIMITS_TOO_MANY_ACTIONS	A habilidade está limitada a 100 ações.	Existem muitas ações de habilidade definidas no manifesto da habilidade. Remova as ações e tente novamente.
Os parâmetros de entrada de ação são limitados	LIMITS_TOO_MANY_INPUTS	As ações são limitadas a 25 entradas.	Existem muitos parâmetros de entrada de ação da habilidade. Remova os parâmetros e tente novamente.
Os parâmetros de saída de ação são limitados	LIMITS_TOO_MANY_OUTPUTS	As ações são limitadas a 25 saídas.	Existem muitos parâmetros de saída de ação da habilidade. Remova o parâmetro e tente novamente.
A contagem de habilidades é limitada	LIMITS_TOO_MANY_SKILLS	O bot pode ter um máximo de 25 habilidades.	Existem muitas habilidades adicionadas a um bot. Remova uma habilidade existente e tente novamente.
O token de segurança é válido	AADERROR_OTHER	Parece que algo deu errado.	Pode haver um erro transitório para adquirir um token de segurança para acionar a habilidade. Tente importar a habilidade novamente.
A habilidade é íntegra	ENDPOINT_HEALTHCHECK_FAILED, HEALTH_PING_FAILED	Ocorreu um erro ao verificar sua habilidade.	O Copilot Studio recebeu uma resposta desconhecida ao enviar uma EndOfConversation atividade para sua habilidade. Verifique se a habilidade está em execução e se ela responde corretamente.
A habilidade é autorizada	ENDPOINT_HEALTHCHECK_UNAUTHORIZED	Essa habilidade não colocou seu bot na lista de permissões.	Verifique se o bot está na lista de permissões da habilidade. Para obter mais informações, consulte o Copilot Studio como configurar uma habilidade.