Implementar uma habilidade para uso no Power Virtual Agents
APLICA-SE A: SDK v4
Uma habilidade é um bot que pode ser usado por outro bot. Dessa forma, você pode criar um só 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 as suas habilidades sejam consumidas por um bot do Power Virtual Agents, há algumas restrições adicionais impostas às habilidades que você precisará considerar.
Restrições de manifesto
O Power Virtual Agents impõe restrições no que pode ser declarado no manifesto de habilidades.
- É possível declarar apenas cem 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 registradas para uso no Power Virtual Agents, seu bot de habilidades deve ser um aplicativo registrado no Microsoft Entra ID. Após a adição de uma habilidade, validamos se a ID do aplicativo da habilidade está no locatário do usuário conectado e se o ponto de extremidade da habilidade corresponde à Home Page URL
do aplicativo registrado.
Antes de efetuar o registro do bot como uma habilidade no Power Virtual Agents, você deve garantir que, para o bot, a home page no portal do Azure esteja definida como o URL do manifesto de habilidade do bot.
Validação executada durante o registro de uma habilidade
Quando um usuário final tenta se conectar à sua habilidade em um bot do Power Virtual Agents, primeiro ele precisa importar a habilidade para o Power Virtual Agents. Sua habilidade passará por uma série de verificações de validação. Uma falha em uma dessas verificações poderá 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 e URL_NOT_HTTPS |
O link não é válido; o link precisa começar com https:// | Digite novamente o link como uma URL segura. |
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 global precisa 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 e disparar a habilidade. Tente importar a habilidade novamente. |
A habilidade é íntegra | ENDPOINT_HEALTHCHECK_FAILED e HEALTH_PING_FAILED |
Ocorreu um erro ao verificar sua habilidade. | O Power Virtual Agents recebeu uma resposta desconhecida ao enviar uma atividade EndOfConversation para sua habilidade. Verifique se a habilidade está em execução e se ela responde corretamente. |
A habilidade é autorizada | ENDPOINT_HEALTHCHECK_UNAUTHORIZED |
Esta habilidade não colocou o bot na lista de permissões. | Verifique se o bot foi adicionado à lista de permissões da habilidade. Para obter mais informações, confira como configurar uma habilidade no Power Virtual Agents. |