Compartilhar via

Configurar uma habilidade para uso nos agentes do Copilot Studio

O Copilot Studio permite que você estenda o agente usando habilidades. Se você já criou e implantou agentes em sua organização (usando o SDK de Agentes do Microsoft 365 ou outras ferramentas de código profissional) para cenários específicos, poderá convertê-los em uma habilidade e registrar essa habilidade em um agente do Copilot Studio.

Observação

Para 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 .

Depois de registrar uma habilidade com um agente do Copilot Studio, você pode disparar as ações de habilidade na conversa sem problemas.

Pré-requisitos

Importante

Os agentes do Copilot Studio oferecem suporte apenas a habilidades criadas usando o SDK do Bot Framework herdado, versão 4.12.0+ e SDK de Agentes do Microsoft 365 v1.0.0+. Novas habilidades devem ser desenvolvidas usando o SDK de Agentes do Microsoft 365.

Para configurar uma habilidade, defina o registro de aplicativo associado no Microsoft Entra ID para sua habilidade como configuração de locatário único.

Quando usar fluxos de agentes vs habilidades

A tabela a seguir ajuda a determinar quando usar fluxos de agentes ou habilidades para uma conversa.

Fator Quando usar fluxos de agentes Quando usar habilidades
Persona Os criadores de 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.
Tipo de 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 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. Consulte estes exemplos:

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 de habilidades. Você pode obter a ID do agente na janela Adicionar uma habilidade.

Para adicionar uma habilidade ao seu agente:

  1. Acessar seu agente.

  2. Selecione Configurações>Habilidades para ir até a página de habilidades.

  3. Selecione Adicionar uma habilidade.

  4. Copie o ID do agente. Você precisa fornecer o ID do agente para o seu desenvolvedor de habilidades.

  5. 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.

  6. 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ê deve 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 propriedades necessárias.
Por exemplo, (name, msaAppId, endpoint único, activities/id, activities/descriptionactivities/type (somente event ou message com suporte)).
Há uma incompatibilidade nos seus pontos de extremidade
(MANIFEST_ENDPOINT_ORIGIN_MISMATCH)		 Verifique se o seu ponto de extremidade da habilidade corresponde ao Publisher domain do 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)		 Revise o link para adicionar 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. Verifique também se o registro do aplicativo da habilidade de locatário único foi implantado no mesmo locatário.
Essa habilidade não incluiu seu agente
(ENDPOINT_HEALTHCHECK_UNAUTHORIZED)		 Verifique se o agente foi adicionado à lista de permissões de habilidades.
  • Last updated on